Pi Worker MCP

io.github.zguiyangv0.1.1更新于 Oct 8, 2026

A host-agnostic MCP worker runtime for supervising local Pi coding-agent processes.

已验证STDIO仅桌面AI & MLDeveloper Tools

概览

AI 生成的概览

通过 stdio MCP 工具（如 spawn、status、steer、continue、abort、list）运行并监督本地 Pi 编码代理工作进程。

功能
一个与宿主无关的 MCP 工作进程运行时，通过本地 stdio MCP 和 Pi RPC 监督有界的本地 Pi 编码代理进程。其工具包括 pi_spawn、pi_status、pi_steer、pi_continue、pi_abort 和 pi_list。它还提供 setup、doctor、update 和 uninstall 命令，为 Codex、Zed 和 OpenCode 宿主固定启动配置。它不管理 Pi 的凭据、提供商或默认模型。
适用场景
当助手需要启动、监控、引导和停止本地 Pi 编码代理工作进程时使用，包括在 Git 工作树中进行隔离的实现工作。适合已在本地运行 Pi、并希望由监督代理协调有界工作任务的用户。
运行要求
需要 Node.js 20+、本地已安装并配置好的 pi 可执行文件，以及在使用隔离工作树时需要 Git。作为本地 stdio 进程运行，通常通过 npx 启动。可选环境变量包括 PI_WORKER_COMMAND、PI_WORKER_MAX_WORKERS、PI_WORKER_RPC_TIMEOUT_MS、PI_WORKER_IDLE_TIMEOUT_MS、PI_WORKER_TASK_TIMEOUT_MS 和 PI_WORKER_ALLOWED_ROOTS。Pi 读取自己的本地认证配置。
安装前请注意
spawn 或 continue 成功仅表示 Pi 接受了工作，并不表示结果正确，监督代理必须检查结果并整合更改。setup 命令会修改 Codex、Zed 或 OpenCode 的宿主配置文件，但只做最小合并，uninstall 也只移除本服务器的条目。工作进程会运行本地编码代理进程，可能更改文件，因此隔离工作应使用 worktree 模式并审查更改。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Pi Worker MCP，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

@zguiyang/pi-worker-mcp

A host-agnostic MCP worker runtime for supervising local Pi coding-agent processes. It uses local stdio MCP and Pi RPC; it is not a hosted service and does not manage Pi credentials, providers, or default models.

Quick start

Prerequisites: Node.js 20+, a locally installed and configured pi executable, and Git when using isolated worktrees.

sh
npx -y @zguiyang/pi-worker-mcp@latest setup

The setup command selects supported hosts and pins their launch configuration to the exact CLI version. A host never silently drifts to a new release.

Supported hosts and scope

HostGlobalProjectConfiguration
Codex~/.codex/config.toml.codex/config.tomlTOML mcp_servers
Zed~/.zed/settings.json on macOS.zed/settings.jsonJSON context_servers
OpenCode~/.config/opencode/opencode.jsonopencode.jsonJSON mcp.servers

Project scope is relative to the directory where setup runs. Zed starts project-defined MCP servers only after the worktree is trusted. Existing configuration is minimally merged; uninstall removes only this server’s entry.

sh
npx -y @zguiyang/[email protected] setup --host codex --scope projectnpx -y @zguiyang/[email protected] setup --host opencode --scope global

Manual / generic MCP configuration

Any stdio MCP client can launch:

text
command: npxargs:    -y @zguiyang/[email protected] serve

This is the release configuration. Do not point user installations at a checkout’s dist/ directory.

Commands

text
pi-worker-mcp servepi-worker-mcp setup [--host codex|zed|opencode] [--scope project|global]pi-worker-mcp doctor [--host …] [--scope …]pi-worker-mcp update [--host …] [--scope …]pi-worker-mcp uninstall [--host …] [--scope …]pi-worker-mcp version

doctor checks Node, the local Pi executable, and selected host configuration without starting a model task or exposing credentials. update is not a package manager: run a newer CLI via npm/npx and it updates only selected configuration pins. uninstall never removes a whole host config, Pi config, Skills, or npm cache.

Model ownership and host independence

Pi owns provider authentication, available models, and its default model. The worker runtime can validate an optional per-worker override and report the effective model, but never configures credentials. Core runtime behavior—Pi RPC, lifecycle, model semantics, concurrency, and permissions—is independent of Codex, Zed, and OpenCode. Host adapters only read, merge, and remove launch configuration.

MCP tools

pi_spawn, pi_status, pi_steer, pi_continue, pi_abort, and pi_list supervise bounded local workers. Successful spawn/continuation means Pi accepted work, not that it is correct; the supervising agent must inspect results and integrate changes. Use worktree mode for isolated implementation work.

Runtime configuration

Environment variableDefaultPurpose
PI_WORKER_COMMANDpiPi executable
PI_WORKER_MAX_WORKERS4Maximum live workers
PI_WORKER_RPC_TIMEOUT_MS15000Per-RPC timeout
PI_WORKER_IDLE_TIMEOUT_MS600000Idle deadline; 0 disables it
PI_WORKER_TASK_TIMEOUT_MS3600000Activity-cycle deadline
PI_WORKER_ALLOWED_ROOTScurrent directoryPath-delimited allowed roots

No secret environment variable is required; Pi reads its own local authentication configuration.

Development from source

Source mode is only for contributors:

sh
npm installnpm run buildnode dist/index.js serve

For release-equivalent testing, use npm pack and execute the resulting .tgz from a clean temporary directory. npm link is not package acceptance.

Registry metadata

server.json follows the official MCP Registry schema and declares an npm stdio package representation. npm and Registry publication remain separate, explicit actions.

License

MIT

来源：README.md，提交 64590c3

工具

0
工具元数据尚未被收录。

版本历史

1
  1. v0.1.1最新Oct 8, 2026