@winstonfassett/web-dev-mcp-gateway

Universal MCP gateway for web development. Proxy any dev server to give AI agents live browser observability — console logs, errors, network requests, DOM queries, and JS evaluation.

Works with any HTTP dev server: Next.js, Vite, Remix, Rails, Django, static files.

Quick Start (standalone proxy)

# Start your dev server
npm run dev  # → localhost:3000

# Start the gateway
npx web-dev-mcp --target http://localhost:3000

# Browse http://localhost:3333 (proxied + instrumented)
# MCP endpoint: http://localhost:3333/__mcp/sse

Framework Adapters

For deeper integration (auto-start, build events, HMR status), use a framework adapter:

| Framework | Package | Setup | |-----------|---------|-------| | Vite | @winstonfassett/web-dev-mcp-vite | 2-line plugin | | Storybook | @winstonfassett/web-dev-mcp-vite | 1-line addon | | Next.js | @winstonfassett/web-dev-mcp-nextjs | 1-line config wrapper |

Adapters auto-start the gateway — no separate terminal needed.

How It Works

Browser ──→ Gateway (:3333) ──→ Dev Server (:3000)
   │             │
   ├─ /__events  │  Console/error/network events (WebSocket)
   ├─ /__rpc     │  DOM queries via capnweb RPC (WebSocket)
   └─ /__mcp/sse │  MCP tools for AI agents (SSE)

1. Gateway proxies all HTTP/WebSocket traffic to your dev server
2. Injected <script> patches console.*, error handlers, fetch/XHR
3. Events stream to gateway → written to NDJSON log files
4. capnweb RPC enables bidirectional browser communication
5. MCP server exposes tools that AI agents call

MCP Tools (core set)

| Tool | Description | |------|-------------| | set_project | Set active project (when multiple dev servers are registered) | | list_projects | List registered dev servers + gateway | | list_browsers | List connected browser tabs | | get_diagnostics | Consolidated logs + errors + build status snapshot | | clear | Truncate logs, set checkpoint for incremental reads | | eval_js_rpc | Run JS with document/window as remote DOM proxies. Persistent state + browser.* helpers |

Full toolset (23 tools): /__mcp/sse?tools=full

CLI

npx web-dev-mcp [options]

Options:
  --target, -t <url>   Dev server URL to proxy
  --port, -p <port>    Gateway port (default: 3333)
  --network            Capture fetch/XHR requests
  --help, -h           Show help

License

MIT