OH-MCPStack

OH-MCPStack 是一个面向 OpenHarmony / 泛在操作系统 的原生 MCP（Model Context Protocol）协议栈原型项目，对应赛题一：泛在操作系统原生的 MCP 协议栈设计。

项目核心目标是把 MCP 能力从上层 Agent 框架中下沉到系统用户态服务 mcpd，统一处理 Agent 与 MCP Server 之间的工具发现、工具调用、缓存、安全和统计，从而降低重复开发成本，减少上下文传输开销，并提升高频工具调用场景下的吞吐量。

当前实现为 C++ 用户态系统服务原型，并提供 OpenHarmony 集成骨架。项目不修改内核，采用更易落地的用户态系统服务路线。

---

1. 项目解决的问题

普通 MCP 应用通常是：

Agent / LangChain / HelloAgents
        |
        v
MCP Server
        |
        v
Tool / API / Data Source

这种方式存在几个问题：

1. 每个 Agent 框架各自维护 MCP 调用逻辑，容易重复实现；
2. tools/list 返回完整工具 schema，占用大量 LLM 上下文；
3. 高频重复工具调用缺少系统级缓存；
4. 认证、权限控制、安全限制分散在应用层；
5. 多 Agent 高并发场景下，后端 MCP Server 压力较大。

OH-MCPStack 将 MCP 协议栈下沉为系统服务：

Agent / LangChain / HelloAgents
        |
        v
mcpd 系统 MCP 服务
        |
        v
MCP Server / Tool Server

mcpd 负责统一代理、缓存、安全和统计，上层 Agent 只需要访问系统提供的统一 MCP 入口。

---

2. 当前已实现能力

能力	状态	说明
C++ MCP 协议栈原型	已完成	cpp/mcpd
Mock MCP Server	已完成	模拟高德地图 MCP 工具
tools/list 转发	已完成	支持完整和紧凑返回
tools/call 转发	已完成	支持工具调用代理
Schema 缓存	已完成	生成 schema_id，减少重复 schema 传输
紧凑工具描述	已完成	降低 Agent 上下文占用
工具结果缓存	已完成	可缓存工具重复调用直接命中 mcpd
Token 认证	已完成	X-Agent-Token
HMAC-SHA256 请求签名	已完成	X-Agent-Signature / X-Agent-Timestamp / X-MCP-Nonce
工具级 ACL	已完成	不同 token 拥有不同工具权限
Nonce 防重放	已完成	X-MCP-Nonce
请求体大小限制	已完成	防止超大请求体攻击
/healthz 健康检查	已完成	服务状态检查
/stats 统计接口	已完成	缓存、安全、请求统计
可观测指标	已完成	/metrics Prometheus 文本指标
性能测试脚本	已完成	direct MCP vs mcpd
安全测试脚本	已完成	认证、ACL、重放、大包
旅行规划端到端 Demo	已完成	对齐 HelloAgents / 高德 MCP 参考案例
OpenHarmony 集成骨架	已完成	openharmony/

---

3. 总体架构

flowchart TD
    A["Agent / Client"] --> B["mcpd :18080"]

    B --> C["Token 认证"]
    B --> D["ACL 工具权限"]
    B --> E["Schema 缓存"]
    B --> F["工具结果缓存"]
    B --> G["Nonce 防重放"]
    B --> H["请求大小限制"]
    B --> I["统计 /stats"]

    B --> J["Mock MCP Server :18081"]

    J --> K["amap.maps_weather"]
    J --> L["amap.maps_text_search"]
    J --> M["amap.maps_direction_transit_integrated_by_address"]
    J --> N["amap.hotel_search"]
    J --> O["amap.restaurant_search"]

默认端口：

服务	地址	说明
mcpd	http://127.0.0.1:18080	系统 MCP 服务
Mock MCP Server	http://127.0.0.1:18081	后端 MCP 工具服务
RPC 接口	/rpc	JSON-RPC POST 接口
健康检查	/healthz	GET 接口
统计接口	/stats	GET 接口

3.1 mcpd 模块拆分

mcpd 已从单文件原型拆成多个模块：

cpp/mcpd/
  main.cpp        启动参数、配置加载和 HTTP Server 入口
  state.h         核心状态、策略结构和模块接口声明
  config.cpp      配置文件解析、默认 Agent/服务安装
  router.cpp      上游 MCP 服务注册、工具名前缀路由
  discovery.cpp   tools/list compact、schema 缓存、渐进式工具搜索
  cache.cpp       结果缓存、TTL、LRU、invalidate/clear
  handler.cpp     JSON-RPC 方法分发、安全检查、统计接口
  security.cpp    HMAC-SHA256 请求签名

这样评审时能清楚看到协议栈由配置、路由、缓存、安全和工具发现等子模块组成，而不是单文件 demo。

---

4. 快速开始

4.1 环境要求

本项目 C++ 原型只依赖系统编译器和 CMake。

推荐环境：

环境	要求
macOS	Apple Clang / CMake
Linux	g++ / CMake
OpenHarmony	当前提供集成骨架，后续接入源码树编译

检查依赖：

g++ --version
cmake --version

macOS 也可以使用系统 clang++。

4.2 编译

cd /Users/wangyue/harmony/oh-mcpstack
./scripts/build_cpp.sh

Linux 服务器上可以指定编译器：

CXX=g++ ./scripts/build_cpp.sh

4.3 启动服务

可以直接运行冒烟脚本，它会自动编译、启动 mock_mcp_server 和 mcpd，并执行基础调用：

./scripts/run_cpp_smoke.sh

如果需要手动启动：

./build/cpp/mock_mcp_server --port 18081
./build/cpp/mcpd --port 18080 --upstream http://127.0.0.1:18081/rpc

配置文件启动方式：

./build/cpp/mcpd --config configs/mcpd.demo.json

configs/mcpd.demo.json 将服务注册、Agent token、ACL、缓存上限和安全参数从 C++ 代码中解耦，便于在 OpenHarmony 设备、边缘节点和本地压测环境中切换部署。

4.4 渐进式工具发现

除了标准 tools/list，mcpd 还提供两个系统扩展接口：

• ohmcp/tools.search：按任务关键词返回少量相关工具，避免一次性把全部工具描述塞进上下文；
• ohmcp/tools.get_schema：按 schema_id 或工具名按需获取完整 inputSchema/outputSchema。

测试：

./scripts/test_cpp_progressive_discovery.sh

服务启动后可访问：

curl http://127.0.0.1:18080/healthz
curl http://127.0.0.1:18080/stats
curl http://127.0.0.1:18080/metrics

注意：/rpc 是 JSON-RPC POST 接口，不是网页。浏览器直接打开 http://127.0.0.1:18081/rpc 通常不会显示有意义内容。

---

5. 示例调用

5.1 查询工具列表

curl -s http://127.0.0.1:18080/rpc \
  -H 'Content-Type: application/json' \
  -H 'X-Agent-Token: demo-token' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"compact":true}}'

5.2 调用天气工具

curl -s http://127.0.0.1:18080/rpc \
  -H 'Content-Type: application/json' \
  -H 'X-Agent-Token: demo-token' \
  -H 'X-MCP-Nonce: demo-001' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"amap.maps_weather","arguments":{"city":"Suzhou"}}}'

5.3 查看统计信息

curl -s http://127.0.0.1:18080/stats

---

6. MCP 工具集合

当前 Mock MCP Server 提供 5 个旅行规划工具，用于对齐比赛参考案例中的 HelloAgents 旅行规划助手和高德 MCP 工具调用场景。

工具名	作用
amap.maps_weather	查询城市天气
amap.maps_text_search	搜索景点 / POI
amap.maps_direction_transit_integrated_by_address	查询跨城路线
amap.hotel_search	搜索酒店
amap.restaurant_search	搜索餐厅

工具元数据包含：

name
title
description
version
category
inputSchema
outputSchema
annotations
x-ohmcp

其中 x-ohmcp 是本项目扩展字段，用于描述系统层优化能力：

{
  "cacheable": true,
  "cacheTtlMs": 60000,
  "requiredPermission": "tool:weather",
  "securityLevel": "normal"
}

---

7. 测试与复现

7.1 完整测试命令

cd /Users/wangyue/harmony/oh-mcpstack
./scripts/build_cpp.sh
./scripts/run_cpp_smoke.sh
./scripts/test_cpp_context_efficiency.sh
./scripts/test_cpp_result_cache.sh
./scripts/test_cpp_cache_controls.sh
./scripts/test_cpp_multi_service_router.sh
./scripts/test_cpp_security.sh
N=3000 ./scripts/bench_cpp_performance.sh
./scripts/run_trip_planner_demo.sh

Linux 服务器：

CXX=g++ ./scripts/build_cpp.sh
CXX=g++ ./scripts/run_cpp_smoke.sh
CXX=g++ ./scripts/test_cpp_context_efficiency.sh
CXX=g++ ./scripts/test_cpp_result_cache.sh
CXX=g++ ./scripts/test_cpp_cache_controls.sh
CXX=g++ ./scripts/test_cpp_multi_service_router.sh
CXX=g++ ./scripts/test_cpp_security.sh
CXX=g++ N=3000 ./scripts/bench_cpp_performance.sh
CXX=g++ ./scripts/run_trip_planner_demo.sh

7.2 测试脚本说明

脚本	作用
scripts/build_cpp.sh	编译 C++ 原型
scripts/run_cpp_smoke.sh	功能冒烟测试
scripts/test_cpp_context_efficiency.sh	测试 tools/list 上下文长度优化
scripts/test_cpp_result_cache.sh	测试工具结果缓存
scripts/test_cpp_cache_controls.sh	测试缓存哈希 key、手动失效、清空、LRU 上限
scripts/test_cpp_multi_service_router.sh	测试多 MCP 服务路由、服务切换、服务级 ACL
scripts/test_cpp_security.sh	测试认证、ACL、Nonce、防大包
scripts/bench_cpp_performance.sh	性能 benchmark
scripts/bench_multi_agent.sh	多 Agent 并发压力测试
scripts/bench_edge_docker.sh	Docker 资源受限边缘节点测试
scripts/run_trip_planner_demo.sh	端到端旅行规划 Demo

---

8. 阶段性测试结果

完整测试报告见：

docs/test_report.md

8.1 上下文长度优化

对象	返回字节数
Direct MCP Full	5070 bytes
mcpd Full	5387 bytes
mcpd Compact	2379 bytes

优化效果：

指标	结果
mcpd Compact 相对 Direct MCP 减少	53.08%
mcpd Compact 相对 mcpd Full 减少	55.84%

该结果对应赛题要求中的“优化上下文长度，提升通信效率 10%”。

8.2 工具结果缓存

指标	结果
第一次相同工具调用 cached=false 数量	1
第二次相同工具调用 cached=true 数量	1
/stats 中 result cache hits	1
/stats 中 result cache misses	2

8.3 安全测试

测试项	预期状态码	结果
无 token 请求	401	通过
错误 token 请求	401	通过
ACL 权限不足	403	通过
Nonce 首次请求	200	通过
Nonce 重放请求	409	通过
超大请求体	413	通过

8.4 性能 benchmark

服务器环境下每条路径 N=3000，独立运行 5 轮，主报告采用中位数：

场景	请求数/轮	QPS 中位数	QPS 均值	耗时中位数
Direct MCP Baseline	3000	393.66	393.11	7620.85 ms
mcpd Cache Miss	3000	285.46	280.85	10509.30 ms
mcpd Cache Hit	3000	1693.75	1808.84	1771.22 ms

• Cache Hit 相对 Direct MCP 的 QPS 提升中位数：349.60%。
• Cache Hit 相对 Cache Miss 的 QPS 提升中位数：466.80%。
• Cache Miss 相对 Direct MCP 的 QPS 变化中位数：-27.83%。

说明：缓存未命中时 mcpd 多一层代理，当前会慢于直连；收益主要来自 TTL 内高频重复查询和多 Agent 共享缓存。原始五轮数据见 reports/final_20260805/performance/。

8.5 多 Agent 并发压力测试

模拟 10、50、100 个并发客户端，每个 Agent 发送 200 个请求。100 Agent 场景：

场景	总请求数	QPS	平均延迟	P95	P99	失败数
Direct MCP	20000	422.45	236.10 ms	246.31 ms	247.16 ms	0
mcpd Cache Miss	20000	284.61	350.32 ms	398.42 ms	400.08 ms	0
mcpd Cache Hit	20000	4086.12	24.37 ms	24.71 ms	25.11 ms	0

Cache Hit 相对 Direct MCP 的 QPS 提升 867.25%，平均延迟降低 89.68%。当前服务端为轻量串行处理模型，因此该测试证明的是并发客户端压力下的稳定性与缓存减负效果，不声明多工作线程线性扩展。

8.6 Docker 资源受限边缘测试

使用当前源码挂载到已有测试镜像，并限制 CPU 与内存。50 Agent 场景：

环境	CPU / 内存	Direct QPS	Cache Hit QPS	Cache Hit 平均延迟	失败数
Edge-1	1 CPU / 512 MB	430.66	1468.04	33.28 ms	0
Edge-2	2 CPU / 1 GB	429.18	4813.64	10.23 ms	0

详细数据见 reports/final_20260805/edge_current/。

9. 端到端 Demo

本项目提供旅行规划 Demo：

./scripts/run_trip_planner_demo.sh

Demo 任务：

上海到苏州三天两晚旅行规划

调用工具：

1. 天气查询；
2. 路线规划；
3. 景点搜索；
4. 酒店搜索；
5. 餐厅搜索。

该 Demo 展示了 Agent 应用如何通过 mcpd 统一调用多个 MCP 工具，并复用系统层缓存和安全能力。

---

10. OpenHarmony 集成方案

OpenHarmony 集成骨架位于：

openharmony/

主要文件：

文件	作用
openharmony/services/mcpd/BUILD.gn	OpenHarmony GN 构建模板
openharmony/services/mcpd/bundle.json	部件配置
openharmony/services/mcpd/init/mcpd.cfg	init 启动配置
openharmony/services/mcpd/mcpd_main.cpp	服务入口模板
openharmony/interfaces/innerkits/include/imcp_service.h	C++ InnerKit 接口草案
openharmony/interfaces/kits/arkts/oh_mcpstack.d.ts	ArkTS Kit 接口草案

当前采用 用户态系统服务 路线，而不是内核模块路线，原因是：

1. MCP 是应用层 JSON-RPC / 工具调用协议，更适合用户态服务承载；
2. 用户态服务更容易调试、升级和与 Agent 框架集成；
3. 可以通过 OpenHarmony init、系统服务、InnerKit、ArkTS Kit 暴露能力；
4. 避免在内核中处理复杂 JSON、网络和权限逻辑。

详细说明见：

docs/openharmony_integration.md

---

11. 仓库结构

cpp/
  common/                  HTTP、JSON、MCP 基础库
  mock_mcp_server/          模拟高德 MCP Server
  mock_calendar_server/     模拟日历 MCP Server
  mcpd/                     系统 MCP 服务原型
  client/                   C++ 命令行客户端
  bench/                    性能测试程序

scripts/
  build_cpp.sh
  run_cpp_smoke.sh
  test_cpp_context_efficiency.sh
  test_cpp_result_cache.sh
  test_cpp_cache_controls.sh
  test_cpp_multi_service_router.sh
  test_cpp_security.sh
  bench_cpp_performance.sh
  run_trip_planner_demo.sh

docs/
  competition_requirements.md
  design.md
  test_plan.md
  test_report.md
  openharmony_integration.md
  performance_benchmark.md
  multi_agent_benchmark.md
  resource_limited_test.md
  security_tests.md
  context_efficiency_test.md
  result_cache.md
  trip_planner_demo.md
  reference_cases.md
  tool_metadata.md

openharmony/
  services/mcpd/
  interfaces/innerkits/
  interfaces/kits/arkts/

---

12. 与赛题要求的对应关系

赛题要求	当前实现
系统原生 MCP 协议栈	C++ 用户态 mcpd 服务 + OpenHarmony 集成骨架
减少中间层性能损耗	系统层统一代理、工具 schema 缓存、结果缓存
性能提升 10%	缓存命中场景五轮 QPS 提升中位数 349.60%
优化上下文长度 10%	tools/list 紧凑返回减少 53.08% 字节数
支持高并发 Agent	已补 10/50/100 Agent 并发压力测试
内置安全机制	token、ACL、nonce、防大包、统计
多 Agent / 边缘节点场景	已完成多 Agent 并发测试和 Docker 资源受限测试
端到端应用案例	旅行规划 Demo
开源代码与文档	已提供源码、脚本、设计文档和测试报告

---

13. 后续计划

当前项目已经完成第一阶段可运行原型，后续重点：

1. 增加资源受限环境测试，例如 1 CPU / 小内存场景；
2. 优化 mcpd 转发路径，例如连接复用、线程池、异步 I/O；
3. 强化 OpenHarmony 真机或源码树编译验证；
4. 准备最终比赛 PPT 和 5 分钟展示视频。

---

14. License

本项目采用 MIT License，见：

LICENSE

9. Agent 框架接入说明

参考 docs/agent_integration.md。该文档说明了如何将 LangChain / HelloAgents 这类上层 Agent 框架从直连 MCP Server 改为连接系统 mcpd，并复用系统层路由、缓存、ACL 和渐进式工具发现能力。

HMAC-SHA256 签名安全增强

mcpd 支持可选的请求签名校验。配置中开启 security.require_signature=true 后，请求必须携带：

X-Agent-Token: demo-token
X-Agent-Timestamp: 1710000000
X-MCP-Nonce: unique-nonce
X-Agent-Signature: sha256=<hmac_hex>

签名消息为：

timestamp + "\n" + nonce + "\n" + raw_json_body

签名算法为 HMAC-SHA256。该机制用于校验消息完整性、防篡改，并结合 nonce 防重放。