How whshang/herdr-mcp works
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: cli.rs Runtime CLI · server.ts Local MCP server · client.ts Outbound link · mcp-handler.ts MCP edge routing
Components 24
Workstation runtime
- Runtime CLI
crates/herdr-mcp/src/cli.rs - Local MCP server
src/server.ts - Deterministic tools
crates/herdr-mcp/src/fs_tools.rs - Agent jobs
crates/herdr-mcp/src/dev.rs - Exec sessions
crates/herdr-mcp/src/exec_sessions.rs - Herdr runtime
crates/herdr-mcp/src/herdr.rs - Outbound link
src/link/client.ts
Public edge
- MCP edge routing
edge/cloudflare/src/mcp-handler.ts - Relay protocol
src/relay/protocol.ts
Identity and grants
- OAuth authorization
edge/cloudflare/src/oauth-public.ts - Token cryptography
edge/cloudflare/src/oauth-token-crypto.ts - Grant migration
crates/herdr-mcp/src/grant_migration.rs - OAuth records
edge/cloudflare/src/oauth-store-do.ts
Browser workflows
- Browser extension
extension/background.js - Browser control
crates/herdr-mcp/src/browser_control.rs - WebChat orchestration
crates/herdr-mcp/src/cli/webchat.rs
Operations and state
- Runtime configuration
crates/herdr-mcp/src/config.rs - Instance identity
crates/herdr-mcp/src/instance.rs - Runtime link migration
crates/herdr-mcp/src/link/migrate_runtime_control.rs - Link ownership
crates/herdr-mcp/src/link/ownership.rs - Process control
crates/herdr-mcp/src/child_process.rs - Artifact import
crates/herdr-mcp/src/artifact_import.rs
Other components
- Web AI client
- Local coding agent
Connections 24
- Web AI client → OAuth authorization: authorizes connector
README.md - OAuth authorization → Token cryptography: issues tokens
edge/cloudflare/src/oauth-public.ts - OAuth records → Token cryptography: uses token crypto
edge/cloudflare/src/oauth-store-do.ts - Web AI client → MCP edge routing: sends MCP requests
README.md - MCP edge routing → Outbound link: routes device tools
README.md - Outbound link → Relay protocol: encodes relay messages
- Outbound link → Local MCP server: dispatches requests
- Local MCP server → Deterministic tools: executes tools
src/server.ts - Local MCP server → Exec sessions: reads sessions
src/server.ts - Deterministic tools → Herdr runtime: operates workspace
README.md - Local coding agent → Runtime CLI: invokes webchat
README.md - Runtime CLI → WebChat orchestration: dispatches command
crates/herdr-mcp/src/cli.rs - WebChat orchestration → Browser extension: coordinates sessions
README.md - Runtime CLI → Browser control: controls pages
README.md - Runtime CLI → Artifact import: imports artifacts
crates/herdr-mcp/src/cli.rs - Runtime CLI → Agent jobs: dispatches agent work
README.md - Agent jobs → Process control: runs processes
- Runtime CLI → Runtime link migration: manages link runtime
- Runtime link migration → Link ownership: checks ownership
crates/herdr-mcp/src/link/migrate_runtime_control.rs - Runtime CLI → Runtime configuration: loads configuration
crates/herdr-mcp/src/main.rs - Runtime configuration → Instance identity: uses instance identity
crates/herdr-mcp/src/config.rs - MCP edge routing → OAuth records: uses connector grants
- Web AI client → Browser extension: uses optional continuity
README.md - Runtime CLI → Grant migration: migrates grants
crates/herdr-mcp/src/cli.rs