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 测试结果：

场景	请求数	QPS
Direct MCP Baseline	3000	357.359
mcpd Cache Miss	3000	293.838
mcpd Cache Hit	3000	6141.31

优化效果：

指标	结果
mcpd Cache Hit 相对 Direct MCP QPS 提升	1618.53%
mcpd Cache Hit 相对 mcpd Cache Miss QPS 提升	1990.03%

说明：缓存未命中时 mcpd 多一层代理，可能慢于直连 MCP；本项目的性能收益主要体现在高频重复查询、可缓存工具和多 Agent 共享缓存场景。

8.5 多 Agent 并发压力测试

服务器环境下模拟 10、50、100 个 Agent 并发调用 MCP 工具，每个 Agent 发送 200 个请求。100 Agent 场景结果：

场景	总请求数	QPS	平均延迟	P95	P99	失败数
Direct MCP	20000	416.63	239.37 ms	244.24 ms	245.71 ms	0
mcpd Cache Miss	20000	345.44	288.51 ms	363.31 ms	372.40 ms	0
mcpd Cache Hit	20000	4536.95	21.94 ms	22.32 ms	23.71 ms	0

100 Agent 下，mcpd Cache Hit 相对普通 MCP 直连 QPS 提升 988.96%，平均延迟降低 90.83%。详细报告见 docs/multi_agent_benchmark.md。

8.6 Docker 资源受限边缘测试

使用 Docker 限制 CPU 和内存模拟边缘节点。50 Agent 场景结果：

环境	CPU / 内存	Direct MCP QPS	mcpd Cache Hit QPS	平均延迟降低	失败数
Edge-1	1 CPU / 512 MB	440.35	1531.80	71.28%	0
Edge-2	2 CPU / 1 GB	438.91	5180.04	91.58%	0

详细报告见 docs/resource_limited_test.md。

---

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 提升 1618.53%
优化上下文长度 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 防重放。