agent-claim-mcp

Agent Claim MCP

语言： 英语 · 日语 · 简体中文 · 俄语 · 西班牙语

当多个编码 Agent 共用一个工作树，且你需要在编辑前使用一个小巧的本地协调原语，而不是完整的编排框架时，请使用 Agent Claim MCP。它让 Agent 专注于一项工作：声明路径、检测冲突并释放所有权，从而避免并行工作时反复改写相同文件。

Agent Claim MCP 是一款本地优先的 MCP 服务，适用于 Claude Code、Cursor、Cline 及其他需要协调文件所有权、但不需要队列、规划器或自定义 AGENTS.md 约定的 MCP 客户端。当前版本仅提供三项边界明确的操作：声明规范化后的路径、检查路径的所有者，以及按路径或声明 ID 释放所有权，并明确报告不同会话之间的冲突。

发布状态：@vk0/[email protected] 已在 npm 上发布，因此对于外部用户，npx -y @vk0/agent-claim-mcp 现在是准确的默认安装方式。第 5 阶段的外部验证可通过 Official MCP Registry 验证或 Smithery 上的正式列表来完成；但在其中一项公开证明得到明确核实之前，当前验证状态仍为待定。Official MCP Registry 验证仍在等待中，因此在引用真实的注册表或 Smithery 证明 URL 之前，不要声称此软件包已通过注册表审核或已在市场上架。

里程碑说明：产品定位仍然保持狭窄，仅提供 3 个工具和一个本地 JSON 账本，用于防止共享工作树中的文件冲突，而不是更广泛的编排平台。

当前下一项手动步骤：完成待处理的人工重新运行及 Official MCP Registry 证明验证流程，然后记录该次运行的结论，而不要仅凭 npm 已上线就假定审核通过。

注册表重新运行快速入门

当前准确状态：

• npm 1.0.0 已上线
• Official MCP Registry 尚未审核通过
• 工作流 25282612113 未完成注册表验证流程
• 仓库已解决此前的 NPM_TOKEN 密钥修复问题，但仍需人工重新运行并验证注册表证明，之后才能视为审核通过

准确的重新运行命令：

gh run rerun 25282612113 --repo vk0dev/agent-claim-mcp

重新运行后，按以下顺序验证：

1. 确认重新运行已在 GitHub Actions 中成功完成
2. 运行 npm run preflight:registry
3. 按照 docs/official-registry-validation-runbook.md 操作
4. 只有完成以上步骤后，才能记录注册表审核通过已得到证明

操作快捷方式：使用运行手册中的操作员快速流程，按准确顺序完成重新运行到验证；并将 npm 上线状态与注册表证明状态分开看待。

适用场景

如果你的工作流已经具备任务路由，但在编辑时仍需要一个简单的类锁原语，请选择此服务：

• 两个或更多 Agent 可以并行修改同一个仓库
• 你希望在编辑文件之前检测冲突，而不是等到合并冲突发生后再处理
• 你希望声明在 TTL 到期后自动失效
• 你希望原语足够简单，其他 Agent 仅凭名称和描述就能理解
• 你不需要捆绑式规则引擎、队列执行器或编排平台

安装

现在，规范的外部安装方式是使用已发布的 npm 包：

{
  "mcpServers": {
    "agent-claim": {
      "command": "npx",
      "args": ["-y", "@vk0/agent-claim-mcp"]
    }
  }
}

状态说明：npm 安装现已可用，但 Official MCP Registry 验证以及 Smithery／其他市场的证明尚未确立，因此应先将其视为可通过 npm 获取，而非已通过市场验证。

如果你是在本地检出版本上开发，而不是使用已发布的包，仍可将 MCP 客户端直接指向已构建的 dist/server.js。

{
  "mcpServers": {
    "agent-claim": {
      "command": "node",
      "args": ["/absolute/path/to/agent-claim-mcp/dist/server.js"]
    }
  }
}

第二个示例仅用于本地开发。在 Windows 上，请将 MCP 客户端指向你自己机器上已构建的 dist/server.js 路径，不要照搬 POSIX 路径。

使用本地路径前先构建一次：

cd /Users/vkdev/projects/agent-claim-mcp
npm ci
npm run build

Claude Code

将 stdio 服务添加到 Claude Code MCP 配置中：

{
  "mcpServers": {
    "agent-claim": {
      "command": "npx",
      "args": ["-y", "@vk0/agent-claim-mcp"]
    }
  }
}

Claude Desktop

Claude Desktop 在 macOS 上使用 ~/Library/Application Support/Claude/claude_desktop_config.json，在 Windows 上使用 %APPDATA%\Claude\claude_desktop_config.json：

{
  "mcpServers": {
    "agent-claim": {
      "command": "npx",
      "args": ["-y", "@vk0/agent-claim-mcp"]
    }
  }
}

保存 claude_desktop_config.json 后，彻底重启 Claude Desktop，使其重新加载 MCP 服务配置。

Cursor

{
  "mcpServers": {
    "agent-claim": {
      "command": "npx",
      "args": ["-y", "@vk0/agent-claim-mcp"]
    }
  }
}

Cline

{
  "mcpServers": {
    "agent-claim": {
      "command": "npx",
      "args": ["-y", "@vk0/agent-claim-mcp"]
    }
  }
}

限制

此服务有意保持精简，并优先支持本地场景。当你的 Agent 共享同一个文件系统视图时再安装它；如果你需要分布式协调，则不适用。

• 认领记录保存在本地磁盘上的台账中，因此只能协调能够读写同一工作树的会话。
• 它不是托管式锁服务、队列或调度器，也不会自行在多台机器之间复制认领记录。
• TTL 过期机制用于防护性清理，不能替代更高层级的任务归属管理或人工审核。
• 路径规范化可以减少路径形式不一致的问题，但 Agent 仍需指向同一个仓库根目录或 cwd，认领才能正确对应。
• 如果你的工作流需要跨主机协调、集中式审计策略或强制审批，请将此服务与单独的编排层配合使用，不要让认领台账超出其适用范围。

发布前的真实多 Agent 运行示例，请参阅 DOGFOOD.md 和 docs/dogfood-report.md 中的证明材料。

工具

claim_files

创建或刷新本地文件认领条目，让并行工作的 Agent 在编辑前了解文件归属，并避免在任务进行期间同时修改同一工作树路径。冲突响应会明确说明情况，因此不同会话之间的重叠认领不会被隐去，也不会只保留在内存中。

输入

{
  "agentId": "coder-a",
  "taskId": "task-123",
  "paths": ["src/foo.ts", "src/bar.ts"],
  "ttlSeconds": 3600,
  "note": "working on parser cleanup",
  "cwd": "/repo"
}

输出

{
  "ok": true,
  "claimed": ["/repo/src/bar.ts", "/repo/src/foo.ts"],
  "conflicts": [],
  "ledgerVersion": 1,
  "claimedUntil": "2026-05-03T16:00:00.000Z"
}

如果任何请求路径已被另一个活跃所有者认领，该工具会返回 ok: false，且不会写入任何内容。

release_claim

移除当前 Agent 所有的现有认领，使已完成、暂停或重新分配的工作不再阻碍其他 Agent 安全地编辑相同路径。

输入

{
  "agentId": "coder-a",
  "paths": ["src/foo.ts"],
  "cwd": "/repo"
}

输出

{
  "ok": true,
  "released": ["/repo/src/foo.ts"],
  "missing": [],
  "ledgerVersion": 1
}

只有当前所有者才能释放活跃认领，无论你是通过 claimId 还是规范化后的 paths 指定目标。这样，在真实的多 Agent 运行后也能完成清理，并确保不同形式的路径始终能一致匹配。

whose_claim

读取本地台账，说明文件路径是空闲还是当前已被认领，并提供所有者、任务、备注和到期时间元数据，以便共享同一工作树的不同会话安全协调。

输入

{
  "paths": ["src/foo.ts", "src/bar.ts"],
  "cwd": "/repo",
  "includeExpired": false
}

输出

{
  "results": [
    {
      "path": "/repo/src/bar.ts",
      "claimed": false
    },
    {
      "path": "/repo/src/foo.ts",
      "claimed": true,
      "ownerAgentId": "coder-a",
      "taskId": "task-123",
      "note": "working on parser cleanup",
      "expiresAt": "2026-05-03T16:00:00.000Z",
      "claimId": "2a08b70c-4203-44a2-b833-31592472de1e"
    }
  ],
  "ledgerVersion": 1
}

真实示例

1. coder-A 认领 foo.ts

{
  "tool": "claim_files",
  "arguments": {
    "agentId": "coder-A",
    "taskId": "task-42",
    "paths": ["src/foo.ts"],
    "note": "refactoring the claim parser",
    "cwd": "/repo"
  }
}

{
  "ok": true,
  "claimed": ["/repo/src/foo.ts"],
  "conflicts": [],
  "ledgerVersion": 1,
  "claimedUntil": "2026-05-03T16:00:00.000Z"
}

2. coder-B 对同一文件发起冲突认领

{
  "tool": "claim_files",
  "arguments": {
    "agentId": "coder-B",
    "paths": ["src/foo.ts", "src/new.ts"],
    "cwd": "/repo"
  }
}

{
  "ok": false,
  "claimed": [],
  "conflicts": [
    {
      "path": "/repo/src/foo.ts",
      "ownerAgentId": "coder-A",
      "expiresAt": "2026-05-03T16:00:00.000Z"
    }
  ],
  "ledgerVersion": 1,
  "claimedUntil": "2026-05-03T16:00:00.000Z"
}

3. coder-A 释放该文件

{
  "tool": "release_claim",
  "arguments": {
    "agentId": "coder-A",
    "paths": ["src/foo.ts"],
    "cwd": "/repo"
  }
}

{
  "ok": true,
  "released": ["/repo/src/foo.ts"],
  "missing": [],
  "ledgerVersion": 1
}

故障排查

claim_files 返回 ok: false

这表示至少有一个请求路径已被另一个活跃所有者认领，因此没有写入任何新内容。检查 conflicts 数组，确认具体重叠的规范化路径和当前的 ownerAgentId，然后使用 whose_claim 检查相同路径，再重试。

{
  "tool": "whose_claim",
  "arguments": {
    "paths": ["src/foo.ts", "src/new.ts"],
    "cwd": "/repo"
  }
}

只要有一个路径发生冲突，混合请求仍会按全有或全无的方式处理。请拆分任务，或等待当前所有者释放冲突路径。

release_claim 携带 claim id 时返回 missing: ["..."]

该 claim id 在释放时并未处于本地账本的有效状态。它可能已被释放、已过期，或从未在此计算机上存在。这不视为部分成功。

release_claim 携带 paths 时返回 released: []

如果 ok 仍为 true，但 released 为空，说明请求的规范化路径与调用者拥有的任何有效 claim 都不匹配。missing 数组会告诉你哪些规范化路径未匹配。

如果不确定路径是空闲的、由其他 Agent 拥有，还是已从账本中移除，请先使用 whose_claim。

释放其他人的 claim

只有当前所有者才能释放有效的 claim。如果路径仍由其他 Agent 拥有，请使用 whose_claim 检查，与该所有者协调，或等待 TTL 到期。

比较

工具	最适合	Agent Claim MCP 有何不同
Agent Claim MCP	为共享工作树提供一种精简的协调机制	它只回答：谁拥有此路径、我能否认领它，以及我能否释放它？
madebyaris/agent-orchestration	更广泛的编排模式、规则、路由、队列和 AGENTS.md 风格的协调	Agent Claim MCP 有意将功能做得更少。它不捆绑队列、规划器行为或仓库策略。它是可组合到其他工作流中的最小本地机制。

选择 Agent Claim MCP，如果你已经有自己的任务分配层，只需要协调路径所有权。

选择更全面的编排项目，如果你希望通过一个软件包定义 Agent 规则、工作队列、协调策略和更高层的执行流程。

常见问题

什么时候应该选择此工具，而不是为每个 Agent 使用一个 git 分支或工作树？

如果多个 Agent 有意共享同一检出目录和文件系统视图，就可以使用 claim——例如，它们共用同一个 node_modules、构建产物或正在运行的开发服务器，或者任务分配层已按文件而非分支拆分工作。为每个 Agent 单独创建分支或工作树，可以通过复制状态并将冲突推迟到合并时来避免冲突；claim 则通过在首次编辑前声明路径所有权来避免冲突，无需额外检出，也无需合并步骤。如果你的工作流已经将每个 Agent 隔离在自己的分支或工作树中，可能根本不需要此服务。

claim 与真正的锁或 git 工作树隔离有什么区别？

claim 是一条建议性的所有权记录，并非强制执行的文件系统锁。没有任何机制会从物理层面阻止行为不当的进程写入已认领的路径；它依赖协作执行，而这正是 MCP Agent 可以遵循的约定：编辑前调用 claim_files，遵守 ok: false，完成后释放。工作树隔离更强，但开销也更大——需要单独检出、重复状态，而且冲突要到合并时才会显现。两者可以组合使用：对长期并行的工作流使用工作树，并在任何多个 Agent 共同操作的单个工作树中使用 claim。

TTL 实际上有什么作用？claim 过期后会发生什么？

每个 claim 都带有 TTL（ttlSeconds，默认值为 3600），过期的 claim 会在下次读取或写入账本时自动清理。这意味着崩溃、被终止或被遗弃的会话永远不会无限期阻塞路径——最坏情况也只会阻塞一个 TTL 时长。过期机制用于保护性清理，而非任务交接：仍在积极工作的 Agent 应刷新自己的 claim（在相同的 agentId 下重新认领相同路径），而不是一开始就申请很长的 TTL。

发生冲突时具体会怎样？

`claim_files` 为全有或全无。如果任何请求路径已被另一个活跃声明占用，该工具就会返回 `ok: false`，不写入任何内容——包括同一请求中不存在冲突的路径——并在 `conflicts` 数组中列出每个发生冲突的规范化路径及其当前的 `ownerAgentId` 和 `expiresAt`。系统不会排队、重试或强制接管。调用方 Agent 决定接下来该怎么做：拆分批次、通过 `whose_claim` 查看所有者、通过自己的任务层进行协调，或等待声明释放或 TTL 到期。

它能同时在不同的 MCP 客户端之间使用吗，例如 Claude Code 和 Cursor？

可以，只要所有客户端都以同一用户身份运行在同一台机器上。每个 MCP 客户端都会启动自己的服务进程，但所有进程都会通过原子性的临时文件加重命名写入，汇聚到同一个磁盘账本，因此在 Claude Code 会话中发起的声明会立即对 Cursor 或 Cline 会话可见。Agent 必须保持一致的一点是路径形式：传入 cwd 或绝对路径，并确保它们解析到同一个仓库根目录，这样不同客户端之间的规范化结果才能一致。

状态存储在哪里？有什么数据会离开我的机器吗？

所有状态都存储在一个本地 JSON 账本中：~/.agent-claim-mcp/ledger.json。没有守护进程、后台进程、网络侦听器、遥测或云同步——服务只会在工具被调用时读取和写入该文件。这也是产品的边界：声明只协调共享同一文件系统视图的会话，跨主机协调明确不在支持范围内。

我可以释放或窃取另一个 Agent 所有的声明吗？

不可以。release_claim 只会移除调用方 agentId 所有的活跃声明，无论是通过 claimId 还是规范化路径指定。如果某个路径仍归另一个 Agent 所有，你可以通过 whose_claim 查看该声明、通过任务层与所有者协调，或等待 TTL 到期。这能让这一基础机制保持可预测：所有权只会通过显式释放或到期而变更，不会被悄然接管。

工作原理

• 声明存储在本地 JSON 账本 ~/.agent-claim-mcp/ledger.json 中
• 路径会规范化为绝对路径，避免不同 Agent 通过相对路径技巧或不同路径形式绕过冲突检测
• 不同会话之间的重叠声明会通过同一个账本处理，而不是依赖内存中的协调
• 读取和写入时会自动清理已过期的声明
• 写入采用临时文件加重命名语义，以实现原子更新

开发

npm ci
npm run build
npm test
npm run smoke

打包

npm 包预计至少包含：

• README.md
• server.json
• 编译后的 dist/

发布前请使用以下检查：

npm pack --dry-run

发布前提条件

预期的发布流程是 GitHub Actions 发布任务，该任务会在推送版本标签后运行。要使无人值守的 npm 发布步骤成功，工作流必须从为 npm 发布配置的仓库密钥中收到非空的 NODE_AUTH_TOKEN。

如果 CI 中缺少 NODE_AUTH_TOKEN 或其值为空，即使包本身已准备就绪，首次 npm 发布尝试也会因 ENEEDAUTH 而失败。重试发布前，请确认 GitHub 仓库密钥已设置并映射到发布任务，而不要尝试在本地重新运行发布步骤。

打标签前，请按照 docs/smoke-proof.md 中的简短冒烟测试清单完成本地验证。

首次发布后的外部验收检查，请使用维护者操作手册 docs/official-registry-validation-runbook.md 和简短录制模板 docs/official-registry-validation-checklist.md。

许可证

MIT