内容
# cxxmcp 示例
[](https://isocpp.org/)
[](https://cmake.org/)
[](https://modelcontextprotocol.io/)
[](https://github.com/caomengxuan666/cxxmcp)
`cxxmcp` C++ MCP SDK 的可复制应用程序样式示例和下游验证。
该仓库故意与 SDK 源代码树分开。它像应用程序作者一样使用 `cxxmcp`：通过 CMake 目标、公共头文件、真正的可执行文件和端到端探针。
## 仓库角色
使用此仓库的原因：
- 复制一个小型、有效的 C++ MCP 程序，并将其适配到应用程序中。
- 从 stdio 服务器通过 HTTP 客户端、任务取消、类型化工具、订阅、回调和传输适配器学习 SDK。
- 验证已安装或相邻的 `cxxmcp` SDK 是否可被下游 CMake 项目使用。
- 在隔离的 SDK 单元测试之外，锻炼现实的 MCP 客户端/服务器行为。
## 示例优先
`examples/` 目录树是主要入口。它包含可复制的程序；每个程序都构建为一个可执行文件，目标名称为 `cxxmcp_`，并且足够小，可以作为下游应用程序代码阅读。
`validation/` 目录树有不同的任务：下游探针、矩阵、烟雾测试和一致性测试，以证明 SDK 消费和行为跨公共功能系列。参见 [`docs/validation.md`](docs/validation.md) 以获取完整的验证地图。
从这里开始：
- `examples/basic/minimal_stdio_server.cpp`：最小的有用_stdio_服务器，包含初始化、一个工具、一个提示、一个资源和原始健康请求。
- `examples/basic/typed_tool_server.cpp`：紧凑的类型化工具对象，包含反射参数/结果结构体和 `ToolContext` 访问。
- `examples/servers/workspace_server.cpp`：现实的只读工作区服务器，包含工具、提示、资源、模板、完成、采样、日志记录和任务能力操作。
- `examples/servers/git_server.cpp`：有界的只读 Git 状态、日志和差异工具。
- `examples/servers/sqlite_server.cpp`：有界的只读 SQLite 架构、表和查询工具，依赖于 `sqlite3` 命令（如果可用）。
- `examples/servers/cmake_ctest_server.cpp`：CMake 预设和 CTest 检查工具，测试执行由显式 `allow_run` 参数控制。
- `examples/servers/json_file_server.cpp`：有界的 JSON 摘要和 JSON 指针查找工具。
- `examples/servers/csv_server.cpp`：有界的 CSV 摘要和样本工具。
- `examples/servers/compile_commands_server.cpp`：有界的 `compile_commands.json` 摘要和源命令查找工具。
- `examples/servers/jsonl_server.cpp`：有界的 JSON Lines 摘要和样本工具。
- `examples/servers/log_triage_server.cpp`：事件/日志分类服务器，包含类型化工具、提示、资源、完成和任务能力日志分析。
- `examples/clients/streamable_http_client.cpp`：独立的 `ClientPeer` + `Service` 流式 HTTP 客户端。
- `examples/clients/elicitation_client.cpp`：客户端诱导处理程序。
- `examples/transports/graceful_shutdown.cpp`：协作取消和幂等 `ServerPeer` + `Service` 关闭。
- `examples/clients/timeout_cancellation_client.cpp`：请求超时、取消令牌、取消通知和幂等 `RequestHandle::cancel()`。
## 可执行文件
### 可复制示例
- `cxxmcp_minimal_stdio_server`：最小的有用_stdio_服务器。它显示初始化、一个 JSON 工具、一个提示、一个资源和原始健康请求。
- `cxxmcp_typed_tool_server`：紧凑的类型化_stdio_服务器。它显示工具对象、`CXXMCP_REFLECT_SELF`、生成的输入/输出模式和 `ToolContext` 访问。
- `cxxmcp_streamable_http_client`：独立的 `ClientPeer` + `Service` 流式 HTTP 客户端。传递端点 URI 或使用默认 `http://127.0.0.1:3000/mcp`。
- `cxxmcp_elicitation_client`：客户端诱导处理程序示例，接受或拒绝 `elicitation/create` 请求。
- `cxxmcp_graceful_shutdown`：小型 `ServerPeer` + `Service` 生命周期探针，显示协作取消和幂等关闭。
- `cxxmcp_timeout_cancellation_client`：专注的 `ClientPeer` 示例，显示请求超时、外部取消令牌、取消通知和幂等 `RequestHandle::cancel()`。
- `cxxmcp_workspace_server`：用于代码/工作区检查的_stdio_ MCP 服务器。它提供有界文件读取、正则表达式搜索、工作区摘要、审查提示、完成建议、样本生成、摘要资源、文件 URI 模板和任务能力只读工具。
- `cxxmcp_git_server`：用于有界只读 Git 检查的_stdio_ MCP 服务器。它公开状态、日志和差异工具，带有结构化输出。
- `cxxmcp_sqlite_server`：用于有界只读 SQLite 检查的_stdio_ MCP 服务器。它在运行时使用 `sqlite3` 命令，并报告工具错误。
- `cxxmcp_cmake_ctest_server`：用于 CMake/CTest 检查的_stdio_ MCP 服务器。它读取 `CMakePresets.json`，列出构建目录中的测试，并仅在 `allow_run=true` 时运行选定的 CTest 测试。
- `cxxmcp_json_file_server`：用于有界 JSON 文件检查的_stdio_ MCP 服务器。它总结根结构并通过 JSON 指针读取值。
- `cxxmcp_csv_server`：用于有界 CSV 检查的_stdio_ MCP 服务器。它总结列并返回小行样本。
- `cxxmcp_compile_commands_server`：用于有界 `compile_commands.json` 检查的_stdio_ MCP 服务器。它总结翻译单元并通过源路径文本查找编译命令。
- `cxxmcp_jsonl_server`：用于有界 JSON Lines 检查的_stdio_ MCP 服务器。它总结行有效性、对象键和小行样本。
- `cxxmcp_log_triage_server`：用于事件/日志分类的_stdio_ MCP 服务器。它总结严重程度计数、提取匹配行、公开播放簿资源、渲染事件报告提示、提供完成建议，并支持任务能力日志工具。
### 验证和一致性
- `cxxmcp_sdk_smoke`：工具、提示、资源、模板、完成、采样、日志记录、原始请求、通知和任务支持的进程内 `ClientPeer`/`ServerPeer` 环回覆盖。
- `cxxmcp_process_stdio_client_probe`：启动最小服务器作为子进程，并验证进程_stdio_客户端使用情况。
- `cxxmcp_conformance_everything_server`：`modelcontextprotocol/conformance` 服务器模式测试的流式 HTTP 服务器。
- `cxxmcp_conformance_everything_client`：`modelcontextprotocol/conformance` 客户端模式测试的命令行客户端。
- 矩阵目标涵盖回调、取消、异步请求、策略钩子、订阅、分页、任务取消、直接 HTTP/SSE、HTTP 身份验证精简版、传输适配器、本机服务器传输、处理程序接口、丰富内容、网关运行时和运行时服务。
验证目标故意不调用每个重载或每个 DTO 序列化器。它们涵盖每个公共功能系列，具有代表性的下游代码，这些代码必须在 SDK 仓库之外编译和运行。
## 构建
从此目录：
```powershell
cmake -S . -B build
cmake --build build --config Release
ctest --test-dir build -C Release --output-on-failure
```
默认情况下，构建会使用相邻的 SDK 源代码树 `../MCPServer.cpp`。要验证已安装的 SDK 包：
```powershell
cmake -S . -B build-installed -DCXXMCP_EXAMPLES_USE_ADJACENT_SDK=OFF -DCMAKE_PREFIX_PATH=<install-prefix>
cmake --build build-installed --config Release
```
相邻源代码构建启用网关目标，以便 HTTP/运行时和应用程序服务示例被编译和测试。如果已安装的软件包不包括 `cxxmcp::gateway`，则网关示例将被 CMake 跳过。
CI 运行两种模式。已安装的软件包作业首先将 SDK 安装到临时前缀，然后使用 `CXXMCP_EXAMPLES_USE_ADJACENT_SDK=OFF` 配置此仓库，证明正常的 `find_package(cxxmcp CONFIG REQUIRED)` 消费，而不是依赖 `add_subdirectory`。
对于在本地 SDK 检出期间开发的聚焦检查：
```powershell
cmake -S . -B build -DCXXMCP_EXAMPLES_SDK_SOURCE_DIR=C:/Users/cmx/repo/MCPServer.cpp
cmake --build build --config Release --target cxxmcp_http_auth_lite_matrix cxxmcp_client_inbound_cancellation_matrix cxxmcp_task_cancel_matrix
ctest --test-dir build -C Release -R "cxxmcp_(http_auth_lite_matrix|client_inbound_cancellation_matrix|task_cancel_matrix)" --output-on-failure
```
`cxxmcp_http_auth_lite_matrix` 是最小的可复制 HTTP 身份验证精简版流程：服务器安装 `AuthProvider`、`HttpTransportOptions::auth_challenge` 和 `ServerPeer`/`mcp::serve`；客户端使用 `Client::StreamableHttpEndpoint::auth_header = "valid-token"` 通过 `ClientPeer::connect_streamable_http`，SDK 将其发送为 `Authorization: Bearer valid-token`。
## MCP 一致性
一致性测试套件单独维护在 `modelcontextprotocol/conformance` 处。简短的服务器端流程：
```powershell
cmake --build build --target cxxmcp_conformance_everything_server --config Release
.\build\cxxmcp_conformance_everything_server.exe 3000
```
然后从一致性检查中运行活动服务器套件：
```powershell
npm start -- server --url http://127.0.0.1:3000/mcp --suite active --verbose
```
当前活动套件验证有 40 个通过检查，0 个失败。最新的保存的所有套件服务器运行有 108 个通过检查，1 个兼容模式失败，客户端所有套件运行有 428 个通过检查，8 个失败检查。参见 [`docs/validation.md`](docs/validation.md) 和 [`CONFORMANCE_STATUS.md`](CONFORMANCE_STATUS.md) 以获取确切的命令、已知异常和原始 stderr 注释。
## 代码配置
将这些配置保持在存储库本地配置文件中，以便从 Codex 测试它们，而不会污染全局 Codex 配置：
```toml
[mcp_servers.cxxmcp-workspace]
command = 'C:\Users\cmx\repo\cxxmcp-examples\build\cxxmcp_workspace_server.exe'
args = ['C:\Users\cmx\repo\MCPServer.cpp']
[mcp_servers.cxxmcp-log-triage]
command = 'C:\Users\cmx\repo\cxxmcp-examples\build\cxxmcp_log_triage_server.exe'
[mcp_servers.cxxmcp-git]
command = 'C:\Users\cmx\repo\cxxmcp-examples\build\cxxmcp_git_server.exe'
[mcp_servers.cxxmcp-sqlite]
command = 'C:\Users\cmx\repo\cxxmcp-examples\build\cxxmcp_sqlite_server.exe'
[mcp_servers.cxxmcp-cmake-ctest]
command = 'C:\Users\cmx\repo\cxxmcp-examples\build\cxxmcp_cmake_ctest_server.exe'
[mcp_servers.cxxmcp-json-file]
command = 'C:\Users\cmx\repo\cxxmcp-examples\build\cxxmcp_json_file_server.exe'
[mcp_servers.cxxmcp-csv]
command = 'C:\Users\cmx\repo\cxxmcp-examples\build\cxxmcp_csv_server.exe'
[mcp_servers.cxxmcp-compile-commands]
command = 'C:\Users\cmx\repo\cxxmcp-examples\build\cxxmcp_compile_commands_server.exe'
[mcp_servers.cxxmcp-jsonl]
command = 'C:\Users\cmx\repo\cxxmcp-examples\build\cxxmcp_jsonl_server.exe'
```
## 学习路径
1. 从 `examples/basic/minimal_stdio_server.cpp` 开始，查看紧凑的_stdio_服务器形状和换行符分隔的传输。
2. 阅读 `examples/basic/typed_tool_server.cpp` 获取类型化工具路径：反射 DTO、生成的模式、工具对象创作和 `ToolContext`。
3. 阅读 `examples/clients/streamable_http_client.cpp` 和 `examples/transports/process_stdio_client_probe.cpp` 获取 `ClientPeer` + `Service` 在网络和子进程传输上的信息。
4. 移至 `examples/servers/workspace_server.cpp`、`examples/servers/git_server.cpp`、`examples/servers/sqlite_server.cpp`、`examples/servers/cmake_ctest_server.cpp` 和 `examples/servers/log_triage_server.cpp` 获取类型化参数/结果、模式、资源、提示、完成、采样、日志记录、原始请求、任务支持和有界的原生工具检查。阅读 `examples/servers/json_file_server.cpp`、`examples/servers/csv_server.cpp`、`examples/servers/compile_commands_server.cpp` 和 `examples/servers/jsonl_server.cpp` 获取紧凑的纯 C++ 文件检查服务器。
5. 阅读 `validation/matrices/client_callbacks_matrix.cpp`、`validation/matrices/client_inbound_cancellation_matrix.cpp` 和 `examples/clients/elicitation_client.cpp` 获取客户端请求和通知处理程序，不作为普通工具，包括取消感知传入回调。
6. 阅读 `examples/transports/graceful_shutdown.cpp`、`validation/matrices/transport_stdio_matrix.cpp` 和 `examples/advanced/native_server_transport_matrix.cpp` 获取服务关闭、角色通用传输和自定义服务器传输。
7. 阅读 `examples/clients/timeout_cancellation_client.cpp` 获取专注的超时和取消行为，然后 `validation/matrices/async_request_matrix.cpp` 获取请求元数据、异步帮助程序、列表-全部帮助程序和类型化完成帮助程序。
8. 阅读 `validation/matrices/policy_subscription_matrix.cpp` 和 `validation/matrices/extension_plugin_adapter_matrix.cpp` 获取服务器策略钩子、订阅、插件 SDK 和适配器。
9. 阅读 `examples/advanced/server_to_client_context_matrix.cpp`、`validation/matrices/handler_interface_matrix.cpp`、`examples/advanced/native_server_transport_matrix.cpp` 和 `examples/advanced/rich_content_cancellation_matrix.cpp` 获取高级对等方回调、处理程序合同、自定义传输、丰富内容和取消。
10. 阅读 `examples/http/direct_http_legacy_sse_matrix.cpp`、`examples/http/http_auth_lite_matrix.cpp`、`validation/matrices/pagination_cursor_matrix.cpp`、`validation/matrices/client_subscription_helper_matrix.cpp` 和 `validation/matrices/task_cancel_matrix.cpp` 获取直接 HTTP/SSE、HTTP 身份验证精简版、分页、订阅和任务取消。
11. 阅读 `validation/matrices/transport_adapter_matrix.cpp` 获取具体到合同的传输桥接器在客户端和服务器角色上。
12. 阅读 `validation/matrices/http_gateway_runtime_matrix.cpp` 和 `validation/matrices/runtime_services_matrix.cpp` 获取流式 HTTP、网关运行时、持久化应用商店、客户端配置、就绪状态/状态和暴露管理。
## 手动 JSON-RPC 探针
_stdio_传输是换行符分隔的 JSON-RPC。发送 `initialize` 后，您可以直接使用非工具的 MCP 方法进行练习。
列出提示：
```json
{"jsonrpc":"2.0","id":2,"method":"prompts/list","params":{}}
```
渲染提示：
```json
{"jsonrpc":"2.0","id":3,"method":"prompts/get","params":{"name":"workspace.review","arguments":{"goal":"check release readiness"}}}
```
读取资源：
```json
{"jsonrpc":"2.0","id":4,"method":"resources/read","params":{"uri":"workspace://summary"}}
```
列出资源模板：
```json
{"jsonrpc":"2.0","id":5,"method":"resources/templates/list","params":{}}
```
请求补全：
```json
{"jsonrpc":"2.0","id":6,"method":"completion/complete","params":{"prefix":"workspace."}}
```
请求服务器端采样：
```json
{"jsonrpc":"2.0","id":7,"method":"sampling/createMessage","params":{"prompt":"summarize the workspace"}}
```
更改日志级别：
```json
{"jsonrpc":"2.0","id":8,"method":"logging/setLevel","params":{"level":"debug"}}
```
按任务调用工具：
```json
{"jsonrpc":"2.0","id":9,"method":"tools/call","params":{"name":"workspace.scan","arguments":{"max_files":100},"task":{"ttl":60}}}
```
调用只读 Git 工具：
```json
{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"git.status","arguments":{"repo":"C:/Users/cmx/repo/MCPServer.cpp","max_bytes":65536}}}
```
调用只读 SQLite 查询：
```json
{"jsonrpc":"2.0","id":11,"method":"tools/call","params":{"name":"sqlite.query","arguments":{"database":"C:/path/to/app.db","sql":"SELECT name FROM sqlite_master WHERE type = 'table'","max_rows":50}}}
```
列出 CTest 测试：
```json
{"jsonrpc":"2.0","id":12,"method":"tools/call","params":{"name":"ctest.list","arguments":{"build_dir":"C:/Users/cmx/repo/cxxmcp-examples/build-reorg-check"}}}
```
读取 JSON 指针：
```json
{"jsonrpc":"2.0","id":13,"method":"tools/call","params":{"name":"json.pointer","arguments":{"path":"C:/Users/cmx/repo/cxxmcp-examples/docs/validation.md","pointer":""}}}
```
采样 CSV 文件：
```json
{"jsonrpc":"2.0","id":14,"method":"tools/call","params":{"name":"csv.sample","arguments":{"path":"C:/path/to/data.csv","rows":10}}}
```
查找编译命令：
```json
{"jsonrpc":"2.0","id":15,"method":"tools/call","params":{"name":"compile_commands.find","arguments":{"path":"C:/Users/cmx/repo/cxxmcp-examples/build-reorg-check/compile_commands.json","file_contains":"workspace_server.cpp"}}}
```
总结 JSON Lines：
```json
{"jsonrpc":"2.0","id":16,"method":"tools/call","params":{"name":"jsonl.summary","arguments":{"path":"C:/path/to/events.jsonl","max_lines":1000}}}
```
## 使用 MCP 客户端运行
工作区服务器：
```json
{
"mcpServers": {
"cxxmcp-workspace": {
"command": "C:/Users/cmx/repo/cxxmcp-examples/build/Release/cxxmcp_workspace_server.exe",
"args": ["C:/Users/cmx/repo/MCPServer.cpp"]
}
}
}
```
日志分类服务器：
```json
{
"mcpServers": {
"cxxmcp-log-triage": {
"command": "C:/Users/cmx/repo/cxxmcp-examples/build/Release/cxxmcp_log_triage_server.exe"
}
}
}
```
Git 服务器：
```json
{
"mcpServers": {
"cxxmcp-git": {
"command": "C:/Users/cmx/repo/cxxmcp-examples/build/Release/cxxmcp_git_server.exe"
}
}
}
```
SQLite 服务器：
```json
{
"mcpServers": {
"cxxmcp-sqlite": {
"command": "C:/Users/cmx/repo/cxxmcp-examples/build/Release/cxxmcp_sqlite_server.exe"
}
}
}
```
CMake/CTest 服务器：
```json
{
"mcpServers": {
"cxxmcp-cmake-ctest": {
"command": "C:/Users/cmx/repo/cxxmcp-examples/build/Release/cxxmcp_cmake_ctest_server.exe"
}
}
}
```
JSON 文件服务器：
```json
{
"mcpServers": {
"cxxmcp-json-file": {
"command": "C:/Users/cmx/repo/cxxmcp-examples/build/Release/cxxmcp_json_file_server.exe"
}
}
}
```
CSV 服务器：
```json
{
"mcpServers": {
"cxxmcp-csv": {
"command": "C:/Users/cmx/repo/cxxmcp-examples/build/Release/cxxmcp_csv_server.exe"
}
}
}
```
编译命令服务器：
```json
{
"mcpServers": {
"cxxmcp-compile-commands": {
"command": "C:/Users/cmx/repo/cxxmcp-examples/build/Release/cxxmcp_compile_commands_server.exe"
}
}
}
```
JSON Lines 服务器：
```json
{
"mcpServers": {
"cxxmcp-jsonl": {
"command": "C:/Users/cmx/repo/cxxmcp-examples/build/Release/cxxmcp_jsonl_server.exe"
}
}
}
```
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器