项目介绍
MCP Server 核心库描述文档
项目概述
MCP Server 是一个基于 Qt/C++ 的 Model Context Protocol (MCP) 服务器框架的实现。该框架提供完整的 MCP 协议实现，支持通过 HTTP 传输层与 MCP 客户端通信，并为 AI 应用提供工具、资源和提示词服务。目前处于 DEMO 阶段。
核心功能
- ✅ 完整的 MCP 协议实现 支持 MCP 协议规范（版本 2025-06-18）
- ✅ HTTP 传输层 基于 HTTP/1.1 协议实现，支持高并发连接
- ✅ 三大核心服务：工具服务、资源服务、提示词服务
- ✅ 配置文件驱动 支持自动加载和启动 JSON 配置文件
- ✅ 灵活的工具注册 支持两种注册方式：功能性注册和对象方法注册
- ✅ 中间件支持 提供中间件机制以支持请求预处理
- ✅ 会话管理 完整的会话生命周期管理
- ✅ 订阅通知 支持资源、工具和提示词变化的通知
架构设计
整体架构
┌─────────────────────────────────────────────────────────┐
│ 应用程序层 │
│ (MCPAutoServer / 自定义服务器实现) │
└────────────────────┬────────────────────────────────────┘
│
┌────────────────────▼────────────────────────────────────┐
│ 服务器接口层 │
│ (IMCPServer / MCPServer) │
└────────────────────┬────────────────────────────────────┘
│
┌────────────┼────────────┐
│ │ │
┌───────▼──────┐ ┌──▼──────┐ ┌──▼──────────┐
│ 工具服务 │ │资源服务 │ │ 提示词服务 │
│ ToolService │ │Resource │ │ Prompt │
│ │ │Service │ │ Service │
└───────┬──────┘ └──┬──────┘ └──┬──────────┘
│ │ │
└────────────┼────────────┘
│
┌────────────────────▼────────────────────────────────────┐
│ 路由与调度层 │
│ (MCPRouter / MCPRequestDispatcher / MCPContext) │
└────────────────────┬────────────────────────────────────┘
│
┌────────────────────▼────────────────────────────────────┐
│ 消息处理层 │
│ (MCPMessage / MCPServerMessage / MCPMessageSender) │
└────────────────────┬────────────────────────────────────┘
│
┌────────────────────▼────────────────────────────────────┐
│ 传输层 │
│ (MCPHttpTransport / IMCPTransport) │
└─────────────────────────────────────────────────────────┘
核心模块描述
1. 服务器层
接口定义：IMCPServer
- 提供统一的服务器接口
- 管理服务器生命周期（启动、停止、运行状态）
- 提供三大服务的访问接口
实现类：MCPServer
- 服务器核心实现
- 协调各组件的初始化
- 管理传输层和会话服务
自动启动：MCPAutoServer
- 根据配置文件自动启动服务器
- 自动检测并加载
MCPServerConfig配置 - 自动绑定工具处理器
2. 服务层
工具服务
接口：IMCPToolService
实现：MCPToolService
功能：
- 工具注册和管理
- 工具调用执行
- 工具列表查询
- 工具变更通知
支持两种注册方式：
- 功能性注册：使用
std::function注册工具处理函数 - 对象方法注册：绑定槽函数到 QOarget
资源服务
接口：IMCPResourceService
实现：MCPResourceService
功能：
- 资源注册和管理
- 资源内容读取
- 资源列表查询
- 资源变更通知
支持两种类型的资源：
- 文件资源：从文件系统加载
- 内容资源：通过函数动态生成
提示词服务
接口：IMCPPromptService
实现：MCPPromptService
功能：
- 提示词注册和管理
- 提示词模板渲染（支持
{{变量名}}占位符） - 查询提示词列表
- 提示词变更通知
3. 路由层
MCPRouter 方法：路由器
- 将 MCP 方法名称映射到处理函数
- 支持中间件机制
- 统一错误处理
MCPRequestDispatcher：请求分配器
- 解析客户端请求
- 路由到相应的处理器
- 生成响应消息
MCPContext：请求上下文
- 封装请求信息
- 提供会话信息访问
- 传递请求参数
4. 消息层
MCPMessage 基本消息类别
- 封装 MCP 协议消息格式
- 支持三种消息类型：请求、响应和通知
Mcpserver-sssage：服务器消息
- 服务器端消息封装
- 支持错误响应生成
MCPMessageSender：消息发送器
- 统一的消息接口
- 处理消息序列化
- 管理连接状态
5. 传输层
MCPHttpTransport HTTP 传输实现
- 基于 Qt 实现 QTcpServer
- 支持 HTTP/1.1 协议
- 线程池管理连接
- 支持高并发请求处理
MCPHttpConnection HTTP 连接管理
- 管理单个 HTTP 连接
- 解析 HTTP 请求
- 构建 HTTP 响应
6. 配置层
IMCPServerConfig：配置接口 MCPServerConfig：配置实现
功能：
- 服务器配置管理（端口、名称、版本等）
- 从目录加载配置（支持 Tools、Resources、Prompts 子目录）
- 将配置保存到目录
配置文件结构：
MCPServerConfig/
├── ServerConfig.json # 主配置文件
├── Tools/ # 工具配置目录
│ ├── calculator.json
│ └── ...
├── Resources/ # 资源配置目录
│ └── ...
└── Prompts/ # 提示词配置目录
└── ...
快速开始
1. 基本用法
方法 1：使用自动启动（推荐）
#include <QCoreApplication>
#include "IMCPServer.h"
#include "MyExampleHandler.h"
int main(int argc, char *argv[])
{
QCoreApplication app(argc, argv);
// 创建工具处理器（必须创建，MCPAutoServer 会通过 objectName 找到它）
MyExampleHandler* pHandler = new MyExampleHandler(qApp);
pHandler->setObjectName("MyExampleHandler");
// 自动启动服务器（从 MCPServerConfig 目录加载配置）
StartAutoMCPServer();
return app.exec();
}
方法 2：手动创建和配置
#include <QCoreApplication>
#include "IMCPServer.h"
int main(int argc, char *argv[])
{
QCoreApplication app(argc, argv);
// 创建服务器实例
auto pServer = IMCPServer::createServer();
// 配置服务器
auto pConfig = pServer->getConfig();
pConfig->setPort(8888);
pConfig->setServerName("MyServer");
// 注册工具
auto pToolService = pServer->getToolService();
QJsonObject inputSchema = {
{"type", "object"},
{"properties", QJsonObject{
{"name", QJsonObject{{"type", "string"}}}
}}
};
QJsonObject outputSchema = {
{"type", "object"},
{"properties", QJsonObject{
{"result", QJsonObject{{"type", "string"}}}
}}
};
pToolService->add("greet", "Greet Tool", "一个问候工具",
inputSchema, outputSchema,
[]() -> QJsonObject {
QJsonObject result;
result["content"] = QJsonArray{QJsonObject{{"type", "text"}, {"text", "Hello!"}}};
return result;
});
// 启动服务器
pServer->start();
return app.exec();
}
2. 创建工具处理器
工具处理器是一个继承自 QObject 的类，包含用于处理工具调用的槽函数：
// MyExampleHandler.h
#pragma once
#include <QObject>
#include <QJsonObject>
class MyExampleHandler : public QObject
{
Q_OBJECT
public:
explicit MyExampleHandler(QObject* parent = nullptr);
public slots:
// 工具处理方法：参数类型必须与 inputSchema 匹配
QJsonObject calculateOperation(double a, double b, const QString& operation);
// 返回值必须是 QJsonObject，符合 outputSchema
};
// MyExampleHandler.cpp
#include "MyExampleHandler.h"
MyExampleHandler::MyExampleHandler(QObject* parent)
: QObject(parent)
{
// 设置属性，让 MCPAutoServer 能够找到这个处理器
setProperty("MPCToolHandlerName", "MyExampleHandler");
}
QJsonObject MyExampleHandler::calculateOperation(double a, double b, const QString& operation)
{
QJsonObject result;
double value = 0;
if (operation == "add") {
value = a + b;
} else if (operation == "subtract") {
value = a - b;
} else if (operation == "multiply") {
value = a * b;
} else if (operation == "divide") {
value = b != 0 ? a / b : 0;
}
result["operands"] = QJsonArray{a, b};
result["operation"] = operation;
result["result"] = value;
result["success"] = true;
result["timestamp"] = QDateTime::currentDateTimeUtc().toString(Qt::ISODate);
return result;
}
3. 示例配置文件
ServerConfig.json
{
"port": 5555,
"serverInfo": {
"name": "MyServer",
"title": "我的 MCP 服务器",
"version": "1.0.0"
},
"instructions": "这是一个示例 MCP 服务器"
}
Tools/calculator.json
{
"name": "calculator",
"title": "计算器",
"description": "支持基本数学运算的计算器工具",
"execHandler": "MyExampleHandler",
"execMethod": "calculateOperation",
"inputSchema": {
"type": "object",
"properties": {
"a": {
"type": "number",
"description": "第一个数字"
},
"b": {
"type": "number",
"description": "第二个数字"
},
"operation": {
"type": "string",
"description": "操作类型",
"enum": ["add", "subtract", "multiply", "divide"]
}
},
"required": ["a", "b", "operation"]
},
"outputSchema": {
"type": "object",
"properties": {
"result": {
"type": "number",
"description": "计算结果"
},
"success": {
"type": "boolean",
"description": "操作是否成功"
}
}
}
}
配置文件详细解释
配置文件目录结构
MCP Server 使用目录结构来组织配置文件，默认配置目录为 MCPServerConfig：
MCPServerConfig/
├── ServerConfig.json # 主配置文件（必需）
├── Tools/ # 工具配置目录（可选）
│ ├── calculator.json
│ ├── my_tool.json
│ └── ...
├── Resources/ # 资源配置目录（可选）
│ ├── config_file.json
│ ├── wrapper_example.json
│ └── ...
└── Prompts/ # 提示词配置目录（可选）
├── code_review.json
├── generate_api_doc.json
└── ...
1. 主配置文件 (ServerConfig.json)
主配置文件定义了服务器的基本信息和操作参数。
字段描述
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
port | 数字 | 是 | 服务器监听端口号（1-65535） |
serverInfo | 对象 | 是 | 服务器信息对象 |
serverInfo.name | 字符串 | 是 | 服务器名称（标识符，建议使用小写字母和连字符） |
serverInfo.title | 字符串 | 是 | 服务器显示标题 |
serverInfo.version | 字符串 | 是 | 服务器版本号（遵循语义版本规范） |
instructions | 字符串 | 否 | 服务器使用说明（可选，用于向客户端描述服务器功能） |
完整示例
{
"port": 5555,
"serverInfo": {
"name": "mcp-x-server",
"title": "MCP X 服务器示例",
"version": "1.0.0"
},
"instructions": "这是一个示例 MCP 服务器，提供了计算器工具、配置资源访问和代码审查提示词等功能。"
}
2. 工具配置文件 (Tools/*.json)
工具配置文件定义了服务器提供的工具，每个工具对应一个 JSON 文件。
字段描述
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
name | 字符串 | 是 | 工具名称（唯一标识符，建议使用小写字母和下划线） |
title | 字符串 | 是 | 工具显示标题 |
description | 字符串 | 是 | 工具功能描述 |
execHandler | 字符串 | 是 | 处理器对象名称（必须与代码中的 QOarget 的 objectName 或 MPCToolHandlerName 属性匹配） |
execMethod | 字符串 | 是 | 方法名称（在处理器类中的 public slots 方法名称） |
inputSchema | 对象 | 是 | 输入参数 JSON Schema（定义工具输入参数的结构和类型） |
outputSchema | 对象 | 是 | 输出结果 JSON Schema（定义工具返回值的结构和类型） |
annotations | 对象 | 否 | 工具注释（可选，用于扩展元数据） |
annotations.audience | 数组 | 否 | 目标受众（例如 ["user", "assistant"]） |
annotations.priority | 数字 | 否 | 优先级（0.0-1.0） |
annotations.lastModified | 字符串 | 否 | 最后修改时间（ISO 8601 格式） |
InputSchema 和 outputSchema
这两个字段遵循 JSON Schema 规范，用于定义工具的参数和返回值结构。
InputSchema 示例：
{
"type": "object",
"properties": {
"a": {
"type": "number",
"description": "第一个数字"
},
"b": {
"type": "number",
"description": "第二个数字"
},
"operation": {
"type": "string",
"description": "操作类型",
"enum": ["add", "subtract", "multiply", "divide"]
}
},
"required": ["a", "b", "operation"]
}
OutputSchema 示例：
{
"type": "object",
"description": "计算器操作结果",
"properties": {
"operands": {
"type": "array",
"description": "参与运算的操作数",
"items": {
"type": "number"
}
},
"operation": {
"type": "string",
"description": "执行的操作"
},
"result": {
"type": "number",
"description": "计算结果"
},
"success": {
"type": "boolean",
"description": "操作是否成功"
},
"timestamp": {
"type": "string",
"description": "操作时间戳"
}
},
"required": ["operands", "operation", "result", "success", "timestamp"]
}
工具处理器方法签名要求
工具处理方法必须满足以下要求：
- 方法必须是
public slots：使用 Qt 的元对象系统 - 参数类型匹配：方法参数类型必须与
inputSchema中定义的类型匹配- JSON Schema
number→ C++double或int - JSON Schema
string→ C++QString - JSON Schema
boolean→ C++bool - JSON Schema
array→ C++QJsonArray - JSON Schema
object→ C++QJsonObject
- JSON Schema
- 返回值类型：必须返回
QJsonObject并且结构符合outputSchema
示例方法签名：
// 对应上面的 inputSchema
QJsonObject calculateOperation(double a, double b, const QString& operation);
完整示例
{
"name": "calculator",
"title": "计算器",
"description": "支持基本数学运算的计算器工具（加、减、乘、除）",
"execHandler": "MyExampleHandler",