cxxmcp

[](LICENSE) -brightgreen.svg) -brightgreen.svg)

生产就绪的 C++17 Model Context Protocol SDK —— 直接在原生 C++ 应用中嵌入 MCP server 和 client，完整覆盖协议能力，通过跨 SDK conformance 验证。

English version: README.md

快速开始

find_package(cxxmcp CONFIG REQUIRED)
target_link_libraries(my_server PRIVATE cxxmcp::server)
target_link_libraries(my_client PRIVATE cxxmcp::client)

#include <cxxmcp/peer.hpp>
#include <cxxmcp/run.hpp>
 
int main() {
    return mcp::ServerPeer::builder()
        .name("demo-server")
        .version("1.0.0")
        .stdio()
        .tool<mcp::protocol::Json, mcp::protocol::Json>("echo",
            [](const mcp::protocol::Json& input) {
                return mcp::protocol::Json{{"echo", input}};
            })
        .run();
}

// Client 端
#include <cxxmcp/peer.hpp>
#include <cxxmcp/run.hpp>
 
int main() {
    int status = 0;
    const auto run_status = mcp::ClientPeer::builder()
        .streamable_http("http://127.0.0.1:3000/mcp")
        .run([&status](auto& svc) {
            if (!svc.peer().initialize().has_value() ||
                !svc.peer().notify_initialized().has_value() ||
                !svc.peer().list_all_tools().has_value() ||
                !svc.peer()
                     .call_tool("echo",
                                mcp::protocol::Json{{"value", "hello"}})
                     .has_value()) {
                status = 1;
            }
        });
    return run_status == 0 ? status : run_status;
}

能力覆盖

领域	状态
Protocol / JSON-RPC	Typed models、序列化、initialize 校验、raw escape hatch
Server SDK	tool/prompt/resource registry、typed handler、task-aware call、notification
Client SDK	HTTP、stdio、process stdio、async helper、roots、sampling、elicitation、tasks
Transports	stdio、process stdio、Streamable HTTP（有状态 session）、legacy SSE 兼容、WebSocket（自动重连）
Packaging	CMake find_package、Conan 2、vcpkg overlay、FetchContent / CPM
Peer/Service boundary	RMCP 风格 role-aware Peer<Role> 和 Service<Role>

协议覆盖： tool、prompt、resource、resource template、completion、logging、roots、sampling、elicitation、task lifecycle、progress、cancellation，以及用于 vendor extension 的 raw JSON-RPC escape hatch。

Conformance： 基于官方 modelcontextprotocol/conformance runner（--suite all）验证。

	cxxmcp	RMCP
Server	109/110 (99%)	48/95 (51%)
Client	448/448 (100%)	— (runner 崩溃)

完整结果见 conformance evidence。

能力快照

cxxmcp 是具备完整协议覆盖、跨 SDK conformance 验证和多种 transport 选项的 release-candidate 质量 C++ MCP SDK。详见 conformance evidence 和 ecosystem maturity evidence。

安装

find_package(cxxmcp CONFIG REQUIRED)
 
# Server
target_link_libraries(my_server PRIVATE cxxmcp::server)
# Client
target_link_libraries(my_client PRIVATE cxxmcp::client)
# 完整 SDK
target_link_libraries(my_app PRIVATE cxxmcp::sdk)

从源码构建：

cmake -S . -B build -DCXXMCP_BUILD_CLIENT=ON -DCXXMCP_BUILD_SERVER=ON
cmake --build build --config Release
cmake --install build --config Release --prefix out/install/cxxmcp

Quick Start 中的 client 示例使用 Streamable HTTP；如果要从源码构建该 client 路径，还需要加上 -DCXXMCP_ENABLE_HTTP=ON。

包管理器：conanfile.py（Conan 2）、packaging/vcpkg/ports/cxxmcp-sdk（vcpkg overlay）、packaging/xmake/（xmake）。详见 package consumption。

CMake Options

Option	Default	说明
CXXMCP_BUILD_SDK	ON	构建聚合 SDK 层（protocol + client + server）
CXXMCP_BUILD_CLIENT	OFF	构建 MCP client library
CXXMCP_BUILD_SERVER	OFF	构建 MCP server library
CXXMCP_BUILD_EXAMPLES	OFF	构建示例
CXXMCP_BUILD_TESTS	BUILD_TESTING	构建测试
CXXMCP_BUILD_BENCHMARKS	OFF	构建 benchmark 可执行文件
CXXMCP_ENABLE_HTTP	OFF	构建 HTTP/SSE transport（默认使用 bundled cpp-httplib，CXXMCP_USE_SYSTEM_DEPS=ON 时使用系统包）
CXXMCP_ENABLE_OPENSSL	OFF	启用 OpenSSL-backed HTTP/WebSocket TLS 支持
CXXMCP_ENABLE_WEBSOCKET	OFF	构建 WebSocket transport（需要 CXXMCP_ENABLE_HTTP）
CXXMCP_ENABLE_AUTH	OFF	构建可选 OAuth 2.1 / DPoP auth target

Package Targets

Target	用途
cxxmcp::protocol	MCP 协议模型和 JSON-RPC 序列化
cxxmcp::transport	Role-generic transport contract
cxxmcp::handler	Client/server handler interface
cxxmcp::peer	Role-aware execution boundary
cxxmcp::service	Service lifecycle boundary
cxxmcp::client	可嵌入 MCP client SDK
cxxmcp::server	可嵌入 MCP server SDK
cxxmcp::auth	可选 OAuth 2.1 / DPoP contract（CXXMCP_ENABLE_AUTH=ON）
cxxmcp::auth_openssl	可选 OpenSSL-backed JOSE/JWT/DPoP helpers（CXXMCP_ENABLE_AUTH=ON，CXXMCP_AUTH_CRYPTO=OpenSSL）
cxxmcp::sdk	聚合 public SDK target

为什么选择 cxxmcp

• 标准 CMake SDK 体验 —— find_package 即用
• C++17 public API，除标准库外无运行时依赖
• 完整 MCP 协议覆盖，typed helper 自动按 capability gate
• 基于官方 runner 的跨 SDK conformance 验证
• RMCP 风格 Peer/Service 架构，为嵌入场景设计
• 开箱支持 stdio、process stdio、Streamable HTTP 和 WebSocket transport

Examples

源码树内示例覆盖 server/client peer、auth、tasks、elicitation 和 transport adapter。运行：

cmake --preset examples && cmake --build --preset examples && ctest --preset examples

完整列表见 examples.md。独立仓库 cxxmcp-examples 通过外部 CMake 项目消费 SDK，覆盖更多高级场景。

文档

• GitHub Pages — API 参考
• Conformance evidence — 测试结果和已知例外
• Compatibility policy — 版本策略、编译器矩阵、ABI
• HTTP transport backend evidence
• Release gates — release-blocking 检查
• Runtime gateway — 外部 gateway 边界
• Examples — 完整示例列表
• Auth design — OAuth 2.1 / DPoP 方向
• Request lifecycle — 超时、取消、进度、关闭
• Contributing | Security | Changelog

项目状态

cxxmcp 是正在准备 official SDK candidate 证据的社区 C++ MCP SDK。Peer/Service boundary、transport 层和 conformance gates 已接近 release candidate 状态。除非被 MCP maintainers 接受，否则它不是官方 MCP SDK。

编译器兼容性

MinGW UCRT64 GCC 和 MinGW CLANG64 Clang 作为 provisional、best-effort 编译器兼容性证据进行跟踪。这些目标不是 release-supported。compiler-compat workflow 在它们保持 provisional 期间以 continue-on-error: true 运行。