qtMCP (Natcoder)

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)                 │
└─────────────────────────────────────────────────────────┘

核心模块

1. 服务器层（IMCPServer/MCPServer）

- IMCPServer：统一的服务器接口；管理服务器生命周期（启动、停止、运行状态），并提供对三个核心服务的访问。 - MCPServer：核心服务器实现；协调组件初始化并管理传输和会话服务。 - MCPAutoServer：自动启动助手；从MCPServerConfig目录加载配置并自动绑定工具处理程序。

1. 服务层

- 工具服务（IMCPToolService/MCPToolService） - 注册和管理工具 - 执行工具调用 - 列出工具 - 工具更改通知 - 支持两种注册方法： 1. 使用std:：Function进行基于函数的注册 1. 基于QObject插槽的注册（绑定到QObject插槽） - 资源服务（IMCP资源服务/MCP资源服务） - 注册和管理资源 - 读取资源内容 - 列出资源 - 资源更改通知 - 支持资源类型： 1. 文件资源（从文件系统加载） 1. 内容资源（按功能生成） 1. 包装资源（为动态内容包装QObject） - 即时服务（IMCPPromptService/MCPPromptService） - 注册和管理提示 - 呈现提示模板（支持｛｛variable｝｝占位符） - 列出提示 - 及时更改通知

1. 路由层

- MCPRouter：将MCP方法名称映射到处理程序；支持中间件和统一的错误处理。 - MCPRequestDispatcher：解析客户端请求，将其路由到处理程序并构建响应。 - MCPContext：会话和请求参数的请求上下文包装器。

1. 消息层

- MCPMessage：基础消息；支持请求、响应和通知类型。 - MCPServerMessage：服务器端消息包装器；支持错误响应。 - MCPMessageSender：统一消息发送方；根据消息和传输类型选择合适的发送策略。

1. 传输层

- MCPHttpTransport：基于Qt QTcpServer的HTTP传输实现；支持HTTP/1.1和线程池连接处理。 - MCPHttpConnection：管理单个HTTP连接（解析请求、构建响应）。

1. 配置层

- 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中进行了翻译。）