MCPOrb

MCPOrb — Portable MCP Packager & Marketplace

🌐 MCPOrb.ai — The PDF for AI-native knowledge delivery.

MCPOrb is a portable, self-contained MCP (Model Context Protocol) server that packages knowledge, index, and runtime into a single local file. It is the critical infrastructure for Harness Engineering: shifting AI value from raw model capability to deterministic, structured system architecture.

Key ecosystem roles:

• Portable MCP Packager — bundles structured knowledge into zero-trust, air-gapped Orbs that run entirely on-device with zero data upload
• MCP Marketplace — browse, publish, and license Orbs at MCPOrbStore
• ANTcell-enabled — designed for the solo-engineer organizational unit to distribute mathematically certain knowledge packs without external SaaS leak risks
• EnumAI-aligned — provides high-fidelity context injection, moving towards deterministic retrieval over probabilistic guesswork

This repository owns the runtime that powers a standalone Orb executable:

• Exposes a MCP Server over stdio JSON-RPC for AI clients like Claude Desktop, Cursor, VS Code
• Serves a local Web UI at http://127.0.0.1:<port>/<token>/ for human inspection
• Exposes MCP Streamable HTTP at http://127.0.0.1:<port>/<token>/mcp when the Web UI server is running
• Loads Orb assets produced elsewhere and serves multi-strategy retrieval at runtime (BM25, TF-IDF, Trigram, Vector, Hybrid)

💡 For pre-built Orbs, trial licenses, and the Builder desktop app, visit MCPOrbStore.

Features

Capability	Description
Zero-trust local execution	Runs entirely on-device with no data upload, no cloud dependency, no telemetry
Single-file portable Orb	One file contains knowledge, search index, and runtime — no npm install, no Docker, no database
Multi-strategy search	BM25 / TF-IDF / Trigram / Vector / Hybrid — built-in, no external service
MCP-native	Exposes standard search_knowledge tool to Claude Desktop, Cursor, VS Code, and any MCP client
Password-gated + encrypted	Optional AES encryption and access password for sensitive knowledge packs
Local Web UI	Built-in axum server at http://127.0.0.1:<port>/<token>/ for human inspection and testing
CLI + GUI	Operates in stdio-only, GUI-only, or combined modes
Cross-platform runtime	Apple Silicon (M1/M2/M3), Linux (Ubuntu 20.04+, Debian), Windows x64

Quick Start

# Build the runtime
cargo build -p mcporb-runtime

# Build Builder-ready full/lite runtimes in target/release/
bash scripts/build-builder-runtimes.sh

# Run the runtime directly against an Orb assets directory
cargo run -p mcporb-runtime -- --assets target/orbs/mda-guide --gui-only --open

To build, inspect, or package Orbs, use the MCPOrbBuilder that is undergoing development.

Packaged Orb Release

The packaged .orb file is still the preferred distributable artifact. It is produced by MCPOrbBuilder, but executed by the runtime in this repository.

Run the packaged Orb

# Open the local Web UI
./target/orbs/mda-guide.orb --gui-only --open

# Expose MCP over stdio only
./target/orbs/mda-guide.orb --stdio-only

# Run MCP stdio, Web UI, and Streamable HTTP
./target/orbs/mda-guide.orb --all-gui

MCP client configuration for the packaged Orb

When you distribute the single-file Orb, point your MCP client at the packaged executable and do not pass --assets.

MCP Client Configuration

Development setup with an external assets directory:

{
  "mcpServers": {
    "mda-guide": {
      "command": "/Users/qingjie.du/HDD/MCPOrb/target/debug/mcporb-runtime",
      "args": ["--assets", "/Users/qingjie.du/HDD/MCPOrb/target/orbs/mda-guide", "--all-gui"]
    }
  }
}

Note: Build the runtime first with cargo build -p mcporb-runtime. For production use, replace debug with release and build with cargo build --release -p mcporb-runtime. If you want Builder-compatible staged binaries (mcporb-runtime-full / mcporb-runtime-lite) in a multi-repo workspace, run bash scripts/build-builder-runtimes.sh.

Single-file packaged Orb setup:

{
  "mcpServers": {
    "mda-guide": {
      "command": "/Users/qingjie.du/HDD/MCPOrb/target/orbs/mda-guide.orb",
      "args": ["--all-gui"]
    }
  }
}

For production distribution, prefer the packaged .orb file over target/debug/mcporb-runtime plus a separate target/orbs/<name>/ directory.

When an Orb runs with --all-gui, MCP clients should call the get_web_ui_url tool to discover the local Web UI address. The URL is not exposed as an MCP resource.

When the Web UI server is running, local MCP clients that support Streamable HTTP can connect to http://127.0.0.1:<port>/<token>/mcp. ChatGPT web/cloud cannot reach that local URL; ChatGPT Desktop can use it only if the installed build supports user-configured local Streamable HTTP MCP servers. If a client expects a remote connector/app URL, publish the Orb through a trusted HTTPS MCP bridge instead.

Architecture

MCPOrb/
├── crates/
│   ├── mcporb-runtime/              # Orb runtime: MCP stdio + axum Web UI (CLI entry point)
│   ├── mcporb-runtime-core/         # Runtime-only data contracts and multi-strategy search logic
│   ├── mcporb-runtime-app/          # macOS Runtime App (Tauri-based GUI wrapper)
│   ├── mcporb-runtime-app-core/     # Shared core for the Runtime App
│   ├── mcporb-embed/                # Vector search query embedder (tract-onnx)
│   ├── mcporb-gateway-core/         # Gateway core logic (runtime lifecycle, metrics)
│   ├── mcporb-gateway-stdio/        # MCP stdio transport for the gateway
│   ├── mcporb-gateway-http/         # MCP Streamable HTTP transport + axum server
│   ├── mcporb-gateway-test-mock-runtime/  # Mock runtime for gateway integration tests
│   └── mcporb-size-spike/           # Runtime binary size spike measurement
├── public-orb/                      # Published showcase Orb artifacts and collateral
└── scripts/                         # Build, packaging, and verification scripts

Startup Modes

Mode	Command	Behavior
Auto (TTY)	./orb	Opens Web UI in browser
Auto (piped)	./orb	MCP stdio + silent Web UI
GUI only	./orb --gui-only --open	Web UI only, opens browser
Stdio only	./orb --stdio-only	MCP stdio, no HTTP server
All GUI	./orb --all-gui	MCP stdio + Web UI + Streamable HTTP
Remember unlock	./orb --unlock	Prompt once, store the unlock key in the OS keychain, then exit

CLI Reference

Flag	Description
--all-gui	MCP stdio + Web UI + Streamable HTTP
--gui-only	Web UI only, no MCP stdio
--stdio-only	MCP stdio only, no HTTP server
--open	Open Web UI in browser (default for --gui-only)
--no-open	Suppress auto-open of browser
--port <PORT>	HTTP server port (default: random)
--token <TOKEN>	Fixed token for HTTP MCP endpoint
--assets <DIR>	Load Orb from an assets directory
--orb-zip <PATH>	Load Orb ZIP bundle directly
--orb-zip-stdin	Read Orb ZIP from stdin (macOS App Sandbox)
--unlock	Prompt for password once, remember on device, then exit
--orb-id <ID>	Orb identifier for metrics persistence
--metrics-dir <DIR>	Directory for persisted metrics files
--bind-external	Bind to 0.0.0.0 instead of 127.0.0.1
--mcp-transport <LABEL>	Override transport label for MCP requests
--library-bookmark <B64>	macOS App Sandbox security-scoped bookmark

Hidden flags (--stdio-gui, --mcp-stdio) are internal aliases and may be removed without notice.

Password Protection

An Orb can be packaged with an optional access password (see the Builder's mcporb package --password). When enabled:

• The Web UI shows a login screen before the dashboard.
• MCP clients see only unlock_orb and get_web_ui_url until unlocked; search_knowledge and resources return a locked error.
• A single successful unlock opens the whole process. Because the default mode when an MCP client launches the Orb is --all-gui, unlocking once in the browser (via get_web_ui_url) also unlocks the in-process stdio MCP, so the password never has to be typed into the LLM conversation.
• unlock_orb (password passed to the tool) and --unlock (terminal prompt that remembers the unlock on this device via the OS keychain) are fallbacks, mainly for --stdio-only deployments.

Optionally, assets can be encrypted (--encrypt-assets): the packaged .orb then embeds only the ciphertext, so documents, chunks, and indexes cannot be extracted by unpacking the file without the password.

Security limits. Password gating and asset encryption protect the static .orb at rest and gate local access; they are not unbreakable DRM. After a correct password the runtime necessarily holds the decrypted, searchable data in memory — encryption does not protect already-decrypted runtime memory. Weak passwords remain crackable offline, so the Builder warns on short ones.

Binary Size Budget

Version	Budget
v0.1 (MVP)	≤ 15 MB
v0.2	≤ 20 MB

Check: bash scripts/check-binary-size.sh

License

MCPOrb Runtime is licensed under the Apache License 2.0.

MCPOrbBuilder is a separate commercial product with its own terms.

Related Resources

Resource	Link	Description
MCPOrbStore	https://mcporb.store	Browse, publish, and license portable MCP Orbs. Get a free 90-day Builder trial.
MCPOrbBuilder	MCPOrbBuilder repo	Desktop application for packaging, inspecting, and signing Orbs
MCPOrb License Server	licensing-site	Self-service licensing, device migration, and subscription management
Official site	https://MCPOrb.ai	Product overview, architecture documentation, and use cases

Related Concepts

• Model Context Protocol (MCP) — open standard enabling AI clients to securely access local data sources and tools
• Harness Engineering — paradigm shift from model-centric to architecture-centric AI systems
• ANTcell (Autonomous Non-divisible Team Cell) — single-engineer organizational unit empowered by deterministic tooling
• EnumAI — paradigm for deterministic retrieval and structured AI interaction

Development

cargo check --workspace
cargo test --workspace
cargo build -p mcporb-runtime --release

Public Orb

Selected showcase Orbs should be published under public-orb/. This directory is intentionally kept in the runtime repository so public Orb releases can ship alongside the runtime brand.