pi-cli-mcp

ローカルにインストールされた pi CLI にコーディングタスクを委任する MCP サーバーです。

エージェントの独自コピーをバンドルする代わりに、実際の pi バイナリをラップするため、すべての呼び出しは ~/.pi/agent/settings.json を継承します — プロバイダー、モデル、思考レベル、拡張機能、AGENTS.md / CLAUDE.md の検出など。モデルスタックに関する情報はここに複製されず、pi をアップグレードしてもサーバーはドリフトしません。

プライマリエージェント（Claude Code、Cursor、任意の MCP クライアント）が pi に作業を委任したい場合に使用します：異なるモデルによるセカンドオピニオン、メインのコンテキストウィンドウの外に保ちたい調査、または並行作業など。

インストール

npx -y pi-cli-mcp            # no install
npm install -g pi-cli-mcp    # or global

Node ≥ 20 と、PATH 上で動作する pi が必要です（npm i -g @earendil-works/pi-coding-agent）。

Claude Code

claude mcp add-json pi -s user '{
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "pi-cli-mcp"],
  "timeout": 3600000
}'
claude mcp list | grep '^pi:'      # expect: ✔ Connected

寛大な timeout が重要です：実際の委任タスクは数分間実行されることがあります。

その他の MCP クライアント

{
  "mcpServers": {
    "pi": { "command": "npx", "args": ["-y", "pi-cli-mcp"] }
  }
}

サーバー名は短く（pi）保ってください：モデルが表示するツール名の一部になります。

ツール

pi

pi({
  prompt: "Map how retries are wired in src/http.rs. Report call sites only.",
  cwd: "/abs/path/to/repo",
  tools: "read,grep,find,ls"
})

pi には権限システムがありません。 デフォルトのツールでは、cwd 内でユーザーとしてファイルを編集し、シェルコマンドを実行します。 タスクが分析の場合は、tools または no_tools を渡してください。サンドボックスが必要な場合は PI_MCP_WRAP を使用してください。

返されるもの

pi の最終回答と集計統計のみ — トランスクリプト、ツール引数、ツール出力は決して返されません：

[session: 0927adc5-a840-4b68-93ca-5ca344c9fafb]

Created note.md containing "hello" and updated target.txt to read "new content".

---
pi: bifrost/minimax/MiniMax-M3 · 5 turns · 4 tool calls: bash, read, write, edit · 11k in / 276 out · 9.8s
pi wrote: note.md, target.txt

• 「最終回答」は stopReason によって定義されます、位置ではありません：最後に確定したアシスタントメッセージ — stopReason が toolUse ではない最後のメッセージ（pi がツール呼び出しステップをマークする方法）。実行途中のナレーションは、前文がツール呼び出しとメッセージを共有している場合でも破棄されます。確定したメッセージにテキストがない場合、それは以前の前文に静かに遡るのではなく、壊れた実行として報告されます。何も確定しなかった場合、最後に生成されたテキストが返され、そのようにラベル付けされます。

• 回答は決して切り詰められません。 上限を設定したい場合は PI_MCP_MAX_OUTPUT を設定してください。診断情報のみが制限されます。

• pi wrote: は pi が実際にファイルを書き込んだ場合にのみ表示されます、そのため副作用チェックとしても機能します。

• 不正な stopReason は呼び出しを失敗させ、フェイルクローズします。 stop / length は成功です；error、 aborted、stopReason の欠落、および既知の語彙外のものはすべて、回答を添付したエラーとして報告されます。検証される stopReason は、返されるメッセージに属するものであり、最後に到着したイベントのものではありません。pi はクリーンに確定しなかったターンで終了コード 0 で終了することがあるため、終了コードだけは信頼されません。

• 生の stdout は回答として返されることはありません。 イベントストリームが期待される契約に一致しない場合、応答はその旨を述べ、到着したものの形状（メッセージ数、stopReason 値、ツール呼び出し数、バイト数）を説明します — トランスクリプト自体は決して返されません。ナレーション、ツール引数、ツール結果が漏洩するためです。

セッション

pi はセッション ID を返し、pi_reply はそれを続行します。会話は pi 自身のセッションファイルに保存されるため、このサーバーを再起動してもフォローアップは機能し続けます — セッション → ディレクトリのマップは ~/.local/state/pi-mcp/sessions.json に永続化されます。

1 つのセッションへの同時返信は直列化されます：2 つの pi プロセスが 1 つのセッションファイルに書き込むと破損する可能性があります。ID が不明な場合、pi は新しい会話を開始し、回答には既存のセッションを続行しているふりをする代わりに、明示的な [warning: no existing session …] が含まれます。

プロセス間の注意点。 セッションミューテックスはプロセスローカルです。2 つの MCP クライアントを 2 つのサーバープロセスに対して実行し、両方が 同じ セッション ID に同時に返信する場合、それらを直列化するものはありません。状態ファイルは再読み取りしてからマージする方式で書き込まれるため、一方のプロセスが学習したセッションが他方によって消去されることはありませんが、基になる pi セッションファイルにはそのような保護はありません。実際には、1 つのクライアントがセッションを所有します；厳密な保証が必要な場合は、サーバープロセスを 1 つに保ってください。

キャンセル

MCP notifications/cancelled は pi を SIGTERM で強制終了し、猶予期間後に SIGKILL にエスカレーションします。子プロセスも一緒に終了します：pi は独自のプロセスグループで実行され、ツリー全体にシグナルが送信されるため、pi がシグナルを転送できなくても、中断された sleep 120 は存続しません。

キャンセルは、呼び出しが並行スロットまたはセッションロックのキューに入る前に登録されるため、待機中にキャンセルされた呼び出しは pi をまったく起動しません。

シャットダウン — stdin EOF、SIGTERM、SIGINT、SIGHUP、または閉じた stdout — は、終了する前に実行中のすべての pi ツリーを回収します。切り離された子プロセスには、それらをクリーンアップする他の親プロセスがありません。

環境

設計

• 呼び出しごとにプロセス。 pi 自身のセッションファイルが信頼できる情報源であり、それがこのサーバーの再起動後もフォローアップが存続する理由です。

• pi -p --mode json。 JSON イベントストリームから、ターン、ツール呼び出し、トークン使用量、コストが得られます — 人間が読める出力のスクレイピングはありません。

• 依存関係なし。 改行区切りの JSON-RPC 2.0 を直接話すため、同期を保つ SDK も、監査するファイルも 1 つだけです。

• 長いプロンプトやダッシュで始まるプロンプト は @file 添付として渡されます。pi には -- セパレータがなく、argv には OS のサイズ制限があるためです。

代替案を選ばない理由

pandysp/pi-mcp-server は @mariozechner/pi-coding-agent@^0.52.9 に依存しています — pi の以前のパッケージ名の下にある古いフォーク — そのため、CLI の代わりにバンドルされたはるかに古いエージェントのコピーを実行し、固定されたプロバイダーリストのみを知っています。エコシステム内の他のすべて（pi-mcp-adapter、pi-mcp-extension およびフォーク）は逆方向に実行されます：pi への MCP サーバー。pi 自体にはネイティブの mcp-server サブコマンドはありません。

テスト

npm test

スイートは stdio を介して実際のサーバーを駆動し、ライブモデルがオンデマンドで生成できないパス（不正な stopReason、過大な回答、キャンセル）には偽の pi バイナリを使用するため、API アクセスは不要で、トークンも消費しません。

ライセンス

MIT