# hkr04/cpp-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/hkr04/cpp-mcp
- Repository: https://github.com/hkr04/cpp-mcp

## Overview

##### Project type and purpose
- This is a C++ framework library (open-source tool) that implements the Model Context Protocol (MCP).
- It provides both client and server APIs for JSON-RPC 2.0 communication, resource abstraction, tool registration/invocation, and supports two transports (HTTP/SSE and stdio).
- It’s intended to be embedded in other C++ applications or used via examples to stand up MCP servers and clients.

##### File structure
Top-level directories:
- common/ : header-only utilities (base64, HTTP client, JSON parser) shared by all modules
- / : public API headers (client, server, message, tool, resource, thread pool, logger, etc.)
- src/ : implementation of the public APIs
- examples/ : standalone small apps illustrating server-side, client-side, agent-side use
- test/ : unit tests using GoogleTest
- CMakeLists.txt & submodule references: build orchestration, optional SSL, test toggles

##### Key insights from README
- Core Components: client interface, SSE client, stdio client, message processing, tool management, resource management, server
- Architecture is modular and extensible: new transports, tools, resources can be added via registration interfaces
- Examples show real-world flows: HTTP server with tools/resources; HTTP client; stdio client spawning a server; an “agent” that chains LLM calls and tools

– External Clients / Agents (could be HTTP or stdio processes)
– Transport Layer
- HTTP/SSE Transport Adapter
- STDIO Transport Adapter
– Core Library
- Message Processor (JSON-RPC serialization/deserialization)
- Tool Registry & Invoker
- Resource Registry & Manager
- Server Core (listener, dispatcher)
– Common Utilities (json.hpp, httplib.h, base64.hpp)
– External Resources/Services
- File System, APIs, LLM endpoints

1. Client app → (selects transport) → Transport Adapter
2. Transport Adapter → JSON-RPC request → Message Processor
3. Message Processor → dispatch to Server Core
4. Server Core → invokes Tool Registry or Resource Manager → calls user-supplied handler or resource implementation
5. Handler → returns JSON result → Tool/Resource → Message Processor
6. Message Processor → JSON-RPC response → Transport Adapter → back to Client

c. Architectural patterns / design principles
- Layered design: separation between transport, messaging, domain (tools/resources)
- Plugin/registry pattern: tools and resources are registered at runtime via abstract interfaces
- Interface vs. implementation: public APIs in include/ vs concrete logic in src/
- Single responsibility: each module handles one concern (e.g., serialization, HTTP comms, dispatching)

d. Key technologies & libraries
– CMake for build configuration
– header-only nlohmann::json for JSON
– cpp-httplib for HTTP/SSE support
– GoogleTest for unit testing
– standard C++17 threading (thread_pool)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Example Applications
    subgraph "Example Applications" 
        direction TB
        ServerExample["server_example.cpp"]:::examples
        SSEClientExample["sse_client_example.cpp"]:::examples
        StdioClientExample["stdio_client_example.cpp"]:::examples
        AgentExample["agent_example.cpp"]:::examples
    end

    %% Transport Layer
    subgraph "Transport Layer" 
        direction TB
        HTTPAdapter["HTTP/SSE Transport Adapter"]:::transport
        STDIOAdapter["STDIO Transport Adapter"]:::transport
    end

    %% Core Library
    subgraph "Core Library"
        direction TB
        MessageProcessor["Message Processor\n(JSON-RPC serialization/deserialization)"]:::core
        ToolRegistry["Tool Registry & Invoker"]:::core
        ResourceManager["Resource Registry & Manager"]:::core
        ServerCore["Server Core\n(listener, dispatcher)"]:::core
        ThreadPool["Thread Pool Utility"]:::core
        Logger["Logger Utility"]:::core
    end

    %% Common Utilities
    subgraph "Common Utilities"
        direction TB
        JSON["JSON Parser\n(nlohmann::json)"]:::util
        HTTPClient["HTTP Client & SSE Support\n(cpp-httplib)"]:::util
        Base64["Base64 Encoding/Decoding"]:::util
    end

    %% Tests & Build
    subgraph "Testing & Build"
        direction TB
        Tests["Unit Tests\n(test/mcp_test.cpp)"]:::tests
        CMakeRoot["CMakeLists.txt"]:::build
        CMakeSrc["src/CMakeLists.txt"]:::build
        CMakeExamples["examples/CMakeLists.txt"]:::build
        CMakeTest["test/CMakeLists.txt"]:::build
    end

    %% Data Flows
    ServerExample -->|selects transport| HTTPAdapter
    ServerExample -->|selects transport| STDIOAdapter
    SSEClientExample -->|selects transport| HTTPAdapter
    StdioClientExample -->|selects transport| STDIOAdapter
    AgentExample -->|selects transport| HTTPAdapter

    HTTPAdapter -->|"JSON-RPC Request"| MessageProcessor
    STDIOAdapter -->|"JSON-RPC Request"| MessageProcessor

    MessageProcessor -->|"dispatch request"| ServerCore
    ServerCore -->|"invoke_tool(name, params)"| ToolRegistry
    ServerCore -->|"invoke_resource(name, params)"| ResourceManager

    ToolRegistry -->|"result JSON"| MessageProcessor
    ResourceManager -->|"result JSON"| MessageProcessor

    MessageProcessor -->|"JSON-RPC Response"| HTTPAdapter
    MessageProcessor -->|"JSON-RPC Response"| STDIOAdapter

    %% Dependencies on utilities
    MessageProcessor --> JSON
    HTTPAdapter --> HTTPClient
    HTTPAdapter --> Base64
    ToolRegistry --> Logger
    ResourceManager --> Logger
    ServerCore --> ThreadPool

    %% Tests & Build relations
    Tests --> MessageProcessor
    Tests --> ToolRegistry
    Tests --> ResourceManager
    Tests --> ServerCore

    CMakeRoot --> CMakeSrc
    CMakeRoot --> CMakeExamples
    CMakeRoot --> CMakeTest

    %% Click Events
    click ServerExample "https://github.com/hkr04/cpp-mcp/blob/main/examples/server_example.cpp"
    click SSEClientExample "https://github.com/hkr04/cpp-mcp/blob/main/examples/sse_client_example.cpp"
    click StdioClientExample "https://github.com/hkr04/cpp-mcp/blob/main/examples/stdio_client_example.cpp"
    click AgentExample "https://github.com/hkr04/cpp-mcp/blob/main/examples/agent_example.cpp"

    click HTTPAdapter "https://github.com/hkr04/cpp-mcp/blob/main/include/mcp_sse_client.h"
    click STDIOAdapter "https://github.com/hkr04/cpp-mcp/blob/main/include/mcp_stdio_client.h"

    click MessageProcessor "https://github.com/hkr04/cpp-mcp/blob/main/include/mcp_message.h"
    click MessageProcessor "https://github.com/hkr04/cpp-mcp/blob/main/src/mcp_message.cpp"

    click ToolRegistry "https://github.com/hkr04/cpp-mcp/blob/main/include/mcp_tool.h"
    click ToolRegistry "https://github.com/hkr04/cpp-mcp/blob/main/src/mcp_tool.cpp"

    click ResourceManager "https://github.com/hkr04/cpp-mcp/blob/main/include/mcp_resource.h"
    click ResourceManager "https://github.com/hkr04/cpp-mcp/blob/main/src/mcp_resource.cpp"

    click ServerCore "https://github.com/hkr04/cpp-mcp/blob/main/include/mcp_server.h"
    click ServerCore "https://github.com/hkr04/cpp-mcp/blob/main/src/mcp_server.cpp"

    click ThreadPool "https://github.com/hkr04/cpp-mcp/blob/main/include/mcp_thread_pool.h"
    click Logger "https://github.com/hkr04/cpp-mcp/blob/main/include/mcp_logger.h"

    click JSON "https://github.com/hkr04/cpp-mcp/blob/main/common/json.hpp"
    click HTTPClient "https://github.com/hkr04/cpp-mcp/blob/main/common/httplib.h"
    click Base64 "https://github.com/hkr04/cpp-mcp/blob/main/common/base64.hpp"

    click Tests "https://github.com/hkr04/cpp-mcp/blob/main/test/mcp_test.cpp"
    click CMakeRoot "https://github.com/hkr04/cpp-mcp/blob/main/CMakeLists.txt"
    click CMakeSrc "https://github.com/hkr04/cpp-mcp/blob/main/src/CMakeLists.txt"
    click CMakeExamples "https://github.com/hkr04/cpp-mcp/blob/main/examples/CMakeLists.txt"
    click CMakeTest "https://github.com/hkr04/cpp-mcp/blob/main/test/CMakeLists.txt"

    %% Styles
    classDef transport fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef core fill:#ccffcc,stroke:#333,stroke-width:1px;
    classDef util fill:#eeeeee,stroke:#333,stroke-width:1px;
    classDef examples fill:#ffe5cc,stroke:#333,stroke-width:1px;
    classDef tests fill:#f2f2f2,stroke:#333,stroke-width:1px;
    classDef build fill:#f0f0f0,stroke:#333,stroke-width:1px;
```
