{
  "markdown": "<div align=\"center\">\n\n# omp-worker-mcp\n\n**Durable Model Context Protocol (MCP) server for delegating background coding tasks and DAG workflows to local Oh My Pi (OMP) CLI sub-agents.**\n\n<p align=\"center\">\n  English •\n  <a href=\"README.zh-CN.md\">简体中文</a> •\n  <a href=\"docs/README.md\">Documentation Hub</a>\n</p>\n\n[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![npm version](https://img.shields.io/npm/v/omp-worker-mcp.svg)](https://www.npmjs.com/package/omp-worker-mcp)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](package.json)\n[![CI](https://github.com/divenire990/omp-worker-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/divenire990/omp-worker-mcp/actions/workflows/ci.yml)\n\n<br />\n\n<img src=\"assets/orchestration.gif\" alt=\"Async DAG Orchestration Flow\" width=\"800\" />\n\n<p align=\"center\">\n  <em>Asynchronous task execution, DAG dependency resolution, path ownership isolation, and structured result verification.</em>\n</p>\n\n[Quick Start](#installation-quick-start) • [Entrypoints](#recommended-entrypoints) • [Safety Contract](#task-safety-ownership) • [Platform Support](#platform-support-boundaries) • [Docs Hub](docs/README.md)\n\n</div>\n\n---\n\n## Value & Operating Model\n\n`omp-worker-mcp` implements an outcome-led **Supervisor-Worker** pattern that decouples high-level planning from concrete implementation:\n\n- **Main Agent Remains in Control**: The primary host harness (e.g., Codex, Claude Code) retains full authority over architecture, task decomposition, trade-off decisions, and final acceptance review.\n- **Durable Local Background Execution**: Concrete, long-running coding, refactoring, and exploratory tasks are offloaded to local OMP worker processes running in the background without blocking conversational turns.\n- **Topological DAG Orchestration**: Independent work units can be orchestrated as a directed acyclic graph (DAG) with automated dependency resolution, concurrency limits, and failure containment.\n- **Explicit Path Ownership Boundaries**: Write tasks must declare explicit write-path ownership. The server validates and rejects overlapping concurrent write scopes in batch DAGs, supplying declared boundaries as worker constraints to prevent write collisions.\n- **Structured Results & Supervised Resumption**: Workers report deliverables via the structured `OMP_WORKER_RESULT` envelope (status, summary, artifacts, verification checks, remaining items). Supervisors can inspect logs in real time and inject corrective guidance via `omp_continue` to retry within the same session.\n\n---\n\n## Installation & Quick Start\n\n### 1. Install OMP\nInstall [Oh My Pi (OMP) from its official project](https://github.com/can1357/oh-my-pi). (Note: running `omp-worker-mcp` requires local Node.js `>= 22.0.0`.)\n\n### 2. Verify OMP Reachability\nVerify that the OMP CLI is reachable in your environment:\n\n```bash\nomp --version\n```\n\n*Troubleshooting: If `omp` is not on your `PATH`, set `OMP_WORKER_OMP_COMMAND` to its executable path in your MCP configuration.*\n\n### 3. Configure OMP & Default Worker Model\nRun `omp setup` in your terminal to authenticate, configure your local OMP environment, and select your default worker model. This default model is what background OMP workers use during task execution.\n\n*(Optional advanced configuration)*: You can specify your default model via `modelRoles.default: <provider>/<model>` in `~/.omp/agent/config.yml`. For upstream configuration options, see [Oh My Pi](https://github.com/can1357/oh-my-pi).\n\n### 4. Install / Register omp-worker-mcp from npm via npx & Restart Host\nAdd `omp-worker-mcp` to your host harness's stdio `mcpServers` configuration. The host runs the published npm package using `npx -y omp-worker-mcp`, which downloads and caches it on first use; ordinary users do not need `git clone` or `npm install -g`. Keep the JSON configuration below as the executable setup and restart your host harness:\n```json\n{\n  \"mcpServers\": {\n    \"omp-worker\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"omp-worker-mcp\"],\n      \"env\": {\n        \"OMP_WORKER_OMP_COMMAND\": \"omp\"\n      }\n    }\n  }\n}\n```\n\n*For detailed client configurations covering Codex (`config.toml`), Claude Code, Cursor, VS Code / GitHub Copilot, Windsurf Cascade, and Continue, see [Client Configurations](docs/client-configurations.md).*\n\n### 5. Send Your First Prompt\nAfter restarting your host harness, paste a read-only inspection prompt directly into your conversation to verify the full delegation chain:\n\n```text\nPlease use the configured omp-worker-mcp to perform a read-only inspection of the current workspace, review the project structure and dependencies, and provide a concise summary report. Do not modify any files.\n```\n---\n\n### For Contributors / Local Development: Building from Source\n\n```bash\ngit clone https://github.com/divenire990/omp-worker-mcp.git\ncd omp-worker-mcp\nnpm ci\nnpm run build\nnpm test\n```\n\n## Recommended Entrypoints\n\nWhile MCP registration and policy heuristics guide host harnesses to select high-level entrypoints based on task complexity, automatic invocation is not guaranteed. Users may also explicitly request omp-worker-mcp in prompts when delegation is critical or if the host falls back to direct execution:\n\n- **`omp_run_compact` (Single Task)**: High-level single-task entrypoint selected by the host to delegate a discrete coding or research assignment, wait up to `wait_seconds` for execution, and return a compact structured summary and artifact list.\n- **`omp_run_batch_compact` (Multi-Task / DAG)**: High-level multi-task entrypoint selected by the host to dispatch interdependent tasks with explicit dependency graphs and concurrency limits, waiting for aggregated results.\n\n*For lower-level primitives (`omp_delegate`, `omp_wait`, `omp_result`, `omp_continue`, `omp_cancel`, `omp_wait_group`, `omp_cancel_group`) and complete schemas, consult the [Tool Reference](docs/tool-reference.md).*\n\n---\n\n## Task Safety & Ownership\n\n1. **Declared Write Ownership in Batch DAGs**: In batch DAG tasks (`omp_run_batch_compact`), `write` task items must explicitly declare the workspace paths they own via `ownership`, while `read_only` task items declare no write scope. For single-task execution (`omp_run_compact`), read-only and no-modification constraints are expressed directly in `goal` and `acceptance`.\n2. **DAG Overlap Validation**: The server validates batch groups and rejects concurrent tasks with overlapping write scopes; tasks operating on shared paths must declare sequential `depends_on` dependencies.\n3. **Structured Verification Contract**: Subagents deliver results using the structured `OMP_WORKER_RESULT` envelope (status, summary, artifacts, verification checks, remaining items).\n\n*High-impact operations (e.g., `npm publish`, `git push`, production deployments, secret modification) must always remain under direct host harness and human supervision.*\n\n---\n\n## Platform Support & Boundaries\n\n- **Upstream Engine**: Interfaces with the [Oh My Pi (OMP)](https://github.com/can1357/oh-my-pi) CLI (MIT License). The upstream binary is **not bundled** and must be installed separately in your local runtime `PATH`.\n- **Runtime Requirement**: Node.js **>= 22.0.0** (native ECMAScript Modules and modern Node.js APIs).\n- **Operating Systems**:\n  - **Windows** and **macOS (Apple Silicon)**: Verified with Node.js 22+ and real OMP CLI end-to-end testing.\n  - **Linux**: Supported by the architecture, but awaiting broader production verification.\n- **Support Tiers**:\n  - **Author-Verified**: Codex (author's daily local workflow; not a cross-platform CI guarantee).\n  - **Documented / Reproducible**: Claude Code, Cursor, VS Code / GitHub Copilot, Windsurf Cascade, Continue (*not CI integration-tested*).\n  - **Cloud / Remote Hosts**: Conditional (*requires complete runtime, OMP CLI in PATH, writable workspace, and process spawning permissions*).\n\n---\n\n## Documentation Hub\n\nDetailed documentation is organized in the [`docs/`](docs/README.md) directory:\n\n- [**Documentation Index**](docs/README.md): Overview of documentation layout and responsibilities.\n- [**Author Workflow Enablement & Architecture**](docs/author-workflow.md): Enablement tutorial, policy templates, host-worker supervision loop, and authoring guidelines.\n- [**Client Configurations**](docs/client-configurations.md): Documented and reproducible configuration guidance for Codex, Claude Code, Cursor, VS Code / GitHub Copilot, Windsurf Cascade, and Continue.\n- [**Operations & State Lifecycle**](docs/operations.md): Environment variables, state directory layout, retention policies, and recovery.\n- [**Tool Reference & Safety Contract**](docs/tool-reference.md): Full MCP tool specifications and safety boundaries.\n- [**Benchmark Protocol**](benchmarks/README.md): Reproducible evaluation protocol comparing direct host execution against supervisor-worker delegation.\n- [**Official MCP Registry Publishing Guide**](docs/registry-publishing.md): Step-by-step maintainer release workflow for npm and the Official MCP Registry.\n\n---\n\n## Compatibility & Changelog\n\n- **Public Contract & Deprecation**: Review [COMPATIBILITY.md](COMPATIBILITY.md) for versioning guarantees.\n- **Release History**: Review [CHANGELOG.md](CHANGELOG.md) for notable updates.\n\n---\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n",
  "bytes": 9374,
  "sha": "d7299ee364b9bdd3293858434ee9dc3bf7d23187a9e39c556a89b54f49f51a74",
  "repo_slug": "divenire990/omp-worker-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_divenire990_omp_worker_mcp_786130cf/readme"
}