# OH-MCPStack

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

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

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

---

## 1. 项目解决的问题

普通 MCP 应用通常是：

```text
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 协议栈下沉为系统服务：

```text
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. 总体架构

```mermaid
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` 已从单文件原型拆成多个模块：

```text
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 | 当前提供集成骨架，后续接入源码树编译 |

检查依赖：

```bash
g++ --version
cmake --version
```

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

### 4.2 编译

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

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

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

### 4.3 启动服务

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

```bash
./scripts/run_cpp_smoke.sh
```

如果需要手动启动：

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

配置文件启动方式：

```bash
./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`。

测试：

```bash
./scripts/test_cpp_progressive_discovery.sh
```

服务启动后可访问：

```bash
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 查询工具列表

```bash
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 调用天气工具

```bash
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 查看统计信息

```bash
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` | 搜索餐厅 |

工具元数据包含：

```text
name
title
description
version
category
inputSchema
outputSchema
annotations
x-ohmcp
```

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

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

---

## 7. 测试与复现

### 7.1 完整测试命令

```bash
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 服务器：

```bash
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. 阶段性测试结果

完整测试报告见：

```text
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：

```bash
./scripts/run_trip_planner_demo.sh
```

Demo 任务：

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

调用工具：

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

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

---

## 10. OpenHarmony 集成方案

OpenHarmony 集成骨架位于：

```text
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、网络和权限逻辑。

详细说明见：

```text
docs/openharmony_integration.md
```

---

## 11. 仓库结构

```text
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 / 小内存场景；
3. 优化 `mcpd` 转发路径，例如连接复用、线程池、异步 I/O；
4. 强化 OpenHarmony 真机或源码树编译验证；
5. 准备最终比赛 PPT 和 5 分钟展示视频。

---

## 14. License

本项目采用 MIT License，见：

```text
LICENSE
```

## 9. Agent 框架接入说明

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

### HMAC-SHA256 签名安全增强

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

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

签名消息为：

```text
timestamp + "\n" + nonce + "\n" + raw_json_body
```

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