pi-delegate-mcp

██████╗ ██╗    ██████╗ ███████╗██╗     ███████╗ ██████╗  █████╗ ████████╗███████╗
██╔══██╗██║    ██╔══██╗██╔════╝██║     ██╔════╝██╔════╝ ██╔══██╗╚══██╔══╝██╔════╝
██████╔╝██║    ██║  ██║█████╗  ██║     █████╗  ██║  ███╗███████║   ██║   █████╗
██╔═══╝ ██║    ██║  ██║██╔══╝  ██║     ██╔══╝  ██║   ██║██╔══██║   ██║   ██╔══╝
██║     ██║    ██████╔╝███████╗███████╗███████╗╚██████╔╝██║  ██║   ██║   ███████╗
╚═╝     ╚═╝    ╚═════╝ ╚══════╝╚══════╝╚══════╝ ╚═════╝ ╚═╝  ╚═╝   ╚═╝   ╚══════╝
                            ███╗   ███╗ ██████╗██████╗
                            ████╗ ████║██╔════╝██╔══██╗
                            ██╔████╔██║██║     ██████╔╝
                            ██║╚██╔╝██║██║     ██╔═══╝
                            ██║ ╚═╝ ██║╚██████╗██║
                            ╚═╝     ╚═╝ ╚═════╝╚═╝

pi コーディングエージェントを委任可能で、誘導可能なワーカーとして公開する MCP サーバーです。

Claude Code（または任意の MCP ホスト）からこのサーバーを指し示し、pi の約 38 のプロバイダー（DeepSeek、Grok、GLM、Kimi、Qwen、Codex、OpenRouter、ローカルの llama.cpp）のいずれかに作業を委任できます。サブエージェントのコンテキストはメインの会話には入りません。

これは何のためのものか

メインのハーネスは高価なモデルで動作し、コンテキストウィンドウを気にしています。そのモデルが行う作業の多くは、そのモデルを必要とせず、むしろコンテキストを積極的に損なうものです。リポジトリ内のすべての呼び出し箇所を grep する、1 つの質問に答えるために 2000 行のファイルを読む、リファクタリングが残したものを監査する、などです。

代わりに、その作業をデリゲートに任せましょう。

• コスト。 単純作業は DeepSeek、GLM、Kimi、Qwen、またはローカルの llama.cpp で実行されます。フロンティア価格を支払うのは、実際にそれらを必要とする推論だけです。

• コンテキスト。 デリゲートは独自の予算でファイルを読み、結果を返します。読み取った 200 KB が会話に入ることはありません。

• 影響範囲。 デリゲートはデフォルトで読み取り専用（read, grep, find, ls）であり、セッション構築時に強制されます。安価なモデルが探索的な作業を行う場合、オプトインしない限りツリーに触れることはできません。

デリゲートは常に pi エージェントです。Codex、Grok、DeepSeek などはその背後にあるモデルを供給します。これはそれらの CLI のラッパーではありません。

Related MCP server: handoff-mcp

なぜ pi なのか、opencode や CLI ラッパーではないのか？

デリゲートが誘導可能であるためには、2 つのチャネルが開いている必要があります。タスクの途中でリダイレクトできなければならず、また、何かを尋ねて、回答があるまでブロックできなければなりません。別のプログラムからコーディングエージェントを駆動するほとんどの方法では、両方が閉じられています。

pi -p と --mode json は ctx.hasUI = false を設定します。そのように開始されたデリゲートは、構造上、発火して忘れるだけです。質問を提起できず、リダイレクトもできません。

opencode の SDK は別のサーバープロセス用の型付きクライアントです。createOpencode() は opencode serve を起動し、HTTP で通信します。クリーンな設計ですが、監視すべき 2 番目のプロセスがあり、公開されるセッションサーフェス（prompt、abort、revert、messages）には、ターン途中のステアリングも、エージェントが呼び出し元に何かを尋ねる経路もありません。

pi は createAgentSession を埋め込み可能なライブラリとして提供しています。このサーバーはセッションオブジェクトをプロセス内に保持するため、session.steer() は現在のツール呼び出しの後、次のモデル呼び出しの前にメッセージを配置でき、合成の uiContext はエージェントの質問を捕捉して answer のために保留します。シェルアウトされるものはなく、監視する必要もありません。

* 質問は pi 拡張機能から来るため、そのチャネルは extensions: true で生成されたデリゲートにのみ開かれています。Web 検索とその他の拡張ツール を参照してください。

（この表は委任チャネルを比較しており、サンドボックス化ではありません。opencode には独自の権限設定があります。このサーバーが何を強制し、何を強制しないかについては、デフォルトで読み取り専用 を参照してください。）

ツール

インストール

Node.js 22.19+ と、一度ログインしたことのある動作する pi インストール（pi、次に /login）が必要です。

Claude Code

claude mcp add pi -e PI_DELEGATE_MODEL=openrouter/stealth/ox-alpha -- npx -y pi-delegate-mcp

任意の MCP ホスト、.mcp.json 経由

{
  "mcpServers": {
    "pi": {
      "command": "npx",
      "args": ["-y", "pi-delegate-mcp"],
      "env": { "PI_DELEGATE_MODEL": "openrouter/stealth/ox-alpha" },
      "timeout": 1800000
    }
  }
}

npx は起動のたびにパッケージを解決します。固定するには、グローバルにインストールしてバイナリを直接呼び出します。

npm install -g pi-delegate-mcp

{ "mcpServers": { "pi": { "command": "pi-delegate-mcp", "timeout": 1800000 } } }

サーバーキーは短くしてください。すべてのツール名のプレフィックスになるためです（mcp__pi__spawn）。

ソースから

git clone https://github.com/howznguyen/pi-delegate-mcp && cd pi-delegate-mcp
npm install && npm run build && npm link

最初の実行

エージェントに何かを委任するよう依頼してください。エージェントは init を一度呼び出してこのサーバーが到達できるものを学習し、次に spawn を呼び出します。

{ "id": "audit-01", "label": "who still imports onnxruntime",
  "prompt": "Search this repo for anything still importing onnxruntime and list the files.",
  "cwd": "/path/to/repo" }

{ "sessionId": "audit-01", "state": "running", "model": "opencode-go/deepseek-v4-flash",
  "activeTools": ["read", "grep", "find", "ls"] }

spawn はすぐに返ります。status で順序付けられたツールトレースと回答をポーリングするか、複数が進行中の場合は sessions を使用します。init が失敗した場合、何が欠けているかを正確に示します。pi がインストールされていない、プロバイダーがログインしていない、一致するモデルスコープがない、などです。

以下の例のモデル名は例示です。models を実行して、自分の pi インストールが実際に到達できるものを確認してください。

トレーサビリティ

spawn と run はどちらも独自の id と自由形式の label を受け入れます。

{
  "id": "search-audit-01",
  "label": "what ONNX removal left behind",
  "prompt": "...",
  "model": "opencode-go/deepseek-v4-flash"
}

ID は [A-Za-z0-9._:-]、1〜64 文字、英数字で始まる必要があり、ライブセッション間で一意である必要があります。省略すると UUID になります。

完了したセッションは消えずに status と sessions で読み取り可能なままなので、デリゲートが実際に何をしたかを後で確認できます。最新の PI_DELEGATE_HISTORY（デフォルト 50）が保持されます。forget で早期に削除できます。

status は順序付けられた toolCalls トレースを返します。デリゲートが実行したすべてのツールと、引数とタイミングです。verbose: true を追加すると、呼び出し ID と結果が含まれます。

{
  "seq": 1,
  "id": "call_467b4bb4…",
  "name": "bash",
  "state": "ok",
  "ms": 10,
  "args": "{\"command\":\"echo hello-trace\"}",
  "result": "hello-trace\n"
}

引数と結果は（PI_DELEGATE_TRACE_ARGS、PI_DELEGATE_TRACE_RESULT）でクリップされ、削除された長さが記録されるため、大きなファイルの 1 回の read がコンテキストをあふれさせることはありません。

デリゲートにもう 1 ターン与える

完了したデリゲートは使い捨てではありません。pi はセッションをメモリに保持するため、follow_up は、すでに読み取ったすべてをコンテキストに保持したまま、同じエージェントに再プロンプトします。

{ "sessionId": "search-audit-01", "prompt": "Now check whether the build files reference it too" }

{ "sessionId": "search-audit-01", "state": "running", "turnsSoFar": 1 }

デリゲートは中断したところから再開します。最初のターンで読み取ったファイルをまだ保持しているため、2 番目の質問は、リポジトリを再読込する新しいセッションではなく、1 回のモデル呼び出しで済みます。

これはデリゲートと会話するための安価な方法です。新しいものを生成すると、タスクを再説明し、同じファイルを再読込するためのコストがかかり、その回答にはそこに至るまでの推論が一切含まれません。

follow_up はまだ作業中のデリゲートを拒否します。タスク途中のリダイレクトは steer の役割だからです。この 2 つは交換可能ではありません。steer は実行中のエージェントのツール呼び出しの間に配置され、follow_up は完了したエージェントで新しいターンを開始します。

ファンアウト

spawn_batch は 1 回の呼び出しでバッチ全体を開始します。タスクはバッチレベルの model、cwd、tools、extensions を継承し、必要に応じて個別にオーバーライドします。

{
  "idPrefix": "audit",
  "model": "opencode-go/deepseek-v4-flash",
  "cwd": "/repo",
  "tools": ["ls"],
  "tasks": [
    { "prompt": "What still imports onnxruntime?", "label": "imports" },
    { "prompt": "Which build files still reference ONNX?", "label": "build" },
    {
      "prompt": "Any ONNX model files left on disk?",
      "label": "artifacts",
      "model": "opencode-go/ox-alpha-free"
    }
  ]
}

これにより、audit-01、audit-02、audit-03 という名前が付けられ、数ミリ秒で返ります。デリゲートの起動は、考えるのを待たないためです。

バッチは何かが開始される前に検証されます。ID 形式、バッチ内の ID の重複、すでにライブの ID、ブロックされたツール、すべてのモデル名。1 つのタスクが不良だと、呼び出しは失敗し、何も起動されません。ファンアウトの半分は最悪の結果です。開始されたデリゲートのコストを支払い、どれが開始されなかったかを特定する必要があるからです。

バッチ全体をポーリングするには、デリゲートごとに 1 つの status ではなく、1 つの sessions 呼び出しを使用します。実際に読みたいデリゲートにのみ status にドロップダウンします。steer と abort はセッションごとに残ります。

呼び出しごとのモデル選択

任意の呼び出しの model は PI_DELEGATE_MODEL をオーバーライドします。解決できない名前はハードエラーであり、デフォルトモデルへのサイレントフォールバックは決してありません。サイレントフォールバックは、要求していないモデルに課金される方法だからです。

どの名前が解決されるかは、pi 自身の enabledModels スコープによって決定されます。このサーバーはそれを単に表示するだけでなく強制します。

opencode-go/deepseek-v4-flash  -> ok      (listed in enabledModels)
opencode-go/glm-5.3            -> refused (out of scope)
knowns-hub/claude-opus         -> ok      (custom provider, see below)

カスタムプロバイダーはスコープをバイパスします。 ~/.pi/agent/models.json で宣言されたプロバイダーが提供するモデルは、enabledModels がその名前を挙げていない場合でも提供されます。プロバイダーを手動で宣言することは、それを使用する意図があると見なされるためです。これが、リストが enabledModels よりもはるかに長くなり得る理由です。スコープ内の 3 つのエントリと 2 つのカスタムプロバイダーで、15 の提供モデルになることは簡単です。init は、該当する場合、models.scopeNote でこれを明示的に示します。

2 つのスイッチでそれを変更できます。

models を呼び出して、現在有効な設定で実際に到達可能なものを確認してください。

ステータスライン

Claude Code は statusLine コマンドを 1 つだけ許可するため、pi-delegate-statusline は既存のものをラップし、このワークスペースのデリゲートを示すセグメントを追加します。

{
  "statusLine": {
    "type": "command",
    "command": "PI_DELEGATE_STATUSLINE_WRAP=ccstatusline pi-delegate-statusline",
    "refreshInterval": 10
  }
}

PI_DELEGATE_STATUSLINE_WRAP を削除すると、pi セグメントのみが表示されます。

π ▸ audit engine·t1·12s audit index·t2·8s   running, with turn counts and elapsed time
π ▸ migrate·t7·3m04s ?1 waiting             one delegate is blocked on a question
π ✓2                                        finished, nothing running

どのデリゲートがどのセッションに属するか

ディレクトリによるフィルタリングだけでは不十分です。同じリポジトリで開かれた 2 つの Claude Code セッションは、互いのデリゲートを表示してしまいます。属性は代わりにプロセス系統を使用します。

MCP ホストはセッションごとに 1 つのサーバーを生成するため、サーバーは process.ppid（ホストの pid）を記録します。同じホストによって生成されたステータスラインは、自身の祖先をたどり、hostPid がそこにある状態ファイルのみを保持します。同じリポジトリ、2 つのセッション、クロストークなし。ディレクトリフィルタは、これが存在する前に書き込まれた状態ファイルのフォールバックとして残ります。

状態は $XDG_STATE_HOME/pi-delegate-mcp/<pid>.json に保存されます（PI_DELEGATE_STATE_DIR で場所を変更可能）。ファイルはプロセスが消えたときに削除されますが、ESRCH の場合のみです。EPERM はプロセスが別のユーザーとして生存していることを意味するためです。サーバーは stdin が閉じるかホストの pid が消えると自動的に終了するため、トランスポートを閉じずにホストが死んでも何も残りません。

デフォルトでは読み取り専用

ツールはセッション構築時に read, grep, find, ls にロックされます。それ以外はセッションが作成される前に拒否されます。

これを広げるには、サーバー上で追加のツールを指定します：

"env": { "PI_DELEGATE_ALLOW_TOOLS": "bash" }

または PI_DELEGATE_ALLOW_WRITE=1 ですべてを許可します。

bash は中間手段ではありません。 pi には権限システムが搭載されていないため、bash を保持するデリゲートは、write と edit がリストに含まれていなくても、ファイルの書き込み、削除、ネットワークへの到達が可能です。これら2つを拒否しつつ bash を許可することは意図を記録するだけで、何も強制しません。Claude Code の権限プロンプトやフックは pi の動作を一切認識しません。本当の境界が必要な場合は、このサーバーをコンテナ内で実行してください。

Web 検索とその他の拡張ツール

pi 自身のツールは read, grep, find, ls, bash, powershell, write, edit です。その中に検索やフェッチはありません。これらは pi 拡張機能から提供され、拡張機能が独自のツールを登録し、デリゲートがそれらを使用できます。

呼び出しで extensions: true を設定し、サーバー上でツール名を許可します：

"env": { "PI_DELEGATE_ALLOW_TOOLS": "web_search,fetch_content" }

{ "prompt": "Find the current Node LTS version and tell me just the number",
  "extensions": true, "tools": ["read", "grep", "find", "ls", "web_search"] }

{ "seq": 1, "name": "web_search", "state": "ok", "ms": 2568,
  "args": "{\"query\":\"latest stable Node.js LTS version\",\"numResults\":5}" }

これが、bash を渡さずにデリゲートにネットワーク到達を許可する方法です。web_search は検索のみが可能で、他のツールと同じ許可リストを通過するため、それを要求しない呼び出しでは読み取り専用のデフォルトは変わりません。

どのツールが存在するかは、サーバーを実行しているユーザーがインストールしているものに依存します。pi-web-access は web_search, fetch_content, source_check, get_search_content を提供します。pi-mcp-adapter は ~/.pi/agent/mcp.json 内の MCP サーバーをブリッジし、mcp として公開します。pi には独自の MCP クライアントがないため、その拡張機能が唯一の経路です。

extensions: true は、意図した拡張機能だけでなく、インストールされているすべての拡張機能を信頼します。 それらはセットとして読み込まれ、このサーバーのプロセスの全権限で実行され、セッションを超えて存続するソケットやタイマーを開くものもあります。デフォルトで有効にするのではなく、必要なデリゲートのために呼び出しごとにオンにしてください。また、実際の起動時間がかかるため、要求されない限りオフになっています。

設定

長時間実行の作業

MCP TypeScript SDK はデフォルトで 60 秒 のリクエストタイムアウトを持ち、実際のタスクはそれを超えてしまいます。優先順位の高い順に3つの防御策があります：

1. spawn + status を使用する。ブロックするものがないため、タイムアウトは適用されません。

2. run は定期的な進行通知を発行し、ホストのタイムアウトをリセットします。

3. .mcp.json の "timeout" または環境変数 MCP_TOOL_TIMEOUT で上限を引き上げます。

CLAUDE_AUTO_BACKGROUND_TASKS=1 を設定すると、Claude Code は約2分後に長時間の MCP 呼び出しをバックグラウンドにします。バックグラウンド化されると進行通知は破棄されるため、(1) または (3) のどちらかを選択し、両方は選択しないでください。

認証

サーバーは資格情報を処理しません。pi は ~/.pi/agent/auth.json から認証し、次に環境変数を使用します。MCP ホストは多くの場合、環境変数が削除された状態でサーバーを起動するため、シェルプロファイルでキーをエクスポートするよりも auth.json（pi を一度実行して /login）を優先してください。

開発

npm install
npm run build       # tsc, src/*.ts -> dist/
npm run typecheck   # tsc --noEmit, strict
npm run test:ci     # offline: boots the server over stdio and lists its tools
npm test            # full suite: needs a logged-in pi, makes real model calls

test:ci は CI が実行するものであり、prepublishOnly がゲートするものです。資格情報やネットワークが不要だからです。npm test は実際のデリゲートを実際のプロバイダーに対して駆動するため、コストがかかり、pi がログインしている環境でのみ動作します。

リリースはタグ駆動です。npm version patch && git push --follow-tags はビルドとテストを実行し、OIDC トラステッドパブリッシングで公開するため、リポジトリ内に npm トークンは保存されません。

Issue とプルリクエストは歓迎します。動作がおかしいデリゲートを報告する場合は、verbose: true を指定した status の toolCalls トレースが役立つ情報です。

先行実装

abatilo/pi-mcp-bridge はよりシンプルな方法を取っています：pi --mode json -p --session-id <uuid> を起動し、pi にセッションをディスク上に永続化させるため、ブリッジは状態を一切保持しません。エレガントで、読む価値があります。その代わりに、ステアリング、質問、ツール制御を犠牲にしています。

ライセンス

MIT