pi-delegate-mcp

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

MCP-сервер, который предоставляет кодинг-агента pi как делегируемого, управляемого работника.

Направьте на него Claude Code (или любой MCP-хост) и делегируйте работу любому из ~38 провайдеров pi (DeepSeek, Grok, GLM, Kimi, Qwen, Codex, OpenRouter, локальный llama.cpp) — контекст субагента останется за пределами вашего основного диалога.

Для чего это нужно

Ваша основная среда работает на дорогой модели с контекстным окном, которое вам дорого. Многое из того, что она делает, не требует этой модели и активно вредит контексту: поиск по репозиторию всех мест вызова, чтение файла на 2000 строк ради ответа на один вопрос, аудит того, что осталось после рефакторинга.

Передайте эту работу делегату:

• Стоимость. Черновая работа выполняется на DeepSeek, GLM, Kimi, Qwen или локальном llama.cpp. Вы платите по ценам передовых моделей только за те рассуждения, которые действительно в них нуждаются.

• Контекст. Делегат читает файлы за свой счёт и возвращает результат. Прочитанные им 200 КБ никогда не попадают в ваш диалог.

• Радиус поражения. Делегаты по умолчанию доступны только на чтение (read, grep, find, ls), что обеспечивается при создании сессии. Дешёвая модель, выполняющая исследовательскую работу, не может коснуться вашего дерева, если вы явно не разрешите ей это.

Делегат — это всегда агент pi. Codex, Grok, DeepSeek и остальные поставляют модель под ним; это не обёртка над их CLI.

Related MCP server: handoff-mcp

Почему pi, а не opencode или CLI-обёртка?

Делегатом можно управлять, только если открыты два канала: вы должны иметь возможность перенаправить его в середине задачи, а он — задать вам вопрос и блокироваться, пока вы не ответите. Большинство способов управления кодинг-агентом из другой программы закрывают оба канала.

pi -p и --mode json устанавливают ctx.hasUI = false. Делегат, запущенный таким образом, является fire-and-forget по построению: он не может задать вопрос, и вы не можете его перенаправить.

opencode SDK — это типизированный клиент для отдельного серверного процесса: createOpencode() запускает opencode serve и общается с ним по HTTP. Чистый дизайн, но это означает второй процесс, за которым нужно следить, а поверхность сессии, которую он предоставляет (prompt, abort, revert, messages), не имеет управления посреди хода и не даёт агенту возможности спросить вызывающую сторону.

pi поставляет createAgentSession как встраиваемую библиотеку. Этот сервер держит объект сессии в своём процессе, так что session.steer() может доставить сообщение после текущего вызова инструмента и до следующего вызова модели, а синтетический uiContext перехватывает вопросы агента и паркует их до answer. Никаких внешних процессов не запускается; ни за чем не нужно следить.

* Вопросы исходят от расширений pi, поэтому этот канал открыт только для делегатов, запущенных с extensions: true. См. Веб-поиск и другие инструменты расширений.

(В таблице сравнивается канал делегирования, а не песочница; у 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), а длина отброшенного записывается, чтобы одно read большого файла не затопило ваш контекст.

Как дать делегату ещё один ход

Завершивший работу делегат не отработан. 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 }

Делегат продолжает с того места, где остановился. Он по-прежнему держит файлы, прочитанные на первом ходе, поэтому второй вопрос стоит один вызов модели, а не новую сессию, заново читающую репозиторий.

Это дешёвый способ поговорить с делегатом. Запуск нового означает повторное объяснение задачи и оплату повторного чтения тех же файлов, а ответ приходит без всех рассуждений, которые к нему привели.

follow_up отказывает делегату, который всё ещё работает, потому что перенаправление посреди задачи — это задача steer. Эти два инструмента не взаимозаменяемы: steer доставляет сообщение между вызовами инструментов работающего агента, follow_up начинает новый ход на завершённом.

Веерный запуск

spawn_batch запускает целый пакет одним вызовом. Задачи наследуют пакетные 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, запрещённые инструменты и каждое имя модели. Одна плохая задача приводит к ошибке вызова, и ничего не запускается. Наполовину выполненный веерный запуск — худший исход, потому что вы платите за делегатов, которые запустились, и всё равно должны выяснить, какие не запустились.

Опрашивайте весь пакет одним вызовом sessions, а не по одному status на делегата. Переходите на status только для того делегата, которого действительно хотите прочитать. steer и abort остаются посессионными.

Выбор модели для каждого вызова

model в любом вызове переопределяет PI_DELEGATE_MODEL. Нераспознаваемое имя — это жёсткая ошибка, а не тихий откат к модели по умолчанию, потому что тихий откат — это как вы в итоге платите за модель, которую не заказывали.

Какие имена распознаются, решает собственная область enabledModels pi, которую этот сервер обеспечивает, а не просто отображает:

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: три записи в области плюс два пользовательских провайдера легко могут означать пятнадцать предлагаемых моделей. init явно сообщает об этом в models.scopeNote, когда это применимо.

Два переключателя меняют это:

Выполните models, чтобы увидеть, что реально доступно при текущей настройке.

Строка состояния

Claude Code разрешает ровно одну команду statusLine, поэтому 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

Какие делегаты относятся к какой сессии

Фильтрации по каталогу недостаточно: две сессии Claude Code, открытые в одном репозитории, показывали бы делегатов друг друга. Вместо этого атрибуция использует родословную процессов.

MCP-хост порождает один сервер на сессию, поэтому сервер записывает process.ppid — pid хоста. Строка состояния, порождённая тем же хостом, проходит по собственной родословной и оставляет только те файлы состояния, чей hostPid она в ней находит. Один репозиторий, две сессии — никаких пересечений. Каталог остаётся фильтром-запасным вариантом для файлов состояния, записанных до появления этой возможности.

Состояние хранится в $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 в его списке. Отказ от этих двух при разрешении bash фиксирует ваше намерение; он ничего не обеспечивает. Запросы разрешений и хуки Claude Code никогда не видят того, что делает pi. Если вам нужна настоящая граница, запускайте этот сервер в контейнере.

Веб-поиск и другие инструменты расширений

Собственные инструменты 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 связывает MCP-серверы из ~/.pi/agent/mcp.json и предоставляет их как mcp. У pi нет собственного MCP-клиента, поэтому это расширение — единственный путь к нему.

extensions: true доверяет всем установленным расширениям, а не только тому, которое вы хотели. Они загружаются как набор, работают с полными привилегиями процесса этого сервера, а некоторые открывают сокеты и таймеры, которые переживают сессию. Включайте его по вызову, для тех делегатов, которым это нужно, а не оставляйте включённым по умолчанию. Это также стоит реального времени запуска, поэтому оно выключено, пока не запрошено.

Конфигурация

Долго выполняющаяся работа

MCP TypeScript SDK по умолчанию использует 60-секундный тайм-аут запроса, который реальная задача превысит. Три защиты в порядке предпочтения:

1. Используйте spawn + status. Ничто не блокируется, поэтому тайм-аут не применяется.

2. run отправляет периодические уведомления о прогрессе, которые сбрасывают тайм-аут хоста.

3. Поднимите потолок с помощью "timeout" в .mcp.json или MCP_TOOL_TIMEOUT в окружении.

CLAUDE_AUTO_BACKGROUND_TASKS=1 заставляет Claude Code переводить длинные MCP-вызовы в фоновый режим примерно через ~2 минуты. Учтите, что уведомления о прогрессе отбрасываются после перевода вызова в фоновый режим, поэтому выбирайте (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 trusted publishing, поэтому нигде в репозитории не хранится npm-токен.

Сообщения о проблемах (issues) и pull request'ы приветствуются. Если вы сообщаете о делегате, который вёл себя некорректно, полезно приложить трассировку toolCalls из status с verbose: true.

Аналоги

abatilo/pi-mcp-bridge идёт более простым путём: запускает pi --mode json -p --session-id <uuid> и позволяет pi сохранять сессии на диске, так что мост вообще не хранит состояние. Элегантно и стоит прочтения. Чтобы достичь этого, он жертвует управлением, вопросами и контролем над инструментами.

Лицензия

MIT