{"id":49791732,"url":"https://github.com/vk0dev/agent-claim-mcp","last_synced_at":"2026-05-12T05:05:42.971Z","repository":{"id":355418923,"uuid":"1228011851","full_name":"vk0dev/agent-claim-mcp","owner":"vk0dev","description":"Local-first MCP server: parallel AI coding agents (Claude Code, Cursor, Codex) coordinate file ownership via JSON ledger. Three tools, no infra.","archived":false,"fork":false,"pushed_at":"2026-05-03T15:04:32.000Z","size":155,"stargazers_count":0,"open_issues_count":9,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-03T15:29:22.173Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vk0dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-03T13:27:59.000Z","updated_at":"2026-05-03T15:04:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vk0dev/agent-claim-mcp","commit_stats":null,"previous_names":["vk0dev/agent-claim-mcp"],"tags_count":1,"template":false,"template_full_name":"vk0dev/mcp-project-template","purl":"pkg:github/vk0dev/agent-claim-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vk0dev%2Fagent-claim-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vk0dev%2Fagent-claim-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vk0dev%2Fagent-claim-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vk0dev%2Fagent-claim-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vk0dev","download_url":"https://codeload.github.com/vk0dev/agent-claim-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vk0dev%2Fagent-claim-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32924388,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-11T17:09:15.040Z","status":"online","status_checked_at":"2026-05-12T02:00:06.338Z","response_time":102,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-12T05:05:31.177Z","updated_at":"2026-05-12T05:05:42.961Z","avatar_url":"https://github.com/vk0dev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Claim MCP\n\n[![npm](https://img.shields.io/npm/v/@vk0/agent-claim-mcp)](https://www.npmjs.com/package/@vk0/agent-claim-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n\nUse Agent Claim MCP when multiple coding agents share one worktree and you need a tiny local coordination primitive before edits, not a full orchestration framework. It gives agents one job: claim paths, detect collisions, and release ownership so parallel work stops stomping the same files.\n\nAgent Claim MCP is a local-first MCP server for Claude Code, Cursor, Cline, and other MCP clients that need file ownership coordination without queues, planners, or custom AGENTS.md conventions. The current release surface centers on three bounded actions only: claim normalized paths, inspect who owns them, and release by path or claim id with explicit conflict reporting across separate sessions.\n\n\u003e Release status: `@vk0/agent-claim-mcp@1.0.0` is live on npm, so the `npx -y @vk0/agent-claim-mcp` install path is now the truthful default for external users. Official MCP Registry validation is still pending, so do not describe the package as registry-accepted until that separate check passes.\n\u003e\n\u003e Current next manual step: fix the repo `NPM_TOKEN` secret, then rerun workflow `25282612113`.\n\n## Registry rerun quickstart\n\nCurrent truthful state:\n- npm `1.0.0` is live\n- Official MCP Registry acceptance is still pending\n- workflow `25282612113` did not complete the registry validation path\n- next manual step is to fix the repo `NPM_TOKEN` secret, then rerun that workflow\n\nExact rerun command:\n\n```bash\ngh run rerun 25282612113 --repo vk0dev/agent-claim-mcp\n```\n\nAfter the rerun, verify in this order:\n1. confirm the rerun completed successfully in GitHub Actions\n2. run `npm run preflight:registry`\n3. follow `docs/official-registry-validation-runbook.md`\n4. only then record registry acceptance as proven\n\n## Why / When to use\n\nChoose this server when your workflow already has task routing, but still needs a simple lock-like primitive at edit time:\n\n- two or more agents can touch the same repo in parallel\n- you want collision detection before file edits, not after merge conflicts\n- you want claims to expire automatically with TTLs\n- you want a narrow primitive that another agent can understand from name + description alone\n- you do **not** want a bundled rules engine, queue runner, or orchestration platform\n\n## Installation\n\nThe canonical external install path is now the published npm package:\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-claim\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@vk0/agent-claim-mcp\"]\n    }\n  }\n}\n```\n\nIf you are developing from a local checkout instead of the published package, you can still point your MCP client at the built `dist/server.js` directly.\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-claim\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/agent-claim-mcp/dist/server.js\"]\n    }\n  }\n}\n```\n\nThat second example is for local development only. On Windows, point your MCP client at the built `dist/server.js` path on your own machine instead of copying a POSIX path literally.\n\nBuild once before using the local path:\n\n```bash\ncd /Users/vkdev/projects/agent-claim-mcp\nnpm ci\nnpm run build\n```\n\n### Claude Code\n\nAdd the stdio server to your Claude Code MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-claim\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@vk0/agent-claim-mcp\"]\n    }\n  }\n}\n```\n\n### Claude Desktop\n\nClaude Desktop uses `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS and `%APPDATA%\\Claude\\claude_desktop_config.json` on Windows:\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-claim\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@vk0/agent-claim-mcp\"]\n    }\n  }\n}\n```\n\nAfter saving `claude_desktop_config.json`, fully restart Claude Desktop so it reloads the MCP server configuration.\n\n### Cursor\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-claim\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@vk0/agent-claim-mcp\"]\n    }\n  }\n}\n```\n\n### Cline\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-claim\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@vk0/agent-claim-mcp\"]\n    }\n  }\n}\n```\n\n## Limitations\n\nThis server is intentionally narrow and local-first. Install it when your agents share one filesystem view, not when you need distributed coordination.\n\n- Claims live in a local ledger on disk, so they only coordinate sessions that can read and write the same worktree.\n- It is not a hosted lock service, queue, or scheduler, and it does not replicate claims across machines by itself.\n- TTL expiry is protective cleanup, not a substitute for higher-level task ownership or human review.\n- Path normalization reduces shape mismatches, but agents still need to point at the same repo root or `cwd` for claims to line up.\n- If your workflow needs cross-host coordination, central audit policy, or mandatory approvals, pair this server with a separate orchestration layer instead of stretching the claim ledger beyond its scope.\n\nFor a real multi-agent run before publishing, see [DOGFOOD.md](./DOGFOOD.md) and the proof artifacts in [docs/dogfood-report.md](./docs/dogfood-report.md).\n\n## Tools\n\n### `claim_files`\n\nCreate or refresh a local file-claim entry so parallel agents can see ownership before editing and avoid stomping the same worktree paths during active tasks. Conflict responses are explicit, so overlapping claims across separate sessions do not stay implicit or in-memory only.\n\n**Input**\n\n```json\n{\n  \"agentId\": \"coder-a\",\n  \"taskId\": \"task-123\",\n  \"paths\": [\"src/foo.ts\", \"src/bar.ts\"],\n  \"ttlSeconds\": 3600,\n  \"note\": \"working on parser cleanup\",\n  \"cwd\": \"/repo\"\n}\n```\n\n**Output**\n\n```json\n{\n  \"ok\": true,\n  \"claimed\": [\"/repo/src/bar.ts\", \"/repo/src/foo.ts\"],\n  \"conflicts\": [],\n  \"ledgerVersion\": 1,\n  \"claimedUntil\": \"2026-05-03T16:00:00.000Z\"\n}\n```\n\nIf any requested path is already claimed by another active owner, the tool returns `ok: false` and writes nothing.\n\n### `release_claim`\n\nRemove an existing claim owned by the current agent so finished, paused, or reassigned work stops blocking other agents from safely editing the same paths.\n\n**Input**\n\n```json\n{\n  \"agentId\": \"coder-a\",\n  \"paths\": [\"src/foo.ts\"],\n  \"cwd\": \"/repo\"\n}\n```\n\n**Output**\n\n```json\n{\n  \"ok\": true,\n  \"released\": [\"/repo/src/foo.ts\"],\n  \"missing\": [],\n  \"ledgerVersion\": 1\n}\n```\n\nOnly the current owner can release an active claim, whether you target it by `claimId` or by normalized `paths`, so cleanup works after real multi-agent runs and path-shape variants resolve consistently.\n\n### `whose_claim`\n\nRead the local ledger and explain whether a file path is free or currently claimed, including owner, task, note, and expiry metadata for safe coordination across separate sessions sharing the same worktree.\n\n**Input**\n\n```json\n{\n  \"paths\": [\"src/foo.ts\", \"src/bar.ts\"],\n  \"cwd\": \"/repo\",\n  \"includeExpired\": false\n}\n```\n\n**Output**\n\n```json\n{\n  \"results\": [\n    {\n      \"path\": \"/repo/src/bar.ts\",\n      \"claimed\": false\n    },\n    {\n      \"path\": \"/repo/src/foo.ts\",\n      \"claimed\": true,\n      \"ownerAgentId\": \"coder-a\",\n      \"taskId\": \"task-123\",\n      \"note\": \"working on parser cleanup\",\n      \"expiresAt\": \"2026-05-03T16:00:00.000Z\",\n      \"claimId\": \"2a08b70c-4203-44a2-b833-31592472de1e\"\n    }\n  ],\n  \"ledgerVersion\": 1\n}\n```\n\n## Real samples\n\n### 1. coder-A claims `foo.ts`\n\n```json\n{\n  \"tool\": \"claim_files\",\n  \"arguments\": {\n    \"agentId\": \"coder-A\",\n    \"taskId\": \"task-42\",\n    \"paths\": [\"src/foo.ts\"],\n    \"note\": \"refactoring the claim parser\",\n    \"cwd\": \"/repo\"\n  }\n}\n```\n\n```json\n{\n  \"ok\": true,\n  \"claimed\": [\"/repo/src/foo.ts\"],\n  \"conflicts\": [],\n  \"ledgerVersion\": 1,\n  \"claimedUntil\": \"2026-05-03T16:00:00.000Z\"\n}\n```\n\n### 2. coder-B collides on the same file\n\n```json\n{\n  \"tool\": \"claim_files\",\n  \"arguments\": {\n    \"agentId\": \"coder-B\",\n    \"paths\": [\"src/foo.ts\", \"src/new.ts\"],\n    \"cwd\": \"/repo\"\n  }\n}\n```\n\n```json\n{\n  \"ok\": false,\n  \"claimed\": [],\n  \"conflicts\": [\n    {\n      \"path\": \"/repo/src/foo.ts\",\n      \"ownerAgentId\": \"coder-A\",\n      \"expiresAt\": \"2026-05-03T16:00:00.000Z\"\n    }\n  ],\n  \"ledgerVersion\": 1,\n  \"claimedUntil\": \"2026-05-03T16:00:00.000Z\"\n}\n```\n\n### 3. coder-A releases the file\n\n```json\n{\n  \"tool\": \"release_claim\",\n  \"arguments\": {\n    \"agentId\": \"coder-A\",\n    \"paths\": [\"src/foo.ts\"],\n    \"cwd\": \"/repo\"\n  }\n}\n```\n\n```json\n{\n  \"ok\": true,\n  \"released\": [\"/repo/src/foo.ts\"],\n  \"missing\": [],\n  \"ledgerVersion\": 1\n}\n```\n\n## Troubleshooting\n\n### `claim_files` returns `ok: false`\n\nThis means at least one requested path is already claimed by another active owner, so nothing new was written. Check the `conflicts` array for the exact overlapping normalized paths and the current `ownerAgentId`, then inspect the same paths with `whose_claim` before retrying.\n\n```json\n{\n  \"tool\": \"whose_claim\",\n  \"arguments\": {\n    \"paths\": [\"src/foo.ts\", \"src/new.ts\"],\n    \"cwd\": \"/repo\"\n  }\n}\n```\n\nIf one path collides, a mixed request is still all-or-nothing. Split the work or wait for the current owner to release the conflicting path.\n\n### `release_claim` with a claim id returns `missing: [\"...\"]`\n\nThat claim id was not active in the local ledger at release time. It may already be released, expired, or never existed on this machine. This is not treated as a partial success.\n\n### `release_claim` with paths returns `released: []`\n\nIf `ok` is still `true` but `released` is empty, the requested normalized paths did not match any active claim owned by the caller. The `missing` array tells you which normalized paths were not matched.\n\nUse `whose_claim` first when you are unsure whether the path is free, owned by another agent, or already gone from the ledger.\n\n### Releasing someone else’s claim\n\nOnly the current owner can release an active claim. If another agent still owns the path, inspect it with `whose_claim`, coordinate with that owner, or wait for the TTL to expire.\n\n## Comparison\n\n| Tool | Best at | Where Agent Claim MCP is different |\n| --- | --- | --- |\n| **Agent Claim MCP** | One narrow coordination primitive for shared worktrees | It only answers: who owns this path, can I claim it, and can I release it? |\n| **madebyaris/agent-orchestration** | Broader orchestration patterns, rules, routing, queues, and AGENTS.md-style coordination | Agent Claim MCP does much less on purpose. It does not bundle queueing, planner behavior, or repo policy. It is the smallest local primitive you can compose into another workflow. |\n\n**Choose Agent Claim MCP** when you already have your own tasking layer and only need path ownership coordination.\n\n**Choose a broader orchestration project** when you want one package to define agent rules, work queues, coordination policy, and higher-level execution flow.\n\n## How it works\n\n- claims are stored in a local JSON ledger at `~/.agent-claim-mcp/ledger.json`\n- paths are normalized to absolute paths so different agents cannot dodge collisions with relative path tricks or path-shape variants\n- overlapping claims across separate sessions resolve through the same ledger instead of relying on in-memory coordination\n- expired claims are pruned automatically on reads and writes\n- writes use temp-file plus rename semantics for atomic updates\n\n## Development\n\n```bash\nnpm ci\nnpm run build\nnpm test\nnpm run smoke\n```\n\n## Packaging\n\nThe npm package is expected to ship at least:\n\n- `README.md`\n- `server.json`\n- compiled `dist/`\n\nUse this check before release:\n\n```bash\nnpm pack --dry-run\n```\n\n## Publish prerequisites\n\nThe expected publish path is the GitHub Actions release job that runs after a version tag push. For the unattended npm publish step to succeed, the workflow must receive a non-empty `NODE_AUTH_TOKEN` from the repo secret configured for npm publishing.\n\nIf `NODE_AUTH_TOKEN` is missing or empty in CI, the first npm publish attempt fails with `ENEEDAUTH` even when the package itself is ready. Before retrying a release, confirm the GitHub repository secret is present and mapped into the publish job rather than trying to re-run publish steps locally.\n\nFor the local proof path before tagging, run the short smoke checklist in [`docs/smoke-proof.md`](./docs/smoke-proof.md).\n\nFor the first post-publish external acceptance check, use the maintainer runbook in [`docs/official-registry-validation-runbook.md`](./docs/official-registry-validation-runbook.md) and the short recording template in [`docs/official-registry-validation-checklist.md`](./docs/official-registry-validation-checklist.md).\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvk0dev%2Fagent-claim-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvk0dev%2Fagent-claim-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvk0dev%2Fagent-claim-mcp/lists"}