Develop

npm install
npm run typecheck       # server/test sources
npm run typecheck:ext   # extension sources (@types/chrome)
npm run build:ext       # bundle the extension → extension-dist/
npm test                # builds, then runs node --test on dist/test
RUN_EXT_SMOKE=1 node --test dist/test/extension-smoke.test.js   # live, headed

The extension

Published on the Chrome Web Store as MCP Extension for Chrome. Extension versions move only when extension/ changes, so the listed build can sit a release behind the npm package; the two negotiate capabilities on connect, so an older extension loses features rather than breaking.

extension/ builds (esbuild) to extension-dist/, loaded via chrome://extensions → Load unpacked → select ~/chrome-mcp-extension, the mirror the server refreshes from extension-dist/ on every boot (loading extension-dist/ directly also works). It pairs itself from the pairing.json the server writes into that folder; the Options page paste of port + token from ~/.chrome-mcp/handshake.json (run npx -y @mehmoodqureshi/chrome-mcp --print-pairing to get the path) is only the fallback.

Reads/interaction use chrome.scripting/chrome.tabs — no "is being debugged" banner, CSP-safe reads (isolated world), testable under Playwright. chrome.debugger is used only where it's needed and worth it: trusted: true input (real OS-level events on React/Vue inputs) and screenshot (captures a specific tab without activating it — safe under parallel batch — with true full-page and element capture). Those ops show the debug banner while attached; the session lingers 1.5s after the last op so a burst of them attaches once. Screenshots are JPEG (quality 70) at CSS-pixel size by default — pass format: "png", quality, or scale to change that.