内容
# 工作树管理协议（worktree-mcp）
一个MCP（模型上下文协议）服务器，用于管理多代理开发工作流的git工作树全生命周期。
## 为什么？
当多个AI代理在同一个代码库上工作时，它们需要隔离。Git工作树提供了这一点——每个代理都有自己的工作目录和自己的分支。但是，单独的工作树是不够的：
- 每个工作树都需要一个独特的端口上的开发服务器
- 环境变量需要按工作树配置
- 服务器需要干净地启动/停止
- 状态需要在会话之间持久化
**worktree-mcp** 自动处理所有这些。
## 功能
- **隔离工作树** — 每个功能分支都有自己的目录
- **自动端口分配** — 工作树之间没有端口冲突
- **开发服务器管理** — 启动/停止并进行健康检查
- **环境生成** — 自动创建 `.env.local`
- **生命周期钩子** — 运行设置/拆除命令
- **状态持久性** — 在MCP重启后存活
- **工作流提示** — 指导代理如何使用工作树
## 安装
```bash
npm install -g worktree-mcp
```
或直接运行：
```bash
npx worktree-mcp
```
## 快速入门
### 1. 添加到您的MCP客户端
**Claude Desktop**（`~/Library/Application Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"worktree": {
"command": "npx",
"args": ["worktree-mcp"]
}
}
}
```
**OpenCode**（`~/.config/opencode/config.json`）：
```json
{
"mcp": {
"worktree": {
"command": "npx",
"args": ["worktree-mcp"]
}
}
}
```
### 2. 在您的存储库中创建配置文件
在您的存储库根目录中创建 `.worktree-agent.yaml`：
```yaml
dev:
command: "npm run dev"
port_env: "PORT"
base_port: 3000
```
### 3. 使用工具
```
Agent: "我需要处理功能-x"
→ worktree_create(branch: "功能-x")
→ worktree_start()
# 在 .worktrees/功能-x 中进行工作，服务器在端口 3000 上
Agent: "完成功能-x"
→ worktree_remove(worktree: "功能-x", mode: "promote")
# 推送到远程并清理
```
## 配置
在您的存储库根目录中创建 `.worktree-agent.yaml`：
```yaml
# 创建工作树的位置（默认：.worktrees）
worktree_dir: ".worktrees"
# 主要开发服务器（必填）
dev:
command: "npm run dev"
port_env: "PORT" # 传递给进程的环境变量
base_port: 3000 # 分配的起始端口
health_check: "http://localhost:${DEV_PORT}/api/health" # 可选
ready_timeout: 30 # 等待健康检查的秒数
# 其他服务（可选）
services:
backend:
command: "python manage.py runserver"
port_env: "PORT"
base_port: 8000
health_check: "http://localhost:${BACKEND_PORT}/health"
db:
command: "docker compose up db"
port_env: "DB_PORT"
base_port: 5432
# .env.local 的环境变量
# 可用的模板变量：${DEV_PORT}、${BACKEND_PORT}、${DB_PORT}、${WORKTREE_NAME}
env:
DATABASE_URL: "postgresql://localhost:${DB_PORT}/app_${WORKTREE_NAME}"
API_URL: "http://localhost:${BACKEND_PORT}"
# 生命周期钩子
hooks:
post_create: "npm install"
pre_remove: "docker compose down"
# AI 代理的指南（出现在 worktree-workflow 提示中）
agent_guidance: |
始终为功能工作创建工作树。
在删除前运行测试：npm test
```
## MCP 工具
| 工具 | 描述 |
|------|-------------|
| `worktree_create` | 创建工作树、分配端口、生成 `.env.local`、运行设置钩子 |
| `worktree_start` | 在后台启动开发服务器、等待健康检查 |
| `worktree_status` | 列出所有工作树、端口和服务器状态 |
| `worktree_stop` | 停止服务器（保持工作树完整） |
| `worktree_remove` | 完全清理，带有模式选项 |
### worktree_create
```typescript
worktree_create(branch: string, base?: string)
```
- 创建 `.worktrees/<branch>` 目录
- 为每个服务分配唯一端口（从 `base_port` 开始递增）
- 生成带有端口绑定的 `.env.local`
- 如果需要，将 `.worktrees/` 添加到 `.gitignore`
- 运行 `post_create` 钩子
### worktree_start
```typescript
worktree_start(worktree?: string, service?: string)
```
- 在后台（分离）生成进程
- 通过 `port_env` 环境变量注入端口
- 等待健康检查（如果配置）或固定超时
- 跟踪 PID 以备后续清理
### worktree_stop
```typescript
worktree_stop(worktree?: string, service?: string)
```
- 发送 SIGTERM，然后在需要时发送 SIGKILL（5 秒后）
- 清理 PID 文件
### worktree_remove
```typescript
worktree_remove(
worktree: string,
mode?: "keep_branch" | "delete_branch" | "promote",
force?: boolean
)
```
模式：
- `keep_branch`（默认）：删除工作树，保持分支以备后用
- `delete_branch`：删除工作树和本地分支
- `promote`：先推送分支到远程，然后删除工作树
### worktree_status
列出所有托管的工作树，包括：
- 分支名称和路径
- 已分配端口
- 服务状态（运行/停止/过时）
- 健康检查结果
## MCP 提示
### worktree-workflow
为 AI 代理提供工作流指南。将此内容注入您的系统中，以帮助代理了解何时以及如何使用工作树。
包括：
- 何时创建工作树与直接工作
- 逐步工作流
- 快速参考表
- 来自配置中的 `agent_guidance` 的项目特定指南
## 工作原理
### 端口分配
每个服务跟踪每个存储库的自己的端口计数器：
```
工作树 1：dev=3000，backend=8000，db=5432
工作树 2：dev=3001，backend=8001，db=5433
工作树 3：dev=3002，backend=8002，db=5434
```
在分配端口之前会验证端口是否空闲。
### 状态持久性
状态存储在 `~/.worktree-mcp/state.json` 中：
```json
{
"version": 1,
"worktrees": {
"/path/to/repo:feature-x": {
"repoPath": "/path/to/repo",
"worktreePath": "/path/to/repo/.worktrees/feature-x",
"branch": "feature-x",
"ports": { "dev": 3001, "backend": 8001 },
"pids": { "dev": 12345, "backend": 12346 }
}
},
"nextPort": {
"/path/to/repo:dev": 3002,
"/path/to/repo:backend": 8002
}
}
```
文件锁定防止与并发MCP实例的竞争条件。
### 环境生成
`.env.local` 使用规范的端口名称生成：
```bash
# 由 worktree-mcp 生成
# 工作树：feature-x
# 服务端口
DEV_PORT=3001
BACKEND_PORT=8001
DB_PORT=5433
# 自定义环境
DATABASE_URL=postgresql://localhost:5433/app_feature-x
API_URL=http://localhost:8001
```
配置中的 `port_env` 控制在生成进程时传递给进程的环境变量。`.env.local` 始终使用规范的 `SERVICE_PORT` 名称以保持一致性。
### 进程管理
- 进程在后台生成（`stdio: ignore`，`unref()`）
- 状态和PID文件中跟踪PID
- 健康检查轮询直到就绪或超时
- 在 `worktree_status` 上检测过时进程
## 多代理示例
```
┌─────────────────────────────────────────────────────────┐
│ 代理 1（协调器） │
│ │
│ "在隔离中启动功能-x" │
│ → worktree_create(branch: "功能-x") │
│ → worktree_start() │
│ │
│ "生成代理 2 以处理功能-x" │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ 代理 2（工作器） │
│ cwd: /repo/.worktrees/功能-x │
│ 服务器：http://localhost:3001 │
│ │
│ 进行更改、提交、测试... │
│ │
│ "完成功能-x" │
│ → worktree_remove(worktree: "功能-x", mode: "promote")│
└─────────────────────────────────────────────────────────┘
```
## 开发
```bash
git clone https://github.com/anthropics/worktree-mcp
cd worktree-mcp
# 安装依赖
npm install
# 构建
npm run build
# 监视模式
npm run dev
```
## 许可证
MIT
