batuta-mcp

---

已停止维护

Claude Code 现在可以自行完成这件事。 它内置了将工作分配到相互隔离的工作树、避免并行 Agent 发生冲突的功能，而这正是本项目旨在提供的能力。

此仓库已归档且只读。它仍然可用——npm 上的内容没有移除，最后发布的版本仍可安装——但它将不再维护，也没有维护的必要。 如果你想了解这个构想而非使用这个软件包，完整设计都在 docs/ 中，许可证也允许你 使用它。

为什么

并行运行多个编码 Agent 很快——直到两个 Agent 修改了同一个文件，悄无声息地覆盖彼此的工作。解决办法不是实时协调，而是隔离：为每个 Agent 分配一组互不重叠的文件，从设计上杜绝冲突。

batuta-mcp 负责完成这种拆分。你只需提供一段想法；它就会返回文件边界互不重叠的计划，并为每个计划创建一个隔离的 git 工作树。

工作原理

这是一个无状态 MCP 服务（stdio）。没有数据库、守护进程或 Web UI——只有三个可组合使用的工具：

1. 将一段想法拆分为 2–5 个计划，确保它们的 fileBoundaries 不重叠（如果重叠，会自动修正一次）。
2. 检查边界是否真正互不重叠。
3. 为每个计划创建一个 git worktree，并返回可直接粘贴的提示词——在不同的终端或标签页中分别打开它们，让每个 Agent 处理一个计划，避免冲突。

「执行工作」的部分（运行 Agent 和终端）留在你的编辑器中；batuta-mcp 只负责规划。

功能

• 🧠 互不重叠的拆分——生成计划时确保同一个文件不会出现在多个计划中。
• ♻️ 自动修正——如果模型返回的边界存在重叠，会重试一次，将它们分开。
• 🌳 创建工作树——为每个计划创建一个隔离的 git worktree，并提供可直接粘贴的提示词。
• 🔒 设计安全——写入磁盘前执行预检（有效的 git 仓库、无重叠、无路径遍历）；dryRun 可预览而不写入。
• 🪶 无状态——不持久化任何内容；使用你已登录的 claude CLI（无需 API 密钥）。

要求

• Bun 1.3+
• git 2.x（用于 scaffold_worktrees）
• 已登录的 claude CLI（用于 decompose_into_plans）
• Claude Code 或任何 MCP 客户端

安装

从 npm 安装——无需克隆：

claude mcp add batuta -- bunx --bun @vorluno/batuta-mcp

从源码安装——如果你想修改它：

git clone https://github.com/vorluno/batuta-mcp.git
cd batuta-mcp
bun install
claude mcp add batuta -- bun run /absolute/path/to/batuta-mcp/src/index.ts

配置

任何 MCP 客户端都可以使用。mcpServers 配置项：

{
  "mcpServers": {
    "batuta": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/batuta-mcp/src/index.ts"]
    }
  }
}

对于 Claude Code，claude mcp add（如上所示）会为你写入此配置。对于 Warp 或 Cursor，请将此代码片段粘贴到它们的 MCP 设置中。

工具

工具	描述
decompose_into_plans	{ brainDump, projectHint?, repoPath? } → { plans, overlapsResolved, attempts }。将工作拆分为边界互不重叠的计划（自动修正一次重叠）。
check_boundary_overlaps	{ plans } → { overlaps, ok }。纯检查：是否有多个计划涉及相同文件？
scaffold_worktrees	{ repoPath, plans, dryRun? } → { results }。预先检查，然后为每个计划执行 git worktree add，并提供可直接粘贴的提示词。

典型流程

1. decompose_into_plans → 边界互不重叠的计划。
2. check_boundary_overlaps → 确认 ok: true（或进行调整）。
3. scaffold_worktrees → 创建工作树；在各自独立的终端/标签页中打开每个工作树，并粘贴其 suggestedPrompt。

开发

bun test          # full suite
bunx tsc --noEmit # type-check

采用测试优先的方式完成了 10 项 TDD 任务，并进行了逐项和整个分支的审查。

贡献与安全

请先阅读 CONTRIBUTING.md——其第一行会告诉你拉取请求是否会被考虑。漏洞请发送至 [email protected]，切勿提交为 issue：详见 SECURITY.md，我们承诺的唯一响应时限是 72 小时内确认收到。

许可证

Apache-2.0 © 2026 Vorluno。详见 NOTICE。

截至 0.1.0（含该版本），本项目使用 MIT 许可证。这些版本仍受 MIT 许可证约束——已授予的许可无法撤销。从 0.2.0 起，本项目改用 Apache-2.0，明确授予专利权。

---