# whshang/herdr-mcp architecture

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

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

## Overview

Herdr-MCP connects Web AI clients to persistent development workstations through an authenticated public MCP edge and an outbound workstation link. The principal flow is connector authorization, MCP tool/device routing, local deterministic or agent-assisted work, and result delivery with explicit mutation-delivery semantics. The README also documents optional browser/WebChat orchestration and signed self-updates. Edges reflect README statements or visible source-index references; unsampled subsystems are included where documented, without guessing internal calls.

Main entry points: [`crates/herdr-mcp/src/cli.rs`](https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/cli.rs) (Runtime CLI), [`src/server.ts`](https://github.com/whshang/herdr-mcp/blob/main/src/server.ts) (Local MCP server), [`src/link/client.ts`](https://github.com/whshang/herdr-mcp/blob/main/src/link/client.ts) (Outbound link), [`edge/cloudflare/src/mcp-handler.ts`](https://github.com/whshang/herdr-mcp/blob/main/edge/cloudflare/src/mcp-handler.ts) (MCP edge routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_local["Workstation runtime"]
  node_rustcli["Runtime CLI<br/>[cli.rs]"]
  node_mcpserver["Local MCP server<br/>[server.ts]"]
  node_mcp_tools["Deterministic tools<br/>[fs_tools.rs]"]
  node_agent_jobs["Agent jobs<br/>[dev.rs]"]
  node_exec_sessions["Exec sessions<br/>[exec_sessions.rs]"]
  node_herdr_runtime["Herdr runtime<br/>[herdr.rs]"]
  node_workstation_link["Outbound link<br/>[client.ts]"]
end

subgraph group_edge["Public edge"]
  node_edge_mcp["MCP edge routing<br/>[mcp-handler.ts]"]
  node_relay_protocol["Relay protocol<br/>[protocol.ts]"]
end

subgraph group_identity["Identity and grants"]
  node_oauth_public["OAuth authorization<br/>[oauth-public.ts]"]
  node_oauth_crypto["Token cryptography"]
  node_grant_migration["Grant migration<br/>[grant_migration.rs]"]
  node_oauth_store[("OAuth records<br/>[oauth-store-do.ts]")]
end

subgraph group_browser["Browser workflows"]
  node_extension["Browser extension<br/>[background.js]"]
  node_browser_control["Browser control<br/>[browser_control.rs]"]
  node_webchat["WebChat orchestration<br/>[webchat.rs]"]
end

subgraph group_operations["Operations and state"]
  node_config["Runtime configuration<br/>[config.rs]"]
  node_instance["Instance identity<br/>[instance.rs]"]
  node_link_migration["Runtime link migration"]
  node_link_ownership["Link ownership<br/>[ownership.rs]"]
  node_child_process["Process control<br/>[child_process.rs]"]
  node_artifact_import["Artifact import<br/>[artifact_import.rs]"]
end

node_webai(("Web AI client"))
node_localagent(("Local coding agent"))

node_webai -->|"authorizes connector"| node_oauth_public
node_oauth_public -->|"issues tokens"| node_oauth_crypto
node_oauth_store -->|"uses token crypto"| node_oauth_crypto
node_webai -->|"sends MCP requests"| node_edge_mcp
node_edge_mcp -->|"routes device tools"| node_workstation_link
node_workstation_link -.->|"encodes relay messages"| node_relay_protocol
node_workstation_link -.->|"dispatches requests"| node_mcpserver
node_mcpserver -->|"executes tools"| node_mcp_tools
node_mcpserver -->|"reads sessions"| node_exec_sessions
node_mcp_tools -->|"operates workspace"| node_herdr_runtime
node_localagent -->|"invokes webchat"| node_rustcli
node_rustcli -->|"dispatches command"| node_webchat
node_webchat -->|"coordinates sessions"| node_extension
node_rustcli -->|"controls pages"| node_browser_control
node_rustcli -.->|"imports artifacts"| node_artifact_import
node_rustcli -->|"dispatches agent work"| node_agent_jobs
node_agent_jobs -.->|"runs processes"| node_child_process
node_rustcli -->|"manages link runtime"| node_link_migration
node_link_migration -->|"checks ownership"| node_link_ownership
node_rustcli -->|"loads configuration"| node_config
node_config -->|"uses instance identity"| node_instance
node_edge_mcp -.->|"uses connector grants"| node_oauth_store
node_webai -.->|"uses optional continuity"| node_extension
node_rustcli -.->|"migrates grants"| node_grant_migration

click node_rustcli "https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/cli.rs"
click node_mcpserver "https://github.com/whshang/herdr-mcp/blob/main/src/server.ts"
click node_mcp_tools "https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/fs_tools.rs"
click node_agent_jobs "https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/dev.rs"
click node_exec_sessions "https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/exec_sessions.rs"
click node_herdr_runtime "https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/herdr.rs"
click node_workstation_link "https://github.com/whshang/herdr-mcp/blob/main/src/link/client.ts"
click node_edge_mcp "https://github.com/whshang/herdr-mcp/blob/main/edge/cloudflare/src/mcp-handler.ts"
click node_relay_protocol "https://github.com/whshang/herdr-mcp/blob/main/src/relay/protocol.ts"
click node_oauth_public "https://github.com/whshang/herdr-mcp/blob/main/edge/cloudflare/src/oauth-public.ts"
click node_oauth_crypto "https://github.com/whshang/herdr-mcp/blob/main/edge/cloudflare/src/oauth-token-crypto.ts"
click node_grant_migration "https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/grant_migration.rs"
click node_extension "https://github.com/whshang/herdr-mcp/blob/main/extension/background.js"
click node_browser_control "https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/browser_control.rs"
click node_webchat "https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/cli/webchat.rs"
click node_config "https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/config.rs"
click node_instance "https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/instance.rs"
click node_link_migration "https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/link/migrate_runtime_control.rs"
click node_link_ownership "https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/link/ownership.rs"
click node_child_process "https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/child_process.rs"
click node_artifact_import "https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/artifact_import.rs"
click node_oauth_store "https://github.com/whshang/herdr-mcp/blob/main/edge/cloudflare/src/oauth-store-do.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_rustcli,node_mcpserver,node_mcp_tools,node_agent_jobs,node_exec_sessions,node_herdr_runtime,node_workstation_link,node_webai toneBlue
class node_edge_mcp,node_relay_protocol toneAmber
class node_oauth_public,node_oauth_crypto,node_grant_migration,node_oauth_store toneMint
class node_extension,node_browser_control,node_webchat toneRose
class node_config,node_instance,node_link_migration,node_link_ownership,node_child_process,node_artifact_import,node_localagent toneIndigo
```

## Components

### Workstation runtime

- [Runtime CLI](https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/cli.rs): `crates/herdr-mcp/src/cli.rs`
- [Local MCP server](https://github.com/whshang/herdr-mcp/blob/main/src/server.ts): `src/server.ts`
- [Deterministic tools](https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/fs_tools.rs): `crates/herdr-mcp/src/fs_tools.rs`
- [Agent jobs](https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/dev.rs): `crates/herdr-mcp/src/dev.rs`
- [Exec sessions](https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/exec_sessions.rs): `crates/herdr-mcp/src/exec_sessions.rs`
- [Herdr runtime](https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/herdr.rs): `crates/herdr-mcp/src/herdr.rs`
- [Outbound link](https://github.com/whshang/herdr-mcp/blob/main/src/link/client.ts): `src/link/client.ts`

### Public edge

- [MCP edge routing](https://github.com/whshang/herdr-mcp/blob/main/edge/cloudflare/src/mcp-handler.ts): `edge/cloudflare/src/mcp-handler.ts`
- [Relay protocol](https://github.com/whshang/herdr-mcp/blob/main/src/relay/protocol.ts): `src/relay/protocol.ts`

### Identity and grants

- [OAuth authorization](https://github.com/whshang/herdr-mcp/blob/main/edge/cloudflare/src/oauth-public.ts): `edge/cloudflare/src/oauth-public.ts`
- [Token cryptography](https://github.com/whshang/herdr-mcp/blob/main/edge/cloudflare/src/oauth-token-crypto.ts): `edge/cloudflare/src/oauth-token-crypto.ts`
- [Grant migration](https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/grant_migration.rs): `crates/herdr-mcp/src/grant_migration.rs`
- [OAuth records](https://github.com/whshang/herdr-mcp/blob/main/edge/cloudflare/src/oauth-store-do.ts): `edge/cloudflare/src/oauth-store-do.ts`

### Browser workflows

- [Browser extension](https://github.com/whshang/herdr-mcp/blob/main/extension/background.js): `extension/background.js`
- [Browser control](https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/browser_control.rs): `crates/herdr-mcp/src/browser_control.rs`
- [WebChat orchestration](https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/cli/webchat.rs): `crates/herdr-mcp/src/cli/webchat.rs`

### Operations and state

- [Runtime configuration](https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/config.rs): `crates/herdr-mcp/src/config.rs`
- [Instance identity](https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/instance.rs): `crates/herdr-mcp/src/instance.rs`
- [Runtime link migration](https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/link/migrate_runtime_control.rs): `crates/herdr-mcp/src/link/migrate_runtime_control.rs`
- [Link ownership](https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/link/ownership.rs): `crates/herdr-mcp/src/link/ownership.rs`
- [Process control](https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/child_process.rs): `crates/herdr-mcp/src/child_process.rs`
- [Artifact import](https://github.com/whshang/herdr-mcp/blob/main/crates/herdr-mcp/src/artifact_import.rs): `crates/herdr-mcp/src/artifact_import.rs`

### Other components

- **Web AI client**
- **Local coding agent**

## Connections

- Web AI client → OAuth authorization: authorizes connector (evidence: `README.md`)
- OAuth authorization → Token cryptography: issues tokens (evidence: `edge/cloudflare/src/oauth-public.ts`)
- OAuth records → Token cryptography: uses token crypto (evidence: `edge/cloudflare/src/oauth-store-do.ts`)
- Web AI client → MCP edge routing: sends MCP requests (evidence: `README.md`)
- MCP edge routing → Outbound link: routes device tools (evidence: `README.md`)
- Outbound link → Relay protocol: encodes relay messages
- Outbound link → Local MCP server: dispatches requests
- Local MCP server → Deterministic tools: executes tools (evidence: `src/server.ts`)
- Local MCP server → Exec sessions: reads sessions (evidence: `src/server.ts`)
- Deterministic tools → Herdr runtime: operates workspace (evidence: `README.md`)
- Local coding agent → Runtime CLI: invokes webchat (evidence: `README.md`)
- Runtime CLI → WebChat orchestration: dispatches command (evidence: `crates/herdr-mcp/src/cli.rs`)
- WebChat orchestration → Browser extension: coordinates sessions (evidence: `README.md`)
- Runtime CLI → Browser control: controls pages (evidence: `README.md`)
- Runtime CLI → Artifact import: imports artifacts (evidence: `crates/herdr-mcp/src/cli.rs`)
- Runtime CLI → Agent jobs: dispatches agent work (evidence: `README.md`)
- Agent jobs → Process control: runs processes
- Runtime CLI → Runtime link migration: manages link runtime
- Runtime link migration → Link ownership: checks ownership (evidence: `crates/herdr-mcp/src/link/migrate_runtime_control.rs`)
- Runtime CLI → Runtime configuration: loads configuration (evidence: `crates/herdr-mcp/src/main.rs`)
- Runtime configuration → Instance identity: uses instance identity (evidence: `crates/herdr-mcp/src/config.rs`)
- MCP edge routing → OAuth records: uses connector grants
- Web AI client → Browser extension: uses optional continuity (evidence: `README.md`)
- Runtime CLI → Grant migration: migrates grants (evidence: `crates/herdr-mcp/src/cli.rs`)