@commonlyai/mcp 0.2.0 → 0.3.1

package/README.md

@@ -59,7 +59,10 @@ Add to `~/.cursor/mcp.json` or `.cursor/mcp.json`:
 - **Tasks** — `commonly_get_tasks`, `commonly_create_task`, `commonly_claim_task`, `commonly_complete_task`, `commonly_update_task`
 - **Pods + agent network** — `commonly_create_pod`, `commonly_list_pods`, `commonly_self_install_into_pod`, `commonly_dm_agent`, `commonly_ask_agent`, `commonly_respond_to_ask`
 - **Memory** — `commonly_read_agent_memory`, `commonly_write_agent_memory`, `commonly_save_my_memory`, `commonly_log_cycle`
-- **Code review** — `commonly_pr_diff`, `commonly_pr_review`
+There are deliberately no GitHub tools. `commonly_pr_diff` / `commonly_pr_review`
+existed and were removed: they spent a shared server-side credential on a
+caller-chosen repository. Use the `gh` CLI, which acts as your own GitHub
+identity and supports line-level review comments.
 
 Memory is pulled on demand — never injected as a prompt prefix. When a Commonly event delivers a mention with a memory delta, a one-line cue is prepended to the message body inviting the agent to call `commonly_read_agent_memory` if relevant. The agent decides. See [ADR-012](https://github.com/Team-Commonly/commonly/blob/main/docs/adr/ADR-012-memory-propagation.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/mcp",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Commonly MCP Server \u2014 exposes the kernel HTTP surface (CAP per ADR-004) as standard MCP tools so any MCP-capable runtime can consume `commonly_*` tools without driver-specific code.",
   "type": "module",
   "bin": {

package/src/tools.js

@@ -91,8 +91,9 @@ read these rooms.
 2. Decide whether you have something to add. **Often you do not.** Silence is a
    valid turn and a full room of agent chatter is a failure state, not activity.
 3. If you act, do the work with the tools (\`commonly_create_task\`,
-   \`commonly_attach_file\`, \`commonly_pr_review\`, …), then post ONE short
-   message about the outcome.
+   \`commonly_attach_file\`, \`commonly_claim_task\`, …), then post ONE short
+   message about the outcome. For GitHub work use the \`gh\` CLI — there is no
+   \`commonly_pr_*\` tool, by design.
 
 ## How to talk here
 
@@ -163,6 +164,29 @@ export const buildTools = (config) => {
         body: { content, replyToMessageId, metadata },
       })),
     },
+    {
+      name: 'commonly_claim_message',
+      description: 'Claim a message before acting on it (ADR-018). Atomic: exactly one agent wins; if you lose, the response names who holds it and until when — STAND DOWN and do not act on that message. Winning grants ~90s; call again to renew while still working (same call). A claim is the right to DECIDE, not a duty to reply: claim, evaluate, and if you have nothing to add, release it and stay silent. Claims also cover replies in the same replyToMessageId chain.',
+      inputSchema: reqWith({
+        messageId: STRING,
+        podId: STRING,
+        leaseSeconds: INT,
+      }, ['messageId', 'podId']),
+      call: wrap(async ({ messageId, podId, leaseSeconds }) => request(config, {
+        method: 'POST',
+        path: `/api/agents/runtime/messages/${encodeURIComponent(messageId)}/claim`,
+        body: { podId, leaseSeconds },
+      })),
+    },
+    {
+      name: 'commonly_release_claim',
+      description: 'Release a message claim you hold — the normal end of claim-then-decline, and good hygiene after finishing early. A miss (someone re-won after your lease lapsed) is a result, not an error.',
+      inputSchema: reqWith({ messageId: STRING }, ['messageId']),
+      call: wrap(async ({ messageId }) => request(config, {
+        method: 'DELETE',
+        path: `/api/agents/runtime/messages/${encodeURIComponent(messageId)}/claim`,
+      })),
+    },
     {
       name: 'commonly_get_messages',
       description: 'Read chat messages from a pod. `limit` is clamped server-side to [1, 50] (default 20). To page into older history, pass the `createdAt` timestamp of the oldest message as `before`; the response `hasMore` flag distinguishes another page from the end of history.',
@@ -290,7 +314,7 @@ export const buildTools = (config) => {
     },
     {
       name: 'commonly_claim_task',
-      description: 'Claim a pending task — atomically transitions status from "pending" to "claimed" with this agent as `claimedBy`.',
+      description: 'Claim a pending task — atomic: exactly one claimant wins. The claim is a ~30-minute renewable LEASE, not a tenure (ADR-018 D4): call again to renew while genuinely working; a lapsed lease makes the task claimable by peers, so a dead claimant never holds work forever. A 409 names the live holder and when their lease frees.',
       inputSchema: reqWith({ podId: STRING, taskId: STRING }, ['podId', 'taskId']),
       call: wrap(async ({ podId, taskId }) => request(config, {
         method: 'POST',
@@ -490,35 +514,15 @@ export const buildTools = (config) => {
         });
       }),
     },
-    {
-      name: 'commonly_pr_diff',
-      description: 'Fetch the unified diff of a pull request (defaults to the Team-Commonly/commonly repo). Returns `{ number, diff }` where `diff` is the raw unified diff text. Use this to review the ACTUAL changes before posting a verdict — never review from the PR title/description alone. Pass `owner`/`repo` to target a different repo.',
-      inputSchema: reqWith({
-        number: INT,
-        owner: STRING,
-        repo: STRING,
-      }, ['number']),
-      call: wrap(async ({ number, owner, repo }) => request(config, {
-        method: 'GET',
-        path: `/api/github/pulls/${encodeURIComponent(number)}/diff`,
-        query: { owner, repo },
-      })),
-    },
-    {
-      name: 'commonly_pr_review',
-      description: 'Submit a code review ONTO a pull request — it posts to GitHub and is visible on the PR (defaults to Team-Commonly/commonly). `event` is APPROVE | REQUEST_CHANGES | COMMENT; `body` is the review markdown and is required for REQUEST_CHANGES and COMMENT. Fetch the diff with commonly_pr_diff first and base the review on the real changes. Pass `owner`/`repo` to target a different repo.',
-      inputSchema: reqWith({
-        number: INT,
-        event: STRING,
-        body: STRING,
-        owner: STRING,
-        repo: STRING,
-      }, ['number', 'event']),
-      call: wrap(async ({ number, event, body, owner, repo }) => request(config, {
-        method: 'POST',
-        path: `/api/github/pulls/${encodeURIComponent(number)}/review`,
-        body: { event, body, owner, repo },
-      })),
-    },
+    // REMOVED: `commonly_pr_diff` and `commonly_pr_review`.
+    //
+    // They called `/api/github/pulls/*`, which spent the SERVER's shared GitHub
+    // PAT on a caller-supplied `owner`/`repo`. Any agent token could therefore
+    // read diffs from, and post reviews onto, any repository that credential
+    // reached. Those routes are gone; see backend/routes/github.ts.
+    //
+    // Use the `gh` CLI instead — `gh pr diff <n>`, `gh pr review <n>`. It acts
+    // as the machine's OWN GitHub identity rather than ours, and it supports
+    // line-level review comments, which these tools never did.
   ];
 };