omp-worker-mcp

omp-worker-mcp

メインの AI エージェントに計画とレビューを任せ、実作業のコーディングはローカルの Oh My Pi ワーカーに任せましょう。

ChatGPT、Codex、Claude Code、Cursor などの MCP クライアントをスーパーバイザーにし、
お使いのマシン上の Oh My Pi（OMP）をバックグラウンドの作業部隊にする MCP サーバーです。

英語 · 简体中文 · ドキュメント

クイックスタート · 使い方 · ツール · 設定 · 安全性モデル · FAQ

機能

多くのコーディングエージェントは、コードの読み取り、計画、編集、テストの実行、修正まで、すべてをひとつの会話とひとつのモデルの予算内で行います。omp-worker-mcp はこの作業を2つの役割に分けます。

omp-worker-mcp は両者をつなぐ橋渡し役です。スーパーバイザーに少数の MCP ツールを提供し、バックグラウンドで OMP を起動して、すべてのジョブをディスクに保存し、大量のログではなく、簡潔で構造化されたレポートを返します。

主な特長

• 単一のタスクにも、計画全体にも対応 — omp_run_compact は単一のタスクを委任します。omp_run_batch_compact は最大50件のタスクを依存関係グラフ（DAG）として実行し、一度に最大10件を並行処理します。
• 宣言された書き込み範囲の検証 — バッチ内で並行して書き込みを行うタスクは、各タスクが担当するパスを宣言する必要があります。宣言された範囲の重複と依存関係の循環は、ワーカーの起動前に拒否されます（これはスケジューリング上のチェックとプロンプトによる制約であり、OS のファイルシステムロックではありません）。
• レビューしやすい結果 — 各ワーカーは、ステータス、概要、変更ファイル、検証の根拠、残作業を含む OMP_WORKER_RESULT エンベロープを出力して完了します。
• 再起動ではなく修正 — omp_continue は同じ OMP セッションにフィードバックを送信するため、ワーカーはコンテキストを維持します。
• ジョブを永続化 — ジョブの記録、ログ、結果はディスクに保存され、MCP サーバーの再起動後も読み取れます。
• ウェブ版 ChatGPT から利用可能 — OpenAI の Secure MCP Tunnel を介して利用できます。インバウンドポートは不要で、ジョブの実行先ディレクトリを制限する許可リスト（OMP_WORKER_ALLOWED_ROOTS。0.2.0 以降で利用可能。npm 0.1.1 にはこの機能はありません）も使用できます。

使用する場面

適している場合

• 意思決定は高性能なモデルに任せ、より高速または低コストのモデルに入力を担当させたい場合。
• 機能の追加、テスト付きのバグ修正、複数モジュールにまたがるリファクタリング、長時間の読み取り専用調査など、委任するのに十分な規模のタスクがある場合。
• エージェント同士が互いの変更を上書きせずに、リポジトリの複数の部分を並行して作業させたい場合。
• ChatGPT を使って考えをまとめ、手元のマシンにあるファイルを操作させたい場合。

おそらく必要ない場合

• 変更が1行だけ、または質問への回答がすぐに済む場合。スーパーバイザー自身のツールのほうが高速です。
• OS レベルの本格的なサンドボックスが必要な場合。このプロジェクトが制御するのは、ジョブの開始場所と、ジョブが触れるよう指示される対象であり、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. 委任する場面をエージェントに伝える

サーバーを登録するとツールが利用可能になりますが、エージェントがそれを選択するようになるわけではありません。プロジェクトの指示ファイル（Codex の場合は AGENTS.md、Claude Code の場合は CLAUDE.md、その他の場合は .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.

表示される内容： エージェントが omp_run_compact を呼び出し、OMP がバックグラウンドで動作して、ファイルを変更せずに短い要約が返ってきます。ジョブが待機時間（デフォルトで 60 s）を超えて実行されると、呼び出しはステータス running の job_id を返し、エージェントは 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 タスクでは何も指定しません。
• 同時に実行される可能性のある 2 つのタスクで、所有するパスを重複させることはできません。代わりに depends_on を使って順序を指定してください。
• max_parallel は 1～10 です（デフォルトは 4）。グループ全体には期限があります（group_timeout_minutes、デフォルトは 60）。
• 待機時間が終わった時点でグループがまだ実行中の場合は、group_id が返されます。omp_wait_group で処理を続けてください。

ジョブを監督する

ツール

パラメーターと制限の詳細：ツールリファレンス。

設定

設定はすべて環境変数を通じて行います。クライアントの MCP 設定（env）またはサーバーを起動するシェルで設定してください。

すべての変数、ディスク上のレイアウト、再起動時の動作について：運用ガイド · .env.example。

安全モデル

omp-worker-mcp が適用する制約

• OMP_WORKER_ALLOWED_ROOTS が設定されている場合（0.2.0 以降で利用可能。npm 0.1.1 にはこの機能がありません）、ジョブの cwd は realpath による解決後、承認済みのルート内にある必要があります。OMP の起動前に、兄弟ディレクトリのプレフィックスを悪用する手法や、シンボリックリンク／ジャンクションを介した逸脱は拒否されます。値が設定されているものの無効な場合は、フェイルクローズします。
• バッチでは、並列実行する write タスクの ownership が互いに重複せず、グラフが非巡回である必要があります。これはワーカーを起動する前にチェックされます。
• ownership と読み取り専用の意図は、明示的な制約として各ワーカーに渡されます。

適用されないこと

• サンドボックスではありません。 OMP とその実行内容は、サーバーを起動したユーザーアカウントと同じ権限を持ちます。ownership はスケジューリング時のチェックとワーカーへの指示であり、ファイルシステムロックではありません。
• 何を安全に実行できるかは判断しません。git push、公開、デプロイ、シークレットの変更は、自分とスーパーバイザーの管理下に置いてください。

リモートアクセス（Secure MCP Tunnel 経由の ChatGPT など）では、必ず OMP_WORKER_ALLOWED_ROOTS を設定し、権限を制限した専用アカウント、コンテナー、または VM の使用も検討してください。脆弱性を報告するには、SECURITY.md を参照してください。

プラットフォームのサポート

検証済みの Linux に関する報告やクライアント設定を歓迎します。貢献方法を参照してください。

よくある質問

ドキュメント

COMPATIBILITY.md では公開仕様とバージョニングポリシーを定義しています。CHANGELOG.md にはリリースが記載されています。

コントリビューション

Issue とプルリクエストを歓迎します。特に 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