How do I use OH-MCPStack?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@OH-MCPStack Plan a trip from Suzhou to Shanghai with weather and hotel search." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

OH-MCPStack

by 123123213weqw

Overview Schema Source Related Servers Discussions Admin

Remote

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

这种方式存在几个问题：

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

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

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

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

Related MCP server: MCP Gateway

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 任务：

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

调用工具：

天气查询；
路线规划；
景点搜索；
酒店搜索；
餐厅搜索。

该 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 接口草案

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

MCP 是应用层 JSON-RPC / 工具调用协议，更适合用户态服务承载；
用户态服务更容易调试、升级和与 Agent 框架集成；
可以通过 OpenHarmony init、系统服务、InnerKit、ArkTS Kit 暴露能力；
避免在内核中处理复杂 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 CPU / 小内存场景；
优化 mcpd 转发路径，例如连接复用、线程池、异步 I/O；
强化 OpenHarmony 真机或源码树编译验证；
准备最终比赛 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 防重放。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

llm-orchestration-agent-2
ai.getvda
MCP-Native LLM Orchestration Agent
Agent Orchestration AI & Machine Learning
1
gatewayOAuth
ai.sealgate
MCP gateway with runtime security policy, tool-call-level control, and audit of agent actions.
Security Agent Orchestration
11
AgentMarketplace A
io.github.raditotev
MCP Server for an Agent Task Marketplace
Autonomous Agents Agent Orchestration
221
Remote MCP A
com.remote-mcp.mcp
The Remote MCP server acts as a standardized bridge between LLM applications (like Claude, ChatGPT, and Cursor) and external services, enabling AI agents to access external tools and resources. Its primary capability is providing a centralized search tool to discover other MCP servers and their respective tools. Unlike local implementations, it runs remotely with OAuth authentication and permission controls for security.
Developer Tools Search Agent Orchestration
13

Related MCP Servers

mcpcute
Agent Orchestration Developer Tools
zhigang1992
A
license
Not graded
quality
C
maintenance
An MCP aggregator that consolidates multiple MCP servers behind a single interface with just 3 tools (search, get details, execute), reducing context pollution for AI agents by avoiding direct exposure of numerous tool schemas.
Updated 22 days ago (2026-09-02 03:39 UTC)
13 npm
2
MIT
MCP Gateway
Developer Tools Agent Orchestration
MikkoParkkola
F
license
A
quality
A
maintenance
A multiplexing gateway that aggregates multiple MCP servers into a single port, significantly reducing context token usage through a Meta-MCP discovery system. It enables dynamic tool discovery and invocation across various transport protocols including stdio, HTTP, and SSE.
Updated 5 hours ago (2026-09-23 21:31 UTC)
15
75
-
slop-mcp
Agent Orchestration Developer Tools
standardbeagle
A
license
B
quality
A
maintenance
An MCP orchestration layer that aggregates multiple MCP servers while exposing only 8 meta-tools, dramatically reducing context window usage, and provides SLOP scripting, event monitoring, and tool customization.
Updated 13 days ago (2026-09-11 00:12 UTC)
10
MIT
harmonyos-dev-mcp
Developer Tools Testing & QA Tools
Deslord319
F
license
D
quality
B
maintenance
Enables HarmonyOS device discovery, app build and deployment, UI automation, E2E inspection, and log validation through MCP tools.
Updated 4 days ago (2026-09-20 01:14 UTC)
18
12
-

OH-MCPStack

1. 项目解决的问题

2. 当前已实现能力

3. 总体架构

3.1 mcpd 模块拆分

4. 快速开始

4.1 环境要求

4.2 编译

4.3 启动服务

4.4 渐进式工具发现

5. 示例调用

5.1 查询工具列表

5.2 调用天气工具

5.3 查看统计信息

6. MCP 工具集合

7. 测试与复现

7.1 完整测试命令

7.2 测试脚本说明

8. 阶段性测试结果

8.1 上下文长度优化

8.2 工具结果缓存

8.3 安全测试

8.4 性能 benchmark

8.5 多 Agent 并发压力测试

8.6 Docker 资源受限边缘测试

9. 端到端 Demo

10. OpenHarmony 集成方案

11. 仓库结构

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

13. 后续计划

14. License

9. Agent 框架接入说明

HMAC-SHA256 签名安全增强

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

mcpcute

MCP Gateway

slop-mcp

harmonyos-dev-mcp