agent-claim-mcp

Agent Claim MCP

言語： 英語 · 日本語 · 简体中文 · Русский · Español

複数のコーディングエージェントが同じワークツリーを共有しており、編集前に本格的なオーケストレーションフレームワークではなく、小さなローカル調整機能が必要な場合は、Agent Claim MCP をお使いください。エージェントに、パスの確保、競合の検出、所有権の解放という単一の役割を与えることで、並行作業で同じファイルを取り合うのを防ぎます。

Agent Claim MCP は、キュー、プランナー、独自の AGENTS.md 規約を使わずにファイルの所有権を調整したい Claude Code、Cursor、Cline、その他の MCP クライアント向けの、ローカル優先の MCP サーバーです。現在のリリースで提供する機能は、範囲を限定した次の 3 つのアクションのみです。正規化されたパスの確保、所有者の確認、パスまたは claim id による解放です。別々のセッション間で競合があれば明示的に報告します。

リリース状況：@vk0/[email protected] は npm で公開済みのため、外部ユーザー向けの標準的なインストール方法は npx -y @vk0/agent-claim-mcp です。フェーズ 5 の外部検証は、Official MCP Registry による検証、または公開中の Smithery 掲載のいずれかで達成できますが、公開された成果物のいずれかが明示的に確認されるまでは、現在の検証状況は保留中です。Official MCP Registry による検証はまだ保留中です。実際の Registry または Smithery の検証 URL が示されるまでは、このパッケージを Registry に承認済み、またはマーケットプレイスに掲載済みと説明しないでください。

マイルストーンの実態：製品の対象範囲は引き続き限定されています。共有ワークツリーでの競合防止を目的とする 3 つのツールとローカル JSON 台帳であり、より広範なオーケストレーションプラットフォームではありません。

現在の次の手動ステップ：Official MCP Registry の検証に向けて、保留中の人手による再実行と検証を完了し、npm で利用可能だからといって承認済みと判断せず、その実行結果を記録してください。

Registry の再実行クイックスタート

現在の正確な状況：

• npm の 1.0.0 は公開済みです
• Official MCP Registry の承認はまだ保留中です
• workflow 25282612113 は Registry の検証手順を完了しませんでした
• このリポジトリでは、以前の NPM_TOKEN シークレット修正は完了していますが、Registry の検証結果を承認済みとして扱うには、人手による再実行と確認が必要です

正確な再実行コマンド：

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. その後に限り、Registry の承認が証明されたものとして記録します

運用担当者向けのショートカット：正確な再実行から検証までの順序は、runbook の運用担当者向けクイックパスを使用してください。また、npm で公開済みであることと Registry の検証状況は別々に扱ってください。

使用する理由／場面

ワークフローにタスクのルーティング機能はすでにあるものの、編集時にシンプルなロックのような機能が必要な場合は、このサーバーを選んでください。

• 2 つ以上のエージェントが、同じリポジトリに並行して変更を加える可能性がある
• マージ競合の後ではなく、ファイル編集の前に競合を検出したい
• TTL によって確保が自動的に期限切れになるようにしたい
• 名前と説明だけで別のエージェントが理解できる、範囲の限られた機能が必要
• ルールエンジン、キュー実行ツール、オーケストレーションプラットフォームをまとめて導入したくない

インストール

現在、標準の外部インストール方法は公開 npm パッケージです。

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

ステータスに関する注記：npm からのインストールは現在利用できますが、Official MCP Registry の検証や Smithery などのマーケットプレイスでの実績はまだ確認できていません。そのため、マーケットプレイスで検証済みではなく、まず npm で利用可能なものとしてお考えください。

公開パッケージではなくローカルのチェックアウトから開発する場合は、ビルド済みの dist/server.js を MCP クライアントに直接指定できます。

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

2 つ目の例はローカル開発専用です。Windows では、POSIX パスをそのままコピーするのではなく、お使いのマシン上にあるビルド済みの dist/server.js のパスを MCP クライアントに指定してください。

ローカルパスを使用する前に、一度ビルドしてください。

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 を保存したら、MCP サーバーの設定を再読み込みするために Claude Desktop を完全に再起動してください。

Cursor

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

Cline

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

制限事項

このサーバーは、意図的に機能を絞り、ローカルファーストで設計されています。エージェントが同じファイルシステムビューを共有する場合にインストールしてください。分散型の調整が必要な場合には適していません。

• クレームはディスク上のローカル台帳に保存されるため、同じワークツリーに対して読み書きできるセッション間でのみ調整できます。
• ホスト型のロックサービス、キュー、スケジューラーではなく、単独でマシン間のクレームを複製することもありません。
• TTL の期限切れは保護的なクリーンアップのためのものであり、より上位のタスク所有権管理や人によるレビューの代わりにはなりません。
• パスの正規化によって形式の不一致は減らせますが、クレームを正しく対応させるには、エージェントが同じリポジトリのルートまたは cwd を指定する必要があります。
• ワークフローでホスト間の調整、中央集約型の監査ポリシー、または必須の承認が必要な場合は、クレーム台帳の適用範囲を超えて利用するのではなく、別のオーケストレーションレイヤーと組み合わせてください。

公開前の実際のマルチエージェント実行については、DOGFOOD.md と docs/dogfood-report.md の証拠資料を参照してください。

ツール

claim_files

ローカルのファイルクレームエントリーを作成または更新します。これにより、並行して作業するエージェントは編集前に所有状況を確認でき、タスクの実行中に同じワークツリーのパスを上書きするのを避けられます。競合は明示的に返されるため、別々のセッション間で重複するクレームが暗黙のままになったり、メモリ内にしか存在しない状態になったりすることはありません。

入力

{
  "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

現在のエージェントが所有する既存のクレームを削除します。これにより、完了、一時停止、または担当変更となった作業が、他のエージェントによる同じパスの安全な編集を妨げなくなります。

入力

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

出力

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

claimId を指定する場合も、正規化された paths を指定する場合も、アクティブなクレームを解放できるのは現在の所有者だけです。そのため、実際のマルチエージェント実行後でもクリーンアップでき、パス形式の違いも一貫して解決されます。

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 を返す

リクエストされたパスの少なくとも 1 つが、別のアクティブな所有者によってすでにクレームされているため、新たな書き込みは行われなかったことを意味します。conflicts 配列で、重複している正規化済みパスと現在の ownerAgentId を確認してから、再試行の前に whose_claim で同じパスを調べてください。

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

1 つのパスが競合すると、複数のパスを含むリクエスト全体が一括で処理され、部分的な書き込みは行われません。作業を分割するか、現在の所有者が競合するパスを解放するまで待ってください。

release_claim にクレーム ID を指定すると missing: ["..."] が返されます

そのクレーム ID は、リリース時点でローカル台帳に存在するアクティブなクレームではありませんでした。すでにリリース済み、期限切れ、またはこのマシン上で作成されたことがない可能性があります。これは部分的な成功として扱われません。

release_claim にパスを指定すると released: [] が返されます

ok が引き続き true でも released が空の場合、要求された正規化済みパスは、呼び出し元が所有するアクティブなクレームに一致しませんでした。missing 配列には、一致しなかった正規化済みパスが示されます。

そのパスが空いているのか、別のエージェントに所有されているのか、すでに台帳から削除されているのかが不明な場合は、まず whose_claim を使用してください。

他のエージェントのクレームをリリースする

アクティブなクレームをリリースできるのは、現在の所有者だけです。別のエージェントがまだそのパスを所有している場合は、whose_claim で確認し、その所有者と調整するか、TTL の期限切れを待ってください。

比較

ツール	得意なこと	Agent Claim MCP との違い
Agent Claim MCP	共有ワークツリー向けの、単一の限定的な調整機能	このパスの所有者は誰か、自分はクレームできるか、リリースできるかだけを回答します。
madebyaris/agent-orchestration	より広範なオーケストレーションパターン、ルール、ルーティング、キュー、AGENTS.md 形式の調整	Agent Claim MCP は意図的に機能を絞っています。キューイング、プランナーの動作、リポジトリポリシーは組み込まれていません。他のワークフローに組み込める、最小限のローカル機能です。

独自のタスク管理レイヤーがすでにあり、必要なのがパスの所有権の調整だけであれば、Agent Claim MCP を選んでください。

エージェントのルール、作業キュー、調整ポリシー、高レベルの実行フローを一つのパッケージで定義したい場合は、より広範なオーケストレーションプロジェクトを選んでください。

よくある質問

エージェントごとに Git ブランチやワークツリーを使う代わりに、これを選ぶのはどのような場合ですか？

複数のエージェントが意図的に同じチェックアウトとファイルシステムの状態を共有する場合は、クレームを選んでください。たとえば、同じ node_modules やビルド成果物、実行中の開発サーバーを再利用する場合や、タスク管理レイヤーがブランチ単位ではなくファイル単位で作業を分割する場合です。エージェントごとのブランチやワークツリーは、状態をコピーして競合をマージ時まで先送りすることで衝突を防ぎます。一方、クレームは追加のチェックアウトやマージ手順なしで、最初の編集前にパスの所有権を宣言して衝突を防ぎます。ワークフローですでに各エージェントが専用のブランチまたはワークツリーに分離されている場合、このサーバーは必要ないかもしれません。

クレームは実際のロックや Git のワークツリー分離とどう違いますか？

クレームは強制力のあるファイルシステムロックではなく、助言的な所有権記録です。不正なプロセスがクレーム済みのパスに書き込むのを物理的に防ぐものはありません。強制力は協調に依存します。これこそが MCP エージェントが従える契約です。編集前に claim_files を呼び出し、ok: false を尊重し、作業が完了したらリリースします。ワークツリーによる分離はより強力ですが、チェックアウトの分離や状態の重複が必要となり、競合がマージ時まで表面化しないという負担があります。この2つは併用できます。長期間にわたる並行作業にはワークツリーを使用し、複数のエージェントが触れる各ワークツリー内ではクレームを使用してください。

TTL は実際に何をするもので、クレームが期限切れになるとどうなりますか？

すべてのクレームには TTL（ttlSeconds、デフォルトは3600）が設定されており、期限切れのクレームは次に台帳を読み取るか書き込む際に自動的に削除されます。これにより、クラッシュ、強制終了、または放棄されたセッションがパスを永久にブロックすることはありません。最悪でも、ブロックされるのは1回の TTL 期間だけです。期限切れは保護のためのクリーンアップであり、タスクの引き継ぎではありません。作業を続けているエージェントは、最初から非常に長い TTL を要求するのではなく、同じ agentId で同じパスを再度クレームして、自分のクレームを更新してください。

競合が発生すると、具体的にどうなりますか？

`claim_files` は全件成功または全件失敗です。要求されたパスのいずれかが、別の有効な claim によってすでに所有されている場合、ツールは `ok: false` を返し、同じリクエスト内の競合しないパスも含めて何も書き込まず、`conflicts` 配列に競合する正規化済みパスと、それぞれの現在の `ownerAgentId` および `expiresAt` を列挙します。キューイング、再試行、強制的な所有権取得はありません。次に何をするかは呼び出し元のエージェントが決定します。バッチを分割する、`whose_claim` で所有者を確認する、独自のタスク管理レイヤーを通じて調整する、または解放か TTL の期限切れを待つ、といった方法があります。

Claude Code と Cursor のように、異なる MCP クライアント間で同時に動作しますか？

はい。すべてのクライアントが同じユーザーとして同じマシン上で実行されている限り、動作します。各 MCP クライアントはそれぞれ独自のサーバープロセスを起動しますが、すべてのプロセスが一時ファイルへの書き込みとリネームを組み合わせたアトミックな書き込みによって、同じディスク上の台帳を共有します。そのため、Claude Code のセッションで作成された claim は、Cursor や Cline のセッションからすぐに確認できます。エージェントが一貫させる必要があるのはパスの形式です。cwd または絶対パスを渡し、同じリポジトリルートに解決されるようにして、クライアント間で正規化が一致するようにしてください。

状態はどこに保存されますか？また、マシン外に送信されるものはありますか？

すべての状態は、ローカルの JSON 台帳 ~/.agent-claim-mcp/ledger.json に保存されます。デーモン、バックグラウンドプロセス、ネットワークリスナー、テレメトリ、クラウド同期はありません。サーバーはツールが呼び出されたときにのみ、このファイルの読み書きを行います。これがこの製品の対象範囲でもあります。claim は同じファイルシステムビューを共有するセッション間を調整するものであり、ホストをまたいだ調整は明示的に対象外です。

別のエージェントが所有する claim を解放したり、奪ったりできますか？

いいえ。release_claim が削除できるのは、claimId または正規化済みパスを指定した場合も、呼び出し元の agentId が所有する有効な claim のみです。別のエージェントがパスを所有している場合は、whose_claim で確認する、その所有者とタスク管理レイヤーを通じて調整する、または TTL の期限切れを待つ方法があります。これにより、このプリミティブの動作は予測可能に保たれます。所有権は明示的な解放か期限切れによってのみ変更され、気付かれないまま奪われることはありません。

動作の仕組み

• claim はローカルの JSON 台帳 ~/.agent-claim-mcp/ledger.json に保存されます
• パスは絶対パスに正規化されるため、相対パスを使ったトリックやパス形式の違いによって、エージェントが競合を回避することはできません
• 別々のセッション間で重複する claim は、メモリ内の調整に依存せず、同じ台帳を通じて解決されます
• 期限切れの claim は、読み取り時と書き込み時に自動的に整理されます
• 書き込みには一時ファイルへの書き込みとリネームのセマンティクスを使用し、アトミックに更新します

開発

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