# activeing123/mcptoon architecture

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

- Interactive diagram: https://gitdiagram.com/activeing123/mcptoon
- Repository: https://github.com/activeing123/mcptoon

## Overview

mcptoon is a local-first MCP and skills hub for agent workflows. A user invokes its CLI to discover installed servers, find tools, and call them; it can also expose configured tools through an MCP gateway, compress schemas for on-demand retrieval, and synchronize servers and skills across agents. The map includes documented OpenAPI/GraphQL, OAuth, resources/prompts, sandbox, and token-usage capabilities. The README establishes these product branches; source excerpts and the index support several internal relationships, but unsampled implementation details are not inferred as call edges.

Main entry points: [`src/mcptoon/serve.py`](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/serve.py) (MCP gateway), [`src/mcptoon/cli.py`](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/cli.py) (Command interface), [`src/mcptoon/sync.py`](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/sync.py) (Agent sync), [`src/mcptoon/compressor.py`](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/compressor.py) (Schema compression)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and configuration"]
  node_cli["Command interface<br/>[cli.py]"]
  node_config["Local configuration<br/>[config.py]"]
  node_discovery["Server discovery<br/>[discover.py]"]
  node_installation["Tool installation<br/>[installer.py]"]
end

subgraph group_gateway["MCP gateway"]
  node_gateway["MCP gateway<br/>[serve.py]"]
  node_routing["Tool routing<br/>[router.py]"]
  node_client["MCP client<br/>[client.py]"]
  node_manifest["Tool manifest<br/>[manifest.py]"]
  node_native["Native tools<br/>[native_tools.py]"]
  node_protocol["Resources and prompts<br/>[mcp_extras.py]"]
  node_openapi["OpenAPI passthrough<br/>[openapi.py]"]
  node_graphql["GraphQL passthrough<br/>[graphql.py]"]
  node_oauth["OAuth<br/>[oauth.py]"]
  node_sandbox["Code sandbox<br/>[exec_sandbox.py]"]
end

subgraph group_agents["Agents and skills"]
  node_sync["Agent sync<br/>[sync.py]"]
  node_skills["Skills catalog<br/>[skills.py]"]
  node_plugin["Agent plugin<br/>[plugin.py]"]
end

subgraph group_efficiency["Context and usage"]
  node_compressor["Schema compression<br/>[compressor.py]"]
  node_simplifier["Schema simplifier"]
  node_toon["TOON encoding<br/>[encoders.py]"]
  node_cache[("Tool cache<br/>[cache.py]")]
  node_usage[("Usage tracking<br/>[usage.py]")]
  node_session[("Session history<br/>[session_log.py]")]
end

node_user(("Agent user"))
node_external{{"MCP servers"}}
node_agentsystem{{"Agent clients"}}

node_user -->|"runs commands"| node_cli
node_cli -->|"discovers tools"| node_discovery
node_cli -->|"installs tools"| node_installation
node_cli -.->|"starts gateway"| node_gateway
node_discovery -->|"scans installed"| node_external
node_cli -->|"calls tools"| node_routing
node_routing -->|"dispatches calls"| node_client
node_client -.->|"sends MCP requests"| node_external
node_gateway -->|"indexes tools"| node_manifest
node_gateway -->|"dispatches tools"| node_routing
node_gateway -->|"exposes native tools"| node_native
node_gateway -->|"serves skill prompts"| node_plugin
node_gateway -->|"uses cached schemas"| node_cache
node_gateway -->|"records usage"| node_usage
node_cli -->|"syncs clients"| node_sync
node_sync -->|"configures clients"| node_agentsystem
node_cli -->|"manages skills"| node_skills
node_skills -->|"shares skills"| node_agentsystem
node_cli -->|"compresses schemas"| node_compressor
node_compressor -->|"simplifies schemas"| node_simplifier
node_simplifier -->|"uses token estimates"| node_usage
node_compressor -.->|"reads cached tools"| node_cache
node_cli -.->|"formats compact output"| node_toon
node_cli -->|"reports savings"| node_usage
node_gateway -.->|"logs tool activity"| node_session
node_gateway -.->|"supports passthrough"| node_openapi
node_gateway -.->|"supports passthrough"| node_graphql
node_gateway -.->|"supports authorization"| node_oauth
node_gateway -.->|"supports execution"| node_sandbox
node_gateway -.->|"supports resources"| node_protocol
node_installation -->|"updates configuration"| node_config
node_sync -->|"reads settings"| node_config

click node_cli "https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/cli.py"
click node_config "https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/config.py"
click node_discovery "https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/discover.py"
click node_installation "https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/installer.py"
click node_gateway "https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/serve.py"
click node_routing "https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/router.py"
click node_client "https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/client.py"
click node_manifest "https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/manifest.py"
click node_native "https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/native_tools.py"
click node_protocol "https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/mcp_extras.py"
click node_openapi "https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/openapi.py"
click node_graphql "https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/graphql.py"
click node_oauth "https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/oauth.py"
click node_sandbox "https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/exec_sandbox.py"
click node_sync "https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/sync.py"
click node_skills "https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/skills.py"
click node_plugin "https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/plugin.py"
click node_compressor "https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/compressor.py"
click node_simplifier "https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/schema_simplifier.py"
click node_toon "https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/_toon/encoders.py"
click node_cache "https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/cache.py"
click node_usage "https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/usage.py"
click node_session "https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/session_log.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_config,node_discovery,node_installation,node_user,node_agentsystem toneBlue
class node_gateway,node_routing,node_client,node_manifest,node_native,node_protocol,node_openapi,node_graphql,node_oauth,node_sandbox toneAmber
class node_sync,node_skills,node_plugin,node_external toneMint
class node_compressor,node_simplifier,node_toon,node_cache,node_usage,node_session toneRose
```

## Components

### CLI and configuration

- [Command interface](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/cli.py): `src/mcptoon/cli.py`
- [Local configuration](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/config.py): `src/mcptoon/config.py`
- [Server discovery](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/discover.py): `src/mcptoon/discover.py`
- [Tool installation](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/installer.py): `src/mcptoon/installer.py`

### MCP gateway

- [MCP gateway](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/serve.py): `src/mcptoon/serve.py`
- [Tool routing](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/router.py): `src/mcptoon/router.py`
- [MCP client](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/client.py): `src/mcptoon/client.py`
- [Tool manifest](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/manifest.py): `src/mcptoon/manifest.py`
- [Native tools](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/native_tools.py): `src/mcptoon/native_tools.py`
- [Resources and prompts](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/mcp_extras.py): `src/mcptoon/mcp_extras.py`
- [OpenAPI passthrough](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/openapi.py): `src/mcptoon/openapi.py`
- [GraphQL passthrough](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/graphql.py): `src/mcptoon/graphql.py`
- [OAuth](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/oauth.py): `src/mcptoon/oauth.py`
- [Code sandbox](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/exec_sandbox.py): `src/mcptoon/exec_sandbox.py`

### Agents and skills

- [Agent sync](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/sync.py): `src/mcptoon/sync.py`
- [Skills catalog](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/skills.py): `src/mcptoon/skills.py`
- [Agent plugin](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/plugin.py): `src/mcptoon/plugin.py`

### Context and usage

- [Schema compression](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/compressor.py): `src/mcptoon/compressor.py`
- [Schema simplifier](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/schema_simplifier.py): `src/mcptoon/schema_simplifier.py`
- [TOON encoding](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/_toon/encoders.py): `src/mcptoon/_toon/encoders.py`
- [Tool cache](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/cache.py): `src/mcptoon/cache.py`
- [Usage tracking](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/usage.py): `src/mcptoon/usage.py`
- [Session history](https://github.com/activeing123/mcptoon/blob/main/src/mcptoon/session_log.py): `src/mcptoon/session_log.py`

### Other components

- **Agent user**
- **MCP servers**
- **Agent clients**

## Connections

- Agent user → Command interface: runs commands (evidence: `README.md`)
- Command interface → Server discovery: discovers tools (evidence: `README.md`)
- Command interface → Tool installation: installs tools (evidence: `README.md`)
- Command interface → MCP gateway: starts gateway (evidence: `src/mcptoon/cli.py`)
- Server discovery → MCP servers: scans installed (evidence: `README.md`)
- Command interface → Tool routing: calls tools (evidence: `README.md`)
- Tool routing → MCP client: dispatches calls (evidence: `src/mcptoon/router.py`)
- MCP client → MCP servers: sends MCP requests
- MCP gateway → Tool manifest: indexes tools (evidence: `src/mcptoon/serve.py`)
- MCP gateway → Tool routing: dispatches tools (evidence: `src/mcptoon/serve.py`)
- MCP gateway → Native tools: exposes native tools (evidence: `src/mcptoon/serve.py`)
- MCP gateway → Agent plugin: serves skill prompts (evidence: `src/mcptoon/serve.py`)
- MCP gateway → Tool cache: uses cached schemas (evidence: `src/mcptoon/serve.py`)
- MCP gateway → Usage tracking: records usage (evidence: `src/mcptoon/serve.py`)
- Command interface → Agent sync: syncs clients (evidence: `README.md`)
- Agent sync → Agent clients: configures clients (evidence: `README.md`)
- Command interface → Skills catalog: manages skills (evidence: `README.md`)
- Skills catalog → Agent clients: shares skills (evidence: `README.md`)
- Command interface → Schema compression: compresses schemas (evidence: `README.md`)
- Schema compression → Schema simplifier: simplifies schemas (evidence: `src/mcptoon/compressor.py`)
- Schema simplifier → Usage tracking: uses token estimates (evidence: `src/mcptoon/schema_simplifier.py`)
- Schema compression → Tool cache: reads cached tools
- Command interface → TOON encoding: formats compact output
- Command interface → Usage tracking: reports savings (evidence: `src/mcptoon/cli.py`)
- MCP gateway → Session history: logs tool activity (evidence: `src/mcptoon/serve.py`)
- MCP gateway → OpenAPI passthrough: supports passthrough (evidence: `README.md`)
- MCP gateway → GraphQL passthrough: supports passthrough (evidence: `README.md`)
- MCP gateway → OAuth: supports authorization (evidence: `README.md`)
- MCP gateway → Code sandbox: supports execution (evidence: `README.md`)
- MCP gateway → Resources and prompts: supports resources (evidence: `README.md`)
- Tool installation → Local configuration: updates configuration (evidence: `src/mcptoon/installer.py`)
- Agent sync → Local configuration: reads settings (evidence: `src/mcptoon/sync.py`)