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.

Quick Start • Configuration • Available Tools • Safety Contract • Upstream Attribution

Key Highlights

• ⚡ Asynchronous Delegated Execution: Offload heavy coding, refactoring, and exploration tasks to background OMP worker instances without blocking your main conversation session.

• 🔀 Topological DAG Orchestration: Execute interdependent batch tasks with automatic topological sorting, concurrency control, and dependency propagation.

• 🛡️ Workspace Path Isolation: Enforce explicit write-path boundaries and prevent overlapping file modifications between concurrent tasks.

• 🔍 Supervised Resumption & Envelopes: Inspect interim logs in real time, extract structured JSON outcome envelopes, and supply supervisory guidance to retry or adjust tasks.

Upstream Attribution & Disclaimer

• External Upstream CLI: This project interfaces with Oh My Pi (OMP), an open-source tool released under the MIT License.

• User Prerequisites:

  • Node.js >= 22.0.0.

  • Users must install and configure their own local instance of the OMP CLI.

  • Users are responsible for complying with the OMP CLI license and terms applicable to their environment.

Features

• Asynchronous Delegated Execution: Launch independent sub-agent coding tasks without blocking the main conversational session.

• DAG & Batch Orchestration: Run interdependent batch tasks with topological dependency sorting, concurrency limits, and automatic dependency propagation.

• Strict Task Safety & Ownership: Built-in validation checks prevent multiple concurrent tasks from writing to overlapping file paths or colliding within the same workspace.

• Continuous Supervision & Feedback: Inspect interim output, stream logs, retrieve structured JSON envelopes, and supply supervisory feedback to continue or retry attempts.

• Cross-Platform Design: Designed for local Node.js environments on Windows, macOS, and Linux; validate OMP CLI availability on your platform.

Installation & Quick Start

# 1. Clone the repository
git clone https://github.com/divenire990/omp-worker-mcp.git
cd omp-worker-mcp

# 2. Install dependencies
npm ci

# 3. Build TypeScript to dist/
npm run build

# 4. Run test suite
npm test

Configuration

Configuration is managed via environment variables (or configured directly in your MCP client).

Cross-Platform Environment Examples

Windows (cmd / PowerShell)

set OMP_WORKER_OMP_COMMAND=omp
set OMP_WORKER_STATE_DIR=C:\Users\YourUser\.codex\state\omp-worker

macOS / Linux (bash / zsh)

export OMP_WORKER_OMP_COMMAND=/usr/local/bin/omp
export OMP_WORKER_STATE_DIR=/home/youruser/.codex/state/omp-worker

Codex MCP Client Configuration Example

Add the server to your Codex MCP configuration (e.g. in config.toml):

Windows Example

[mcp_servers.omp-worker]
command = "node"
args = ["C:/path/to/omp-worker-mcp/dist/index.js"]

[mcp_servers.omp-worker.env]
OMP_WORKER_OMP_COMMAND = "omp"
OMP_WORKER_STATE_DIR = "C:/Users/YourUser/.codex/state/omp-worker"

macOS / Linux Example

[mcp_servers.omp-worker]
command = "node"
args = ["/path/to/omp-worker-mcp/dist/index.js"]

[mcp_servers.omp-worker.env]
OMP_WORKER_OMP_COMMAND = "/usr/local/bin/omp"
OMP_WORKER_STATE_DIR = "/home/youruser/.codex/state/omp-worker"

Available MCP Tools

Task Safety & Ownership Contract

1. Write vs. Read-Only Isolation:

   • write tasks must declare the specific file paths they own.

   • read_only tasks are strictly restricted from workspace modification.

2. DAG Overlap Verification:

   • Tasks running in parallel cannot declare overlapping write boundaries.

   • Tasks modifying shared paths must declare explicit linear DAG dependencies (depends_on).

3. Structured Verification Contract:

   • Every completed sub-task is expected to return structured verification details and updated artifact descriptions.

License

This project is licensed under the MIT License.