OH-MCP-Native

A system-native MCP (Model Context Protocol) protocol stack for OpenHarmony.

OH-MCP-Native moves MCP tool discovery, session management, cross-framework caching, context optimization, tool routing, identity-based authorization, data classification, security auditing, and MCP-specific attack mitigation out of per-framework agent middleware and down into a user-space OpenHarmony system service. LangChain, HelloAgents, and native OpenHarmony applications can then share one unified, secure, observable, cross-device MCP capability.

The codebase is split into a platform-independent core plus thin platform shells:

• A protocol core and Linux fallback that are fully runnable and testable on a plain host — no sudo, no service installation, no global config.
• An OpenHarmony SystemAbility scaffold (C++) with compile-tested, fail-closed replacement points for Binder identity, HUKS, HiSysEvent, and DSoftBus, ready to build inside a standard-system source tree.

Why system-native MCP

The service combines OS identity, HUKS, audit, DSoftBus, and shared system state behind one MCP endpoint. A per-framework library shares nothing across frameworks; a standalone gateway caches only among its own clients and still trusts self-reported identity.

Capability	Why it needs the OS	Demonstrated by
Cross-framework shared cache	one system service is shared system-wide by every framework, not just the clients of one gateway	run_cross_framework_demo.sh: one upstream call, one cross-agent cache hit
Real application-identity auth	Binder yields the caller’s true uid/pid/bundle/accessTokenId; a user-space library runs at app privilege and trusts self-reported identity	policy enforced before tool execution; NativeStatus() target gate
Cross-device tool routing	one registry merges local and remote tools and routes/fails over transparently	run_cross_device_demo.sh: authenticated relay, edge-01 -> edge-02 failover, cache fallback
secure-mcp profile	security expressed as negotiated protocol fields and signed manifests, not a side channel	initialize negotiation, signed tools/list, classified result _meta
Retransmission governance	duplicate concurrent calls converge before reaching upstream	run_retransmission_demo.sh: 16 identical calls collapse to 1 execution
Context optimization	a compressed tool view plus content-addressed result references cut model-injected tokens	result-reference token reduction ~73%

Verified locally

Reproduce with bash scripts/run_all_local_checks.sh. These are real local measurements (host-dependent); the OpenHarmony on-device gates are listed under Status.

Check	Result
C++ smoke suite (ctest)	5/5 passed
Python unit/integration suite	142 tests passed
Latency ablation (100 req, concurrency 8)	UDS warm-cache p50 4 ms vs HTTP no-cache ~13 ms (3x faster)
Result-reference context tokens	~73% reduction (weather.get)
Retransmission governance	16 identical calls -> 1 execution
Integration surface	39 -> 13 LoC (LangChain + HelloAgents adapters)
Security red-team matrix	16/16 checks pass

Architecture

A caller is admitted once (identity, negotiation, policy, guard); everything below the admission plane is shared system state.

Framework / OH-native callers
  LangChain | HelloAgents | official MCP SDK | AutoGen | Cline | OH app
        |  Binder IPC | Streamable HTTP | stdio | UDS
        v
mcpd  --  admission plane
          caller identity -> secure-mcp negotiation -> policy / quota -> guard
        |
        v
          protocol plane
          lifecycle | tools | resources | prompts | tasks / progress
        |
        v
          system services
          shared cache | retry governor | context (result_ref) | audit | metrics
        |
        +--> local MCP tools (weather / calc / fs)
        +--> remote edge MCP node  (DSoftBus target / HTTP relay fallback)

See docs/01_design.md for the full design and docs/00_overview.md for the documentation reading order.

Runnable surface

• MCP JSON-RPC core: initialize, notifications/initialized, ping, tools/list, tools/call, resources/{list,read,subscribe,unsubscribe}, prompts/{list,get}, notifications/{cancelled,progress,message}, tasks/{list,cancel}, logging/setLevel, shutdown, notifications/exit, plus explicit unsupported responses for sampling/createMessage and elicitation/create.
• Transports: Streamable-HTTP-style POST /mcp endpoint (JSON responses; GET returns 405 and SSE streaming is not implemented), stdio (python3 -m oh_mcp_native.stdio_server), and a Unix domain socket fallback (python3 -m oh_mcp_native.uds_server).
• Policy checks by caller identity and tool scope; per-agent QPS/concurrency quotas; replay-nonce protection and origin checks on the HTTP endpoint.
• System shared cache with scope/data-class isolation and an encrypted at-rest file provider for the Linux fallback.
• Context optimizer (compressed tool view, result references, observation de-duplication), retry governor (circuit breaking, in-flight de-duplication), output/manifest/prompt guard, and a metrics snapshot endpoint.
• secure-mcp profile: initialize capability negotiation, signed tool manifests (HMAC dev signer, optional OpenSSL Ed25519 verification), data classification, and an encrypted audit log fallback.
• Cross-device L1 routing via a local remote-relay edge node with HMAC channel authentication and node failover.
• Six framework adapter surfaces (LangChain, HelloAgents, official MCP SDK, AutoGen, Cline/Cursor config, OpenHarmony native).
• OpenHarmony SystemAbility source skeleton with a fail-closed native backend factory, a read-only OH_ROOT gate preflight, and scaffold validation.

Build and verify

All commands stay inside the workspace.

bash scripts/build_linux.sh            # Python syntax build + C++ core/scaffold + ctest
bash scripts/run_unit_tests.sh         # Python unit/integration/security suite
bash scripts/run_all_local_checks.sh   # gate + build + tests + every demo + benchmark

Start the Linux fallback transports:

bash scripts/start_mcpd_linux.sh   # HTTP /mcp on 127.0.0.1:7000
bash scripts/start_mcpd_stdio.sh   # stdio transport
bash scripts/start_mcpd_uds.sh     # Unix domain socket fallback

Example HTTP call:

curl -sS http://127.0.0.1:7000/health
curl -sS -X POST http://127.0.0.1:7000/mcp \
  -H 'Authorization: Bearer dev-token' \
  -H 'X-MCP-Agent-Id: com.demo.tripplanner' \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"weather.get","arguments":{"city":"Beijing"}}}'

Repository layout

src/oh_mcp_native/         protocol core, transports, security, cache, optimizer
src/core/cpp/              portable C++ core (smoke target)
src/platform/openharmony/  SystemAbility scaffold (proxy/stub/SA, native backends)
src/platform/linux/        Linux daemon smoke shell
adapters/                  six framework adapter surfaces
examples/                  runnable demos (trip planner, cross-device, red team, ...)
bench/                     load generator, ablation, concurrency sweep, plots
configs/                   policy and server configuration
official_tests/            import/run harness for externally provided tests
tests/                     Python unit/integration tests and C++ smoke tests
scripts/                   build, run, test, and OpenHarmony integration scripts
docs/                      design, integration, API, security, routing, reproduce

Status

The Linux fallback, protocol core, transports, security, caching, context optimizer, retry governance, secure-mcp negotiation, cross-device L1 relay, and all adapters are verified locally by the test, demo, and benchmark suites. The remaining work requires an OpenHarmony target and is intentionally not stubbed as complete:

• Build and run the SystemAbility in a standard-system source tree and replace the four native backends (Binder identity, HUKS, HiSysEvent, DSoftBus) with on-device implementations.
• Run externally provided official tests and real third-party MCP servers in the target environment.

See docs/02_openharmony_integration.md for the bring-up path.