MCP (Model Context Protocol) — C++ 高性能实现

📖 项目简介

基于 C++17 实现的高性能 Model Context Protocol (MCP) 系统，包含 Client / Server / Tools 完整生态。解决 AI Agent 调用外部工具时接口不统一、多工具上下文注入成本高、以及现有 Python SDK 不适合嵌入 C++ 后端场景的问题。

核心特性

🏗️ 系统架构

┌─────────────────────────────────────────────────────────────┐
│                        main.cpp                              │
│            参数解析 → 加载插件 → 创建 Gateway → Start()       │
└───────────────────────────┬─────────────────────────────────┘
                            │
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
       ┌────────────┐ ┌─────────┐ ┌──────────────┐
       │StdioGateway│ │SseGateway│ │HttpStream    │
       │            │ │         │ │Gateway       │
       │ 1个Session │ │http_server│ │http_server   │
       │ stdin/stdout│ │SessionMgr│ │SessionMgr    │
       └────────────┘ └─────────┘ └──────────────┘
                            │
                    ┌───────┴───────┐
                    ▼               ▼
             ┌────────────┐  ┌────────────┐
             │ Session A  │  │ Session B  │
             │ Server +   │  │ Server +   │
             │ Transport  │  │ Transport  │
             │ (独立线程)  │  │ (独立线程)  │
             └────────────┘  └────────────┘
                    │
                    ▼
             ┌────────────┐
             │  插件层     │
             │ (全局共享)  │
             │ dlopen 加载 │
             └────────────┘

📁 项目结构

mcp/
├── CMakeLists.txt                 # 根构建文件
├── .env.example                   # 环境变量模板
│
├── mcp_server/                    # MCP 服务端
│   ├── src/
│   │   ├── gateway/               # 网关层（HTTP 路由 + 会话管理）
│   │   │   ├── IGateway.h         #   网关接口
│   │   │   ├── StdioGateway.*     #   Stdio 网关
│   │   │   ├── SseGateway.*       #   SSE 网关
│   │   │   └── HttpStreamGateway.* #   Streamable HTTP 网关
│   │   ├── server/                # 协议层（JSON-RPC 处理）
│   │   ├── session/               # 会话层（SessionManager）
│   │   ├── transport/             # 传输层（消息队列通信）
│   │   ├── loader/                # 插件加载器
│   │   └── interface/             # 抽象接口
│   └── plugins/                   # 工具插件
│       ├── weather/               #   天气查询
│       ├── calculator/            #   计算器
│       ├── code-review/           #   代码审查
│       ├── geo-tools/             #   🆕 空间分析（坐标转换/缓冲区/最近设施/地理编码）
│       └── ...
│
├── mcp_client/                    # MCP 客户端
│   ├── include/agent_rpc/mcp/
│   │   ├── mcp_client.h           # 客户端接口
│   │   ├── mcp_agent_integration.h # AI Agent 集成
│   │   └── rag/                   # RAG 智能工具路由
│   │       ├── embedding_service.h    # Embedding 服务
│   │       ├── embedding_cache.h      # LRU 向量缓存
│   │       ├── vector_index.h         # 向量索引
│   │       ├── tool_retriever.h       # 工具检索器
│   │       └── tool_validator.h       # 工具验证器
│   └── src/
│
├── common/                        # 公共组件
├── examples/                      # 示例代码
└── docs/                          # 文档

🚀 快速开始

环境要求

• C++17 编译器（GCC 9+ / Clang 10+ / MSVC 2019+）
• CMake 3.20+
• libcurl（HTTP 请求）
• pthread

编译

# 克隆仓库
git clone https://github.com/your-username/mcp.git
cd mcp

# 配置环境变量
cp .env.example .env
# 编辑 .env，填入你的 DASHSCOPE_API_KEY

# 编译
mkdir build && cd build
cmake ..
make -j$(nproc)

运行

# Stdio 模式（Claude Desktop 默认）
./mcp_server/mcp_server -p ./mcp_server/plugins

# SSE 模式
./mcp_server/mcp_server -s -p ./mcp_server/plugins

# Streamable HTTP 模式（支持多客户端）
./mcp_server/mcp_server --httpstream -p ./mcp_server/plugins --port 8080

集成到 Claude Desktop

将以下配置添加到 ~/.config/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "mcp-server": {
      "command": "/path/to/build/mcp_server/mcp_server",
      "args": ["-p", "/path/to/build/mcp_server/plugins"]
    }
  }
}

🔧 传输模式详解

Streamable HTTP（推荐）

符合 MCP 2025-03-26 规范，支持多客户端并发：

客户端                          服务端
  │                               │
  │── POST /mcp ────────────────→│  (initialize)
  │←── 200 + Mcp-Session-Id ────│
  │                               │
  │── POST /mcp ────────────────→│  (tools/list)
  │←── 200 + JSON ─────────────│
  │                               │
  │── POST /mcp ────────────────→│  (tools/call)
  │   Accept: text/event-stream   │
  │←── SSE: progress ──────────│  (chunked 流式响应)
  │←── SSE: elicitation ───────│  (服务端反问客户端)
  │── POST /mcp ────────────────→│  (客户端回复)
  │←── SSE: final result ──────│

SSE 模式

客户端                          服务端
  │                               │
  │── GET /sse ─────────────────→│  (建立 SSE 长连接)
  │←── event: endpoint ────────│  (返回消息地址)
  │                               │
  │── POST /messages ──────────→│  (发送请求)
  │←── SSE: data: {响应} ──────│  (通过 SSE 管道返回)

Stdio 模式

客户端 (Claude Desktop)          服务端
  │                               │
  │── stdin: JSON-RPC ──────────→│
  │←── stdout: JSON-RPC ────────│

🧠 RAG 智能工具路由

当工具数量较多时，通过 RAG 技术动态筛选最相关的工具注入上下文：

用户: "帮我查北京天气"
    │
    ▼
Embedding API (DashScope text-embedding-v2)
    │
    ▼
向量相似度检索 (余弦相似度, Top-K)
    │
    ▼
探针测试验证 (从 Schema 生成假参数, 实际调用测试)
    │
    ▼
输出: [get_weather, get_forecast]  (Token 节省约 80%)

🌍 空间分析工具（GIS）

内置空间分析插件，为 AI Agent 提供 GIS 能力：

# 通过 MCP 协议调用示例
# Agent: "帮我查北京天安门附近的医院"
# → geocode("北京天安门") → (116.397, 39.908)
# → transform_coordinate(WGS84→GCJ02) → (116.403, 39.909)
# → 调用地图 API 搜索附近医院
# → find_nearest(天安门, 医院列表) → 排序结果

🧩 插件开发

插件基于 C 动态链接库实现，支持热插拔：

// weather_plugin.cpp
#include "PluginAPI.h"

extern "C" {
    PluginInfo* GetPluginInfo() {
        static PluginInfo info = {
            .name = "weather-tools",
            .version = "1.0.0",
            .type = PLUGIN_TYPE_TOOLS
        };
        return &info;
    }

    int GetToolCount() { return 1; }

    PluginTool* GetTool(int index) {
        static PluginTool tool = {
            .name = "get_weather",
            .description = "Get weather forecast for a city",
            .inputSchema = R"({"type":"object","properties":{"city":{"type":"string"}}})"
        };
        return &tool;
    }

    char* HandleRequest(const char* request) {
        return strdup(R"({"content":[{"type":"text","text":"晴天 25°C"}]})");
    }
}

编译后将 .so 文件放入 plugins/ 目录即可自动加载。

📊 技术栈

📄 License

MIT License