browser_mcp — VSCode docs browser + hosted MCP

A single VSCode extension that displays auto-generated, self-contained HTML documentation in a real-DOM pane, and hosts an MCP server so Claude (via Claude Code) can develop and test that documentation UI — navigating, screenshotting, reading console/network, and crawling links.

One extension process owns everything:

┌─ VSCode extension host (one process) ──────────────────────────────────────┐
│  • Docs HTTP server  →  http://127.0.0.1:<ephemeral>/...   (static docs)     │
│  • Webview pane      →  <iframe> of the docs URL — REAL, selectable DOM      │
│  • Stateless MCP HTTP server  →  http://127.0.0.1:8765/mcp                   │
│  • MCP tool handlers ── drive ──► pane (postMessage) + Playwright (IPC)       │
│  • Activity-bar view + commands; spawns & owns the sidecar                   │
└───────────────▲──────────────────────────────────────────────┬─────────────┘
   Claude Code   │ HTTP (.mcp.json type:"http")                 │ stdio JSON
   (terminal)    │                                              ▼
                 │                       ┌─ Playwright sidecar (child process) ─┐
                 └───────────────────────┤  headless Chromium; goto/screenshot/ │
                                         │  click; console + network capture    │
                                         └──────────────────────────────────────┘

A navigate updates the pane and the Playwright page in the same handler — always in sync, no lockfile/discovery. The pane shows real DOM (humans read/select); Playwright is the AI's surface (screenshots + inspection); both render the same URL.

Why this shape? VSCode 1.126 routes the built-in Simple Browser to a new "integrated browser" that opens a fresh tab per programmatic navigation, and you can't screenshot a VSCode pane. So we render docs in our own webview and use a co-located headless Chromium for pixels.

Requirements

• Node.js ≥ 20 (developed on 25), VSCode ≥ 1.101, Claude Code.
• A Chromium build for playwright-core. Fetched automatically on first use — the extension runs the playwright-core installer (shown as a progress notification) the first time a browser is needed, into the shared Playwright cache (~/Library/Caches/ms-playwright on macOS, ~/.cache/ms-playwright on Linux, %LOCALAPPDATA%\ms-playwright on Windows). No manual step; subsequent runs reuse it.

Setup

npm install          # installs deps (extension workspace)
npm run build        # esbuild → extension/dist/extension.js + dist/sidecar/main.js
npm run install:ext  # builds + sideloads into ~/.vscode/extensions, carrying playwright-core

Then Developer: Reload Window in VSCode to activate. (Re-run npm run install:ext + reload after editing the extension — the installed copy is a snapshot.)

Alternative install: npm run package:ext → extension/docs-browser-extension.vsix → Extensions view → Install from VSIX (remove any sideloaded copy first). The .vsix bundles playwright-core, so it installs cleanly on another machine; Chromium is still fetched on first use. (Building the .vsix requires the zip CLI on the build machine; installing it does not.)

Use in another project

The extension is installed per user (in ~/.vscode/extensions), so once installed it's available to every VSCode window — you don't reinstall per project. To use it in another project:

1. Point it at your docs. Set docsBrowser.docsDir (workspace setting) to your generated HTML output directory (relative to the workspace root, or absolute). Activity Bar → Docs Browser → the gear, or run Docs Browser: Open Settings.
2. Register the MCP server. Run Docs Browser: Create MCP config (.mcp.json) from the Command Palette (or the view title bar). It writes/merges a .mcp.json in the workspace root pointing Claude Code at the hosted server, preserving any other servers already listed.
3. Reload the window, then start Claude Code in that folder (run /mcp if the tools don't connect immediately).

That's it — no per-project build or install. Note the single-window / fixed-port assumption below if you keep multiple projects open at once.

Connect Claude Code

.mcp.json (project scope) points Claude Code at the extension-hosted server:

{ "mcpServers": { "docs-browser": { "type": "http", "url": "http://127.0.0.1:8765/mcp" } } }

The extension activates on VSCode startup and binds 127.0.0.1:8765 (configurable via docsBrowser.mcpPort). Start Claude Code in this folder and approve the server. If the tools show "failed" (e.g. Claude Code started before the extension was listening), run /mcp to reconnect — the server is stateless, so it recovers across VSCode reloads.

Usage

• Activity Bar → Docs Browser: an "Open Docs Browser" button + a clickable page list + Open/Refresh; when no docs are found yet, a welcome panel links to the docs-directory setting and the MCP-config command.
• Command Palette: Docs Browser: Open, Docs Browser: Refresh, Docs Browser: Create MCP config (.mcp.json), Docs Browser: Open Settings.
• From Claude: navigate/screenshot/etc.; the pane mirrors what Claude does.

MCP tools

Tool	Purpose
open_docs / navigate	Open/go to a page (mirrors to the pane)
back / forward / reload	History + reload
screenshot	PNG (fullPage, selector, savePath)
get_page_title	{title, url} — confirm where you landed
get_page_text / get_links	Rendered text / link graph
list_pages	HTML files in the docs dir
read_console	JS errors/warnings on the current page
read_network	Failed / 4xx / 5xx requests (broken assets)
check_links	Crawl internal links → broken targets + orphan pages
click	Click by selector or text (pane follows)
pane_state	Pane URL + preflight status + recent webview events (sync/debug)

Settings

• docsBrowser.docsDir (default docs) — directory of generated HTML to serve.
• docsBrowser.mcpPort (default 8765) — fixed MCP port (strict; fails loudly on conflict).
• docsBrowser.maxCrawlPages (default 500) — page cap for check_links; raise for large doc sets (check_links warns when the cap is hit). Applied at activation.

Layout

extension/
  src/        types.ts (contracts), extension.ts, tools.ts, mcpServer.ts,
              paneController.ts, browserClient.ts, docsServer.ts, checkLinks.ts
  sidecar/    main.ts          # Playwright child process
  test/       *.mjs + integration.ts   # standalone module + integration tests
  build.mjs       # esbuild (extension + sidecar)
  build-vsix.mjs  # package a .vsix (bundle + inject playwright-core)
docs/         # sample docs (replace with your generated output)
.mcp.json     # Claude Code MCP registration (http)
scripts/install-extension.sh

Tests

• Module tests: node extension/test/{sidecar,pane,mcp,docs}.mjs
• Full pipeline (headless, real Chromium + MCP HTTP client): node extension/run-integration.mjs

Notes & caveats

• MCP over HTTP: if Claude Code starts before the extension is listening, reconnect via /mcp. Stateless transport handles VSCode reloads.
• Pane: VSCode find-in-page (Cmd+F) may not reach inside the cross-origin iframe; keyboard focus inside the iframe can swallow some VSCode shortcuts/copy.
• Sidecar: owned by the extension; group-killed on deactivate so Chromium doesn't orphan.
• Multi-window: a second VSCode window contends for the fixed MCP port (strict → fails loudly); single-window assumed.