OpenHarmony 原生 MCP 协议栈

本仓库用于实现 OpenHarmony 赛事赛题“泛在操作系统原生的 MCP 协议栈设计”。

当前版本提供一个可复现的协议栈 MVP，服务名为 oh-mcpd。它支持 MCP 风格的 JSON-RPC 请求、生命周期初始化、工具列表、工具调用、Bearer Token 认证、Origin 校验、缓存指标、gzip 传输优化、Benchmark 脚本、Python 适配器，以及 OpenHarmony 原生集成骨架。

GitLink 仓库：https://gitlink.org.cn/ohanabi/OpenHarmony.git

架构

Agent / 演示程序
  -> adapters/python/oh_mcp_client
  -> oh_mcpd Python MVP 服务
  -> 认证、JSON-RPC、会话、缓存、压缩、指标、工具注册表
  -> mock 天气 / 路线 / POI 工具

openharmony/ 和 src/ 目录保存 OpenHarmony 原生集成文件和 C++ 实现入口。当前 Python 服务是本地测试和 Benchmark 复现用的参考实现；后续会把已验证的协议逻辑迁移到 C++ 原生服务。

当前已经提供 C++ 原生核心闭环，支持 stdio 模式下的 initialize、session/close、tools/list、tools/call、metrics/get 和 audit/list。C++ 原生侧已具备会话、重复 request id 防重放、工具列表缓存、工具结果缓存、审计日志、工具级指标、参数校验、HS256 JWT Bearer Token 校验和按 agent 固定窗口限流。Python MVP 继续作为 HTTP、压缩和 Benchmark 的行为对照实现。

本阶段 C++ 原生 HTTP 传输继续对齐 MCP Streamable HTTP 关键边界，Windows 本地构建产物可通过 --http <port> 启动 GET /health、GET /metrics 和 POST /mcp，支持 MCP-Protocol-Version、Mcp-Session-Id、initialize 响应 session header、401/403/429 HTTP 状态映射和异常 Content-Length 防护。

环境要求

• Python 3.10+
• pytest，用于运行测试
• 只有构建 OpenHarmony 原生服务骨架时才需要 OpenHarmony SDK 或源码树

安装测试依赖：

python -m pip install -r requirements.txt

运行服务

启动 MCP 服务：

python -m oh_mcpd --config configs/oh-mcpd.yaml

健康检查：

Invoke-RestMethod http://127.0.0.1:8080/health

初始化会话：

$body = '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"demo","version":"0.1"}}}'
Invoke-RestMethod http://127.0.0.1:8080/mcp -Method Post -Headers @{Authorization='Bearer dev-token'} -Body $body -ContentType 'application/json'

使用 stdio 传输运行：

python -m oh_mcpd --stdio

演示

服务启动后运行：

python examples/multi_agent_demo/run_demo.py
python examples/trip_planner_demo/run_mock_trip.py

测试

python -m pytest -q
python scripts/check_native_sources.py
python scripts/check_openharmony_integration.py
python scripts/check_competition_compliance.py

当前测试覆盖：

• JSON-RPC 解析错误
• initialize、tools/list、tools/call
• session/close 会话关闭
• 缺失 token 和错误 token
• HS256 JWT issuer、audience、expiration、scope 校验
• Origin allow-list 拦截
• MCP-Protocol-Version 和 Mcp-Session-Id header 行为
• session 过期、未知 session、重复 request id 防重放
• 请求体大小限制和审计日志
• 按 agent 固定窗口限流
• 工具参数校验和工具级调用指标
• JSON-RPC id 边界校验
• 工具 schema 缓存与工具结果缓存指标
• gzip payload 优化

C++ 原生构建

本地 Windows 环境支持两种编译方式：

powershell -ExecutionPolicy Bypass -File scripts\build_native_gpp.ps1
powershell -ExecutionPolicy Bypass -File scripts\build_native_cl.ps1

产物：

• build/oh_mcpd_native.exe：MSYS2 MinGW g++ 构建
• build/oh_mcpd_native_cl.exe：Visual Studio Build Tools cl 构建

运行原生 smoke 测试，覆盖 initialize、tools/list、tools/call、session/close、metrics/get、audit/list、缓存命中、重复 request id 拦截和工具参数错误：

python scripts/test_native_smoke.py build\oh_mcpd_native_cl.exe
$env:PATH='C:\msys64\ucrt64\bin;' + $env:PATH; python scripts/test_native_smoke.py build\oh_mcpd_native.exe

运行原生 HTTP smoke 测试，覆盖 /health、/metrics、POST /mcp、Bearer Token 透传、HS256 JWT issuer/audience/expiration/scope、按 agent 限流、MCP-Protocol-Version、Mcp-Session-Id、工具调用、审计字段和异常 HTTP 头边界：

python scripts/test_native_http_smoke.py

Benchmark

python benchmark/run_latency_test.py --target baseline --output reports/baseline_latency.json
python benchmark/run_latency_test.py --target oh-mcpd --output reports/oh_mcpd_latency.json
python benchmark/run_throughput_test.py --target baseline --concurrency 1 --output reports/baseline_qps_c1.json
python benchmark/run_throughput_test.py --target oh-mcpd --concurrency 1 --output reports/oh_mcpd_qps_c1.json
python benchmark/run_throughput_test.py --target baseline --concurrency 10 --output reports/baseline_qps_c10.json
python benchmark/run_throughput_test.py --target oh-mcpd --concurrency 10 --output reports/oh_mcpd_qps_c10.json
python benchmark/run_throughput_test.py --target baseline --concurrency 50 --output reports/baseline_qps_c50.json
python benchmark/run_throughput_test.py --target oh-mcpd --concurrency 50 --output reports/oh_mcpd_qps_c50.json
python benchmark/run_throughput_test.py --target baseline --concurrency 100 --output reports/baseline_qps_c100.json
python benchmark/run_throughput_test.py --target oh-mcpd --concurrency 100 --output reports/oh_mcpd_qps_c100.json
python benchmark/run_payload_test.py --target baseline --output reports/baseline_payload.json
python benchmark/run_payload_test.py --target oh-mcpd --output reports/oh_mcpd_payload.json
powershell -ExecutionPolicy Bypass -File scripts\build_native_cl.ps1
python benchmark/run_native_latency_test.py --kind cl --output reports/native_cl_latency.json
python benchmark/run_native_throughput_test.py --kind cl --output reports/native_cl_qps.json
python benchmark/run_native_http_latency_test.py --output reports/native_http_latency.json
python benchmark/run_native_http_throughput_test.py --concurrency 1 --output reports/native_http_qps_c1.json
python benchmark/run_native_http_throughput_test.py --concurrency 10 --output reports/native_http_qps_c10.json
python benchmark/run_native_http_throughput_test.py --concurrency 50 --output reports/native_http_qps_c50.json
python benchmark/run_native_http_throughput_test.py --concurrency 100 --output reports/native_http_qps_c100.json
python benchmark/analyze_results.py --reports reports --output docs/测试报告.md

baseline 关闭缓存和压缩；oh-mcpd 启用工具 schema 缓存、工具调用结果缓存和自适应 gzip 统计；native-cl 通过 C++ 原生 stdio 服务测量原生协议栈核心延迟和吞吐；native-http-cl 通过 C++ 原生 HTTP 传输测量 socket/HTTP 解析路径下的端到端延迟和并发吞吐。延迟 benchmark 输出 P50/P95/P99。

OpenHarmony 集成

原生集成骨架：

• openharmony/BUILD.gn
• openharmony/bundle.json
• openharmony/service_config/oh_mcpd.cfg
• src/main.cpp
• src/core/json_rpc.*
• src/core/mcp_service.*
• src/security/auth.*
• src/tools/tool_registry.*
• src/transport/http/http_server_win.*

建议在 OpenHarmony 源码树中的放置位置：

foundation/ai/oh_mcpd

构建命令模板：

bash scripts/build_openharmony.sh

当前工作区不是完整 OpenHarmony 源码树，因此原生构建验证需要在目标 OpenHarmony 环境中执行。 本仓库提供 python scripts/check_openharmony_integration.py 检查 BUILD.gn、bundle.json、service config 和原生源文件映射，但该检查不等价于真实 hb build。

提交材料

• 特性设计文档：docs/特性设计文档.md
• 测试方案文档：docs/测试方案文档.md
• 测试报告：docs/测试报告.md
• 赛事符合性矩阵：docs/赛事符合性矩阵.md
• PPT 大纲：docs/答辩PPT大纲.md
• 链接与资料记录：docs/链接访问记录.md
• 源码、测试、Benchmark 脚本和演示程序均在本仓库内