pi-mcp-server

MCP-сервер, который делегирует задачи вашему локально установленному pi CLI.

Он оборачивает настоящий бинарник 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 и рабочий pi в 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

Щедрый 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 нет системы разрешений. С инструментами по умолчанию он редактирует файлы и выполняет shell-команды от имени вашего пользователя внутри 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.

Одновременные ответы в одну сессию сериализуются: два процесса pi, пишущих в один файл сессии, могли бы повредить его. Если id неизвестен, pi начинает новую переписку, а ответ содержит явное [warning: no existing session …] вместо того, чтобы делать вид, что продолжает старую.

Межпроцессное ограничение. Мьютекс сессии действует только в пределах одного процесса. Если вы запустите два MCP-клиента против двух процессов сервера и оба ответят в один и тот же id сессии одновременно, они никак не сериализуются. Файл состояния перезаписывается по схеме «прочитать-изменить-записать», так что сессии, узнанные одним процессом, не стираются другим, но у самого файла сессии pi такой защиты нет. На практике одна сессия принадлежит одному клиенту; если нужна жёсткая гарантия — держите один процесс сервера.

Отмена

MCP notifications/cancelled убивает pi сигналом SIGTERM с эскалацией до SIGKILL после льготного периода. Дочерние процессы гибнут вместе с ним: pi запускается в собственной группе процессов, и сигнал уходит всему дереву, так что прерванный sleep 120 не переживёт отмену, даже если pi сам не смог пробросить сигнал.

Отмена регистрируется до постановки в очередь на слот конкурентности или блокировку сессии, поэтому вызов, отменённый пока ещё ждал, вообще не запускает pi.

Завершение работы — закрытие stdin (EOF), SIGTERM, SIGINT, SIGHUP или закрытие stdout — вычищает все запущенные процессы pi перед выходом. Отделённые дочерние процессы остаются без родителя, который мог бы их прибрать.

Окружение

Устройство

• Процесс на каждый вызов. Собственные файлы сессий pi — источник истины; именно поэтому продолжения переживают перезапуск этого сервера.

• pi -p --mode json. Поток json-событий даёт ходы, вызовы инструментов, расход токенов и стоимость — никакого парсинга человекочитаемого вывода.

• Без зависимостей. JSON-RPC 2.0 через newline-delimited поток реализован напрямую, так что нет SDK, за которым нужно следить, и аудировать достаточно один файл.

• Длинные промпты и промпты, начинающиеся с -, передаются как вложение @file, потому что у pi нет разделителя --, а у argv есть лимит размера ОС.

Почему не альтернативы

pandysp/pi-mcp-server зависит от @mariozechner/pi-coding-agent@^0.52.9 — старого форка под прежним именем пакета pi — так что он запускает встроенную копию гораздо более старого агента вместо вашего CLI и знает только фиксированный список провайдеров. Всё остальное в экосистеме (pi-mcp-adapter, pi-mcp-extension и форки) работает в обратную сторону: MCP-серверы внутрь pi. У самого pi нет встроенной подкоманды mcp-server.

Тесты

npm test

Набор тестов гоняет настоящий сервер через stdio и использует фейковый бинарник pi для тех путей, которые живая модель не может выдать по требованию (плохой stopReason, ответы сверх лимита, отмена), так что ему не нужен доступ к API и он не тратит токены.

Лицензия

MIT