How rayss868/fastmcp-browser works
FastMCP Browser lets an AI client automate tabs in its existing Chromium or Firefox profile. The principal workflow is MCP over stdio into the server’s tool dispatcher, across a token-authenticated loopback WebSocket bridge, then through the extension’s background command handling to page-level snapshots and actions. Session and multi-profile routing, semantic references, screenshots, evaluation, and network observation are distinct capabilities. The excerpts establish server dispatch and page-engine helpers; some extension wiring and capability details are documented or indexed but not shown in source excerpts.
Main entry points: background.js Extension background · engine.js Page command engine · bridge.ts WebSocket bridge · index.ts MCP entry
Components 19
MCP server
- MCP entry
server/src/index.ts - Tool dispatcher
server/src/tools.ts - WebSocket bridge
server/src/bridge.ts - Bridge protocol
server/src/protocol.ts
Browser extension
- Extension background
extension/src/background.js - Browser adapter
extension/src/adapters/runtime.js - API compatibility
extension/src/adapters/compatibility.js - Persistent session
extension/src/session.js - Command router
extension/src/router.js
Page automation
- Page command engine
extension/src/content/engine.js - Snapshot engine
extension/src/content/snapshot.js - DOM semantics
extension/src/content/semantics.js - Element references
extension/src/content/refs.js - Pointer actions
extension/src/content/pointer.js
Browser capabilities
- Page evaluation
extension/src/evaluate.js - Screenshots
extension/src/screenshot.js - Network observation
extension/src/network-monitor.js
Other components
- AI client
- Real browser
Connections 24
- AI client → MCP entry: stdio MCP
README.md - MCP entry → Tool dispatcher: dispatches tools
server/src/index.ts - MCP entry → WebSocket bridge: creates bridge
server/src/index.ts - Tool dispatcher → WebSocket bridge: requests commands
server/src/tools.ts - WebSocket bridge → Bridge protocol: uses message types
server/src/bridge.ts - WebSocket bridge → Extension background: bridges commands
README.md - Extension background → Command router: routes commands
extension/src/background.js - Extension background → Persistent session: manages session
extension/src/background.js - Extension background → Page evaluation: handles evaluation
extension/src/background.js - Extension background → Screenshots: handles screenshots
extension/src/background.js - Extension background → Network observation: tracks network
extension/src/background.js - Browser adapter → API compatibility: wraps browser APIs
extension/src/adapters/runtime.js - Extension background → Browser adapter: uses browser APIs
- Command router → Page command engine: dispatches page commands
- Page command engine → Snapshot engine: creates snapshots
extension/src/content/engine.js - Page command engine → DOM semantics: queries DOM
extension/src/content/engine.js - Page command engine → Element references: resolves references
extension/src/content/engine.js - Page command engine → Pointer actions: uses pointer actions
extension/src/content/engine.js - Snapshot engine → Element references: allocates references
extension/src/content/snapshot.js - Page command engine → Real browser: acts on page
- Persistent session → Real browser: groups tabs
- Page evaluation → Real browser: evaluates page
- Screenshots → Real browser: captures tab
- Network observation → Real browser: observes requests