custom-browser-mcp

MCP server that turns any live URL into a multi-output design bundle: a11y tree, design tokens, screenshot, Claude-consumable DSL, Figma REST JSON. Zero LLM API cost. Persistent Chromium context.

Tools (3)

analyze_page

Multi-output bundle. Pick any subset of {a11y, tokens, screenshot}.

// input
{
  "url": "https://example.com",
  "outputs": ["a11y", "tokens", "screenshot"],
  "viewport": { "width": 1440, "height": 900 },
  "full_page_screenshot": true,
  "wait_until": "networkidle",
  "timeout_ms": 30000
}

Output: Bundle v1.0.0 (schema). Versioned snapshot_id (sha256 url+ts).

to_claude

cbm/htmltoclaude/v0 — compact YAML DSL. Token-economical for Claude ingestion.

// input
{ "url": "https://example.com", "format": "yaml" }

Output: YAML with hoisted token refs (c0..cN colors, f0..fN fonts), 4-tuple boxes, node types FRAME|TEXT|IMAGE|SVG|GROUP|INPUT, conservative pruning of empty GROUPs, shadowRoot recursion, warnings for iframe_cross_origin / bg_gradient_unmapped / shadow_dom_skipped.

Sample: examples/awwwards-sotd.htmltoclaude.yaml (180 nodes, ~19.5K tokens).

to_figma

cbm/htmltofigma/v0 — Figma REST node JSON. Custom adapter (no proprietary API).

// input
{ "url": "https://example.com" }

Output: { document: { children: [{ type: "CANVAS", children: [FigmaNode...] }] }, warnings, metrics }. Mapping table:

Sample: examples/awwwards-sotd.htmltofigma.json (180 nodes, ~174 KB JSON).

Deferred Phase 3+: SVG paths, gradients (GRADIENT_LINEAR), box shadows (DROP_SHADOW), auto-layout, COMPONENT/INSTANCE detection.

Install

bun install
bunx playwright install chromium-headless-shell

Run

bun run serve              # stdio MCP server
bun run smoke [url]        # analyze_page smoke
bun run smoke:claude [url] # to_claude smoke (writes out/htmltoclaude-{N}n.yaml)
bun run smoke:figma [url]  # to_figma smoke   (writes out/htmltofigma-{N}n.json)
bun run consolidate [url]  # sequential 3-tool + assert htmltoclaude↔figma node parity
bun run typecheck          # tsc --noEmit

Wire into Claude Code (.mcp.json)

{
  "mcpServers": {
    "custom-browser": {
      "command": "bun",
      "args": ["run", "serve"],
      "cwd": "/absolute/path/to/custom-browser-mcp"
    }
  }
}

Restart Claude Code. Verify with /mcp — should list custom-browser with 3 tools.

Stack

• Bun 1.3 — runtime + package manager

• TypeScript 5

• @modelcontextprotocol/sdk 1.29 — stdio transport

• Playwright 1.60 — Chromium headless persistent context

• Zod 4 — input/output schema validation

• yaml 2.9 — YAML serialization (to_claude)

Architecture

src/
├── lib/
│   └── browser.ts          ← shared Chromium persistent context (singleton, viewport-aware)
├── extractors/
│   ├── a11y.ts             ← page.locator(':root').ariaSnapshot() YAML
│   ├── tokens.ts           ← getComputedStyle walk → colors/fonts/spacing/type
│   ├── screenshot.ts       ← page.screenshot({ fullPage })
│   ├── htmltoclaude.ts     ← in-browser walker + token hoist + conservative pruning
│   └── figma.ts            ← ClaudeBundle → FigmaDocument pure transform
├── tools/
│   ├── analyze_page.ts
│   ├── to_claude.ts
│   └── to_figma.ts
├── schemas/
│   └── output.ts           ← Zod Bundle v1.0.0
└── server.ts               ← MCP stdio + 3 tool registrations

Single Chromium persistent context shared across all 3 tools (factory in src/lib/browser.ts). Profile: out/.chromium-profile/ (override via CBM_USER_DATA_DIR env). Warm context ≈ 25% speedup vs cold launch.

Browser mode (3 options)

Set via CBM_BROWSER_MODE env var. Defaults to chromium.

# Mode chromium (default — managed download)
bun run smoke https://example.com

# Mode chrome (use system Chrome)
CBM_BROWSER_MODE=chrome bun run smoke https://example.com

# Mode cdp (connect to running Chrome with debug port)
# Step 1: launch Chrome with debug port
google-chrome --remote-debugging-port=9222
# Step 2: run with CDP mode
CBM_BROWSER_MODE=cdp CBM_CDP_URL=http://localhost:9222 bun run smoke https://example.com

CDP mode shares ALL browser state (cookies, localStorage, logged-in accounts) — useful for scraping behind login walls, but privacy risk : MCP sees all your tabs and sessions.

Cost & performance

Measured smoke baseline against Awwwards SOTD (1440×900, networkidle), Mac arm64:

Phase 1 + 2 are 100% local Chromium. Optional LLM augmentation (vision tagging, code emit) gated Phase 3+.

License

MIT

Status

Phase 1 (analyze_page) + Phase 1b (to_claude) + Phase 2 v0 (to_figma) shipped. Roadmap & deferred coverage in research/PHASE-2-FIGMA-ADAPTER (private spec).

Issues / PRs welcome.