# mark3labs/mcphost architecture

> Architecture diagram of the GitHub repository mark3labs/mcphost, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mark3labs/mcphost
- Repository: https://github.com/mark3labs/mcphost

## Overview

##### Main Components
- CLI Interface & Command Handlers: This represents the entry point for user interactions. Use components from the "cmd" directory (e.g., mcp.go, root.go and main.go) that parse CLI flags and commands.
- Configuration Management: The project loads settings (like MCP server commands/arguments and API keys) from a JSON configuration file (defaulted to ~/.mcp.json, customizable via a flag).
- LLM Provider Abstraction: In the "pkg/llm" package there is an abstraction over language model providers. Identify:
- Common interface and provider contracts defined in pkg/llm/provider.go.
- Concrete implementations for Anthropic (in pkg/llm/anthropic/*), Ollama (in pkg/llm/ollama/*), and OpenAI (in pkg/llm/openai/*).
- Message History: The pkg/history module (e.g., message.go) handles context management by storing conversation history.
- MCP Server Integration: Although not a separate dynamic module, the configuration for external MCP servers (e.g., filesystem server, SQLite server) is essential for tool integration and should be represented as external components.
- External Services & APIs: Identify external systems the application talks to:
- Remote APIs (e.g., Anthropic’s or OpenAI’s endpoints).
- Local processes/services (e.g., the Ollama server, various MCP servers like the SQLite or filesystem server).

##### Relationships and Interactions
- User interacting via the CLI, which triggers the command handlers.
- The CLI module passes commands and configuration data to the core application logic.
- The message history module integrates at the core level to manage context across interactions.
- Dependency relationships between the configuration (loaded on startup) and how it influences both provider selection and external tool (MCP server) calls.

##### Architectural Patterns and Design Principles
- Plugin/Strategy Pattern: The provider abstraction follows a strategy pattern – each provider (Anthropic, Ollama, OpenAI) adheres to a common interface defined in pkg/llm/provider.go.
- External Integration: The configuration-driven approach for connecting to external MCP servers emphasizes decoupling, which is an important design principle to capture.

##### Technology-Specific Details
- Language: Written in Go (noting dependencies like go.mod and go.sum).
- Deployment: CLI tool packaged with Go’s build tools and integrated with CI/CD (e.g., workflows in .github/workflows).
- Environment: Requires API keys and external installations (e.g., Ollama, Anthropic API) – mention these in external service components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User("User Input"):::user

    subgraph "CLI Layer"
        CLI1("MCP Command Handler"):::cli
        CLI2("Root Command Handler"):::cli
        CLI3("Main Entry"):::cli
    end

    Core("Core Application Module"):::internal
    Config("Configuration Manager (~/.mcp.json)"):::internal
    History("Message History"):::history

    subgraph "LLM Provider Layer"
        ProvInterface("LLM Provider Abstraction Interface"):::provider
        Anthropic("Anthropic Provider Implementation"):::provider
        Ollama("Ollama Provider Implementation"):::provider
        OpenAI("OpenAI Provider Implementation"):::provider
    end

    ExternalAPIs("External APIs/Services"):::external
    LocalOllama("Local Ollama Server"):::external
    MCPServers("MCP Servers (Filesystem/SQLite)"):::external

    %% Connections from User to CLI
    User -->|"triggers"| CLI1
    User -->|"triggers"| CLI2
    User -->|"triggers"| CLI3

    %% Connections from CLI to Core Application Module
    CLI1 -->|"calls"| Core
    CLI2 -->|"calls"| Core
    CLI3 -->|"calls"| Core

    %% Core module interactions
    Core -->|"loads"| Config
    Core -->|"manages"| History
    Core -->|"selects"| ProvInterface
    Config -->|"configures"| ProvInterface

    %% LLM Provider Layer implementations
    ProvInterface -->|"implements"| Anthropic
    ProvInterface -->|"implements"| Ollama
    ProvInterface -->|"implements"| OpenAI

    %% External interactions
    Anthropic -->|"calls"| ExternalAPIs
    OpenAI -->|"calls"| ExternalAPIs
    Ollama -->|"calls"| LocalOllama
    Core -->|"dispatches_to"| MCPServers

    %% Click Events
    click CLI1 "https://github.com/mark3labs/mcphost/blob/main/cmd/mcp.go"
    click CLI2 "https://github.com/mark3labs/mcphost/blob/main/cmd/root.go"
    click CLI3 "https://github.com/mark3labs/mcphost/blob/main/main.go"
    click ProvInterface "https://github.com/mark3labs/mcphost/blob/main/pkg/llm/provider.go"
    click Anthropic "https://github.com/mark3labs/mcphost/tree/main/pkg/llm/anthropic"
    click Ollama "https://github.com/mark3labs/mcphost/tree/main/pkg/llm/ollama"
    click OpenAI "https://github.com/mark3labs/mcphost/tree/main/pkg/llm/openai"
    click History "https://github.com/mark3labs/mcphost/blob/main/pkg/history/message.go"

    %% Styles
    classDef user fill:#f9c,stroke:#333,stroke-width:2px;
    classDef cli fill:#bbf,stroke:#333,stroke-width:2px;
    classDef internal fill:#bfb,stroke:#333,stroke-width:2px;
    classDef provider fill:#fbf,stroke:#333,stroke-width:2px;
    classDef history fill:#aff,stroke:#333,stroke-width:2px;
    classDef external fill:#faa,stroke:#333,stroke-width:2px;
```
