cpp-mcp/README.md

MCP Protocol Framework

Model Context Protocol (MCP) 是一个开放协议，为AI模型和代理提供与各种资源、工具和服务交互的标准化方式。本框架实现了MCP协议的核心功能，符合2024-11-05基本协议规范。

核心特性

• JSON-RPC 2.0通信: 基于JSON-RPC 2.0标准的请求/响应通信
• 资源抽象: 文件、API等资源的标准接口
• 工具注册: 注册和调用带有结构化参数的工具
• 可扩展架构: 易于扩展新的资源类型和工具
• 多传输支持: 支持HTTP和标准输入/输出(stdio)通信方式

组件

MCP C++库包含以下主要组件：

核心组件

客户端接口 (mcp_client.h)

定义了MCP客户端的抽象接口，所有具体的客户端实现都继承自这个接口。

SSE客户端 (mcp_sse_client.h, mcp_sse_client.cpp)

使用HTTP和Server-Sent Events (SSE)与MCP服务器通信的客户端实现。

Stdio客户端 (mcp_stdio_client.h, mcp_stdio_client.cpp)

使用标准输入/输出与MCP服务器通信的客户端实现，可以启动子进程并与之通信。

消息处理 (mcp_message.h, mcp_message.cpp)

处理JSON-RPC消息的序列化和反序列化。

工具管理 (mcp_tool.h, mcp_tool.cpp)

管理和调用MCP工具。

资源管理 (mcp_resource.h, mcp_resource.cpp)

管理MCP资源。

服务器 (mcp_server.h, mcp_server.cpp)

实现MCP服务器功能。

示例

HTTP服务器示例 (examples/server_example.cpp)

MCP服务器实现示例，带有自定义工具:

• 时间工具: 获取当前时间
• 计算器工具: 执行数学运算
• 回显工具: 处理和分析文本
• 招呼工具：返回Hello, +传入名字+!，默认返回Hello, World!

HTTP客户端示例 (examples/client_example.cpp)

连接到服务器的MCP客户端示例:

• 获取服务器信息
• 列出可用工具
• 使用参数调用工具
• 访问资源

Stdio客户端示例 (examples/stdio_client_example.cpp)

展示如何使用stdio客户端与本地服务器通信:

• 启动本地服务器进程
• 访问文件系统资源
• 调用服务器工具

如何使用

设置HTTP服务器

// 创建并配置服务器
mcp::server server("localhost", 8080);
server.set_server_info("MCP Example Server", "2024-11-05");

// 注册工具
mcp::json hello_handler(const mcp::json& params) {
    std::string name = params.contains("name") ? params["name"].get<std::string>() : "World";
    return {
        {
            {"type", "text"},
            {"text", "Hello, " + name + "!"}
        }
    };
}

mcp::tool hello_tool = mcp::tool_builder("hello")
        .with_description("Say hello")
        .with_string_param("name", "Name to say hello to", "World")
        .build();

server.register_tool(hello_tool, hello_handler);

// 注册资源
auto file_resource = std::make_shared<mcp::file_resource>("<file_path>");
server.register_resource("file://<file_path>", file_resource);

// 启动服务器
server.start(true);  // 阻塞模式

创建HTTP客户端

// 连接到服务器
mcp::sse_client client("localhost", 8080);

// 初始化连接
client.initialize("My Client", "1.0.0");

// 调用工具
mcp::json params = {
    {"name", "Client"}
};

mcp::json result = client.call_tool("hello", params);

使用SSE客户端

SSE客户端使用HTTP和Server-Sent Events (SSE) 与MCP服务器通信。这是一种基于Web标准的通信方式，适合与支持HTTP/SSE的服务器通信。

#include "mcp_sse_client.h"

// 创建客户端，指定服务器地址和端口
mcp::sse_client client("localhost", 8080);
// 或者使用基础URL
// mcp::sse_client client("http://localhost:8080");

// 设置认证令牌（如果需要）
client.set_auth_token("your_auth_token");

// 设置自定义请求头（如果需要）
client.set_header("X-Custom-Header", "value");

// 初始化客户端
if (!client.initialize("My Client", "1.0.0")) {
    // 初始化失败处理
}

// 调用工具
json result = client.call_tool("tool_name", {
    {"param1", "value1"},
    {"param2", 42}
});

使用Stdio客户端

Stdio客户端可以与任何支持stdio传输的MCP服务器进行通信，例如：

• @modelcontextprotocol/server-everything - 示例服务器
• @modelcontextprotocol/server-filesystem - 文件系统服务器
• 其他支持stdio传输的MCP服务器

#include "mcp_stdio_client.h"

// 创建客户端，指定服务器命令
mcp::stdio_client client("npx -y @modelcontextprotocol/server-everything");
// mcp::stdio_client client("npx -y @modelcontextprotocol/server-filesystem /path/to/directory");

// 初始化客户端
if (!client.initialize("My Client", "1.0.0")) {
    // 初始化失败处理
}

// 访问资源
json resources = client.list_resources();
json content = client.read_resource("resource://uri");

// 调用工具
json result = client.call_tool("tool_name", {
    {"param1", "value1"},
    {"param2", "value2"}
});

构建框架

框架依赖以下库:

• httplib.h - HTTP服务器和客户端
• json.hpp - JSON解析和生成
• gtest - 测试

所有依赖项都包含在仓库中。

使用CMake构建示例:

cmake -B build
cmake --build build --config Release

许可证

本框架根据MIT许可证提供。有关详细信息，请参阅LICENSE文件。