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

功能：

• 工具注册和管理
• 工具调用执行
• 工具列表查询
• 工具变更通知

支持两种注册方式：

1. 功能性注册：使用 std::function 注册工具处理函数
2. 对象方法注册：绑定槽函数到 QOarget

资源服务

接口：IMCPResourceService 实现：MCPResourceService

功能：

• 资源注册和管理
• 资源内容读取
• 资源列表查询
• 资源变更通知

支持两种类型的资源：

1. 文件资源：从文件系统加载
2. 内容资源：通过函数动态生成

提示词服务

接口：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"]
}

工具处理器方法签名要求

工具处理方法必须满足以下要求：

1. 方法必须是 public slots：使用 Qt 的元对象系统
2. 参数类型匹配：方法参数类型必须与 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
3. 返回值类型：必须返回 QJsonObject 并且结构符合 outputSchema

示例方法签名：

// 对应上面的 inputSchema
QJsonObject calculateOperation(double a, double b, const QString& operation);

完整示例

{
    "name": "calculator",
    "title": "计算器",
    "description": "支持基本数学运算的计算器工具（加、减、乘、除）",
    "execHandler": "MyExampleHandler",