196 lines
5.4 KiB
Markdown
196 lines
5.4 KiB
Markdown
# MCP Protocol Framework
|
||
|
||
[Model Context Protocol (MCP)](https://spec.modelcontextprotocol.io/specification/2024-11-05/architecture/) 是一个开放协议，为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服务器
|
||
|
||
```cpp
|
||
// 创建并配置服务器
|
||
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客户端
|
||
|
||
```cpp
|
||
// 连接到服务器
|
||
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的服务器通信。
|
||
|
||
```cpp
|
||
#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服务器](https://www.pulsemcp.com/servers)
|
||
|
||
```cpp
|
||
#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构建示例:
|
||
```bash
|
||
cmake -B build
|
||
cmake --build build --config Release
|
||
```
|
||
|
||
|
||
## 许可证
|
||
|
||
本框架根据MIT许可证提供。有关详细信息，请参阅LICENSE文件。 |