# rayss868/fastmcp-browser architecture

> Architecture diagram of the GitHub repository rayss868/fastmcp-browser, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rayss868/fastmcp-browser
- Repository: https://github.com/rayss868/fastmcp-browser

## Overview

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: [`extension/src/background.js`](https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/background.js) (Extension background), [`extension/src/content/engine.js`](https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/content/engine.js) (Page command engine), [`server/src/bridge.ts`](https://github.com/rayss868/fastmcp-browser/blob/main/server/src/bridge.ts) (WebSocket bridge), [`server/src/index.ts`](https://github.com/rayss868/fastmcp-browser/blob/main/server/src/index.ts) (MCP entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["MCP server"]
  node_mcp["MCP entry<br/>[index.ts]"]
  node_tools["Tool dispatcher<br/>[tools.ts]"]
  node_bridge["WebSocket bridge<br/>[bridge.ts]"]
  node_protocol["Bridge protocol<br/>[protocol.ts]"]
end

subgraph group_extension["Browser extension"]
  node_background["Extension background<br/>[background.js]"]
  node_adapter["Browser adapter<br/>[runtime.js]"]
  node_compat["API compatibility<br/>[compatibility.js]"]
  node_session[("Persistent session<br/>[session.js]")]
  node_router["Command router<br/>[router.js]"]
end

subgraph group_page["Page automation"]
  node_engine["Page command engine<br/>[engine.js]"]
  node_snapshot["Snapshot engine<br/>[snapshot.js]"]
  node_semantics["DOM semantics<br/>[semantics.js]"]
  node_refs["Element references<br/>[refs.js]"]
  node_pointer["Pointer actions<br/>[pointer.js]"]
end

subgraph group_capabilities["Browser capabilities"]
  node_evaluate["Page evaluation<br/>[evaluate.js]"]
  node_screenshots["Screenshots<br/>[screenshot.js]"]
  node_network["Network observation<br/>[network-monitor.js]"]
end

node_client(("AI client"))
node_browser(("Real browser"))

node_client -->|"stdio MCP"| node_mcp
node_mcp -->|"dispatches tools"| node_tools
node_mcp -->|"creates bridge"| node_bridge
node_tools -->|"requests commands"| node_bridge
node_bridge -->|"uses message types"| node_protocol
node_bridge -->|"bridges commands"| node_background
node_background -->|"routes commands"| node_router
node_background -->|"manages session"| node_session
node_background -->|"handles evaluation"| node_evaluate
node_background -->|"handles screenshots"| node_screenshots
node_background -->|"tracks network"| node_network
node_adapter -->|"wraps browser APIs"| node_compat
node_background -.->|"uses browser APIs"| node_adapter
node_router -.->|"dispatches page commands"| node_engine
node_engine -->|"creates snapshots"| node_snapshot
node_engine -->|"queries DOM"| node_semantics
node_engine -->|"resolves references"| node_refs
node_engine -->|"uses pointer actions"| node_pointer
node_snapshot -->|"allocates references"| node_refs
node_engine -.->|"acts on page"| node_browser
node_session -.->|"groups tabs"| node_browser
node_evaluate -.->|"evaluates page"| node_browser
node_screenshots -.->|"captures tab"| node_browser
node_network -.->|"observes requests"| node_browser

click node_mcp "https://github.com/rayss868/fastmcp-browser/blob/main/server/src/index.ts"
click node_tools "https://github.com/rayss868/fastmcp-browser/blob/main/server/src/tools.ts"
click node_bridge "https://github.com/rayss868/fastmcp-browser/blob/main/server/src/bridge.ts"
click node_protocol "https://github.com/rayss868/fastmcp-browser/blob/main/server/src/protocol.ts"
click node_background "https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/background.js"
click node_adapter "https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/adapters/runtime.js"
click node_compat "https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/adapters/compatibility.js"
click node_session "https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/session.js"
click node_router "https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/router.js"
click node_engine "https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/content/engine.js"
click node_snapshot "https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/content/snapshot.js"
click node_semantics "https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/content/semantics.js"
click node_refs "https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/content/refs.js"
click node_pointer "https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/content/pointer.js"
click node_evaluate "https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/evaluate.js"
click node_screenshots "https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/screenshot.js"
click node_network "https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/network-monitor.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp,node_tools,node_bridge,node_protocol,node_client,node_browser toneBlue
class node_background,node_adapter,node_compat,node_session,node_router toneAmber
class node_engine,node_snapshot,node_semantics,node_refs,node_pointer toneMint
class node_evaluate,node_screenshots,node_network toneRose
```

## Components

### MCP server

- [MCP entry](https://github.com/rayss868/fastmcp-browser/blob/main/server/src/index.ts): `server/src/index.ts`
- [Tool dispatcher](https://github.com/rayss868/fastmcp-browser/blob/main/server/src/tools.ts): `server/src/tools.ts`
- [WebSocket bridge](https://github.com/rayss868/fastmcp-browser/blob/main/server/src/bridge.ts): `server/src/bridge.ts`
- [Bridge protocol](https://github.com/rayss868/fastmcp-browser/blob/main/server/src/protocol.ts): `server/src/protocol.ts`

### Browser extension

- [Extension background](https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/background.js): `extension/src/background.js`
- [Browser adapter](https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/adapters/runtime.js): `extension/src/adapters/runtime.js`
- [API compatibility](https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/adapters/compatibility.js): `extension/src/adapters/compatibility.js`
- [Persistent session](https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/session.js): `extension/src/session.js`
- [Command router](https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/router.js): `extension/src/router.js`

### Page automation

- [Page command engine](https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/content/engine.js): `extension/src/content/engine.js`
- [Snapshot engine](https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/content/snapshot.js): `extension/src/content/snapshot.js`
- [DOM semantics](https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/content/semantics.js): `extension/src/content/semantics.js`
- [Element references](https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/content/refs.js): `extension/src/content/refs.js`
- [Pointer actions](https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/content/pointer.js): `extension/src/content/pointer.js`

### Browser capabilities

- [Page evaluation](https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/evaluate.js): `extension/src/evaluate.js`
- [Screenshots](https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/screenshot.js): `extension/src/screenshot.js`
- [Network observation](https://github.com/rayss868/fastmcp-browser/blob/main/extension/src/network-monitor.js): `extension/src/network-monitor.js`

### Other components

- **AI client**
- **Real browser**

## Connections

- AI client → MCP entry: stdio MCP (evidence: `README.md`)
- MCP entry → Tool dispatcher: dispatches tools (evidence: `server/src/index.ts`)
- MCP entry → WebSocket bridge: creates bridge (evidence: `server/src/index.ts`)
- Tool dispatcher → WebSocket bridge: requests commands (evidence: `server/src/tools.ts`)
- WebSocket bridge → Bridge protocol: uses message types (evidence: `server/src/bridge.ts`)
- WebSocket bridge → Extension background: bridges commands (evidence: `README.md`)
- Extension background → Command router: routes commands (evidence: `extension/src/background.js`)
- Extension background → Persistent session: manages session (evidence: `extension/src/background.js`)
- Extension background → Page evaluation: handles evaluation (evidence: `extension/src/background.js`)
- Extension background → Screenshots: handles screenshots (evidence: `extension/src/background.js`)
- Extension background → Network observation: tracks network (evidence: `extension/src/background.js`)
- Browser adapter → API compatibility: wraps browser APIs (evidence: `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 (evidence: `extension/src/content/engine.js`)
- Page command engine → DOM semantics: queries DOM (evidence: `extension/src/content/engine.js`)
- Page command engine → Element references: resolves references (evidence: `extension/src/content/engine.js`)
- Page command engine → Pointer actions: uses pointer actions (evidence: `extension/src/content/engine.js`)
- Snapshot engine → Element references: allocates references (evidence: `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
