pi-cli-mcp

Servidor MCP que delega tareas de codificación en tu CLI pi instalada localmente.

Envuelve el binario real pi en lugar de incluir su propia copia del agente, por lo que cada llamada hereda tu ~/.pi/agent/settings.json — proveedor, modelos, nivel de pensamiento, extensiones, descubrimiento de AGENTS.md / CLAUDE.md. Nada de tu pila de modelos se duplica aquí, y el servidor no se desvía cuando actualizas pi.

Úsalo cuando tu agente principal (Claude Code, Cursor, cualquier cliente MCP) deba delegar trabajo a pi: una segunda opinión de un modelo diferente, una investigación que quieras mantener fuera de la ventana de contexto principal, o trabajo en paralelo.

Install

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

Requiere Node ≥ 20 y un pi funcional en 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

El generoso timeout importa: una tarea delegada real puede ejecutarse durante minutos.

Any other MCP client

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

Mantén el nombre del servidor corto (pi): se convierte en parte de los nombres de las herramientas que ve tu modelo.

Tools

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 no tiene sistema de permisos. Con sus herramientas predeterminadas edita archivos y ejecuta comandos de shell como tu usuario dentro de cwd. Pasa tools o no_tools siempre que la tarea sea de análisis. Usa PI_MCP_WRAP si quieres un sandbox.

What comes back

Solo la respuesta final de pi más estadísticas agregadas — nunca la transcripción, los argumentos de herramientas ni la salida de herramientas:

[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

• "Respuesta final" se define por stopReason, no por posición: el último mensaje de asistente que se asentó — el último cuyo stopReason no es toolUse, que es como pi marca los pasos de llamada a herramientas. La narración a mitad de ejecución se descarta incluso cuando un preámbulo comparte mensaje con una llamada a herramienta. Si el mensaje asentado no tiene texto, se informa como una ejecución rota en lugar de retroceder silenciosamente a un preámbulo anterior. Si nada se asentó, se devuelve el último texto producido, etiquetado como tal.

• La respuesta nunca se trunca. Establece PI_MCP_MAX_OUTPUT si quieres un límite. Solo los diagnósticos están limitados.

• pi wrote: aparece solo cuando pi realmente escribió archivos, por lo que también sirve como comprobación de efectos secundarios.

• Un stopReason incorrecto hace fallar la llamada, con cierre seguro. stop / length son éxito; error, aborted, un stopReason faltante y cualquier cosa fuera del vocabulario conocido se informan como errores con la respuesta aún adjunta. El stopReason que se valida pertenece al mensaje que se devuelve, no al evento que llegó último. pi puede salir con 0 en un turno que no se asentó limpiamente, por lo que el código de salida por sí solo no es de fiar.

• La salida estándar cruda nunca se devuelve como respuesta. Si el flujo de eventos no coincide con el contrato esperado, la respuesta lo dice y describe la forma de lo que llegó (número de mensajes, valores de stopReason, número de llamadas a herramientas, número de bytes) — nunca la transcripción en sí, que filtraría narración, argumentos de herramientas y resultados de herramientas.

Sessions

pi devuelve un id de sesión; pi_reply la continúa. La conversación vive en los propios archivos de sesión de pi, por lo que los seguimientos siguen funcionando entre reinicios de este servidor — el mapa sesión → directorio se persiste en ~/.local/state/pi-mcp/sessions.json.

Las respuestas concurrentes a una sesión se serializan: dos procesos pi escribiendo un mismo archivo de sesión lo corromperían. Si un id es desconocido, pi inicia una conversación nueva y la respuesta lleva un [warning: no existing session …] explícito en lugar de fingir que continúa.

Advertencia entre procesos. El mutex de sesión es local al proceso. Si ejecutas dos clientes MCP contra dos procesos de servidor y ambos responden al mismo id de sesión al mismo tiempo, nada los serializa. El archivo de estado se escribe con relectura y fusión, por lo que las sesiones aprendidas por un proceso no son borradas por el otro, pero el archivo de sesión subyacente de pi no tiene tal protección. En la práctica, un cliente es dueño de una sesión; si necesitas una garantía firme, mantén un solo proceso de servidor.

Cancellation

MCP notifications/cancelled mata a pi con SIGTERM, escalando a SIGKILL después de un período de gracia. Los hijos van con él: pi se ejecuta en su propio grupo de procesos y se señala a todo el árbol, por lo que un sleep 120 interrumpido no sobrevive incluso si pi no reenvía la señal.

La cancelación se registra antes de que la llamada se ponga en cola para un espacio de concurrencia o un bloqueo de sesión, por lo que una llamada que se cancela mientras aún espera nunca inicia pi.

El apagado — EOF de stdin, SIGTERM, SIGINT, SIGHUP o stdout cerrado — recolecta todos los árboles de pi en ejecución antes de salir. Los hijos separados no tienen otro padre que los limpie.

Environment

Design

• Proceso por llamada. Los propios archivos de sesión de pi son la fuente de verdad, lo que hace que los seguimientos sobrevivan a un reinicio de este servidor.

• pi -p --mode json. El flujo de eventos json es lo que produce turnos, llamadas a herramientas, uso de tokens y costo — sin extraer de la salida legible por humanos.

• Sin dependencias. Se habla JSON-RPC 2.0 delimitado por nuevas líneas directamente, por lo que no hay SDK que mantener sincronizado y nada que auditar excepto un archivo.

• Los prompts largos o que comienzan con guion se pasan como adjunto @file, ya que pi no tiene separador -- y argv tiene un límite de tamaño del sistema operativo.

Why not the alternatives

pandysp/pi-mcp-server depende de @mariozechner/pi-coding-agent@^0.52.9 — el antiguo fork bajo el nombre de paquete anterior de pi — por lo que ejecuta una copia incluida de un agente mucho más antiguo en lugar de tu CLI, y solo conoce una lista fija de proveedores. Todo lo demás en el ecosistema (pi-mcp-adapter, pi-mcp-extension y forks) va en la dirección opuesta: servidores MCP hacia pi. pi en sí no tiene un subcomando nativo mcp-server.

Tests

npm test

La suite maneja el servidor real a través de stdio y usa un binario pi falso para los caminos que un modelo en vivo no puede producir bajo demanda (stopReason incorrecto, respuestas demasiado grandes, cancelación), por lo que no necesita acceso a API y no gasta tokens.

License

MIT