omp-worker-mcp

omp-worker-mcp

让你的主 AI Agent 负责规划和审查，并将实际编码工作交给本地 Oh My Pi 工作器。

一个 MCP 服务，可将 ChatGPT、Codex、Claude Code、Cursor 和其他 MCP 客户端变成 监督者，
并将你自己机器上的 Oh My Pi（OMP）变成后台 工作团队。

English · 简体中文 · 文档

快速开始 · 用法 · 工具 · 配置 · 安全模型 · 常见问题

功能介绍

大多数编码 Agent 都在同一处完成所有工作：读取代码、规划、编辑、运行测试、修复——全部发生在同一段对话中，并消耗同一个模型的预算。omp-worker-mcp 将这些工作拆分为两个角色：

omp-worker-mcp 是两者之间的桥梁。它为监督者提供一小组 MCP 工具，在后台启动 OMP，将每项任务保存在磁盘上，并返回简短的结构化报告，而不是一大堆日志。

亮点

• 单项任务或完整计划——omp_run_compact 可委派单项任务；omp_run_batch_compact 可将最多 50 项任务作为依赖关系图（DAG）运行，每次最多运行 10 项。
• 声明式写入范围校验——批处理中的并行写入任务必须声明其负责的路径；在任何工作器启动前，系统会拒绝声明范围重叠和依赖循环（这是调度检查和提示词约束，并非操作系统文件系统锁）。
• 结果便于审查——每个工作器完成后都会生成一个 OMP_WORKER_RESULT 信封，其中包含状态、摘要、已更改文件、验证证据和待处理事项。
• 修正而非重启——omp_continue 会向同一个 OMP 会话发送反馈，因此工作器会保留上下文。
• 持久化任务——任务记录、日志和结果都保存在磁盘上，即使 MCP 服务重启后仍可读取。
• 支持从网页版 ChatGPT 使用——通过 OpenAI 的 Secure MCP Tunnel 实现：无需开放入站端口，并提供允许列表（OMP_WORKER_ALLOWED_ROOTS，从 0.2.0 开始提供；npm 0.1.1 不包含此功能），用于限制任务可运行的目录。

适用场景

适合以下情况

• 你希望由能力更强的模型做决策，同时由更快或更便宜的模型负责输入；
• 任务规模足以交接：一个功能、带测试的错误修复、多模块重构，或耗时较长的只读调查；
• 你希望并行处理仓库中的多个部分，同时避免 Agent 互相覆盖；
• 你习惯用 ChatGPT 思考，并希望它能操作你自己机器上的文件。

以下情况可能不值得使用

• 变更只有一行，或问题很简单——主管自身的工具更快；
• 你需要真正的操作系统级沙箱。此项目控制任务从哪里开始，以及告知任务可以触及什么内容，而不是 OMP 在技术上能够做什么（参见安全模型）。

快速开始

你需要： Node.js ≥ 22 · 已安装 Oh My Pi · 一个 MCP 客户端（Codex、Claude Code、Cursor、ChatGPT 等）。

1. 安装并设置 OMP

按照官方说明安装 OMP，然后：

omp --version   # confirm the CLI is on your PATH
omp setup       # sign in and choose the default model

你在此处选择的默认模型将用于所有工作者。（高级设置：在 ~/.omp/agent/config.yml 中设置 modelRoles.default: <provider>/<model>。）

如果 omp 不在你的 PATH 中，请在下方的 MCP 配置中将 OMP_WORKER_OMP_COMMAND 设置为可执行文件的完整路径。

2. 在客户端中注册 MCP 服务

无需全局安装——客户端会通过 npx -y omp-worker-mcp 运行已发布的软件包。选择你的客户端：

[mcp_servers.omp-worker]
command = "npx"
args = ["-y", "omp-worker-mcp"]

[mcp_servers.omp-worker.env]
OMP_WORKER_OMP_COMMAND = "omp"

# Optional (Codex Code Mode only): let Codex call omp-worker tools directly
# without code-mode wrapping. Per the current Codex config reference, merge into
# your existing [features.code_mode] table (do not create a duplicate table header)
# and append "mcp__omp_worker" while preserving any other list entries:
[features.code_mode]
direct_only_tool_namespaces = ["mcp__omp_worker"]

export OMP_WORKER_OMP_COMMAND=omp
export OMP_WORKER_ALLOWED_ROOTS='["/Users/you/Projects"]'   # strongly recommended for remote access (available since 0.2.0; 0.1.1 lacks this feature)
export CONTROL_PLANE_API_KEY='<runtime-api-key>'

tunnel-client init \
  --sample sample_mcp_stdio_local \
  --profile omp-worker \
  --tunnel-id <your-tunnel-id> \
  --mcp-command "npx -y omp-worker-mcp"

tunnel-client doctor --profile omp-worker --explain
tunnel-client run --profile omp-worker

claude mcp add omp-worker --scope user --env OMP_WORKER_OMP_COMMAND=omp -- npx -y omp-worker-mcp

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

更改配置后，请重启客户端。

3. 告诉你的 Agent 何时委派

注册服务会让工具变为可用，但不会让 Agent 主动选择使用它们。请在项目的指令文件 AGENTS.md（Codex）、CLAUDE.md（Claude Code）、.cursorrules / .github/copilot-instructions.md（其他客户端）中添加一条简短策略，或添加到 ChatGPT 的项目指令中：

## Delegation policy (omp-worker-mcp)
- Quick questions, single-file edits, design discussion: do it yourself.
- Substantive single tasks (feature, bug fix, refactor, long investigation): inspect briefly,
  then delegate with `omp_run_compact`, giving a clear `goal` and `acceptance` criteria.
- Multi-part work: use `omp_run_batch_compact`. Parallel write tasks need disjoint `ownership`;
  tasks touching the same files must be ordered with `depends_on`.
- Review every result. If acceptance is not met, use `omp_continue` with specific feedback.
- Never delegate `git push`, publishing, deployments or secret changes — confirm those with the user.

更完整的模板：请参阅作者工作流 → 策略模板。

4. 运行你的第一个任务

先从只读任务开始：

Use omp-worker-mcp to do a read-only inspection of this workspace: summarize the
project structure and dependencies. Do not modify any files.

你应该看到： Agent 调用 omp_run_compact，OMP 在后台运行，并返回一段简短摘要，且没有文件发生更改。如果任务运行时间超过等待窗口（默认 60 s），调用会返回状态为 running 的 job_id，Agent 会继续调用 omp_wait——这是正常情况。

用法

设置好策略后，只需描述你想要的结果。以下示例展示了监督器在底层发送的内容。

单个任务

“在 src/net/ 中为 HTTP 客户端添加指数退避机制，编写单元测试，并确保 npm test 通过。”

// omp_run_compact
{
  "cwd": "/path/to/repo",
  "goal": "Add exponential backoff (max 5 retries) to src/net/client.ts for 5xx and network errors.",
  "acceptance": [
    "Unit tests cover the retry and give-up paths",
    "npm test passes"
  ],
  "timeout_minutes": 30
}

返回的内容很简洁（删节示例）：

{
  "job_id": "job-…",
  "status": "completed",
  "attempt": 1,
  "max_attempts": 3,
  "session_id": "sess-…",
  "summary": "Added retry with exponential backoff to the HTTP client.",
  "artifacts": [
    { "path": "src/net/client.ts", "description": "retry loop + backoff helper" },
    { "path": "test/net/client.test.ts", "description": "retry / give-up tests" }
  ],
  "verification": ["npm test: all tests passed"],
  "remaining": [],
  "details_path": "…/jobs/job-…/job.json"
}

将多个任务作为 DAG 执行

“并行地为 API 添加 /health 端点，并为 UI 添加状态徽章，然后添加一个涵盖两者的集成测试。”

graph LR
  api["api · write src/api/"] --> tests["tests · write tests/"]
  ui["ui · write src/ui/"] --> tests

// omp_run_batch_compact
{
  "cwd": "/path/to/repo",
  "max_parallel": 2,
  "tasks": [
    { "id": "api",   "goal": "Add GET /health returning build info.", "access": "write", "ownership": ["src/api/"] },
    { "id": "ui",    "goal": "Show a status badge fed by /health.",   "access": "write", "ownership": ["src/ui/"] },
    { "id": "tests", "goal": "Add an integration test for /health and the badge.",
      "depends_on": ["api", "ui"], "access": "write", "ownership": ["tests/"],
      "acceptance": ["npm test passes"] }
  ]
}

值得了解的规则：

• write 任务必须在 ownership 中列出其负责的路径（相对于 cwd）；read_only 任务不列出路径。
• 两个可能同时运行的任务不能负责重叠路径——应使用 depends_on 为它们排序。
• max_parallel 的取值范围为 1–10（默认值为 4）；整个任务组都有截止时间（group_timeout_minutes，默认值为 60）。
• 如果等待窗口结束时任务组仍在运行，你会获得一个 group_id；请使用 omp_wait_group 继续等待。

监督任务

工具

完整参数和限制：工具参考。

配置

所有配置均通过环境变量完成，可在客户端的 MCP 配置（env）中设置，也可在启动服务的 Shell 中设置。

所有变量、磁盘布局和重启行为：运维 · .env.example。

安全模型

omp-worker-mcp 强制执行的约束

• 设置 OMP_WORKER_ALLOWED_ROOTS 后 (自 0.2.0 起可用；npm 0.1.1 不具备此功能)，作业的 cwd 必须通过 realpath 解析到获准根目录内。相邻目录前缀技巧和符号链接／junction 越界都会在 OMP 启动前被拒绝；如果设置了该值但值无效，则会默认拒绝。
• 在批处理中，并行 write 任务的 ownership 必须互不重叠，且依赖图必须无环；这些检查会在启动任何工作进程前完成。
• ownership 和只读意图会作为明确约束传递给每个工作进程。

它不会做什么

• 它不是沙箱。OMP 及其运行的任何程序都拥有启动服务的用户账户的相同权限。ownership 是一项调度检查和对工作进程的指令，并非文件系统锁。
• 它不会判断运行什么才安全。请自行处理 git push、发布、部署和机密变更，并由主管 Agent 负责监督。

对于远程访问（例如，通过 Secure MCP Tunnel 使用 ChatGPT），请务必设置 OMP_WORKER_ALLOWED_ROOTS，并考虑使用专用的低权限账户、容器或 VM。如需报告漏洞，请参阅 SECURITY.md。

平台支持

非常欢迎提交 Linux 报告和你已验证的客户端配置 — 请参阅贡献指南。

常见问题

文档

COMPATIBILITY.md 定义了公开契约和版本策略；CHANGELOG.md 列出各个版本。

参与贡献

欢迎提交问题和拉取请求，尤其欢迎 Linux 验证和经过测试的客户端配置。请从 CONTRIBUTING.md 开始。要从源代码构建：

git clone https://github.com/divenire990/omp-worker-mcp.git
cd omp-worker-mcp
npm ci
npm test        # builds, then runs the test suite against a fake OMP

致谢

本项目基于 Model Context Protocol TypeScript SDK 构建，并围绕 Oh My Pi（MIT）设计。OMP 不包含在本项目中，必须单独安装。本项目独立开发，与 OMP、OpenAI 或 Anthropic 均无关联。

许可证

MIT