# worker-mcp

一个 stdio MCP server，让 Claude Code（或任何 MCP 客户端）把编码任务委派给一个
worker CLI 执行。调用方（Claude）只做计划、监督和验收，worker 负责所有实际的
代码修改和命令执行。

## 原理

server 通过子进程调用 `<worker-cli> -p <prompt> --output-format stream-json`（无头模式），
解析其 stream-json 输出，把 worker 的最终回复和 `session_id` 返回给调用方。

默认 worker 是 Kimi Code CLI（`kimi`），可通过环境变量 `WORKER_CLI_BIN` 换成任何
兼容同一 CLI 契约的执行器：支持 `-p` 无头执行、`-S <id>` / `-c` 会话续接，
并以 stream-json 逐行输出 `role=assistant`（回复）和 `role=meta`（`session_id`）事件。

**注意**：worker 无头模式会**自动批准所有工具调用**（等同于 yolo），
可以在指定 `cwd` 内自由读写文件、执行命令。请只把可信的项目目录传给 `cwd`。

## 工作模式：Claude 监督计划，worker 执行

server 在 MCP `instructions` 和工具描述中写明了分工，Claude Code 连接后会自动遵循：

- **Claude（监督/计划）**：拆解目标、决定步骤顺序、为每步编写**自包含任务书**
  （背景、涉及文件、改什么、验收标准——worker 看不到 Claude 的上下文）、
  验收每步结果（读文件/diff、让 worker 跑测试）、失败时用 `worker_continue` 打回重修。
- **worker（执行）**：在指定 `cwd` 内完成所有实际的代码修改和命令执行。

Claude 被引导不自己调用 Edit/Write 等工具改代码（软引导，非强制拦截）。

## 工具

| 工具 | 说明 |
| --- | --- |
| `worker_run(prompt, cwd, timeout=600)` | 在 `cwd` 开启新 worker 会话执行任务，返回结果和 `session_id` |
| `worker_continue(prompt, cwd, session_id?, timeout=600)` | 对既有会话追加指令；不传 `session_id` 时续接 `cwd` 最近一次会话 |

## 安装

项目内已用 uv 管理独立 Python 3.12（不依赖系统 Python）：

```bash
# 如需从零重建环境：
curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR="$PWD/.tools" INSTALLER_NO_MODIFY_PATH=1 sh
UV_PYTHON_INSTALL_DIR="$PWD/.tools/python" .tools/uv venv --python 3.12 .venv
.tools/uv pip install --python .venv/bin/python "mcp>=1.0"
```

## 注册到 Claude Code

```bash
claude mcp add worker -- /Users/quinlanhoo/Code/KIMI-MCP/KIMI-MCP/.venv/bin/python /Users/quinlanhoo/Code/KIMI-MCP/KIMI-MCP/server.py
```

之后在 Claude Code 中即可通过 `worker_run` / `worker_continue` 工具把任务交给 worker。

## 配置

| 环境变量 | 默认 | 说明 |
| --- | --- | --- |
| `WORKER_CLI_BIN` | `kimi` | worker CLI 路径（须兼容上述 CLI 契约） |
| `WORKER_TIMEOUT` | `600` | 默认超时秒数（工具参数可单独覆盖） |