AI导哈

MCP服务器框架

MCP Server是一个基于Qt/C++实现的MCP协议服务器框架，提供完整的MCP协议支持和HTTP传输层。

  • by natcoder
  • C++
  • 本地部署
  • 8 星标
  • 更新于
在 GitHub 查看 natcoder/qtmcp

使用说明

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目录加载配置并自动绑定工具处理程序。

  2. 服务层

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

  3. 路由层

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

  4. 消息层

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

  5. 传输层

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

  6. 配置层

    • IMCPServerConfig/MCPServerConfig：配置接口和实现。
      • 管理服务器配置（端口、名称、版本等）
      • 从目录加载配置（支持“工具”、“资源”、“提示”子目录）
      • 将配置保存到目录

配置目录结构：

MCPServerConfig/
├── ServerConfig.json      # main configuration
├── Tools/                 # tool configuration directory
│   ├── calculator.json
│   └── ...
├── Resources/             # resource configuration directory
│   └── ...
└── Prompts/               # prompts configuration directory
    └── ...

快速开始

1.基本用法

选项1——自动启动（推荐）

#include <QCoreApplication>
#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 <QCoreApplication>
#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 <QObject>
#include <QJsonObject>

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

相关 MCP