内容
-mcp
`worker-mcp` 是一个模型上下文协议（MCP）服务器，它赋予了一个高度智能的协调代理（如3.5 Sonnet 或 Gemini Pro）来生成、控制地指导低智能的本地托管工作代理。
与编写本地 LLM 工具循环不同，`worker-mcp` 通过在 JSON-RPC 模式下运行 **`pi` 编码代理**（`endil-works/pi-coding-agent`）来委托编码、bash 和文件系统操作。由于这些小型本地模型需要大量的监督，`worker-mcp` 充当了一个 gating 和审计的中间层。
## 功能特点
- **交互式 gating（同意钩子）**：自动拦截和阻止高风险操作（例如执行 shell 命令或写入文件），并在执行前提示协调者进行审批。
- **MCP 工具集成**：标准化的工具用于生成工作会话、调度提示、列出活动运行器以及批准/拒绝待处理命令。
- **日志和历史资源**：消息历史和子进程日志（包括 `stderr` 输出）作为标准 MCP 资源公开。
- **会话注册持久性**：会话配置和目录绑定通过 `~/.config/worker-mcp/sessions.json` 中的状态文件在服务器重启后仍然保留。
- **自动扩展部署**：直接将 supervisor gate 扩展部署到 `~/.config/worker-mcp/`，并在生成工作代理时显式加载它（不影响独立的 `pi` 代理运行）。
## 安装与使用
`worker-mcp` 已在 npm 上发布为 [@noosxe/worker-mcp](https://www.npmjs.com/package/@noosxe/worker-mcp)。对于大多数用户来说，这是一个推荐的安装路径。
### 1. 通过 npm 安装（推荐）
#### 选项 A：全局安装
在系统上全局安装软件包：
```bash
npm install -g @noosxe/worker-mcp
# 或使用 pnpm
pnpm add -g @noosxe/worker-mcp
```
全局安装后，可以使用 `worker-mcp` 命令运行服务器。
#### B：通过 npx 临时运行
或者，可以立即在 stdio 上运行服务器，而无需安装：
```bash
npx @noosxe/worker-mcp
```
### 2. 通过 Nix 安装
该项目还提供了一个 Nix flake，以确保环境的一致于安装。
#### 选项 A：（临时）
可以使用 Nix 立即在 stdio 上运行服务器：
```bash
nix run github:noosxe/worker-mcp
```
#### 选项 B：安装到用户配置文件
在用户配置文件中全局安装 `worker-mcp` 可执行文件：
```bash
nix profile install github:noosxe/worker-mcp
```
安装完成后，可以使用以下命令运行：
```bash
worker-m```
### 3. 通过 Flake Overlay 声明式安装（系统 / Home Manager）
如果通过 NixOS 或 Home Manager 以声明式管理操作系统的用户配置文件，可以使用我们的默认 overlay。
#### 步骤 3.1：添加 Flake 输入
将 `worker-mcp` 添加到系统的 `flake.nix` 输入部分：
```nix
inputs = {
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
# 添加 worker-mcp 输入
worker-mcp.url = "github:noosxe/worker-mcp";
};
```
#### 步骤 3.2：配置 Overlay 并安装
##### 选项 A：NixOS 配置
将 overlay 添加到 `nixpkgs` 并在系统软件包中包含 `worker-mcp`：
```nix
outputs = { self, nixpkgs, worker-mcp, ... }@inputs: {
nixosConfigurations.my-system = nixpkgs.lib.nixosSystem {
system = "x86_64-linux"; # 或您的系统架构
modules = [
({ pkgs, ... }: {
# 应用 overlay
nixpkgs.overlays = [
worker-mcp.overlays.default
];
# 安装软件包
environment.systemPackages = [
pkgs.worker-mcp
];
})
./configuration.nix
];
};
};
```
##### 选项 B：Home Manager 配置
将 overlay 添加到 `nixpkgs` 并在用户软件包：
```nix
outputs = { self, nixpkgs, worker-mcp, ... }@inputs: {
homeConfigurations.my-user = inputs.home-manager.lib.homeManagerConfiguration {
pkgs = import nixpkgs {
system = "x86_64-linux";
overlays = [ worker-mcp.default ];
};
modules = [
({ pkgs, ... }: {
# 安装软件包
home.packages = [
pkgs.worker-mcp
];
})
./home.nix
];
};
};
```
## 集成（Antigravity CLI / `agy`）
要将 `worker-mcp` 服务器注册到 Antigravity TUI/CLI（`agy`），请按照以下步骤操作：
### 步骤 1：通过 `mcp_config.json`（声明式）
Antigravity CLI 从专用配置文件（而非旧的 `settings.json` MCP 服务器。在以下位置之一添加配置：
* **全局配置**：`~/.gemini/config_config.json`
* **项目本地配置**agents/mcp_config.json`（在项目工作区的根目录下）
#### 配置文件模式：
##### 选项 A：如果全局安装（通过 npm 或 Nix）
```json
{
"mcpServers": {
"worker-mcp": {
"command": "worker-mcp",
"args": []
}
}
}
```
##### 选项 B：如果通过 npx 临时运行
```json
{
"Servers": {
"worker-mcp": "command": "",
"args": [
"-y",
"@noosxe/worker-mcp"
]
}
}
}
```
##### 选项 C：如果通过 GitHub Flake 临时运行
```json
{
cpServers": {
"worker-mcp": {
"command": "nix",
"args": [
"run",
"github:no/worker-mcp?ref=main"
]
}
}
}
```
##### 选项 D：声明式 Home Manager 配置
如果通过 Home Manager 管理用户配置文件，可以home.nix` `home.file` 和 `builtins.toJSON` 声明全局 `mcp_config.json` 文件：
```nix
home.file.".gemini/config/mcp_config.json".text = builtins.to mcpServers = {
worker-mcp = {
# 如果通过 overlay 在系统/软件包或全局通过 npm 安装：
command = "worker-mcp";
args = [];
# 或者，如果通过 npx 临时运行：
# command = "npx";
# args = [ "-y" "@noosxe/worker-mcp" ];
# 或者，如果通过 Nix 临时运行：
# command = "nix";
# args = [ "run" "github:noosxe/worker-mref=main" ];
};
};
};
```
步骤 2：通过 TUI（`/mcp`验证和管理
在将服务器配置添加到 `mcp_config 后，可以在 CLI 中交互式地管理它：
1. 启动 Antigravity TUI：
```bash
agy
```
2. 在提示输入中输入斜杠命令 `/mcp` 并按 `Enter`。
3. 一个交互式管理覆盖层将打开，显示 `worker-mcp` 在列表中。您可以检查其状态，触发手动重新加载，或验证工具/资源是否被协调代理成功发现。
## 运行配置
### 环境变量
- **`WORKER_MCP_PI_PATH`**：`pi` 编码代理二进制文件的绝对路径（默认为在 `PATH` 中搜索 `pi`）。
### 先决条件
确保在本地系统上安装了全局 `pi` 编码代理 CLI：
```bash
npm install -g @earendil-works/pi-coding-agent
```
在 `pi` 中配置模型（例如，使用 `pi --mode rpc` 设置默认模型，或注册 Ollama 模型定义）。
## MCP 参考
### 暴露的工具
* `spawn_pi_session`：在指定的工作区目录中生成一个新的受监管的工作代理。
* `send_pi_command`：向工作会话发送提示（当回合结算时解析）。
* _pi_sessions`：会话、目录目标和的列表。
*get_pending_actions`：获取待处理的命令的详细信息，。
* `approve：批准执行受控调用。
* _action`：阻止受工具调用并转发反馈正代理的路径。
暴露的资源
*worker-mcp://sessions/{sessionId}/history`：返回对话日志和内部消息* `worker-mcp://sessionId}/logs`：返回子进程的 stdout/stderr 跟踪日志。
## 本地开发
如果为此做出贡献，**必须**进入 Nix：
```bash
nix develop
```
该包装了：
- **Node.js 24**
- **pnpm**
- **TypeScript**
- **BiomeJS**
### 开发任务
- **代码质量（检查、Lint、格式化）**：`biome check --write src/`
- **编译 TypeScript**：`pnpm run build`
运行**：`pnpm run dev`
- **构建 Nix 派生**：`nix build`
