# muwinds/local-tool-bridge architecture

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

- Interactive diagram: https://gitdiagram.com/muwinds/local-tool-bridge
- Repository: https://github.com/muwinds/local-tool-bridge

## Overview

Local Tool Bridge lets ChatGPT or another MCP client invoke tools on the user’s computer, with a desktop control panel for policies, approvals, and audit visibility. The main flow is client → authenticated MCP transport (optionally through the Secure MCP Tunnel) → dispatcher → policy and approval checks → filesystem or shell tools. Direct Remote MCP is a separate optional ingress with its own authentication choices. The graph reflects the README and sampled source; unsampled HTTP, WebSocket, and Direct MCP internals are represented only at the documented subsystem level.

Main entry points: [`src/crates/core/src/dispatch.rs`](https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/core/src/dispatch.rs) (RPC Dispatcher), [`src/crates/host/src/lib.rs`](https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/host/src/lib.rs) (Host Runtime), [`src/crates/gui/src/main.rs`](https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/gui/src/main.rs) (Control Panel), [`src/crates/host/src/direct_mcp.rs`](https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/host/src/direct_mcp.rs) (Direct Remote MCP)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_panel["Control Panel<br/>[main.rs]"]
  node_panel_state["Panel State<br/>[app.rs]"]
  node_approval["Approval Dialog<br/>[approver.rs]"]
end

subgraph group_ingress["Client Ingress"]
  node_host_runtime["Host Runtime<br/>[lib.rs]"]
  node_mcp["Loopback MCP<br/>[mcp.rs]"]
  node_direct_mcp["Direct Remote MCP<br/>[direct_mcp.rs]"]
  node_oauth["OAuth And PKCE<br/>[oauth.rs]"]
  node_tunnel["Secure MCP Tunnel<br/>[tunnel.rs]"]
  node_http_ws["HTTP / WebSocket<br/>[http.rs]"]
  node_websocket["WebSocket Transport<br/>[websocket.rs]"]
end

subgraph group_execution["Tool Execution"]
  node_dispatcher["RPC Dispatcher<br/>[dispatch.rs]"]
  node_registry["Tool Registry<br/>[mod.rs]"]
  node_codex_tools["Codex Tools<br/>[codex.rs]"]
  node_filesystem_tools["Filesystem Tools<br/>[fs.rs]"]
  node_shell_tool["Shell Tool<br/>[shell.rs]"]
end

subgraph group_safety["Policy And Audit"]
  node_policy["Policy Engine<br/>[mod.rs]"]
  node_sandbox["Path Sandbox<br/>[path.rs]"]
  node_audit[("Audit Log<br/>[audit.rs]")]
end

node_user(("Local User"))
node_client(("ChatGPT / MCP Client"))
node_local_files["Local Filesystem"]
node_shell["System Shell"]

node_user -->|"configures"| node_panel
node_panel -->|"starts"| node_host_runtime
node_panel -->|"renders"| node_panel_state
node_panel_state -->|"presents requests"| node_approval
node_approval -->|"answers approval"| node_dispatcher
node_host_runtime -->|"starts"| node_mcp
node_host_runtime -.->|"starts optional"| node_direct_mcp
node_host_runtime -.->|"starts optional"| node_http_ws
node_host_runtime -.->|"starts optional"| node_websocket
node_host_runtime -->|"builds"| node_dispatcher
node_panel -.->|"starts optional"| node_tunnel
node_tunnel -.->|"forwards requests"| node_mcp
node_client -.->|"calls tools"| node_tunnel
node_client -->|"calls tools"| node_mcp
node_client -.->|"calls tools"| node_direct_mcp
node_direct_mcp -.->|"uses optional auth"| node_oauth
node_mcp -->|"dispatches RPC"| node_dispatcher
node_direct_mcp -.->|"dispatches RPC"| node_dispatcher
node_http_ws -.->|"dispatches RPC"| node_dispatcher
node_websocket -.->|"dispatches RPC"| node_dispatcher
node_dispatcher -->|"evaluates calls"| node_policy
node_dispatcher -->|"looks up tools"| node_registry
node_dispatcher -->|"records calls"| node_audit
node_registry -->|"registers"| node_codex_tools
node_codex_tools -->|"delegates file calls"| node_filesystem_tools
node_codex_tools -->|"delegates execution"| node_shell_tool
node_filesystem_tools -->|"resolves paths"| node_sandbox
node_policy -->|"checks confinement"| node_sandbox
node_filesystem_tools -->|"reads and writes"| node_local_files
node_shell_tool -->|"runs commands"| node_shell

click node_panel "https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/gui/src/main.rs"
click node_panel_state "https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/gui/src/app.rs"
click node_approval "https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/gui/src/approver.rs"
click node_host_runtime "https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/host/src/lib.rs"
click node_mcp "https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/host/src/mcp.rs"
click node_direct_mcp "https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/host/src/direct_mcp.rs"
click node_oauth "https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/host/src/oauth.rs"
click node_tunnel "https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/host/src/tunnel.rs"
click node_http_ws "https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/host/src/http.rs"
click node_websocket "https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/host/src/websocket.rs"
click node_dispatcher "https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/core/src/dispatch.rs"
click node_registry "https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/core/src/tools/mod.rs"
click node_codex_tools "https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/core/src/tools/codex.rs"
click node_filesystem_tools "https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/core/src/tools/fs.rs"
click node_shell_tool "https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/core/src/tools/shell.rs"
click node_policy "https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/core/src/policy/mod.rs"
click node_sandbox "https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/core/src/policy/path.rs"
click node_audit "https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/core/src/audit.rs"

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_panel,node_panel_state,node_approval,node_user,node_client toneBlue
class node_host_runtime,node_mcp,node_direct_mcp,node_oauth,node_tunnel,node_http_ws,node_websocket toneAmber
class node_dispatcher,node_registry,node_codex_tools,node_filesystem_tools,node_shell_tool toneMint
class node_policy,node_sandbox,node_audit toneRose
class node_local_files,node_shell toneIndigo
```

## Components

### User Interface

- [Control Panel](https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/gui/src/main.rs): `src/crates/gui/src/main.rs`
- [Panel State](https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/gui/src/app.rs): `src/crates/gui/src/app.rs`
- [Approval Dialog](https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/gui/src/approver.rs): `src/crates/gui/src/approver.rs`

### Client Ingress

- [Host Runtime](https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/host/src/lib.rs): `src/crates/host/src/lib.rs`
- [Loopback MCP](https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/host/src/mcp.rs): `src/crates/host/src/mcp.rs`
- [Direct Remote MCP](https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/host/src/direct_mcp.rs): `src/crates/host/src/direct_mcp.rs`
- [OAuth And PKCE](https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/host/src/oauth.rs): `src/crates/host/src/oauth.rs`
- [Secure MCP Tunnel](https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/host/src/tunnel.rs): `src/crates/host/src/tunnel.rs`
- [HTTP / WebSocket](https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/host/src/http.rs): `src/crates/host/src/http.rs`
- [WebSocket Transport](https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/host/src/websocket.rs): `src/crates/host/src/websocket.rs`

### Tool Execution

- [RPC Dispatcher](https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/core/src/dispatch.rs): `src/crates/core/src/dispatch.rs`
- [Tool Registry](https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/core/src/tools/mod.rs): `src/crates/core/src/tools/mod.rs`
- [Codex Tools](https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/core/src/tools/codex.rs): `src/crates/core/src/tools/codex.rs`
- [Filesystem Tools](https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/core/src/tools/fs.rs): `src/crates/core/src/tools/fs.rs`
- [Shell Tool](https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/core/src/tools/shell.rs): `src/crates/core/src/tools/shell.rs`

### Policy And Audit

- [Policy Engine](https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/core/src/policy/mod.rs): `src/crates/core/src/policy/mod.rs`
- [Path Sandbox](https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/core/src/policy/path.rs): `src/crates/core/src/policy/path.rs`
- [Audit Log](https://github.com/muwinds/local-tool-bridge/blob/master/src/crates/core/src/audit.rs): `src/crates/core/src/audit.rs`

### Other components

- **Local User**
- **ChatGPT / MCP Client**
- **Local Filesystem**
- **System Shell**

## Connections

- Local User → Control Panel: configures
- Control Panel → Host Runtime: starts
- Control Panel → Panel State: renders
- Panel State → Approval Dialog: presents requests
- Approval Dialog → RPC Dispatcher: answers approval
- Host Runtime → Loopback MCP: starts
- Host Runtime → Direct Remote MCP: starts optional
- Host Runtime → HTTP / WebSocket: starts optional
- Host Runtime → WebSocket Transport: starts optional
- Host Runtime → RPC Dispatcher: builds
- Control Panel → Secure MCP Tunnel: starts optional
- Secure MCP Tunnel → Loopback MCP: forwards requests
- ChatGPT / MCP Client → Secure MCP Tunnel: calls tools
- ChatGPT / MCP Client → Loopback MCP: calls tools
- ChatGPT / MCP Client → Direct Remote MCP: calls tools
- Direct Remote MCP → OAuth And PKCE: uses optional auth
- Loopback MCP → RPC Dispatcher: dispatches RPC
- Direct Remote MCP → RPC Dispatcher: dispatches RPC
- HTTP / WebSocket → RPC Dispatcher: dispatches RPC
- WebSocket Transport → RPC Dispatcher: dispatches RPC
- RPC Dispatcher → Policy Engine: evaluates calls
- RPC Dispatcher → Tool Registry: looks up tools
- RPC Dispatcher → Audit Log: records calls
- Tool Registry → Codex Tools: registers
- Codex Tools → Filesystem Tools: delegates file calls
- Codex Tools → Shell Tool: delegates execution
- Filesystem Tools → Path Sandbox: resolves paths
- Policy Engine → Path Sandbox: checks confinement
- Filesystem Tools → Local Filesystem: reads and writes
- Shell Tool → System Shell: runs commands