FilesLast commitLast update
21 days ago
21 days ago
21 days ago
21 days ago
17 days ago
17 days ago
19 days ago
5 months ago
21 days ago
2 months ago
5 months ago
README

MCP C++ SDK

目录

概述

MCP C++ SDK 是 Model Context Protocol 的 C++ 实现,提供 MCP 客户端与服务器能力,支持 Streamable HTTP 与 stdio 传输。

  • 构建 MCP 客户端:连接 MCP 服务器,调用 Tool / Resource / Prompt 等
  • 构建 MCP 服务器:注册 Tool / Resource / Prompt,处理协议生命周期
  • 支持鉴权、Sampling、Progress、Roots 等扩展能力(详见示例与 API 文档)

文档

文档 说明
依赖说明 运行/编译依赖、版本、各发行版安装命令
测试说明 单元测试、集成测试、覆盖率
API 文档索引 Client / Server API、协议对照

环境要求

  • 操作系统:Linux(主要验证平台)、macOS
  • 编译器:C++17 及以上
  • CMake:≥ 3.15(见根目录 CMakeLists.txt)
  • 依赖:完整说明见 docs/dependencies.md

版本要求(摘要)

依赖 最低版本 用途
C++ 编译器 C++17 语言标准
CMake 3.15 构建系统
OpenSSL 1.1.1 TLS、加密
libcurl 8.12 HTTP Client 传输
nlohmann_json 3.11.2 JSON 序列化
libevent 2.1.12 事件循环
http_parser 2.9.4 HTTP 解析

系统依赖安装

请按发行版使用对应包管理器。Debian/Ubuntu 使用 apt-get(包名多为 *-dev);RHEL/CentOS/Fedora/EulerOS 使用 yum/dnf(包名多为 *-devel),两者不可混用。

推荐一键安装(检测发行版并安装 OpenSSL、libcurl 开发包;不含编译器与 CMake):

cd MCP/cpp-sdk
bash scripts/install_deps.sh

也可手动安装(含编译工具链与常用系统开发包):

Ubuntu / Debian(apt-get)

sudo apt-get update
sudo apt-get install -y \
  build-essential cmake \
  libssl-dev \
  libcurl4-openssl-dev \
  libevent-dev \
  nlohmann-json3-dev

CentOS / RHEL / Fedora / EulerOS(yum/dnf)

sudo yum install -y \
  gcc-c++ cmake \
  openssl-devel \
  libcurl-devel \
  libevent-devel
# Fedora 等也可使用:sudo dnf install -y ...

macOS(Homebrew)

brew install cmake openssl curl libevent nlohmann-json

快速入门

在仓库 MCP/cpp-sdk 目录下,按以下顺序执行(约 5–15 分钟,视网络与编译环境而定)。

前置条件:已安装 C++17 编译器与 CMake ≥ 3.15,并完成上一节系统依赖安装。install_deps.sh 仅安装 OpenSSL、libcurl 开发包,不包含编译器与 CMake(见 依赖说明)。

cd MCP/cpp-sdk

# 1. 安装 OpenSSL、libcurl 开发包(或按上一节手动安装)
bash scripts/install_deps.sh

# 2. 编译 SDK(产物:output/lib/libmcp.so)
#    第三方库(含 nlohmann_json)优先使用系统包;系统没有时由 CMake 下载到 third_party/
bash scripts/build.sh

# 3. 构建并运行全部示例(须先完成步骤 2;-t all 会自动先起 Server)
sh scripts/run_example.sh

脚本调用说明:

脚本 解释器 说明
install_deps.sh bash Bash 脚本,勿用 sh 调用
build.sh bash 同上
run_example.sh sh POSIX sh 脚本,可用 sh 或 ./(需可执行权限)

nlohmann_json:主工程 build.sh 与示例构建均优先使用系统 nlohmann_json;系统未安装时,build.sh 会拉取到 third_party/nlohmann_json-src,示例也会回退使用该目录。若系统已有 nlohmann 开发包,则不会生成 third_party/nlohmann_json-src,示例仍可直接编译。

仅运行某一类示例:

方式一:单终端一键(推荐首次验证)

sh scripts/run_example.sh              # 或 -t all:后台起 Server 并依次跑全部 Client

方式二:双终端(Server 常驻,便于反复调试 Client)

# 终端 1:前台运行 Server(Ctrl+C 停止;不要用 nohup 包一层 scripts/run_example.sh)
sh scripts/run_example.sh -t server

# 终端 2:Server 已监听后再跑 Client
sh scripts/run_example.sh -t tool
sh scripts/run_example.sh -t sampling

也可用各子目录下的 example/server_example/run_example.sh(终端 1)与 example/client_example/*/run_example.sh(终端 2)。

默认 Server 端点:http://127.0.0.1:8000/mcp。指定端口示例:

sh scripts/run_example.sh -p 9000 -t all

注意:

  • 必须先有 Server 再跑 Client。
  • -t all / 无参数:同一脚本内后台起 Server,结束后自动停止。
  • -t server:前台常驻,供另一终端连接;脚本退出时不会误杀 Server(旧版会在 EXIT 时 kill 后台进程,导致双终端流程失败)。

构建与安装

统一入口为 scripts/build.sh(不是根目录下的 build.sh)。

# Release 构建(默认)
./scripts/build.sh

# Debug 构建(含调试符号,-g -O0)
./scripts/build.sh -t Debug

# 编译并启用单元测试
./scripts/build.sh -t Debug --with-tests

# 覆盖率构建 + 运行测试报告(见 docs/testing.md)
./scripts/build.sh -t Debug --coverage

# 安装到系统(需要 sudo)
./scripts/build.sh -i

常用 CMake 裁剪选项(经 build.sh 传入):

选项 含义
--no-client 不编译 Client 组件
--no-server 不编译 Server 组件
--no-http 不编译 HTTP 传输(仅 stdio 等)
--asan 启用 AddressSanitizer(自动使用 Debug)
-s, --stdio 启用 stdio 相关单元测试

构建产物:

路径 说明
output/lib/libmcp.so 共享库
include/mcp/*.h 公共头文件(源码树,安装后位于 prefix/include)

集成到自己工程时,链接 libmcp.so 并添加头文件路径 include/mcp(或安装后的 include 目录)。详见各示例下的 CMakeLists.txt。

运行示例

示例位于 example/ 目录(注意是单数 example,非 examples)。各子目录有独立 run_example.sh,也可使用统一脚本 scripts/run_example.sh。

示例 路径 说明
Server example/server_example/ HTTP Server,含 Tool/Prompt/Resource/Auth 等
Tool Client example/client_example/tool_example/ Initialize、ListTools、CallTool
Prompt Client example/client_example/prompt_example/ ListPrompts、GetPrompt
Resource Client example/client_example/resource_example/ List/Read/Subscribe Resource
Sampling Client example/client_example/sampling_example/ 服务端发起的 sampling

运行测试

./scripts/build.sh -t Debug --with-tests
cd build && ctest --output-on-failure

覆盖率与 HTML 报告见 docs/testing.md。

日志

SDK 默认将诊断日志输出到 stdout。stdio 传输模式下请通过 SetLogCallback 重定向日志,避免污染协议通道。详见 docs/logging.md。

License

本项目依据 Apache-2.0 许可证授权。

Copyright (c) 2025 Huawei Technologies Co., Ltd. All rights reserved.

Third-Party Notices

本项目包含或依赖第三方开源软件,其版权和许可证信息均归原作者所有,并在相应文件中予以说明。