oh-native-mcp-runtime

本项目面向 OpenHarmony 风格系统实现一个用户态原生 MCP 协议栈原型。核心机制是 **Context Capability Protocol (CCP)**：tools/list 生成可验证的上下文能力，tools/call 必须在校验并消费该能力后才能执行工具，从而将 MCP 工具发现与调用绑定为一条可审计路径。CCP 的绑定语义为 binding_semantics="argument_constraints"——能力对发现期声明的参数约束签名，而非具体参数取值；因此运行时 does not claim to sign a canonical hash of concrete call arguments。

作者团队：武汉大学计算机学院。

队长：蔡克烨队员：黄越伶

核心能力

原生 MCP 运行时：native-mcp-runtime --stdio --project-root <repo>（读取 configs/runtime.json，需设置 MCP_LOCAL_SECRET）
协议方法：initialize、ping、tools/list、tools/call、resources/list、resources/read、prompts/list、prompts/get、metrics/read
JSON-RPC 兼容：支持单行请求、batch 数组和无 id 的 notification
生命周期通知：支持 notifications/initialized 与 notifications/cancelled
CCP 安全机制：上下文能力签名、schema 哈希校验、nonce 防重放、TTL 过期、key_epoch 进程隔离
生产安全：共享 token 认证、角色 ACL、输出守卫 (OutputGuard)、审计日志、确定性错误码 (-320xx)
传输安全：JSON-RPC 请求/响应大小边界、上游 HTTP 超时与体长限制
效率优化：直接路由、资源缓存、上下文压缩、条件摘要 (not_modified)、持久化 stdio 传输
多智能体隔离：不同 agent 获得不同作用域工具视图，无法复用彼此的上下文能力
治理控制：RequestGovernor 配额/并发限制、幂等重试、熔断器、发布者信任存储
OpenHarmony 集成：SystemAbility 生命周期、IPC stub/proxy、BUILD.gn、bundle.json、GN/Ninja ARM/musl 交叉编译

WSL2 构建与验证

git clone <repo-url>
cd oh-native-mcp-runtime

# 构建
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j2

# 测试
ctest --test-dir build --output-on-failure
pytest -q

# 演示
bash scripts/run_demo.sh --mode full

# 基准测试
bash scripts/run_bench.sh --modes raw,compact,capability,full --requests 10 --concurrency 2 --repeat 1

如果 WSL2 中缺少 pytest：

python3 -m pip install pytest

常用命令

直接启动 Runtime 需要 MCP_LOCAL_SECRET（至少 32 字节）。二进制位于 build/src/native_mcp_runtime/src/native-mcp-runtime，通过 --project-root 指向仓库根目录以加载 configs/*.json。

# 共享密钥（≥32 字节）
export MCP_LOCAL_SECRET=$(python3 -c 'import secrets; print(secrets.token_hex(32))')
BIN=build/src/native_mcp_runtime/src/native-mcp-runtime

# 单次 JSON-RPC 请求：握手
"$BIN" --json-rpc-once '{"jsonrpc":"2.0","id":1,"method":"initialize"}' --project-root .

# 列出某个 agent 在一次会话中可见的工具视图
"$BIN" --json-rpc-once '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"agent_id":"trip_planner_agent","session_id":"s1"}}' --project-root .

# 持久化 stdio 传输：从 stdin 逐行读取 JSON-RPC 请求
"$BIN" --stdio --project-root .

# 完整的 tools/list -> tools/call 能力（CCP）流程见端到端演示
bash scripts/run_demo.sh --mode full

说明：tools/call 必须携带 tools/list 返回并签名的上下文能力（CCP），需按发现→校验→消费的顺序进行，因此推荐用 scripts/run_demo.sh 观察完整链路。可用的 agent_id 见 configs/agents.json。

基准测试

基准测试对比四种运行模式：

模式	说明
`raw`	无任何安全开销的原始路径
`compact`	紧凑工具视图，减少上下文
`capability`	CCP 能力签名与校验
`full`	完整模式：能力 + 缓存 + result_ref + 审计

bash scripts/run_bench.sh --modes raw,compact,capability,full --requests 10 --concurrency 2 --repeat 1

持久化 stdio 传输基准：

bash scripts/run_persistent_stdio_bench.sh

多智能体隔离基准：

bash scripts/run_multi_agent.sh --modes raw,compact,capability,full --requests 20 --concurrency 4 --repeat 1

最终报告位于：

results/bench/ — 基准 JSON 数据
results/bench_summary.md — 基准汇总

安全模式

正常运行时仅允许 capability 和 full 模式。raw/compact 需要 --unsafe-benchmark-modes 标志，仅用于消融实验，输出标记 security_profile=unsafe_benchmark。

MCP_LOCAL_SECRET（至少 32 字节）是直接启动 Runtime 的强制要求。

仓库结构

目录	说明
`src/`	C++17 原生 MCP 运行时核心实现
`include/`	公共头文件
`tools/`	mcpctl 和 mcpbench 工具
`tests/`	C++ 与 Python 测试
`configs/`	运行时配置文件
`docs/`	设计、测试、部署和 OpenHarmony 移植文档
`openharmony/`	OpenHarmony SystemAbility 适配与集成片段
`scripts/`	构建、测试、基准、演示与打包脚本
`examples/`	使用示例
`results/`	基准与证据输出
`dist/`	提交包输出
`third_party/`	第三方依赖
`.github/workflows/`	CI 工作流