OpenHarmony Native MCP Stack

第八届 CCF 开源创新大赛 · 泛在操作系统方向 · OpenHarmony 开源任务挑战赛
赛题一：泛在操作系统原生的 MCP 协议栈设计

OpenHarmony Native MCP Stack 是一个面向泛在操作系统的 MCP 原生协议栈用户态原型。它把分散在 Agent 框架里的 MCP 中间件能力，下沉为可缓存、可鉴权、可审计、可度量的系统服务。

本项目当前实现了一个 Rust 编写的 Native MCP Broker、一个 Python Agent SDK、多 Agent 城市行程规划 demo、baseline vs native benchmark、安全测试和完整评审文档。所有核心演示均可离线运行，不依赖外部大模型、云 API 或真实硬件。

核心结论

在本地可复现 benchmark 中，native path 通过 context fingerprint cache 把重复 MCP schema/context 从每次完整传输变成一次写入、多次引用：

指标	Baseline	Native MCP Stack	提升
p50 latency	96423 us	927 us	99.04% 降低
p95 latency	99630 us	1109 us	98.89% 降低
throughput	81.309 rps	2932.007 rps	3506.01% 提升
avg payload	40547.81 B	483 B	98.81% 降低
cache hit rate	0.00%	100.00%	broker cache

结果文件见 reports/benchmark-summary.md 和 reports/benchmark-results.json。

为什么是 OS-native MCP

传统 Agent 应用通常在各自框架内接 MCP server。这个模式在 demo 中简单，但在泛在操作系统场景会出现：

多 Agent 重复传输 tool schema、prompt fragment 和任务上下文。
每个框架重复维护连接、重试、工具崩溃处理和协议适配。
Agent 身份、工具权限、审计记录散落在应用层。
系统无法统一观察 MCP 调用延迟、吞吐、失败和越权行为。

本项目把 MCP 调用收敛到系统服务形态的 broker：

flowchart LR
    A["Agent / App"] --> B["Python Agent SDK"]
    B --> C["Native MCP Broker (Rust)"]
    C --> D["Policy Engine"]
    C --> E["Context Cache"]
    C --> F["Metrics Collector"]
    C --> G["Mock / HTTP / stdio Tool Adapter"]

已实现能力

Native MCP Broker： Rust / Axum 实现，提供 /rpc、/baseline、/metrics、/healthz。
Context Cache： 首次传输完整 context，后续通过 context_ref 引用，broker 侧恢复。
安全机制： HMAC-SHA256 签名、timestamp skew 校验、nonce 防重放、Agent allowlist、路径越权拦截。
Policy Engine： configs/policy.json 声明 Agent secret、工具权限、payload 限制和路径限制。
多 Agent Demo： planner、weather、route、budget 4 类 Agent 协同完成重庆城市行程规划。
Benchmark： baseline full-context vs native context-cache，自动生成 JSON 和 Markdown 报告。
测试门禁： Rust 单测、Python 单测、live broker 安全测试、demo smoke。

快速开始

环境要求

Rust 1.80+
Python 3.10+
macOS / Linux

无需安装 Python 第三方依赖。

运行测试

scripts/run_tests.sh

当前本机结果：

Rust unit tests: 6 passed
Python unit tests: 1 passed, 5 live tests skipped in offline unit phase
Live broker security tests: 5 passed
Demo smoke: passed

运行 demo

scripts/run_demo.sh

demo 会自动启动 broker，并执行多 Agent 城市行程规划：

planner-agent 调用 poi.search 和 route.plan
weather-agent 调用 weather.query
route-agent 调用 route.plan
budget-agent 调用 budget.estimate

运行 benchmark

scripts/run_benchmark.sh

输出：

生成提交包

scripts/package_submission.sh

提交包输出到 submission/oh-mcp-stack-submission.zip 或 .tar.gz。

项目结构

.
├── configs/                    broker 与 policy 配置
├── crates/broker/              Rust Native MCP Broker
├── python/oh_mcp_client/       Python Agent SDK
├── python/demos/               多 Agent demo 与 benchmark
├── tests/                      Python 单元测试与 live 安全测试
├── scripts/                    一键测试、demo、benchmark、打包
├── reports/                    benchmark 结果
├── docs/                       设计、复现、测试、映射、视频脚本
└── submission/                 本地生成的提交包

文档入口

docs/story.md：竞赛故事线。
docs/DESIGN.md：系统设计。
docs/REPRODUCE.md：复现指南。
docs/TEST_PLAN.md：测试方案。
docs/TEST_REPORT.md：测试报告。
docs/OPENHARMONY_MAPPING.md：迁移到 OpenHarmony SystemAbility 的映射。
docs/FINAL_VIDEO_SCRIPT.md：5 分钟展示视频脚本。
docs/COMPETITION.md：原始赛题信息备份。

当前边界

本项目是初赛阶段的用户态系统服务原型，不是 OpenHarmony 内核补丁或已合入 OpenHarmony 主线的 SystemAbility。项目用可运行代码和可复现指标证明：MCP 下沉到 OS 服务层后，可以在多 Agent 场景中统一降低上下文传输成本、集中安全策略、归集调用指标。

后续迁移路径见 docs/OPENHARMONY_MAPPING.md。

许可证

本项目使用 Apache-2.0 协议，见 LICENSE。第三方依赖和声明见 NOTICE 与 THIRD_PARTY.md。

Conflicts:

README.md