omp-worker-mcp

omp-worker-mcp

Durable Model Context Protocol (MCP) server for delegating asynchronous coding tasks and DAG workflows to local Oh My Pi (OMP) CLI sub-agents.

English • 简体中文 • Documentation Hub

Asynchronous task execution, DAG dependency resolution, path ownership isolation, and structured result verification.

Quick Start • Minimal Config • Tool Overview • Safety Contract • Benchmark Protocol • Platform Support • Docs Hub

Key Highlights

• ⚡ Asynchronous Task Delegation: Offload long-running coding, refactoring, and exploration tasks to background OMP workers without blocking conversational turns.
• 🔀 Topological DAG Orchestration: Execute interdependent batch tasks with automatic dependency validation, concurrency pool limiting, and failure containment.
• 🛡️ Workspace Path Isolation: Enforce explicit write-path boundaries to prevent overlapping modifications between parallel tasks.
• 🔍 Supervised Resumption & Envelopes: Inspect interim execution logs in real time, extract structured result envelopes (OMP_WORKER_RESULT), and inject supervisory feedback via omp_continue.
• 💾 Persistent State & Configurable Retention: File-backed state persistence for job metadata and logs with optional TTL and storage capacity bounds.

Why This Architecture?

omp-worker-mcp adopts a supervisor-worker delegation model: a premium host LLM (such as Codex or Claude Code) focuses on architecture, task decomposition, and acceptance review, while autonomous omp-worker-mcp background workers handle concrete execution.

Empirical Hypothesis: Delegating execution-heavy coding tasks to background workers frees the primary host harness to focus on high-level design and verification, reducing conversational context fatigue while enabling multi-task parallelism. Evaluate this hypothesis empirically using our reproducible Benchmark Protocol.

Platform Support & Boundaries

• Upstream Engine: Interfaces with the Oh My Pi (OMP) CLI (MIT License). The upstream binary is not bundled and must be installed in your local runtime PATH.
• Runtime Requirement: Node.js >= 22.0.0 (native ESM and standard library capabilities).
• Operating Systems:
  • Windows (win32) & macOS (darwin / Apple Silicon): Fully verified with Node 22+ and real OMP CLI E2E testing.
  • Linux (x86_64, aarch64): Architectural design target; awaiting broader production verification.
• Support Tiers:
  • Author-Verified: Codex (author's daily local workflow; not a cross-platform CI guarantee).
  • Documented / Reproducible: Claude Code, WorkBuddy, Claude Desktop, Cursor, Cline, VS Code, Copilot CLI (not CI integration-tested).
  • Cloud / Remote Hosts: Conditional (requires complete runtime, OMP CLI in PATH, writable workspace, and process spawning permissions).

Installation & Quick Start

omp-worker-mcp is an MCP server launched by stdio MCP hosts (such as Codex, Claude Code, etc.) using npx or a global install, rather than a standalone interactive CLI.

Host Stdio Command (Recommended)

# Executed by your stdio MCP host configuration (e.g., mcpServers)
npx -y omp-worker-mcp

Global Installation

# Install globally via npm
npm install -g omp-worker-mcp

Building from Source

git clone https://github.com/divenire990/omp-worker-mcp.git
cd omp-worker-mcp
npm ci
npm run build
npm test

Minimal MCP Configuration

Add omp-worker-mcp to your host harness's mcpServers configuration using standard stdio transport:

{
  "mcpServers": {
    "omp-worker": {
      "command": "npx",
      "args": ["-y", "omp-worker-mcp"],
      "env": {
        "OMP_WORKER_OMP_COMMAND": "omp"
      }
    }
  }
}

For detailed configs covering Codex (config.toml), Claude Code CLI, WorkBuddy, and other clients, see Client Configurations.

Available MCP Tools

Single Task Delegation Tools

Tool	Purpose
omp_run_compact	Recommended for single tasks: Delegates a coding task and waits up to wait_seconds for a compact summary.
omp_delegate	Low-level dispatch: Spawns an asynchronous background worker and returns a job_id.
omp_wait	Polls or waits for an asynchronous job to reach a terminal status or timeout.
omp_result	Inspects attempt history, stdout/stderr logs, modified artifacts, and structured result envelopes.
omp_continue	Injects supervisory guidance into a failed or blocked task to retry within the same session.
omp_cancel	Sends a cancellation signal to terminate a running job and its child process tree.

Batch & DAG Orchestration Tools

Tool	Purpose
omp_run_batch_compact	Recommended for multi-task workflows: Runs an interdependent task DAG with concurrency control and waits for completion.
omp_wait_group	Waits for progress or completion of an asynchronous batch task group.
omp_cancel_group	Cancels all active and queued tasks within a batch group.

For complete tool schemas and parameter references, consult the Tool Reference.

Task Safety & Ownership

• Write vs. Read-Only Boundaries: write tasks must explicitly declare the workspace paths they own via ownership; read_only tasks are strictly prohibited from modifying files.
• DAG Overlap Verification: Parallel tasks within the same batch cannot declare overlapping write boundaries; tasks sharing paths must declare sequential depends_on dependencies.
• Structured Verification Contract: Subagents deliver deliverables using the structured OMP_WORKER_RESULT envelope (status, summary, artifacts, verification checks, remaining items).

High-impact operations (e.g., npm publish, git push, production deployments, secret modification) must always remain under direct host harness and human supervision.

Documentation Hub

Detailed documentation is organized in the docs/ directory:

• Documentation Index: Overview of documentation layout and responsibilities.
• Author Workflow & Architecture: Host-Worker supervision loop, execution strategies, and authoring guidelines.
• Client Configurations: Documented and reproducible configuration guidance for Codex, Claude Code, WorkBuddy, Cursor, VS Code, and more.
• Operations & State Lifecycle: Environment variables, state directory layout, retention policies, and recovery.
• Tool Reference & Safety Contract: Full MCP tool specifications and safety boundaries.
• Benchmark Protocol: Reproducible evaluation protocol comparing direct host execution against supervisor-worker delegation.

Compatibility & Changelog

• Public Contract & Deprecation: Review COMPATIBILITY.md for versioning guarantees.
• Release History: Review CHANGELOG.md for notable updates.

License

This project is licensed under the MIT License.