# beehiveinnovations/pal-mcp-server architecture

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

## Overview

PAL MCP is an MCP server that lets a CLI or IDE client invoke specialized AI tools, retain conversation context, and use multiple model providers. The main path is client request → server dispatch and model resolution → simple or guided workflow tool → provider response → MCP result. Workflow tools support distinct activities such as code review, debugging, planning, and validation; the separate clink bridge launches external AI CLIs. The README documents broader capabilities than the sampled implementation excerpts, so uncertain internal wiring is omitted.

Main entry points: [`server.py`](https://github.com/beehiveinnovations/pal-mcp-server/blob/main/server.py) (Tool registry), [`tools/workflow/workflow_mixin.py`](https://github.com/beehiveinnovations/pal-mcp-server/blob/main/tools/workflow/workflow_mixin.py) (Workflow tools), [`providers`](https://github.com/beehiveinnovations/pal-mcp-server/tree/main/providers) (Provider adapters), [`tools/clink.py`](https://github.com/beehiveinnovations/pal-mcp-server/blob/main/tools/clink.py) (Clink tool)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["MCP server"]
  node_server["MCP server<br/>[server.py]"]
  node_tool_registry["Tool registry<br/>[server.py]"]
end

subgraph group_tools["AI tools"]
  node_simple_tools["Simple tools<br/>[base.py]"]
  node_workflow_tools["Workflow tools<br/>[workflow_mixin.py]"]
  node_review["Code review<br/>[codereview.py]"]
  node_debug["Debugging<br/>[debug.py]"]
  node_planner["Planning<br/>[planner.py]"]
  node_analysis_tools["Analysis tools<br/>[analyze.py]"]
  node_validation_tools["Validation tools<br/>[precommit.py]"]
end

subgraph group_providers["Model providers"]
  node_provider_registry["Provider registry<br/>[registry.py]"]
  node_provider_adapters["Provider adapters"]
  node_model_registries["Model registries"]
end

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

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

node_client(("CLI / IDE client"))
node_model_service(("AI model service"))
node_external_cli(("External AI CLIs"))

node_client -->|"sends requests"| node_server
node_server -->|"dispatches tools"| node_tool_registry
node_tool_registry -->|"invokes"| node_simple_tools
node_tool_registry -->|"invokes"| node_workflow_tools
node_workflow_tools -->|"specializes"| node_review
node_workflow_tools -->|"specializes"| node_debug
node_workflow_tools -->|"specializes"| node_planner
node_tool_registry -->|"dispatches"| node_analysis_tools
node_tool_registry -->|"dispatches"| node_validation_tools
node_server -->|"resolves models"| node_provider_registry
node_provider_registry -->|"selects provider"| node_provider_adapters
node_provider_adapters -->|"reads capabilities"| node_model_registries
node_simple_tools -->|"requests completions"| node_provider_adapters
node_client -->|"continues threads"| node_conversation
node_server -->|"records turns"| node_conversation
node_conversation -->|"reads and writes"| node_storage
node_client -->|"invokes"| node_clink_tool
node_clink_tool -->|"loads CLI config"| node_clink_registry
node_clink_tool -->|"launches agents"| node_clink_agents
node_clink_agents -->|"runs subprocess"| node_external_cli
node_provider_adapters -->|"sends model requests"| node_model_service

click node_server "https://github.com/beehiveinnovations/pal-mcp-server/blob/main/server.py"
click node_tool_registry "https://github.com/beehiveinnovations/pal-mcp-server/blob/main/server.py"
click node_simple_tools "https://github.com/beehiveinnovations/pal-mcp-server/blob/main/tools/simple/base.py"
click node_workflow_tools "https://github.com/beehiveinnovations/pal-mcp-server/blob/main/tools/workflow/workflow_mixin.py"
click node_review "https://github.com/beehiveinnovations/pal-mcp-server/blob/main/tools/codereview.py"
click node_debug "https://github.com/beehiveinnovations/pal-mcp-server/blob/main/tools/debug.py"
click node_planner "https://github.com/beehiveinnovations/pal-mcp-server/blob/main/tools/planner.py"
click node_analysis_tools "https://github.com/beehiveinnovations/pal-mcp-server/blob/main/tools/analyze.py"
click node_validation_tools "https://github.com/beehiveinnovations/pal-mcp-server/blob/main/tools/precommit.py"
click node_conversation "https://github.com/beehiveinnovations/pal-mcp-server/blob/main/utils/conversation_memory.py"
click node_storage "https://github.com/beehiveinnovations/pal-mcp-server/blob/main/utils/storage_backend.py"
click node_provider_registry "https://github.com/beehiveinnovations/pal-mcp-server/blob/main/providers/registry.py"
click node_provider_adapters "https://github.com/beehiveinnovations/pal-mcp-server/tree/main/providers"
click node_model_registries "https://github.com/beehiveinnovations/pal-mcp-server/tree/main/providers/registries"
click node_clink_tool "https://github.com/beehiveinnovations/pal-mcp-server/blob/main/tools/clink.py"
click node_clink_registry "https://github.com/beehiveinnovations/pal-mcp-server/blob/main/clink/registry.py"
click node_clink_agents "https://github.com/beehiveinnovations/pal-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_tool_registry,node_client toneBlue
class node_simple_tools,node_workflow_tools,node_review,node_debug,node_planner,node_analysis_tools,node_validation_tools toneAmber
class node_provider_registry,node_provider_adapters,node_model_registries toneMint
class node_conversation,node_storage toneRose
class node_clink_tool,node_clink_registry,node_clink_agents,node_model_service,node_external_cli toneIndigo
```

## Components

### MCP server

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

### AI tools

- [Simple tools](https://github.com/beehiveinnovations/pal-mcp-server/blob/main/tools/simple/base.py): `tools/simple/base.py`
- [Workflow tools](https://github.com/beehiveinnovations/pal-mcp-server/blob/main/tools/workflow/workflow_mixin.py): `tools/workflow/workflow_mixin.py`
- [Code review](https://github.com/beehiveinnovations/pal-mcp-server/blob/main/tools/codereview.py): `tools/codereview.py`
- [Debugging](https://github.com/beehiveinnovations/pal-mcp-server/blob/main/tools/debug.py): `tools/debug.py`
- [Planning](https://github.com/beehiveinnovations/pal-mcp-server/blob/main/tools/planner.py): `tools/planner.py`
- [Analysis tools](https://github.com/beehiveinnovations/pal-mcp-server/blob/main/tools/analyze.py): `tools/analyze.py`
- [Validation tools](https://github.com/beehiveinnovations/pal-mcp-server/blob/main/tools/precommit.py): `tools/precommit.py`

### Model providers

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

### Conversation context

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

### CLI bridge

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

### Other components

- **CLI / IDE client**
- **AI model service**
- **External AI CLIs**

## Connections

- CLI / IDE client → MCP server: sends requests
- MCP server → Tool registry: dispatches tools
- Tool registry → Simple tools: invokes
- Tool registry → Workflow tools: invokes
- Workflow tools → Code review: specializes
- Workflow tools → Debugging: specializes
- Workflow tools → Planning: specializes
- Tool registry → Analysis tools: dispatches
- Tool registry → Validation tools: dispatches
- MCP server → Provider registry: resolves models
- Provider registry → Provider adapters: selects provider
- Provider adapters → Model registries: reads capabilities
- Simple tools → Provider adapters: requests completions
- CLI / IDE client → Conversation memory: continues threads
- MCP server → Conversation memory: records turns
- Conversation memory → Thread storage: reads and writes
- CLI / IDE client → Clink tool: invokes
- Clink tool → CLI configuration: loads CLI config
- Clink tool → CLI agents: launches agents
- CLI agents → External AI CLIs: runs subprocess
- Provider adapters → AI model service: sends model requests