Worktree MCP Manager

工作树MCP经理

AI优先的git工作树管理器，具有三个界面：原生macOS应用程序、CLI和用于AI代理的MCP服务器。

内置Rust+Tauri+React。旨在让Claude Code、Cursor和其他AI代理自主管理git工作树。

建筑

┌──────────────────────────────────────────────────┐
│                  worktree-core (Rust)             │
│  state · merge · ci · hooks · agent orchestration │
│  conflict prediction · diff intelligence · ...    │
└──────┬──────────────┬──────────────┬─────────────┘
       │              │              │
  ┌────▼────┐   ┌─────▼─────┐  ┌────▼────────┐
  │   CLI   │   │ Tauri GUI │  │ MCP Server  │
  │  (Rust) │   │  (React)  │  │ (TypeScript)│
  └─────────┘   └───────────┘  └─────────────┘

这三个接口共享相同的Rust核心库(worktree-core)，因此无论您是使用GUI、CLI还是通过MCP使用AI代理，行为都是相同的。

特性

工作树管理

• 创建、列出和删除git工作树
• 自动框架检测（Laravel、Node.js、Rust等）
• 在APFS上使用CoW（写时复制）在工作树之间复制配置文件
• PHP项目的Laravel Herd链接/取消链接
• Vite端口自动分配以避免冲突

Git操作

• 阶段、取消阶段、提交、拉、推、取
• 分支签出、创建和删除
• 暂存管理（保存、弹出、删除、列表）
• 工作台之间的文件抓取（樱桃采摘单个文件）
• 并排观看差异

合并与集成

• 四种合并策略：合并、挤压、重基、快进
• 模拟合并预览（通过 git merge-tree，无工作目录更改）
• 五级分支集成检查（SameCommit、Ancestor、NoAddedChanges、TreesMatch、MergeAddsNote）
• 不接触工作目录的冲突预测
• 合并和清理：一次操作中合并+删除工作树+删除分支

AI代理编排

• 基于文件锁的多代理工作树声明(.git/wt-agents.json)
• 具有自动失效声明释放功能的心跳协议（超时10分钟）
• 任务路由器：根据分支名称相关性为给定任务建议最佳工作树
• 差异智能：7个文件类别的语义分析和风险评分
• 克劳德的上下文注入(.claude/context.md)和光标(.cursorrules)

CI/CD集成

• GitHub操作和GitLab CI状态轮询 gh 和 glab 命令行界面
• PR/MR信息：编号、URL、可合并状态、审核状态
• 检查状态聚合（待定、通过、失败）

工作流程和挂钩

• 四个内置工作流：feature_collete、hotfix、daily_sync、review_prep
• 自定义TOML工作流定义(~/.worktree/workflows/*.toml)
• 具有自动项目类型检测的顺序步骤执行
• 六个生命周期挂钩：创建后、切换后、合并前、合并后、删除前、删除后
• 后台钩子执行与日志记录

安全与HITL（人在环）

• 破坏性操作标记为 [DANGER:DESTRUCTIVE] 在MCP工具描述中
• GUI中危险操作的确认对话框
• 审核每个MCP工具调用的日志记录（工具、参数、成功/失败、持续时间）
• 速率限制（50个请求/5秒）
• 通过以下方式分配存储库 WORKTREE_ALLOWED_REPOS 环境变量

GUI功能

• 带有回购扫描和冲突雷达的多回购仪表板
• 分支图可视化
• 网格、列表和表视图模式
• 每个工作台卡上的CI状态徽章和工作台状态指示器
• 工作流执行面板（列表、运行、查看结果）
• Stash管理面板（创建、应用、删除）
• 代理人索赔监控小组
• 设置中的挂钩管理器
• 命令面板（Cmd+K）
• 持久的亮/暗主题
• 通过git指纹轮询实现智能自动刷新（间隔3秒，仅在更改时重新加载）
• LLM提交模板管理

先决条件

• 锈 稳定（via 生锈)
• Node.js >=18（使用npm）

对于CI状态功能（可选）：

• GitHub命令行界面(gh)GitHub仓库
• GitLab命令行界面(glab)GitLab仓库

安装

这两个选项都从克隆存储库和安装依赖项开始：

git clone https://github.com/GastonGelhorn/worktree-mcp-manager.git
cd worktree-mcp-manager
npm install
cd mcp-server && npm install && cd ..

选项A——生产构建（推荐）

npm run tauri build

这将编译Rust CLI，捆绑MCP服务器，构建React前端，并将所有内容打包到macOS应用程序中。

构建完成后：

• 应用程序： target/release/bundle/macos/Worktree MCP Manager.app --拖动到 /Applications
• DMG： target/release/bundle/dmg/Worktree MCP Manager_0.1.0_aarch64.dmg （未使用）

已安装的应用程序在以下位置捆绑了自己的MCP服务器二进制文件：

/Applications/Worktree MCP Manager.app/Contents/MacOS/mcp-server

方案B——开发模式

npm run tauri dev

在调试模式下编译Rust CLI，用热重载启动Vite，并打开Tauri窗口。前端变化会立即反映出来；Rust更改需要重新启动。

在开发模式下，MCP服务器直接通过Node运行：

node mcp-server/index.js

测试

npm test              # Frontend tests (Vitest)
npm run test:mcp      # MCP server tests
npm run test:all      # Both
cargo test            # Rust core + CLI tests

MCP服务器设置

MCP服务器通过stdio公开了62个工具，让AI代理（Claude Code、Cursor等）以编程方式控制工作树。

MCP服务器二进制文件的位置取决于您的安装方式：

光标

全球(~/.cursor/mcp.json)--建议在生产构建后使用

添加以下内容 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "worktree-manager": {
      "command": "/Applications/Worktree MCP Manager.app/Contents/MacOS/mcp-server",
      "args": []
    }
  }
}

如果您正在dev模式下运行，请将该命令替换为 node 并将路径传递到入口点：

{
  "mcpServers": {
    "worktree-manager": {
      "command": "node",
      "args": ["/absolute/path/to/worktree-mcp-manager/mcp-server/index.js"]
    }
  }
}

项目本地（在此仓库内工作时）

已配置。此回购包括 .cursor/mcp.json 当您打开项目时，游标会自动读取。无需额外设置。

克劳德代码

全球-生产构建后推荐

claude mcp add worktree-manager /Applications/Worktree\ MCP\ Manager.app/Contents/MacOS/mcp-server

如果您在开发模式下运行：

claude mcp add worktree-manager node /absolute/path/to/worktree-mcp-manager/mcp-server/index.js

证实 claude mcp list.

项目本地（在此仓库内工作时）

已配置。根 .mcp.json 声明服务器，以便Claude Code在您打开项目时自动拾取它。

Laravel Herd MCP（独立服务）

该项目与Laravel Herd集成（例如。 herd_link / herd_unlink 工具），但 Herd自己的MCP服务器是一个单独的服务“完整”的羊群MCP集成通常是 每用户/每台机器，而不是此回购本身可以启用的功能。

• 您必须安装Laravel Herd并启用其MCP服务器 在您选择的代理中（Claude Code和/或Cursor等）。
• 不需要更改项目代码 使用Herd MCP；该配置位于IDE/代理MCP设置中，并指向Herd .phar，通常与 SITE_PATH 设置为项目根目录。

参考： 羊群文档——人工智能集成

克劳德代码

claude mcp add herd php /Applications/Herd.app/Contents/Resources/herd-mcp.phar -e SITE_PATH="$(pwd)"

光标

添加新的MCP服务器（光标设置→ 工具和集成→ 新的MCP服务器）使用以下配置：

{
  "herd": {
    "command": "php",
    "args": ["/Applications/Herd.app/Contents/Resources/herd-mcp.phar"],
    "env": { "SITE_PATH": "YOUR-SITE-PATH" }
  }
}

其他代理商

任何兼容MCP的代理都可以通过stdio连接到服务器。请指出：

• 生产建设： /Applications/Worktree MCP Manager.app/Contents/MacOS/mcp-server
• 开发模式： node mcp-server/index.js

MCP工具参考

62个工具分为7个模块：

工作树工具（4）

Git工具（16）

合并工具（5）

代理工具（4）

实用工具（22）

环境工具（6）

工作流工具（5）

代理使用示例

这些示例显示了AI编码代理（Cursor、Claude Code等）如何与Worktree MCP Manager服务器交互。提示具有说明性；代理决定调用哪些工具。

1.通过代理安全提交Git

• 你说（在你的编辑/法学硕士）:

  I'm in /Users/me/code/my-repo. Use the worktree MCP tools to:
  - Show me what changed
  - Stage only the changes in src/components/SearchBar.tsx
  - Create a commit with a good Conventional Commit message

• 代理人通常会:

- 呼叫 get_changes 总结已暂存/未暂存的文件。 - 呼叫 stage_files 仅用 src/components/SearchBar.tsx. - 呼叫 get_commit_template 正确格式化消息。 - 呼叫 commit （可选配 allowUncommitted=false 以避免提交剩余的更改）。

2.任务的特征分支工作树

• 你说:

  Create an isolated worktree for a new feature branch "feat/search-refactor" from main,
  run the dev server, and then guide me through the files you change.
  Use the worktree MCP tools, not raw git commands.

• 代理人通常会:

- 使用 list_worktrees 和 list_branches 了解当前的布局。 - 呼叫 add_worktree 随着 baseBranch=main 和 branchName=feat/search-refactor. - 呼叫 start_process 在该工作树中运行特定于项目的开发服务器。 - 编辑后，使用 stage_files + get_commit_template + commit 创建一个或多个提交。

3.人在循环合并和清理

• 你说:

  In this repo, check if branch "feat/search-refactor" is safely integratable into main.
  If it merges cleanly, propose the plan first and, after I confirm, perform the merge
  and clean up the feature worktree using the MCP tools.

• 代理人通常会:

- 呼叫 check_branch_integration 了解集成状态。 - 呼叫 merge_dry_run 在不接触工作目录的情况下预览冲突。 - 向您展示一份人类可读的摘要，并要求确认。 - 批准后，致电 merge_and_cleanup （或 merge_worktree + remove_worktree)应用合并和整理。

4.Worktrees之间的代理切换

• 你说:

  Mark the current worktree as ready for review and hand it off so another agent
  can safely continue from here. Use the dedicated handoff/handoff-related tools.

• 代理人通常会:

- 确保工作台清洁(has_uncommitted_changes)或者明确解释剩下的东西。 - 使用 handoff_worktree 执行复合的“准备切换”步骤。 - 可选使用 agent_claim_worktree / agent_release_worktree 这样一次只有一个代理修改工作台。

项目结构

worktree/
├── crates/
│   ├── worktree-core/src/          # Rust core library (24 modules)
│   │   ├── state.rs                # Worktree state detection
│   │   ├── merge.rs                # Multi-strategy merge
│   │   ├── ci.rs                   # CI/CD status polling
│   │   ├── agent_orchestration.rs  # Multi-agent coordination
│   │   ├── conflict_prediction.rs  # Non-destructive conflict check
│   │   ├── task_router.rs          # AI task routing
│   │   ├── diff_intelligence.rs    # Semantic diff analysis
│   │   ├── workflows.rs            # Workflow engine
│   │   ├── hooks.rs                # Lifecycle hooks
│   │   ├── context_v2.rs           # AI context injection
│   │   ├── integration.rs          # Branch integration check
│   │   ├── shortcuts.rs            # Branch shortcut resolution
│   │   ├── git.rs                  # Git command execution
│   │   ├── copier.rs               # File copying with CoW
│   │   ├── herd.rs                 # Laravel Herd integration
│   │   ├── framework.rs            # Framework detection
│   │   └── ...
│   └── worktree-cli/               # CLI binary (clap)
├── src/                            # React frontend (Tauri)
│   ├── components/
│   │   ├── layout/                 # Header, Sidebar, MainPanel
│   │   ├── worktree/               # WorktreeGrid, MergeDialog, CiStatusBadge, ...
│   │   ├── agent/                  # AgentClaimsPanel
│   │   ├── workflow/               # WorkflowPanel (run/list workflows)
│   │   ├── git/                    # StashPanel (stash management)
│   │   ├── dashboard/              # Dashboard, ConflictRadar, StatCard
│   │   ├── graph/                  # BranchGraph, CommitDetailPanel
│   │   ├── settings/               # SettingsDrawer, HooksManager, TemplateManager
│   │   ├── sidebar/                # BranchTree, WorktreeList, RepoSelector
│   │   └── shared/                 # ConfirmDialog, CommandPalette, Toast, ...
│   ├── stores/                     # Zustand state (6 slices)
│   ├── lib/                        # Tauri command bindings, router, theme
│   └── types/                      # TypeScript interfaces
├── src-tauri/                      # Tauri backend (56 commands)
├── mcp-server/                     # MCP server (TypeScript)
│   ├── index.ts                    # Modular entry point
│   └── tools/                      # 7 tool modules (62 tools)
└── scripts/
    └── build-prod.sh               # Production build orchestrator

环境变量

键盘快捷键（GUI）

许可证

麻省理工学院