feat: MCP Streamable HTTP server with full CLI command parity

[dkisser]

Summary

Adds a Model Context Protocol (MCP) server using Streamable HTTP to Browser Bridge, letting MCP-compatible agents (Claude Desktop, Cursor, etc.) control browsers through the same WebSocket protocol used by the CLI.

The MCP server runs inside the existing apps/websocket Bun process, binding to 127.0.0.1:3003/mcp by default. All CLI browser-control commands are now exposed as MCP tools.

What's included

• MCP bootstrap (apps/websocket/src/mcp/)

  • FastMCP server with httpStream transport
  • Per-session browser selection and auto-detection
  • Shared command/event client wrapper around @browser-bridge/websocket/client

• MCP tools (21 total)

  • Browser management: list_browsers, set_browser
  • Navigation: navigate, go_back, go_forward, refresh
  • Tabs: tab_list, tab_new, tab_close, tab_switch
  • DOM interaction: click, type, select, scroll, hover
  • Information extraction: get_text, get_html, screenshot, pageinfo
  • Waits: wait_element, wait_navigation

• Documentation

  • docs/mcp-setup.md with config snippets for Claude Desktop and Cursor
  • README MCP section
  • Implementation plan under docs/superpowers/plans/

Testing

• bun run test — 116 tests pass
• bun run type-check — clean
• bunx @biomejs/biome check --write . — clean
• MCP server starts and binds to loopback (127.0.0.1:3003/mcp)

Test plan / TODO

• Run end-to-end smoke test with @modelcontextprotocol/sdk client
• Verify each new tool against a real browser extension
• Review coverage report and consider adding registration-path tests for the few remaining uncovered registerXTool callbacks

Notes

• The internal WebSocket URL used by MCP tools is hardcoded to 127.0.0.1.
• Authentication is left to the WebSocket handshake; the MCP endpoint itself is localhost-only by default (BRIDGE_MCP_HOSTNAME).
• Coverage for new MCP code is ~79% (core logic fully covered; remaining gaps are mostly boilerplate FastMCP execute callback wrappers).

🤖 Generated with Claude Code