# jiawei686/jev-ultrafast-mcp architecture

> Architecture diagram of the GitHub repository jiawei686/jev-ultrafast-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jiawei686/jev-ultrafast-mcp
- Repository: https://github.com/jiawei686/jev-ultrafast-mcp

## Overview

jev-ultrafast-mcp is a browser-automation product with two user-facing surfaces: an MCP server for agents and a Chrome extension for observation and macro replay. The main agent workflow submits a goal, lets the server choose and execute guarded page actions, then checks the result with code. The graph also shows direct observe/act tools, macro replay, and the extension’s parallel replay path. Source excerpts are partial, so uncertain internal dispatch details are omitted; documented capabilities are retained.

Main entry points: [`jev_ultrafast_mcp/server.py`](https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/jev_ultrafast_mcp/server.py) (MCP tool server), [`chrome-extension/lib/session.js`](https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/chrome-extension/lib/session.js) (Extension session), [`jev_ultrafast_mcp/browser.py`](https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/jev_ultrafast_mcp/browser.py) (Browser session), [`chrome-extension/popup.js`](https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/chrome-extension/popup.js) (Extension popup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mcp["MCP orchestration"]
  node_server["MCP tool server<br/>[server.py]"]
  node_config["Runtime config<br/>[config.py]"]
end

subgraph group_runtime["Browser runtime"]
  node_browser["Browser session<br/>[browser.py]"]
  node_cdp["CDP transport<br/>[cdp.py]"]
  node_observer["Page observer<br/>[observer.js]"]
  node_safety["URL safety<br/>[safety.py]"]
end

subgraph group_capabilities["Goal capabilities"]
  node_policy["Goal policy<br/>[policy.py]"]
  node_assertions["Result assertions<br/>[assertions.py]"]
  node_macros["Macro recording<br/>[macros.py]"]
end

subgraph group_extension["Chrome extension"]
  node_popup["Extension popup<br/>[popup.js]"]
  node_background["Extension worker<br/>[background.js]"]
  node_extsession["Extension session<br/>[session.js]"]
  node_extobserver["Extension observer<br/>[observer.js]"]
  node_extmacro["Macro resolver<br/>[macro.js]"]
  node_store[("Macro storage<br/>[store.js]")]
  node_renderer["Observation renderer<br/>[render.js]"]
end

node_agent(("Agent / MCP client"))
node_page["Web page"]
node_chrome["Chromium browser"]
node_model["TypeSafe decision model"]

node_agent -->|"calls tools"| node_server
node_server -->|"reads settings"| node_config
node_server -->|"opens and operates"| node_browser
node_server -->|"runs goal loop"| node_policy
node_server -->|"checks result"| node_assertions
node_server -->|"records and replays"| node_macros
node_browser -->|"checks navigation"| node_safety
node_browser -->|"sends commands"| node_cdp
node_cdp -->|"controls browser"| node_chrome
node_browser -->|"injects and reads"| node_observer
node_observer -->|"observes and guards"| node_page
node_chrome -->|"renders"| node_page
node_policy -.->|"requests decisions"| node_model
node_popup -->|"sends requests"| node_background
node_popup -->|"renders observations"| node_renderer
node_background -->|"creates and dispatches"| node_extsession
node_background -->|"manages macros"| node_store
node_extsession -->|"reads page state"| node_extobserver
node_extsession -->|"resolves replay"| node_extmacro
node_extsession -->|"drives active tab"| node_chrome
node_extobserver -->|"observes and guards"| node_page
node_popup -->|"lists macros"| node_store
node_extsession -->|"formats observation"| node_renderer

click node_server "https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/jev_ultrafast_mcp/server.py"
click node_config "https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/jev_ultrafast_mcp/config.py"
click node_browser "https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/jev_ultrafast_mcp/browser.py"
click node_cdp "https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/jev_ultrafast_mcp/cdp.py"
click node_observer "https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/jev_ultrafast_mcp/js/observer.js"
click node_policy "https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/jev_ultrafast_mcp/policy.py"
click node_assertions "https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/jev_ultrafast_mcp/assertions.py"
click node_macros "https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/jev_ultrafast_mcp/macros.py"
click node_safety "https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/jev_ultrafast_mcp/safety.py"
click node_popup "https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/chrome-extension/popup.js"
click node_background "https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/chrome-extension/background.js"
click node_extsession "https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/chrome-extension/lib/session.js"
click node_extobserver "https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/chrome-extension/lib/observer.js"
click node_extmacro "https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/chrome-extension/lib/macro.js"
click node_store "https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/chrome-extension/lib/store.js"
click node_renderer "https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/chrome-extension/lib/render.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_server,node_config,node_agent,node_chrome toneBlue
class node_browser,node_cdp,node_observer,node_safety toneAmber
class node_policy,node_assertions,node_macros toneMint
class node_popup,node_background,node_extsession,node_extobserver,node_extmacro,node_store,node_renderer toneRose
class node_page,node_model toneIndigo
```

## Components

### MCP orchestration

- [MCP tool server](https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/jev_ultrafast_mcp/server.py): `jev_ultrafast_mcp/server.py`
- [Runtime config](https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/jev_ultrafast_mcp/config.py): `jev_ultrafast_mcp/config.py`

### Browser runtime

- [Browser session](https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/jev_ultrafast_mcp/browser.py): `jev_ultrafast_mcp/browser.py`
- [CDP transport](https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/jev_ultrafast_mcp/cdp.py): `jev_ultrafast_mcp/cdp.py`
- [Page observer](https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/jev_ultrafast_mcp/js/observer.js): `jev_ultrafast_mcp/js/observer.js`
- [URL safety](https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/jev_ultrafast_mcp/safety.py): `jev_ultrafast_mcp/safety.py`

### Goal capabilities

- [Goal policy](https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/jev_ultrafast_mcp/policy.py): `jev_ultrafast_mcp/policy.py`
- [Result assertions](https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/jev_ultrafast_mcp/assertions.py): `jev_ultrafast_mcp/assertions.py`
- [Macro recording](https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/jev_ultrafast_mcp/macros.py): `jev_ultrafast_mcp/macros.py`

### Chrome extension

- [Extension popup](https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/chrome-extension/popup.js): `chrome-extension/popup.js`
- [Extension worker](https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/chrome-extension/background.js): `chrome-extension/background.js`
- [Extension session](https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/chrome-extension/lib/session.js): `chrome-extension/lib/session.js`
- [Extension observer](https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/chrome-extension/lib/observer.js): `chrome-extension/lib/observer.js`
- [Macro resolver](https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/chrome-extension/lib/macro.js): `chrome-extension/lib/macro.js`
- [Macro storage](https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/chrome-extension/lib/store.js): `chrome-extension/lib/store.js`
- [Observation renderer](https://github.com/jiawei686/jev-ultrafast-mcp/blob/main/chrome-extension/lib/render.js): `chrome-extension/lib/render.js`

### Other components

- **Agent / MCP client**
- **Web page**
- **Chromium browser**
- **TypeSafe decision model**

## Connections

- Agent / MCP client → MCP tool server: calls tools
- MCP tool server → Runtime config: reads settings
- MCP tool server → Browser session: opens and operates
- MCP tool server → Goal policy: runs goal loop
- MCP tool server → Result assertions: checks result
- MCP tool server → Macro recording: records and replays
- Browser session → URL safety: checks navigation
- Browser session → CDP transport: sends commands
- CDP transport → Chromium browser: controls browser
- Browser session → Page observer: injects and reads
- Page observer → Web page: observes and guards
- Chromium browser → Web page: renders
- Goal policy → TypeSafe decision model: requests decisions
- Extension popup → Extension worker: sends requests
- Extension popup → Observation renderer: renders observations
- Extension worker → Extension session: creates and dispatches
- Extension worker → Macro storage: manages macros
- Extension session → Extension observer: reads page state
- Extension session → Macro resolver: resolves replay
- Extension session → Chromium browser: drives active tab
- Extension observer → Web page: observes and guards
- Extension popup → Macro storage: lists macros
- Extension session → Observation renderer: formats observation