使用说明

项目简介

oatpp-mcp 是一个使用 C++ Oat++ Web 框架开发的 Model Context Protocol (MCP) 服务器库。它旨在帮助开发者快速搭建 MCP 后端服务，以便 LLM 应用能够安全、高效地访问上下文信息和外部功能。该库特别强调了 API 工具的自动生成，能够将现有的 Oat++ API Controller 快速转换为 LLM 可调用的工具。

主要功能点

资源 (Resources) 管理: 支持托管和管理各种类型的资源，例如文件、数据库记录等，并允许 LLM 客户端通过 URI 访问这些资源。
工具 (Tools) 注册与执行: 允许注册自定义工具，扩展 LLM 的能力，例如日志记录工具、API 接口调用工具等。特别支持从 Oat++ API Controller 自动生成工具。
Prompt 模板 (Prompts) 定义与渲染: 支持定义和管理 Prompt 模板，为 LLM 提供可定制的交互模式，例如代码审查 Prompt。
传输协议: 支持 STDIO 和 HTTP SSE 两种传输协议，方便不同场景下的部署和使用。
服务器特性: 实现了 MCP 服务器规范中的 Prompts, Resources, Tools 等核心功能，并提供会话管理和能力声明。
API 工具自动生成: 可以根据现有的 Oat++ API Controller 自动生成对应的 Tool，极大地简化了将现有 API 集成到 MCP 服务器的过程。

安装步骤

安装 Oat++ 框架: 确保已安装 Oat++ 框架及其依赖，参考 Oat++ Repository 的安装指南。

克隆 oatpp-mcp 仓库:

git clone https://github.com/oatpp/oatpp-mcp.git
cd oatpp-mcp

编译和安装 oatpp-mcp 模块:

mkdir build && cd build
cmake ..
make install

服务器配置

MCP 客户端需要配置 MCP 服务器的启动命令 (command) 及其参数 (args) 以建立连接。以下是基于 oatpp-mcp 仓库信息生成的服务器配置示例（JSON 格式）：

{
  "serverName": "oatpp-mcp-server",
  "command": "/path/to/oatpp-mcp-executable",  // 请替换为 oatpp-mcp 可执行文件的实际路径，通常在 build 目录下
  "args": [],  // oatpp-mcp 服务器可执行文件通常不需要额外的启动参数
  "transport": "stdio" // 或者 "sse"，根据客户端和服务器的配置选择传输协议
}

配置参数注释:

'serverName': 服务器名称，可以自定义，用于在客户端标识服务器。
'command': 必须配置。指向编译后的 oatpp-mcp 服务器可执行文件的绝对路径。编译后通常在 'build' 目录下，具体路径需要根据你的编译环境确定。
'args': 启动参数列表，对于 oatpp-mcp 示例，通常为空数组 '[]'。如果服务器需要额外的配置参数，可以在这里添加。
'transport': 必须配置。指定客户端与服务器通信的传输协议。
- '"stdio"': 使用标准输入输出流 (STDIO) 进行通信。适用于本地调试或简单的命令行交互场景。
- '"sse"': 使用 HTTP Server-Sent Events (SSE) 协议通过 HTTP 进行通信。需要服务器以 HTTP SSE 模式运行，并配置相应的 HTTP 服务端口。

选择传输协议:

STDIO: 配置 '"transport": "stdio"' 并确保 MCP 客户端配置为使用 STDIO 连接。服务器端启动时，需要使用 'server.stdioListen()' 方法。
SSE: 配置 '"transport": "sse"' 并确保 MCP 客户端配置为使用 SSE 连接和正确的服务器地址 (例如 'http://localhost:3001/mcp/sessions/{sessionId}')。服务器端启动时，需要将 'server.getSseController()' 添加到 HTTP 服务器的路由中，并运行 HTTP 服务器，例如示例中的 'runHttpServer(server)' 函数。

基本使用方法

启动 MCP 服务器:
- STDIO 模式: 编译并运行 'oatpp-mcp' 项目，确保服务器端代码中调用了 'server.stdioListen()'。
- SSE 模式: 编译并运行 'oatpp-mcp' 项目，确保服务器端代码中将 'server.getSseController()' 添加到了 HTTP 路由，并运行了 HTTP 服务器 (例如，通过 'runHttpServer(server)' 启动)。
配置 MCP 客户端:
- 根据你选择的传输协议 (STDIO 或 SSE)，配置 MCP 客户端连接到 oatpp-mcp 服务器。你需要提供服务器的启动命令和参数 (如上面的 JSON 配置示例)。
与 MCP 服务器交互:
- 客户端连接成功后，即可按照 MCP 协议规范，向服务器发送 JSON-RPC 请求，例如：
  - 获取服务器能力 ('initialize' 方法)
  - 列出可用工具 ('tools/list' 方法)
  - 调用工具 ('tools/call' 方法)
  - 列出可用 Prompt ('prompts/list' 方法)
  - 调用 Prompt ('prompts/get' 方法)
  - 读取资源 ('resources/read' 方法)
  - 等等。
- 服务器会根据请求，返回 JSON-RPC 响应或发送通知。你可以利用提供的示例代码和测试用例来了解如何添加自定义的 Prompts, Resources, 和 Tools，以及如何通过客户端与服务器进行交互。

示例代码参考:

'README.md' 中提供了 STDIO 和 SSE 模式下启动服务器的 C++ 代码示例。
'/test/oatpp-mcp/app/ServerTest.cpp' 文件中包含了更完整的服务器配置和功能测试代码，可以作为进一步学习和参考的入口。
'/test/oatpp-mcp/app/tools', '/test/oatpp-mcp/app/resources', '/test/oatpp-mcp/app/prompts' 目录下提供了示例 Tool, Resource, 和 Prompt 的实现，可以参考学习如何扩展服务器功能。

关键词