# weavetab/mcp architecture

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

- Interactive diagram: https://gitdiagram.com/weavetab/mcp
- Repository: https://github.com/weavetab/mcp

## Overview

Weavetab is a local MCP automation engine for AI agents controlling Chromium and Electron applications. Its main workflow accepts an MCP tool request, applies security/session handling, connects to a local CDP target, runs a browser or desktop action, and returns a compact semantic view or action result. The map includes documented capabilities such as delta reads, plugins, CAPTCHA solving, and credential protection. Some subsystems are represented at their exact enclosing directories because their implementation files were not excerpted; uncertain internal wiring is omitted.

Main entry points: [`src/server.ts`](https://github.com/weavetab/mcp/blob/main/src/server.ts) (MCP tool server), [`src/cdp/connector.ts`](https://github.com/weavetab/mcp/blob/main/src/cdp/connector.ts) (CDP connector), [`src/tools/read.ts`](https://github.com/weavetab/mcp/blob/main/src/tools/read.ts) (Semantic map), [`src/config/loader.ts`](https://github.com/weavetab/mcp/blob/main/src/config/loader.ts) (Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["MCP entry"]
  node_index["CLI startup<br/>[index.ts]"]
  node_server["MCP tool server<br/>[server.ts]"]
end

subgraph group_runtime["Automation runtime"]
  node_connector["CDP connector<br/>[connector.ts]"]
  node_desktop["Desktop discovery<br/>[discovery.ts]"]
  node_tools["Browser tool suite"]
  node_click["Click interaction<br/>[click.ts]"]
  node_fill["Fill and type<br/>[fill.ts]"]
  node_captcha["CAPTCHA solving"]
end

subgraph group_intelligence["Page intelligence"]
  node_walker["Semantic page walker<br/>[walker.ts]"]
  node_map["Semantic map<br/>[read.ts]"]
  node_delta[("Snapshot deltas<br/>[delta.ts]")]
end

subgraph group_extensions["Extensions"]
  node_plugins["Plugin system"]
  node_hooks["Plugin hook pipeline<br/>[pipeline.ts]"]
end

subgraph group_support["Security and state"]
  node_security["Request security<br/>[guard.ts]"]
  node_config["Configuration<br/>[loader.ts]"]
  node_session[("Session registry<br/>[session.ts]")]
  node_audit["Audit logging<br/>[logger.ts]"]
  node_secrets["Credential protection<br/>[secrets.ts]"]
end

node_agent(("AI agent"))
node_target(("Chromium or Electron"))

node_agent -->|"sends tool requests"| node_server
node_index -->|"starts"| node_server
node_server -->|"checks requests"| node_security
node_server -->|"connects target"| node_connector
node_server -->|"dispatches tools"| node_tools
node_server -->|"runs map"| node_map
node_server -->|"tracks sessions"| node_session
node_connector -->|"opens CDP socket"| node_target
node_connector -->|"discovers apps"| node_desktop
node_connector -->|"registers targets"| node_session
node_target -->|"provides page state"| node_walker
node_map -->|"builds semantic map"| node_walker
node_map -->|"computes reread delta"| node_delta
node_click -->|"dispatches interaction"| node_target
node_fill -->|"enters text"| node_target
node_captcha -->|"simulates mouse behavior"| node_target
node_server -.->|"dispatches capability"| node_captcha
node_server -.->|"loads extensions"| node_plugins
node_plugins -->|"dispatches lifecycle hooks"| node_hooks
node_server -->|"uses configuration"| node_config
node_connector -->|"reads target settings"| node_config
node_server -->|"records actions"| node_audit
node_fill -->|"protects credentials"| node_secrets
node_config -->|"logs diagnostics"| node_audit

click node_index "https://github.com/weavetab/mcp/blob/main/src/index.ts"
click node_server "https://github.com/weavetab/mcp/blob/main/src/server.ts"
click node_security "https://github.com/weavetab/mcp/blob/main/src/security/guard.ts"
click node_config "https://github.com/weavetab/mcp/blob/main/src/config/loader.ts"
click node_connector "https://github.com/weavetab/mcp/blob/main/src/cdp/connector.ts"
click node_desktop "https://github.com/weavetab/mcp/blob/main/src/desktop/discovery.ts"
click node_session "https://github.com/weavetab/mcp/blob/main/src/state/session.ts"
click node_tools "https://github.com/weavetab/mcp/tree/main/src/tools"
click node_click "https://github.com/weavetab/mcp/blob/main/src/tools/click.ts"
click node_fill "https://github.com/weavetab/mcp/blob/main/src/tools/fill.ts"
click node_walker "https://github.com/weavetab/mcp/blob/main/src/cdp/walker.ts"
click node_map "https://github.com/weavetab/mcp/blob/main/src/tools/read.ts"
click node_delta "https://github.com/weavetab/mcp/blob/main/src/state/delta.ts"
click node_captcha "https://github.com/weavetab/mcp/tree/main/src/anticaptcha"
click node_plugins "https://github.com/weavetab/mcp/tree/main/src/plugin"
click node_hooks "https://github.com/weavetab/mcp/blob/main/src/plugin/pipeline.ts"
click node_audit "https://github.com/weavetab/mcp/blob/main/src/audit/logger.ts"
click node_secrets "https://github.com/weavetab/mcp/blob/main/src/security/secrets.ts"

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_index,node_server toneBlue
class node_connector,node_desktop,node_tools,node_click,node_fill,node_captcha toneAmber
class node_walker,node_map,node_delta toneMint
class node_plugins,node_hooks toneRose
class node_security,node_config,node_session,node_audit,node_secrets,node_agent,node_target toneIndigo
```

## Components

### MCP entry

- [CLI startup](https://github.com/weavetab/mcp/blob/main/src/index.ts): `src/index.ts`
- [MCP tool server](https://github.com/weavetab/mcp/blob/main/src/server.ts): `src/server.ts`

### Automation runtime

- [CDP connector](https://github.com/weavetab/mcp/blob/main/src/cdp/connector.ts): `src/cdp/connector.ts`
- [Desktop discovery](https://github.com/weavetab/mcp/blob/main/src/desktop/discovery.ts): `src/desktop/discovery.ts`
- [Browser tool suite](https://github.com/weavetab/mcp/tree/main/src/tools): `src/tools`
- [Click interaction](https://github.com/weavetab/mcp/blob/main/src/tools/click.ts): `src/tools/click.ts`
- [Fill and type](https://github.com/weavetab/mcp/blob/main/src/tools/fill.ts): `src/tools/fill.ts`
- [CAPTCHA solving](https://github.com/weavetab/mcp/tree/main/src/anticaptcha): `src/anticaptcha`

### Page intelligence

- [Semantic page walker](https://github.com/weavetab/mcp/blob/main/src/cdp/walker.ts): `src/cdp/walker.ts`
- [Semantic map](https://github.com/weavetab/mcp/blob/main/src/tools/read.ts): `src/tools/read.ts`
- [Snapshot deltas](https://github.com/weavetab/mcp/blob/main/src/state/delta.ts): `src/state/delta.ts`

### Extensions

- [Plugin system](https://github.com/weavetab/mcp/tree/main/src/plugin): `src/plugin`
- [Plugin hook pipeline](https://github.com/weavetab/mcp/blob/main/src/plugin/pipeline.ts): `src/plugin/pipeline.ts`

### Security and state

- [Request security](https://github.com/weavetab/mcp/blob/main/src/security/guard.ts): `src/security/guard.ts`
- [Configuration](https://github.com/weavetab/mcp/blob/main/src/config/loader.ts): `src/config/loader.ts`
- [Session registry](https://github.com/weavetab/mcp/blob/main/src/state/session.ts): `src/state/session.ts`
- [Audit logging](https://github.com/weavetab/mcp/blob/main/src/audit/logger.ts): `src/audit/logger.ts`
- [Credential protection](https://github.com/weavetab/mcp/blob/main/src/security/secrets.ts): `src/security/secrets.ts`

### Other components

- **AI agent**
- **Chromium or Electron**

## Connections

- AI agent → MCP tool server: sends tool requests (evidence: `README.md`)
- CLI startup → MCP tool server: starts (evidence: `src/index.ts`)
- MCP tool server → Request security: checks requests (evidence: `README.md`)
- MCP tool server → CDP connector: connects target (evidence: `src/server.ts`)
- MCP tool server → Browser tool suite: dispatches tools (evidence: `src/server.ts`)
- MCP tool server → Semantic map: runs map (evidence: `src/server.ts`)
- MCP tool server → Session registry: tracks sessions (evidence: `src/server.ts`)
- CDP connector → Chromium or Electron: opens CDP socket (evidence: `README.md`)
- CDP connector → Desktop discovery: discovers apps (evidence: `src/cdp/connector.ts`)
- CDP connector → Session registry: registers targets (evidence: `README.md`)
- Chromium or Electron → Semantic page walker: provides page state (evidence: `README.md`)
- Semantic map → Semantic page walker: builds semantic map (evidence: `README.md`)
- Semantic map → Snapshot deltas: computes reread delta (evidence: `src/state/delta.ts`)
- Click interaction → Chromium or Electron: dispatches interaction (evidence: `README.md`)
- Fill and type → Chromium or Electron: enters text (evidence: `README.md`)
- CAPTCHA solving → Chromium or Electron: simulates mouse behavior (evidence: `README.md`)
- MCP tool server → CAPTCHA solving: dispatches capability
- MCP tool server → Plugin system: loads extensions
- Plugin system → Plugin hook pipeline: dispatches lifecycle hooks (evidence: `src/plugin/pipeline.ts`)
- MCP tool server → Configuration: uses configuration (evidence: `src/server.ts`)
- CDP connector → Configuration: reads target settings (evidence: `src/cdp/connector.ts`)
- MCP tool server → Audit logging: records actions (evidence: `README.md`)
- Fill and type → Credential protection: protects credentials (evidence: `README.md`)
- Configuration → Audit logging: logs diagnostics (evidence: `src/config/loader.ts`)
