# feder-cr/invisible_playwright_mcp architecture

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

- Interactive diagram: https://gitdiagram.com/feder-cr/invisible_playwright_mcp
- Repository: https://github.com/feder-cr/invisible_playwright_mcp

## Overview

This package offers two entry points to a local stealth-browser agent: an MCP server for an assistant, and a standalone web chat with a live browser pane. In the web flow, a user submits an instruction, a conversation’s agent uses its persistent MCP link, and browser tools operate on a page; sessions and transcripts persist locally. MCP tools route through work and browser actions. The README documents OpenRouter, proxy, profile, seed, and engine options. Source excerpts and the index support the internal links shown; UI internals and some runtime wiring are not fully sampled.

Main entry points: [`src/invisible_playwright_mcp/mcp/server.py`](https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/mcp/server.py) (MCP server), [`src/invisible_playwright_mcp/mcp/work.py`](https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/mcp/work.py) (Browser work), [`src/invisible_playwright_mcp/routes.py`](https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/routes.py) (HTTP routes), [`src/invisible_playwright_mcp/mcp/plan.py`](https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/mcp/plan.py) (Launch planning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["CLI<br/>[cli.py]"]
end

subgraph group_conversation["Conversation UI"]
  node_routes["HTTP routes<br/>[routes.py]"]
  node_ui["Web UI"]
  node_ui_js["UI interactions"]
  node_sessions["Conversation registry<br/>[sessions.py]"]
  node_chat["Conversation<br/>[chat.py]"]
  node_agent["Agent loop<br/>[agent.py]"]
  node_link["MCP client link<br/>[link.py]"]
end

subgraph group_mcp["MCP server"]
  node_mcp_server["MCP server<br/>[server.py]"]
  node_work["Browser work<br/>[work.py]"]
  node_actions["Browser actions<br/>[actions.py]"]
  node_plan["Launch planning<br/>[plan.py]"]
  node_identity["Browser identity<br/>[identity.py]"]
  node_proxy["Proxy settings<br/>[proxy.py]"]
end

subgraph group_browser["Browser runtime"]
  node_browser_session["Browser session<br/>[session.py]"]
  node_engine["Engine manager<br/>[engine.py]"]
  node_browser["Stealth browser"]
end

subgraph group_shared["Shared services"]
  node_storage[("Session storage<br/>[storage.py]")]
  node_mcp_store["Browser state store<br/>[store.py]"]
  node_chats["Chat persistence<br/>[chats.py]"]
  node_llm["OpenRouter client<br/>[llm.py]"]
  node_env["Environment config<br/>[env.py]"]
end

node_user(("User"))
node_assistant(("MCP assistant"))
node_model_provider["Model provider"]
node_web["Visited websites"]

node_user -->|"starts UI or MCP"| node_cli
node_assistant -->|"uses MCP tools"| node_mcp_server
node_user -->|"submits instructions"| node_ui
node_cli -->|"starts web app"| node_routes
node_routes -->|"serves page"| node_ui
node_ui_js -.->|"calls HTTP routes"| node_routes
node_routes -->|"selects conversation"| node_sessions
node_routes -->|"starts or stops turns"| node_chat
node_sessions -->|"creates conversations"| node_chat
node_sessions -->|"spawns server link"| node_link
node_sessions -->|"loads conversations"| node_chats
node_chat -->|"runs agent"| node_agent
node_chat -->|"drives browser tools"| node_link
node_agent -->|"requests tools"| node_link
node_link -->|"connects to server"| node_mcp_server
node_cli -->|"starts server"| node_mcp_server
node_mcp_server -->|"dispatches browser work"| node_work
node_mcp_server -->|"exposes operations"| node_actions
node_mcp_server -->|"uses launch plan"| node_plan
node_mcp_server -->|"uses state store"| node_mcp_store
node_mcp_server -->|"starts engine fetch"| node_engine
node_work -->|"resolves identity"| node_identity
node_work -->|"resolves launch settings"| node_plan
node_work -->|"persists browser state"| node_mcp_store
node_work -->|"runs operations"| node_actions
node_work -->|"opens browser session"| node_browser_session
node_work -->|"checks readiness"| node_engine
node_plan -->|"uses identity"| node_identity
node_plan -->|"resolves proxy"| node_proxy
node_actions -->|"operates on page"| node_browser_session
node_browser_session -->|"launches stealth browser"| node_browser
node_engine -->|"provides engine binary"| node_browser
node_browser -->|"browses pages"| node_web
node_chats -->|"reads and writes chats"| node_storage
node_mcp_store -->|"reads and writes state"| node_storage
node_cli -->|"configures model client"| node_llm
node_llm -->|"resolves model setting"| node_env
node_agent -.->|"requests model responses"| node_model_provider
node_llm -->|"sends model requests"| node_model_provider
node_plan -.->|"supports optional proxy"| node_proxy

click node_cli "https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/cli.py"
click node_routes "https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/routes.py"
click node_ui "https://github.com/feder-cr/invisible_playwright_mcp/tree/main/src/invisible_playwright_mcp/ui"
click node_ui_js "https://github.com/feder-cr/invisible_playwright_mcp/tree/main/src/invisible_playwright_mcp/ui/js"
click node_sessions "https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/sessions.py"
click node_chat "https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/chat.py"
click node_agent "https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/agent.py"
click node_link "https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/link.py"
click node_mcp_server "https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/mcp/server.py"
click node_work "https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/mcp/work.py"
click node_actions "https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/mcp/actions.py"
click node_plan "https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/mcp/plan.py"
click node_identity "https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/mcp/identity.py"
click node_proxy "https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/mcp/proxy.py"
click node_browser_session "https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/mcp/session.py"
click node_engine "https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/engine.py"
click node_storage "https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/storage.py"
click node_mcp_store "https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/mcp/store.py"
click node_chats "https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/chats.py"
click node_llm "https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/llm.py"
click node_env "https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/env.py"

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_cli,node_user toneBlue
class node_routes,node_ui,node_ui_js,node_sessions,node_chat,node_agent,node_link toneAmber
class node_mcp_server,node_work,node_actions,node_plan,node_identity,node_proxy toneMint
class node_browser_session,node_engine,node_browser toneRose
class node_storage,node_mcp_store,node_chats,node_llm,node_env,node_assistant,node_model_provider,node_web toneIndigo
```

## Components

### Entry points

- [CLI](https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/cli.py): `src/invisible_playwright_mcp/cli.py`

### Conversation UI

- [HTTP routes](https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/routes.py): `src/invisible_playwright_mcp/routes.py`
- [Web UI](https://github.com/feder-cr/invisible_playwright_mcp/tree/main/src/invisible_playwright_mcp/ui): `src/invisible_playwright_mcp/ui`
- [UI interactions](https://github.com/feder-cr/invisible_playwright_mcp/tree/main/src/invisible_playwright_mcp/ui/js): `src/invisible_playwright_mcp/ui/js`
- [Conversation registry](https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/sessions.py): `src/invisible_playwright_mcp/sessions.py`
- [Conversation](https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/chat.py): `src/invisible_playwright_mcp/chat.py`
- [Agent loop](https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/agent.py): `src/invisible_playwright_mcp/agent.py`
- [MCP client link](https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/link.py): `src/invisible_playwright_mcp/link.py`

### MCP server

- [MCP server](https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/mcp/server.py): `src/invisible_playwright_mcp/mcp/server.py`
- [Browser work](https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/mcp/work.py): `src/invisible_playwright_mcp/mcp/work.py`
- [Browser actions](https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/mcp/actions.py): `src/invisible_playwright_mcp/mcp/actions.py`
- [Launch planning](https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/mcp/plan.py): `src/invisible_playwright_mcp/mcp/plan.py`
- [Browser identity](https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/mcp/identity.py): `src/invisible_playwright_mcp/mcp/identity.py`
- [Proxy settings](https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/mcp/proxy.py): `src/invisible_playwright_mcp/mcp/proxy.py`

### Browser runtime

- [Browser session](https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/mcp/session.py): `src/invisible_playwright_mcp/mcp/session.py`
- [Engine manager](https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/engine.py): `src/invisible_playwright_mcp/engine.py`
- **Stealth browser**

### Shared services

- [Session storage](https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/storage.py): `src/invisible_playwright_mcp/storage.py`
- [Browser state store](https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/mcp/store.py): `src/invisible_playwright_mcp/mcp/store.py`
- [Chat persistence](https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/chats.py): `src/invisible_playwright_mcp/chats.py`
- [OpenRouter client](https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/llm.py): `src/invisible_playwright_mcp/llm.py`
- [Environment config](https://github.com/feder-cr/invisible_playwright_mcp/blob/main/src/invisible_playwright_mcp/env.py): `src/invisible_playwright_mcp/env.py`

### Other components

- **User**
- **MCP assistant**
- **Model provider**
- **Visited websites**

## Connections

- User → CLI: starts UI or MCP
- MCP assistant → MCP server: uses MCP tools
- User → Web UI: submits instructions
- CLI → HTTP routes: starts web app (evidence: `src/invisible_playwright_mcp/cli.py`)
- HTTP routes → Web UI: serves page (evidence: `src/invisible_playwright_mcp/routes.py`)
- UI interactions → HTTP routes: calls HTTP routes
- HTTP routes → Conversation registry: selects conversation (evidence: `src/invisible_playwright_mcp/routes.py`)
- HTTP routes → Conversation: starts or stops turns (evidence: `src/invisible_playwright_mcp/routes.py`)
- Conversation registry → Conversation: creates conversations (evidence: `src/invisible_playwright_mcp/sessions.py`)
- Conversation registry → MCP client link: spawns server link (evidence: `src/invisible_playwright_mcp/sessions.py`)
- Conversation registry → Chat persistence: loads conversations (evidence: `src/invisible_playwright_mcp/sessions.py`)
- Conversation → Agent loop: runs agent (evidence: `src/invisible_playwright_mcp/chat.py`)
- Conversation → MCP client link: drives browser tools (evidence: `src/invisible_playwright_mcp/chat.py`)
- Agent loop → MCP client link: requests tools (evidence: `src/invisible_playwright_mcp/agent.py`)
- MCP client link → MCP server: connects to server (evidence: `src/invisible_playwright_mcp/link.py`)
- CLI → MCP server: starts server (evidence: `src/invisible_playwright_mcp/cli.py`)
- MCP server → Browser work: dispatches browser work (evidence: `src/invisible_playwright_mcp/mcp/server.py`)
- MCP server → Browser actions: exposes operations (evidence: `src/invisible_playwright_mcp/mcp/server.py`)
- MCP server → Launch planning: uses launch plan (evidence: `src/invisible_playwright_mcp/mcp/server.py`)
- MCP server → Browser state store: uses state store (evidence: `src/invisible_playwright_mcp/mcp/server.py`)
- MCP server → Engine manager: starts engine fetch (evidence: `src/invisible_playwright_mcp/mcp/server.py`)
- Browser work → Browser identity: resolves identity (evidence: `src/invisible_playwright_mcp/mcp/work.py`)
- Browser work → Launch planning: resolves launch settings (evidence: `src/invisible_playwright_mcp/mcp/work.py`)
- Browser work → Browser state store: persists browser state (evidence: `src/invisible_playwright_mcp/mcp/work.py`)
- Browser work → Browser actions: runs operations (evidence: `src/invisible_playwright_mcp/mcp/work.py`)
- Browser work → Browser session: opens browser session (evidence: `src/invisible_playwright_mcp/mcp/work.py`)
- Browser work → Engine manager: checks readiness (evidence: `src/invisible_playwright_mcp/mcp/work.py`)
- Launch planning → Browser identity: uses identity (evidence: `src/invisible_playwright_mcp/mcp/plan.py`)
- Launch planning → Proxy settings: resolves proxy (evidence: `src/invisible_playwright_mcp/mcp/plan.py`)
- Browser actions → Browser session: operates on page (evidence: `src/invisible_playwright_mcp/mcp/actions.py`)
- Browser session → Stealth browser: launches stealth browser (evidence: `src/invisible_playwright_mcp/mcp/session.py`)
- Engine manager → Stealth browser: provides engine binary (evidence: `src/invisible_playwright_mcp/engine.py`)
- Stealth browser → Visited websites: browses pages
- Chat persistence → Session storage: reads and writes chats (evidence: `src/invisible_playwright_mcp/chats.py`)
- Browser state store → Session storage: reads and writes state (evidence: `src/invisible_playwright_mcp/mcp/store.py`)
- CLI → OpenRouter client: configures model client (evidence: `src/invisible_playwright_mcp/cli.py`)
- OpenRouter client → Environment config: resolves model setting (evidence: `src/invisible_playwright_mcp/llm.py`)
- Agent loop → Model provider: requests model responses
- OpenRouter client → Model provider: sends model requests
- Launch planning → Proxy settings: supports optional proxy (evidence: `src/invisible_playwright_mcp/mcp/plan.py`)