pi-cli-mcp

MCP-Server, der Programmieraufgaben an Ihre lokal installierte pi CLI delegiert.

Es kapselt die echte pi-Binärdatei, anstatt eine eigene Kopie des Agents zu bündeln, sodass jeder Aufruf Ihre ~/.pi/agent/settings.json erbt – Provider, Modelle, Denkstufe, Erweiterungen, AGENTS.md / CLAUDE.md-Erkennung. Nichts an Ihrem Modell-Stack wird hier dupliziert, und der Server driftet nicht, wenn Sie pi aktualisieren.

Verwenden Sie es, wenn Ihr primärer Agent (Claude Code, Cursor, jeder MCP-Client) Arbeiten an pi übergeben soll: eine zweite Meinung von einem anderen Modell, eine Untersuchung, die Sie aus dem Hauptkontextfenster heraushalten möchten, oder parallele Arbeit.

Installation

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

Erfordert Node ≥ 20 und ein funktionierendes pi auf PATH (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

Das großzügige timeout ist wichtig: Eine echte delegierte Aufgabe kann Minuten dauern.

Jeder andere MCP-Client

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

Halten Sie den Servernamen kurz (pi): Er wird Teil der Toolnamen, die Ihr Modell sieht.

Werkzeuge

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 hat kein Berechtigungssystem. Mit seinen Standardwerkzeugen bearbeitet es Dateien und führt Shell-Befehle als Ihr Benutzer innerhalb von cwd aus. Übergeben Sie tools oder no_tools, wenn die Aufgabe eine Analyse ist. Verwenden Sie PI_MCP_WRAP, wenn Sie eine Sandbox möchten.

Was zurückkommt

Nur pi's endgültige Antwort plus aggregierte Statistiken – niemals das Transkript, Tool-Argumente oder Tool-Ausgabe:

[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

• „Endgültige Antwort" wird durch stopReason definiert, nicht durch die Position: die letzte Assistenten-Nachricht, die sich gesetzt hat – die letzte, deren stopReason nicht toolUse ist, so markiert pi Tool-Aufruf-Schritte. Erzählungen während des Laufs werden verworfen, selbst wenn eine Präambel eine Nachricht mit einem Tool-Aufruf teilt. Wenn die gesetzte Nachricht keinen Text hat, wird dies als fehlerhafter Lauf gemeldet, anstatt stillschweigend auf eine frühere Präambel zurückzugreifen. Wenn nichts gesetzt wurde, wird der letzte erzeugte Text zurückgegeben, entsprechend gekennzeichnet.

• Die Antwort wird nie abgeschnitten. Setzen Sie PI_MCP_MAX_OUTPUT, wenn Sie eine Obergrenze möchten. Nur Diagnosen sind begrenzt.

• pi wrote: erscheint nur, wenn pi tatsächlich Dateien geschrieben hat, dient also als Nebenwirkungsprüfung.

• Ein schlechter stopReason lässt den Aufruf fehlschlagen, fail-closed. stop / length sind Erfolg; error, aborted, ein fehlender stopReason und alles außerhalb des bekannten Vokabulars werden als Fehler gemeldet, wobei die Antwort weiterhin angehängt ist. Der validierte stopReason gehört zu der zurückgegebenen Nachricht, nicht zu dem Ereignis, das zuletzt eingetroffen ist. pi kann mit Exit-Code 0 beenden, wenn ein Turn nicht sauber abgeschlossen wurde, daher wird dem Exit-Code allein nicht vertraut.

• Rohes stdout wird nie als Antwort zurückgegeben. Wenn der Ereignisstrom nicht dem erwarteten Vertrag entspricht, sagt die Antwort dies und beschreibt die Form des Angekommenen (Nachrichtenzahl, stopReason-Werte, Tool-Aufruf-Zahl, Byte-Zahl) – niemals das Transkript selbst, das Erzählung, Tool-Argumente und Tool-Ergebnisse preisgeben würde.

Sitzungen

pi gibt eine Sitzungs-ID zurück; pi_reply setzt sie fort. Die Konversation lebt in pi's eigenen Sitzungsdateien, sodass Folgeanfragen über Neustarts dieses Servers hinweg funktionieren – die Zuordnung Sitzung → Verzeichnis wird in ~/.local/state/pi-mcp/sessions.json gespeichert.

Gleichzeitige Antworten auf eine Sitzung werden serialisiert: Zwei pi-Prozesse, die eine Sitzungsdatei schreiben, würden sie beschädigen. Wenn eine ID unbekannt ist, startet pi eine neue Konversation und die Antwort trägt eine explizite [warning: no existing session …]-Warnung, anstatt so zu tun, als würde sie fortgesetzt.

Prozessübergreifender Hinweis. Der Sitzungs-Mutex ist prozesslokal. Wenn Sie zwei MCP-Clients gegen zwei Serverprozesse ausführen und beide gleichzeitig auf dieselbe Sitzungs-ID antworten, serialisiert nichts sie. Die Zustandsdatei wird mit erneutem Lesen und anschließendem Zusammenführen geschrieben, sodass Sitzungen, die ein Prozess gelernt hat, nicht vom anderen gelöscht werden, aber die zugrunde liegende pi-Sitzungsdatei hat keinen solchen Schutz. In der Praxis besitzt ein Client eine Sitzung; wenn Sie eine harte Garantie benötigen, halten Sie einen Serverprozess.

Abbruch

MCP notifications/cancelled beendet pi mit SIGTERM, eskaliert nach einer Gnadenfrist zu SIGKILL. Kinder gehen mit: pi läuft in einer eigenen Prozessgruppe und der gesamte Baum wird signalisiert, sodass ein unterbrochenes sleep 120 nicht überlebt, selbst wenn pi das Signal nicht weiterleitet.

Der Abbruch registriert sich, bevor der Aufruf für einen Parallelitätsslot oder eine Sitzungssperre in die Warteschlange geht, sodass ein Aufruf, der abgebrochen wird, während er noch wartet, pi überhaupt nie startet.

Herunterfahren – stdin EOF, SIGTERM, SIGINT, SIGHUP oder ein geschlossenes stdout – erntet jeden laufenden pi-Baum, bevor es beendet wird. Abgekoppelte Kinder haben keinen anderen Elternteil, der sie aufräumt.

Umgebung

Design

• Prozess pro Aufruf. pi's eigene Sitzungsdateien sind die Quelle der Wahrheit, was Folgeanfragen über einen Neustart dieses Servers hinweg überleben lässt.

• pi -p --mode json. Der JSON-Ereignisstrom liefert Turns, Tool-Aufrufe, Token-Nutzung und Kosten – kein Scraping von menschenlesbarer Ausgabe.

• Keine Abhängigkeiten. Newline-getrenntes JSON-RPC 2.0 wird direkt gesprochen, sodass es kein SDK gibt, das synchron gehalten werden muss, und nichts zu prüfen ist außer einer Datei.

• Lange oder mit Bindestrich beginnende Prompts werden als @file-Anhang übergeben, da pi kein ---Trennzeichen hat und argv eine OS-Größenbeschränkung hat.

Warum nicht die Alternativen

pandysp/pi-mcp-server hängt von @mariozechner/pi-coding-agent@^0.52.9 ab – dem alten Fork unter pi's früherem Paketnamen –, sodass es eine gebündelte Kopie eines viel älteren Agents anstelle Ihrer CLI ausführt und nur eine feste Providerliste kennt. Alles andere im Ökosystem (pi-mcp-adapter, pi-mcp-extension und Forks) läuft in die entgegengesetzte Richtung: MCP-Server in pi. pi selbst hat keinen nativen mcp-server-Unterbefehl.

Tests

npm test

Die Suite treibt den echten Server über stdio und verwendet eine gefälschte pi-Binärdatei für die Pfade, die ein Live-Modell nicht auf Abruf erzeugen kann (schlechter stopReason, überdimensionierte Antworten, Abbruch), sodass sie keinen API-Zugriff benötigt und keine Tokens verbraucht.

Lizenz

MIT