# openagentplatform/dive-mcp-host architecture

> Architecture diagram of the GitHub repository openagentplatform/dive-mcp-host, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openagentplatform/dive-mcp-host
- Repository: https://github.com/openagentplatform/dive-mcp-host

## Overview

##### Project type and purpose
- Dive MCP Host is a Python-based language-model hosting service.
- It exposes both an HTTP/WebSocket API and a CLI, manages conversation state, persists to a database, and brokers calls to multiple external LLM providers.

##### File structure
- Top-level package: dive_mcp_host
- cli – command-line interface layer
- host – core “Model Context Protocol” engine, agents, chat orchestration, context/checkpoint helpers
- httpd – HTTP service (routers, middlewares, dependency injection, database migrations, msg_store abstractions)
- models – fake/example models for testing
- scheduler – (future) async task scheduling
- Configuration & infra: alembic.ini, mcp_config.json, model_config.json, scripts/run_pg.sh
- Tests cover host logic, HTTP routers, database stores, CLI, tools, etc.

##### README for additional insights
- Confirms feature set: unified LLM interface, persistence, HTTP+WebSocket API, CLI, multithreading.
- Mentions use of LangChain/LangGraph.

##### Main components
a. Interface Layer
- HTTP Server (FastAPI/Starlette app in dive_mcp_host/httpd)
- Routers (chat, config, models, tools, openai proxy, utils)
- Middlewares (general, kwargs parsing, rate limiter)
- CLI Client (dive_cli entry point in dive_mcp_host/cli)
b. Core Host Engine
- HostConfig & DiveMcpHost (lifecycle management)
- Agent Factory & ChatAgent (message sequencing, tool-in-prompt handling)
- Prompt & System Prompt modules
- Checkpointer, Context Manager
c. Data Layer
- Message Store abstraction (SQLite, PostgreSQL) in host/store and httpd/database/msg_store
- ORM models & Alembic migrations
- Cache & Local store for ephemeral data
d. External Dependencies
- LLM providers (OpenAI, Anthropic, Google, etc.)
- Local tools (echo, local_http_server, stdio_server, mcp_server)
e. Supporting Services
- Scheduler (background tasks)
- Logging subsystem

##### Relationships & interactions
- HTTP Server and CLI both depend on the Core Host Engine APIs.
- Core Engine invokes agents which request LLM responses via provider adapters.
- Core Engine reads/writes conversation state to the Data Layer.
- Database migrations are applied at startup via Alembic.
- Scheduler may trigger periodic jobs (e.g., cleaning up old contexts).
- Tools can be invoked in-prompt by agents (tool-in-prompt pattern).

##### Architectural patterns & design principles
- Layered architecture: Interface → Core → Data
- Dependency inversion: msg_store and model providers are abstract interfaces with concrete implementations (plugin-style)
- CQRS-style separation: routers handle HTTP concerns, delegating to host business logic
- Asynchronous concurrency: HTTP/WebSocket handlers and host chat sessions are async

##### Technologies, frameworks, and libraries
- Python 3.12+
- FastAPI/Starlette (HTTP service)
- Click or Typer (CLI)
- SQLAlchemy + Alembic (ORM & migrations)
- SQLite / PostgreSQL (message storage)
- LangChain / LangGraph (workflow orchestration)
- uv (uv pip, uv sync, uv run) for environment management
- PyTest for testing

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Interface Layer
    subgraph "Interface Layer"
        subgraph "HTTP Server" 
            HTTPEntry["_main.py"]:::frontend
            App["app.py"]:::frontend
            Server["server.py"]:::frontend
            HTTPEntry -->|starts| App
            App -->|runs| Server

            subgraph "Routers"
                ChatR["chat.py"]:::frontend
                ConfigR["config.py"]:::frontend
                ModelsR["models.py"]:::frontend
                ModelVerifyR["model_verify.py"]:::frontend
                OpenAIR["openai.py"]:::frontend
                ToolsR["tools.py"]:::frontend
                UtilsR["utils.py"]:::frontend
            end
            App -->|includes| ChatR & ConfigR & ModelsR & ModelVerifyR & OpenAIR & ToolsR & UtilsR

            subgraph "Middlewares"
                GeneralM["general.py"]:::frontend
                KwargsM["kwargs.py"]:::frontend
                RateLimiter["rate_limiter.py"]:::frontend
            end
            App -->|uses| GeneralM & KwargsM & RateLimiter

            Dependencies["dependencies.py"]:::frontend
            App -->|injects| Dependencies
        end

        subgraph "CLI Client"
            CLI["cli.py"]:::frontend
            CLItypes["cli_types.py"]:::frontend
            CLIMigrate["migrate.py"]:::frontend
            CLI -->|parses| CLItypes
            CLI -->|migrations| CLIMigrate
        end
    end

    %% Core Host Engine
    subgraph "Core Host Engine"
        HostClass["host.py"]:::core
        LLMConf["llm.py"]:::core
        Errors["errors.py"]:::core
        ChatSession["chat.py"]:::core
        Prompt["prompt.py"]:::core

        subgraph "Agents"
            AgentFactory["agent_factory.py"]:::core
            ChatAgent["chat_agent.py"]:::core
            MessageOrder["message_order.py"]:::core
            ToolsInPrompt["tools_in_prompt.py"]:::core
        end

        Checkpointer["checkpointer.py"]:::core
        ContextMgr["context.py"]:::core
    end

    %% Data Layer
    subgraph "Data Layer"
        HostStore["sqlite.py"]:::data
        subgraph "HTTP Msg Store"
            AbstractStore["abstract.py"]:::data
            BaseStore["base.py"]:::data
            StoreSQLite["sqlite.py"]:::data
            StorePostgres["postgresql.py"]:::data
        end
        ORM["orm_models.py"]:::data
        Migrations["migrations/versions/"]:::data
        MigrateRunner["migrate.py"]:::data
        CacheStore["cache.py"]:::data
        LocalStore["local.py"]:::data
    end

    %% External Dependencies & Tools
    subgraph "External Dependencies & Tools"
        LLMProviders["llm.py"]:::external
        EchoTool["echo.py"]:::external
        LocalHTTPTool["local_http_server.py"]:::external
        StdIOTool["stdio_server.py"]:::external
        MCPServerTool["mcp_server.py"]:::external
        MiscTools["misc.py & model_types.py"]:::external
        ToolsLog["log.py"]:::external
    end

    %% Supporting Services
    subgraph "Supporting Services"
        Scheduler["scheduler/__init__.py"]:::core
        Logger["log.py"]:::core
    end

    %% Relationships
    ChatR -->|"HTTP call"| HostClass
    CLI -->|"CLI call"| HostClass
    HostClass -->|"reads/writes"| HostStore
    HostClass -->|"reads/writes"| AbstractStore
    HostClass -->|"invokes"| AgentFactory
    AgentFactory -->|"creates"| ChatAgent
    ChatAgent -->|"orders"| MessageOrder
    ChatAgent -->|"tool invoke"| ToolsInPrompt
    HostClass -->|"checkpoints"| Checkpointer
    HostClass -->|"manages context"| ContextMgr
    HostClass -->|"migration"| MigrateRunner
    HostClass -->|"uses ORM"| ORM
    HostClass -->|"uses cache"| CacheStore
    HostClass -->|"uses local store"| LocalStore
    HostClass -->|"calls providers"| LLMProviders
    ToolsInPrompt -->|"invokes"| EchoTool & LocalHTTPTool & StdIOTool & MCPServerTool & MiscTools
    ToolsLog -->|"logs"| ToolsInPrompt
    Scheduler -->|"schedules jobs"| HostClass
    Logger -->|"logs events"| HostClass & AgentFactory

    %% Click Events
    click HTTPEntry "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/httpd/_main.py"
    click App "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/httpd/app.py"
    click Server "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/httpd/server.py"
    click ChatR "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/httpd/routers/chat.py"
    click ConfigR "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/httpd/routers/config.py"
    click ModelsR "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/httpd/routers/models.py"
    click ModelVerifyR "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/httpd/routers/model_verify.py"
    click OpenAIR "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/httpd/routers/openai.py"
    click ToolsR "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/httpd/routers/tools.py"
    click UtilsR "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/httpd/routers/utils.py"
    click GeneralM "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/httpd/middlewares/general.py"
    click KwargsM "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/httpd/middlewares/kwargs.py"
    click RateLimiter "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/httpd/rate_limiter.py"
    click Dependencies "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/httpd/dependencies.py"
    click CLI "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/cli/cli.py"
    click CLItypes "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/cli/cli_types.py"
    click CLIMigrate "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/cli/migrate.py"
    click HostClass "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/host/host.py"
    click LLMConf "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/host/conf/llm.py"
    click Errors "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/host/errors.py"
    click ChatSession "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/host/chat.py"
    click Prompt "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/host/prompt.py"
    click AgentFactory "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/host/agents/agent_factory.py"
    click ChatAgent "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/host/agents/chat_agent.py"
    click MessageOrder "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/host/agents/message_order.py"
    click ToolsInPrompt "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/host/agents/tools_in_prompt.py"
    click Checkpointer "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/host/helpers/checkpointer.py"
    click ContextMgr "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/host/helpers/context.py"
    click HostStore "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/host/store/sqlite.py"
    click AbstractStore "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/httpd/database/msg_store/abstract.py"
    click BaseStore "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/httpd/database/msg_store/base.py"
    click StoreSQLite "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/httpd/database/msg_store/sqlite.py"
    click StorePostgres "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/httpd/database/msg_store/postgresql.py"
    click ORM "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/httpd/database/orm_models.py"
    click Migrations "https://github.com/openagentplatform/dive-mcp-host/tree/main/dive_mcp_host/httpd/database/migrations/versions/"
    click MigrateRunner "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/httpd/database/migrate.py"
    click CacheStore "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/httpd/store/cache.py"
    click LocalStore "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/httpd/store/local.py"
    click LLMProviders "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/host/conf/llm.py"
    click EchoTool "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/host/tools/echo.py"
    click LocalHTTPTool "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/host/tools/local_http_server.py"
    click StdIOTool "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/host/tools/stdio_server.py"
    click MCPServerTool "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/host/tools/mcp_server.py"
    click MiscTools "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/host/tools/misc.py"
    click ToolsLog "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/host/tools/log.py"
    click Scheduler "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/scheduler/__init__.py"
    click Logger "https://github.com/openagentplatform/dive-mcp-host/blob/main/dive_mcp_host/log.py"

    %% Styles
    classDef frontend fill:#B3CDE3,stroke:#005B96,color:#000;
    classDef core fill:#C7E9B4,stroke:#238B45,color:#000;
    classDef data fill:#FDD0A2,stroke:#E6550D,color:#000;
    classDef external fill:#DADAEB,stroke:#6A51A3,color:#000;
```
