OH-MCP CapsuleBus

A capability-secure, zero-copy execution substrate for Model Context Protocol tool calls, targeting OpenHarmony-style ubiquitous systems.

Instead of exposing every tool as an external server reached over JSON-RPC, CapsuleBus treats a tool call as an OS-managed capsule execution: a signed tool capsule runs in a sandbox, reached through an invocation-scoped capability token, with a control-plane / data-plane split so large results never enter the JSON-RPC copy chain. The MCP surface (initialize, tools/list, tools/call) is preserved, so standard clients keep working while the internal path is the capsule ABI.

The implementation is host-safe: no root, no destructive shell operations, no external network dependency at run time. All generated data stays under run/, results/, dist/, web/, native/build/, capsules/, and .venv/.

Architecture

A tool call enters through the MCP adapter, the PolicyEngine mints an invocation-scoped capability token, and the capsule runs on one of three executors (Python handler, WASM under Wasmtime, or the native worker). Its result is written into a MAP_SHARED arena and returned as a handle — only 48-byte control records cross the ring, and taint propagates through the object graph so a poisoned or secret-derived value cannot silently reach a privileged tool.

What is implemented

• Native zero-copy data plane (native/): an io_uring-style SQ/CQ shared-memory ring plus a fixed-slot object arena (capsule_ring.hpp), a two-process daemon + client (capsulebusd.cpp), and a benchmark (capsule_bench.cpp) that measures it against a base64/JSON-RPC baseline. The payload stays in a MAP_SHARED arena (Ashmem-equivalent on OpenHarmony); only 48-byte control records cross the ring. The worker validates every untrusted SQE offset and length against the arena and enforces the per-opcode capability bits before touching memory.
• WASM/WASI capsule sandbox (capsulebus/wasm_executor.py, capsules/wasm/*.wat): capsules run under Wasmtime with no ambient authority; the host ABI is capability-gated and CPU is bounded by fuel. The gate is precise (an authorized secret read is allowed, an undeclared one denied) and a runaway loop is killed by the fuel limit.
• mcpcc (capsulebus/mcpcc.py) compiles MCP tool schemas into .mcap capsule packages with minified manifests, policy files, typed C++/Python/TS stubs, signature hashes and an SBOM. Output is deterministic.
• CapsuleBusRuntime (capsulebus/runtime.py) executes registered capsules through invocation-scoped capability tokens, enforces the deadline budget, and records every decision to an audit ledger.
• ObjectStore (capsulebus/object_store.py) keeps large payloads out of the LLM context and returns compact object handles with provenance and taint.
• PolicyEngine (capsulebus/security.py) blocks undeclared secret reads, network exfiltration, prompt-injection taint into privileged tools, and Level-4 actuation without confirmation.
• McpAdapter (capsulebus/mcp.py) implements initialize, tools/list, tools/call, and ping, negotiates the protocol version, and carries CapsuleBus-specific fields under the spec _meta envelope.
• OpenHarmony adapter (adapters/openharmony/): GN/SystemAbility target sources plus Ashmem/Binder/DSoftBus compatibility shims and a host smoke that exercises the adapter contract on Linux without hb, gn, hdc, or root.
• Dashboard (frontend/): a React + Three.js + ECharts metrics dashboard built with Vite. Third-party libraries are installed under frontend/node_modules and are not part of the source tree.

Build and test

# Native zero-copy data plane -> native/build/{capsule_bench,capsulebusd}
bash scripts/build_native.sh

# Optional: project venv with Wasmtime (real WASM capsules) and pytest
python3 -m venv .venv
./.venv/bin/python -m pip install -r requirements.txt pytest

# Tests (WASM tests skip without Wasmtime; native tests skip without g++)
./.venv/bin/python -m pytest -q

tests/ covers the runtime, capability policy and taint flow, deadline enforcement, the object store, mcpcc (determinism + typed ABI), the MCP adapter and _meta extension path, the active router, the WASM sandbox (precise gate + fuel limit + allow/deny network paths), and the native data plane (a real two-process zero-copy round trip plus the SQE validation guard checks).

Run the layers directly

./native/build/capsule_bench all                     # W1 concurrency + W2 large payload + guard checks (JSON on stdout)
./native/build/capsule_bench validate                # data-plane input-validation guard checks only
./native/build/capsulebusd serve run/shm/d.arena &   # two-process daemon ...
./native/build/capsulebusd client run/shm/d.arena 1048576 1000   # ... + checksum-verified client
python3 scripts/run_native_dataplane.py              # -> results/native_dataplane.json
./.venv/bin/python scripts/run_wasm_capsules.py      # -> results/wasm_capsules.json
python3 -m capsulebus.demo                           # end-to-end edge-inspection demo -> results/

Full pipeline

bash scripts/run_showcase.sh

This builds the native data plane, runs the WASM capsules, executes the end-to-end demo, renders the static status page and dashboard, verifies the dashboard with Playwright, writes a validation summary and artifact manifest, and packages a portable bundle. Key outputs:

• results/showcase_summary.json — machine-readable run summary.
• results/native_dataplane.json — measured zero-copy ring vs base64/JSON-RPC, plus the data-plane guard checks.
• results/wasm_capsules.json — WASM capability-sandbox scenarios.
• results/security_redteam.json — red-team blocking output.
• results/validation_summary.json — pass/fail validation matrix.
• results/artifact_manifest.json — SHA-256 inventory of generated artifacts.
• web/showcase.html / web/dashboard/index.html — status page and dashboard.

web/showcase.html is a self-contained page and opens directly in a browser. The dashboard is a single-page app that loads ES modules, so serve it over HTTP rather than file://:

python3 -m http.server -d web/dashboard 8000   # then open http://127.0.0.1:8000/

OpenHarmony boundary

A full target build needs hb, gn, hdc, or repo and an OpenHarmony source tree, none of which are assumed here. The pipeline therefore runs the adapter in host mode and records that boundary in results/host_status.md. The same adapters/openharmony/native_service sources are used for the target build when a tree is available; see docs/openharmony_porting.md.

See docs/design.md, docs/security_model.md, and docs/benchmark_methodology.md for details.