MCP服务器核心库文档
项目概述
MCP Server是模型上下文协议（MCP）服务器框架的Qt/C++实现。该框架提供了完整的MCP协议实现，并通过HTTP传输层支持MCP客户端。
主要特点
- ✅ 完整的MCP协议实现：支持MCP规范（版本2025-06-18）
- ✅ HTTP传输层：基于HTTP/1.1，支持高并发
- ✅ 三大核心服务：工具、资源、提示
- ✅ 配置驱动：支持JSON配置自动加载和启动
- ✅ 灵活的工具注册：支持函数样式和QObject插槽注册
- ✅ 中间件支持：为请求预处理提供中间件机制
- ✅ 会话管理：完整的会话生命周期管理
- ✅ 订阅通知：支持资源、工具和提示的更改通知
建筑
总体架构
┌─────────────────────────────────────────────────────────┐
│ Application Layer │
│ (MCPAutoServer / custom server implementations) │
└────────────────────┬────────────────────────────────────┘
│
┌────────────────────▼────────────────────────────────────┐
│ Server Interface Layer │
│ (IMCPServer / MCPServer) │
└────────────────────┬────────────────────────────────────┘
│
┌──────────────┼──────────────┐
│ │ │
┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼──────────┐
│ Tool Service│ │Resource │ │ Prompt Service │
│ (Tools) │ │Service │ │ (Prompts) │
└─────┬──────┘ └────┬─────┘ └────┬──────────┘
│ │ │
└──────────────┼──────────────┘
│
┌────────────────────▼────────────────────────────────────┐
│ Routing & Dispatch Layer │
│ (MCPRouter / MCPRequestDispatcher / MCPContext) │
└────────────────────┬────────────────────────────────────┘
│
┌────────────────────▼────────────────────────────────────┐
│ Message Handling Layer │
│ (MCPMessage / MCPServerMessage / MCPMessageSender) │
└────────────────────┬────────────────────────────────────┘
│
┌────────────────────▼────────────────────────────────────┐
│ Transport Layer │
│ (MCPHttpTransport / IMCPTransport) │
└─────────────────────────────────────────────────────────┘核心模块
- 服务器层（IMCPServer/MCPServer）
- IMCPServer：统一的服务器接口；管理服务器生命周期（启动、停止、运行状态），并提供对三个核心服务的访问。 - MCPServer：核心服务器实现；协调组件初始化并管理传输和会话服务。 - MCPAutoServer：自动启动助手；从MCPServerConfig目录加载配置并自动绑定工具处理程序。
- 服务层
- 工具服务（IMCPToolService/MCPToolService） - 注册和管理工具 - 执行工具调用 - 列出工具 - 工具更改通知 - 支持两种注册方法： 1. 使用std:：Function进行基于函数的注册 1. 基于QObject插槽的注册（绑定到QObject插槽） - 资源服务（IMCP资源服务/MCP资源服务） - 注册和管理资源 - 读取资源内容 - 列出资源 - 资源更改通知 - 支持资源类型： 1. 文件资源（从文件系统加载） 1. 内容资源（按功能生成） 1. 包装资源（为动态内容包装QObject） - 即时服务（IMCPPromptService/MCPPromptService） - 注册和管理提示 - 呈现提示模板（支持｛｛variable｝｝占位符） - 列出提示 - 及时更改通知
- 路由层
- MCPRouter：将MCP方法名称映射到处理程序；支持中间件和统一的错误处理。 - MCPRequestDispatcher：解析客户端请求，将其路由到处理程序并构建响应。 - MCPContext：会话和请求参数的请求上下文包装器。
- 消息层
- MCPMessage：基础消息；支持请求、响应和通知类型。 - MCPServerMessage：服务器端消息包装器；支持错误响应。 - MCPMessageSender：统一消息发送方；根据消息和传输类型选择合适的发送策略。
- 传输层
- MCPHttpTransport：基于Qt QTcpServer的HTTP传输实现；支持HTTP/1.1和线程池连接处理。 - MCPHttpConnection：管理单个HTTP连接（解析请求、构建响应）。
- 配置层
- IMCPServerConfig/MCPServerConfig：配置接口和实现。 - 管理服务器配置（端口、名称、版本等） - 从目录加载配置（支持“工具”、“资源”、“提示”子目录） - 将配置保存到目录
配置目录结构：
MCPServerConfig/
├── ServerConfig.json # main configuration
├── Tools/ # tool configuration directory
│ ├── calculator.json
│ └── ...
├── Resources/ # resource configuration directory
│ └── ...
└── Prompts/ # prompts configuration directory
└── ...快速开始
1.基本用法
选项1——自动启动（推荐）
#include
#include "IMCPServer.h"
#include "MyExampleHandler.h"
int main(int argc, char *argv[])
{
QCoreApplication app(argc, argv);
// Create the tool handler (must be created; MCPAutoServer finds it by objectName)
MyExampleHandler* pHandler = new MyExampleHandler(qApp);
pHandler->setObjectName("MyExampleHandler");
// Auto-start the server (loads configuration from MCPServerConfig directory)
StartAutoMCPServer();
return app.exec();
}选项2——手动创建和配置
#include
#include "IMCPServer.h"
int main(int argc, char *argv[])
{
QCoreApplication app(argc, argv);
// Create the server instance
auto pServer = IMCPServer::createServer();
// Configure server
auto pConfig = pServer->getConfig();
pConfig->setPort(8888);
pConfig->setServerName("MyServer");
// Register a tool
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", "A greeting tool",
inputSchema, outputSchema,
-> QJsonObject {
QJsonObject result;
result["content"] = QJsonArray{QJsonObject{{"type", "text"}, {"text", "Hello!"}}};
return result;
});
// Start server
pServer->start();
return app.exec();
}2.创建工具处理程序
工具处理程序是一个QObject派生类，它提供插槽方法来处理工具调用：
// MyExampleHandler.h
#pragma once
#include
#include
class MyExampleHandler : public QObject
{
Q_OBJECT
public:
explicit MyExampleHandler(QObject* parent = nullptr);
public slots:
// Tool handler method: parameter types must match inputSchema
QJsonObject calculateOperation(double a, double b, const QString& operation);
// Return type must be QJsonObject matching outputSchema
};（其他部分继续介绍配置文件示例、加载机制、最佳实践、处理程序解析器和其他详细文档——在README中进行了翻译。）