# beehiveinnovations/zen-mcp-server architecture

> Architecture diagram of the GitHub repository beehiveinnovations/zen-mcp-server, 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/beehiveinnovations/zen-mcp-server
- Repository: https://github.com/beehiveinnovations/zen-mcp-server

## Overview

PAL MCP is a Model Context Protocol server that lets an AI client invoke specialized coding tools and consult multiple model providers while maintaining conversation context. The primary path is client request → server tool dispatch → simple or guided workflow execution → model response returned through the server; conversation state supports continuity across turns. The README also documents multi-pass review, planning, debugging and other coding workflows, plus clink’s external CLI bridge. Sampled source confirms server dispatch, shared tool/workflow infrastructure, and provider registries; unsampled tool wiring is not expanded.

Main entry points: [`server.py`](https://github.com/beehiveinnovations/zen-mcp-server/blob/main/server.py) (MCP server), [`providers`](https://github.com/beehiveinnovations/zen-mcp-server/tree/main/providers) (Provider adapters), [`tools/clink.py`](https://github.com/beehiveinnovations/zen-mcp-server/blob/main/tools/clink.py) (Clink tool), [`tools/simple/base.py`](https://github.com/beehiveinnovations/zen-mcp-server/blob/main/tools/simple/base.py) (Simple tool runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["MCP entry"]
  node_server["MCP server<br/>[server.py]"]
end

subgraph group_tools["Coding tools"]
  node_simple["Simple tool runtime<br/>[base.py]"]
  node_workflow["Workflow runtime<br/>[workflow_mixin.py]"]
  node_review["Code review<br/>[codereview.py]"]
  node_toolset["Coding workflows"]
  node_prompts["Workflow prompts"]
end

subgraph group_context["Conversation context"]
  node_memory["Conversation memory"]
  node_storage[("Thread storage<br/>[storage_backend.py]")]
end

subgraph group_models["Model access"]
  node_provider_registry["Provider registry<br/>[registry.py]"]
  node_provider_types["Provider adapters"]
  node_model_registry["Model registries"]
  node_model_config["Model capabilities"]
end

subgraph group_bridge["CLI bridge"]
  node_clink_tool["Clink tool<br/>[clink.py]"]
  node_clink_registry["CLI registry<br/>[registry.py]"]
  node_clink_agents["CLI agents"]
end

node_client(("AI client"))
node_model_services(("Model services"))
node_cli_process(("External CLI"))

node_client -->|"requests tools"| node_server
node_server -->|"returns results"| node_client
node_server -->|"dispatches"| node_simple
node_server -->|"dispatches"| node_workflow
node_server -->|"manages turns"| node_memory
node_simple -->|"requests model"| node_provider_registry
node_workflow -->|"reads thread"| node_memory
node_memory -->|"reads and writes"| node_storage
node_provider_registry -->|"selects provider"| node_provider_types
node_provider_types -->|"resolves models"| node_model_registry
node_model_registry -->|"provides capabilities"| node_model_config
node_provider_types -->|"sends requests"| node_model_services
node_model_services -->|"returns responses"| node_provider_types
node_client -->|"invokes bridge"| node_clink_tool
node_clink_tool -->|"loads CLI config"| node_clink_registry
node_clink_tool -->|"launches agent"| node_clink_agents
node_clink_agents -->|"runs CLI"| node_cli_process
node_review -->|"uses workflow runtime"| node_workflow
node_review -->|"uses review prompt"| node_prompts
node_toolset -.->|"includes tools"| node_simple

click node_server "https://github.com/beehiveinnovations/zen-mcp-server/blob/main/server.py"
click node_simple "https://github.com/beehiveinnovations/zen-mcp-server/blob/main/tools/simple/base.py"
click node_workflow "https://github.com/beehiveinnovations/zen-mcp-server/blob/main/tools/workflow/workflow_mixin.py"
click node_review "https://github.com/beehiveinnovations/zen-mcp-server/blob/main/tools/codereview.py"
click node_toolset "https://github.com/beehiveinnovations/zen-mcp-server/tree/main/tools"
click node_prompts "https://github.com/beehiveinnovations/zen-mcp-server/tree/main/systemprompts"
click node_memory "https://github.com/beehiveinnovations/zen-mcp-server/blob/main/utils/conversation_memory.py"
click node_storage "https://github.com/beehiveinnovations/zen-mcp-server/blob/main/utils/storage_backend.py"
click node_provider_registry "https://github.com/beehiveinnovations/zen-mcp-server/blob/main/providers/registry.py"
click node_provider_types "https://github.com/beehiveinnovations/zen-mcp-server/tree/main/providers"
click node_model_registry "https://github.com/beehiveinnovations/zen-mcp-server/tree/main/providers/registries"
click node_model_config "https://github.com/beehiveinnovations/zen-mcp-server/blob/main/providers/shared/model_capabilities.py"
click node_clink_tool "https://github.com/beehiveinnovations/zen-mcp-server/blob/main/tools/clink.py"
click node_clink_registry "https://github.com/beehiveinnovations/zen-mcp-server/blob/main/clink/registry.py"
click node_clink_agents "https://github.com/beehiveinnovations/zen-mcp-server/tree/main/clink/agents"

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_server,node_client toneBlue
class node_simple,node_workflow,node_review,node_toolset,node_prompts toneAmber
class node_memory,node_storage toneMint
class node_provider_registry,node_provider_types,node_model_registry,node_model_config toneRose
class node_clink_tool,node_clink_registry,node_clink_agents,node_model_services,node_cli_process toneIndigo
```

## Components

### MCP entry

- [MCP server](https://github.com/beehiveinnovations/zen-mcp-server/blob/main/server.py): `server.py`

### Coding tools

- [Simple tool runtime](https://github.com/beehiveinnovations/zen-mcp-server/blob/main/tools/simple/base.py): `tools/simple/base.py`
- [Workflow runtime](https://github.com/beehiveinnovations/zen-mcp-server/blob/main/tools/workflow/workflow_mixin.py): `tools/workflow/workflow_mixin.py`
- [Code review](https://github.com/beehiveinnovations/zen-mcp-server/blob/main/tools/codereview.py): `tools/codereview.py`
- [Coding workflows](https://github.com/beehiveinnovations/zen-mcp-server/tree/main/tools): `tools`
- [Workflow prompts](https://github.com/beehiveinnovations/zen-mcp-server/tree/main/systemprompts): `systemprompts`

### Conversation context

- [Conversation memory](https://github.com/beehiveinnovations/zen-mcp-server/blob/main/utils/conversation_memory.py): `utils/conversation_memory.py`
- [Thread storage](https://github.com/beehiveinnovations/zen-mcp-server/blob/main/utils/storage_backend.py): `utils/storage_backend.py`

### Model access

- [Provider registry](https://github.com/beehiveinnovations/zen-mcp-server/blob/main/providers/registry.py): `providers/registry.py`
- [Provider adapters](https://github.com/beehiveinnovations/zen-mcp-server/tree/main/providers): `providers`
- [Model registries](https://github.com/beehiveinnovations/zen-mcp-server/tree/main/providers/registries): `providers/registries`
- [Model capabilities](https://github.com/beehiveinnovations/zen-mcp-server/blob/main/providers/shared/model_capabilities.py): `providers/shared/model_capabilities.py`

### CLI bridge

- [Clink tool](https://github.com/beehiveinnovations/zen-mcp-server/blob/main/tools/clink.py): `tools/clink.py`
- [CLI registry](https://github.com/beehiveinnovations/zen-mcp-server/blob/main/clink/registry.py): `clink/registry.py`
- [CLI agents](https://github.com/beehiveinnovations/zen-mcp-server/tree/main/clink/agents): `clink/agents`

### Other components

- **AI client**
- **Model services**
- **External CLI**

## Connections

- AI client → MCP server: requests tools
- MCP server → AI client: returns results
- MCP server → Simple tool runtime: dispatches
- MCP server → Workflow runtime: dispatches
- MCP server → Conversation memory: manages turns
- Simple tool runtime → Provider registry: requests model
- Workflow runtime → Conversation memory: reads thread
- Conversation memory → Thread storage: reads and writes
- Provider registry → Provider adapters: selects provider
- Provider adapters → Model registries: resolves models
- Model registries → Model capabilities: provides capabilities
- Provider adapters → Model services: sends requests
- Model services → Provider adapters: returns responses
- AI client → Clink tool: invokes bridge
- Clink tool → CLI registry: loads CLI config
- Clink tool → CLI agents: launches agent
- CLI agents → External CLI: runs CLI
- Code review → Workflow runtime: uses workflow runtime
- Code review → Workflow prompts: uses review prompt
- Coding workflows → Simple tool runtime: includes tools