@nimara-app/mcp 0.6.0 → 0.8.0

package/dist/index.js

@@ -9,7 +9,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 // package.json
 var package_default = {
   name: "@nimara-app/mcp",
-  version: "0.6.0",
+  version: "0.8.0",
   private: false,
   mcpName: "io.github.langskip-studios/nimara",
   description: "Nimara MCP server \u2014 AI tool integration for Claude, Codex, and others",
@@ -20,7 +20,8 @@ var package_default = {
     "nimara-mcp": "dist/index.js"
   },
   files: [
-    "dist",
+    "dist/index.js",
+    "dist/index.js.map",
     "README.md"
   ],
   keywords: [
@@ -45,7 +46,8 @@ var package_default = {
     dev: "node build.mjs",
     start: "node dist/index.js",
     typecheck: "tsc --noEmit",
-    prepublishOnly: "npm run typecheck && npm run build"
+    prepublishOnly: "npm run typecheck && npm run build",
+    test: "vitest run"
   },
   dependencies: {
     "@modelcontextprotocol/sdk": "^1.0.0",
@@ -53,10 +55,15 @@ var package_default = {
     zod: "^3.23.0"
   },
   devDependencies: {
+    "@clerk/hono": "^0.1.79",
+    "@clerk/mcp-tools": "^0.6.0",
     "@nimara/convex": "workspace:*",
     "@types/node": "^20.0.0",
     esbuild: "^0.23.0",
-    typescript: "^5.0.0"
+    hono: "^4.13.8",
+    typescript: "^5.0.0",
+    vitest: "^2.1.9",
+    wrangler: "4.132.0"
   },
   engines: {
     node: ">=20"
@@ -74,13 +81,33 @@ A status must be one of the project's \`statuses\` from list_projects, spelled e
 
 When you pick up an item: update_work_item { status: <in-progress status>, agentWorking: true, model: <the model you run as> }. That lights its row for 15 minutes and lets the app say whose agent, and which, is on it; any write or read of the item renews it, and on a long stretch with no Nimara calls, heartbeat_work_item every few minutes keeps it lit. Post a comment at real milestones. If you stop early, agentWorking: false. Moving to the last status clears it.
 
-Mention a person in a comment as [@Name](user:<userId>) and they are notified. Append agent research to a description under the exact heading "## Research (auto)", never editing the human text above it. When you open a PR, put the displayId in its title.`;
+People are userIds from list_project_members: mention one in a comment as [@Name](user:<userId>), or hand them the item with update_work_item's assigneeId / reviewerId; each notifies them. Append agent research to a description under the exact heading "## Research (auto)", never editing the human text above it. When you open a PR, put the displayId in its title and it links itself; unlink_pr removes a PR that landed on the wrong item.`;
 
 // src/convex.ts
 import { ConvexHttpClient } from "convex/browser";
+import { ConvexError } from "convex/values";
 var cachedClient = null;
+function describeConvexError(err) {
+  if (err instanceof ConvexError) {
+    const data = err.data;
+    if (typeof data === "string" && data.trim()) return data;
+    if (typeof data === "object" && data !== null) {
+      const { code, message } = data;
+      if ((code === "user" || code === "forbidden") && typeof message === "string" && message.trim()) {
+        return message;
+      }
+      if (code === "unauthenticated") return "This token is not valid. Generate a new one in Nimara \u2192 Settings \u2192 Personal Access Tokens.";
+    }
+  }
+  const raw = err instanceof Error ? err.message : String(err);
+  const requestId = /\[Request ID: ([^\]]+)\]/.exec(raw)?.[1];
+  if (requestId || err instanceof ConvexError) {
+    return requestId ? `Nimara could not complete that call (request ${requestId}). Check the arguments and try again.` : "Nimara could not complete that call. Check the arguments and try again.";
+  }
+  return `Nimara could not reach its backend: ${raw || "unknown transport error"}. Nothing is wrong with the arguments; check the server's NIMARA_CONVEX_URL and try again.`;
+}
 function getConvexClient() {
-  if (cachedClient) return cachedClient;
+  if (cachedClient) return wrap(cachedClient);
   const url = process.env.NIMARA_CONVEX_URL;
   if (!url) {
     throw new Error(
@@ -88,9 +115,22 @@ function getConvexClient() {
     );
   }
   cachedClient = new ConvexHttpClient(url);
-  return cachedClient;
+  return wrap(cachedClient);
 }
-function getToken() {
+function wrap(client) {
+  return {
+    action: async (ref, args) => {
+      try {
+        return await client.action(ref, args);
+      } catch (err) {
+        throw new Error(describeConvexError(err));
+      }
+    }
+  };
+}
+function getToken(extra) {
+  const fromRequest = extra?.authInfo?.token;
+  if (fromRequest) return fromRequest;
   const token = process.env.NIMARA_TOKEN;
   if (!token) {
     throw new Error(
@@ -122,13 +162,14 @@ function registerListOrgs(server) {
       description: "List all organizations (and the personal workspace) the authenticated user belongs to. Use this first to discover org IDs needed by other tools.",
       inputSchema: {},
       annotations: {
+        title: "List organizations",
         readOnlyHint: true,
         openWorldHint: false
       }
     },
-    async () => {
+    async (_args, extra) => {
       const client = getConvexClient();
-      const orgs = await client.action(api.mcp.listOrgs, { token: getToken() });
+      const orgs = await client.action(api.mcp.listOrgs, { token: getToken(extra) });
       return {
         content: [{ type: "text", text: JSON.stringify(orgs, null, 2) }]
       };
@@ -145,14 +186,15 @@ function registerListProjects(server) {
       description: "List projects in a given organization. Call list_orgs first to find the orgId. Each project includes `statuses` \u2014 its workflow in board order. Read that before setting a status on any item: those names are the only accepted values, and anything else is rejected.",
       inputSchema: { orgId: z.string().describe("orgId from list_orgs") },
       annotations: {
+        title: "List projects",
         readOnlyHint: true,
         openWorldHint: false
       }
     },
-    async ({ orgId }) => {
+    async ({ orgId }, extra) => {
       const client = getConvexClient();
       const projects = await client.action(api.mcp.listProjects, {
-        token: getToken(),
+        token: getToken(extra),
         orgId
       });
       return {
@@ -195,6 +237,7 @@ function registerListWorkItems(server) {
         )
       },
       annotations: {
+        title: "List work items",
         readOnlyHint: true,
         openWorldHint: false
       }
@@ -208,9 +251,9 @@ function registerListWorkItems(server) {
       type,
       parentId,
       needsReview
-    }) => {
+    }, extra) => {
       const page = await getConvexClient().action(api.mcp.listWorkItems, {
-        token: getToken(),
+        token: getToken(extra),
         projectId,
         limit,
         cursor,
@@ -251,13 +294,14 @@ function registerGetWorkItems(server) {
         )
       },
       annotations: {
+        title: "Get work items by id",
         readOnlyHint: true,
         openWorldHint: false
       }
     },
-    async ({ displayIds, workItemIds, projectId }) => {
+    async ({ displayIds, workItemIds, projectId }, extra) => {
       const result = await getConvexClient().action(api.mcp.getWorkItems, {
-        token: getToken(),
+        token: getToken(extra),
         displayIds,
         workItemIds,
         projectId
@@ -287,11 +331,14 @@ function registerSearchWorkItems(server) {
         ),
         limit: z4.number().int().min(1).max(25).optional().describe("Maximum results (default and maximum 25).")
       },
-      annotations: { readOnlyHint: true }
+      annotations: {
+        title: "Search work items",
+        readOnlyHint: true
+      }
     },
-    async ({ projectId, q, limit }) => {
+    async ({ projectId, q, limit }, extra) => {
       const result = await getConvexClient().action(api.mcp.searchWorkItems, {
-        token: getToken(),
+        token: getToken(extra),
         projectId,
         q,
         limit
@@ -318,13 +365,14 @@ function registerListAiReviewQueue(server) {
         )
       },
       annotations: {
+        title: "List the AI review queue",
         readOnlyHint: true,
         openWorldHint: false
       }
     },
-    async ({ projectId, limit, cursor }) => {
+    async ({ projectId, limit, cursor }, extra) => {
       const page = await getConvexClient().action(api.mcp.listAiReviewQueue, {
-        token: getToken(),
+        token: getToken(extra),
         projectId,
         limit,
         cursor
@@ -347,13 +395,14 @@ function registerGetActiveBlock(server) {
         projectId: z6.string().describe("projectId from list_projects")
       },
       annotations: {
+        title: "Get the active block",
         readOnlyHint: true,
         openWorldHint: false
       }
     },
-    async ({ projectId }) => {
+    async ({ projectId }, extra) => {
       const block = await getConvexClient().action(api.mcp.getActiveBlock, {
-        token: getToken(),
+        token: getToken(extra),
         projectId
       });
       return {
@@ -400,16 +449,17 @@ function registerCreateWorkItem(server) {
         priority: z7.enum(["p0", "p1", "p2", "p3"]).optional().describe("p0 highest, p3 lowest. Defaults to p2.")
       },
       annotations: {
+        title: "Create a work item",
         readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: false,
         openWorldHint: false
       }
     },
-    async (args) => {
+    async (args, extra) => {
       const client = getConvexClient();
       const result = await client.action(api.mcp.createWorkItem, {
-        token: getToken(),
+        token: getToken(extra),
         ...args
       });
       return {
@@ -432,7 +482,9 @@ function registerCreateProject(server) {
         prefix: z8.string().min(1).max(8).describe(
           "Short uppercase prefix for work item IDs (e.g. 'NIM'). Unique per org."
         ),
-        description: z8.string().optional().describe("Optional markdown description"),
+        description: z8.string().max(280).optional().describe(
+          "Optional, and usually best left out. At most one or two plain sentences (280 characters) saying what the project is for \u2014 it shows behind an info button on the project page, so headings, stack notes, decisions and lineage do not belong here. Put that kind of context in a document (create_document) or the project's README instead."
+        ),
         isPrivate: z8.boolean().optional().describe(
           "If true, only explicitly added members see it. Defaults to false."
         ),
@@ -441,16 +493,17 @@ function registerCreateProject(server) {
         )
       },
       annotations: {
+        title: "Create a project",
         readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: false,
         openWorldHint: false
       }
     },
-    async (args) => {
+    async (args, extra) => {
       const client = getConvexClient();
       const result = await client.action(api.mcp.createProject, {
-        token: getToken(),
+        token: getToken(extra),
         ...args
       });
       return {
@@ -495,7 +548,7 @@ function registerUpdateWorkItem(server) {
   server.registerTool(
     "update_work_item",
     {
-      description: "Update an existing work item: title, description, status, priority, parent, or review flags. Any update also stamps the item as AI-touched.",
+      description: "Update an existing work item: title, description, status, priority, parent, assignee, reviewer, or review flags. Any update also stamps the item as AI-touched.",
       inputSchema: {
         workItemId: z9.string().describe("workItemId from list_work_items"),
         title: z9.string().min(1).optional().describe(TITLE_GUIDANCE),
@@ -505,6 +558,12 @@ function registerUpdateWorkItem(server) {
         status: z9.string().optional().describe(STATUS_GUIDANCE),
         priority: z9.enum(["p0", "p1", "p2", "p3"]).optional(),
         parentId: z9.string().nullable().optional().describe("New parent workItemId, null to move to root."),
+        assigneeId: z9.string().nullable().optional().describe(
+          "userId of the person to assign, from list_project_members; null to unassign. The person is notified. Must be someone on the project."
+        ),
+        reviewerId: z9.string().nullable().optional().describe(
+          "userId of the person to ask for review, from list_project_members; null to clear. The person is notified. Pair it with the Review status when you hand work over. Moving an item back up the workflow clears the reviewer unless the same call names one."
+        ),
         needsReview: z9.boolean().optional().describe(
           "Flag the item for manual human review \u2014 set true when your enrichment was thin or uncertain."
         ),
@@ -520,15 +579,16 @@ function registerUpdateWorkItem(server) {
         model: z9.string().optional().describe("With agentWorking: the model you are running as, e.g. claude-opus-5, so the app can say which agent is on this. Your harness is reported automatically.")
       },
       annotations: {
+        title: "Update a work item",
         readOnlyHint: false,
         destructiveHint: true,
         idempotentHint: true,
         openWorldHint: false
       }
     },
-    async ({ model, ...args }) => {
+    async ({ model, ...args }, extra) => {
       const result = await getConvexClient().action(api.mcp.updateWorkItem, {
-        token: getToken(),
+        token: getToken(extra),
         ...args,
         agent: agentArg(model)
       });
@@ -557,6 +617,7 @@ function registerMoveWorkItem(server) {
         )
       },
       annotations: {
+        title: "Move a work item to another project",
         readOnlyHint: false,
         // Renumbering display IDs and deleting label/milestone links are
         // overwrites, not additions — this belongs with the tools a client
@@ -568,10 +629,10 @@ function registerMoveWorkItem(server) {
         openWorldHint: false
       }
     },
-    async ({ workItemId, targetProjectId }) => {
+    async ({ workItemId, targetProjectId }, extra) => {
       const result = await getConvexClient().action(
         api.mcp.moveWorkItemToProject,
-        { token: getToken(), workItemId, targetProjectId }
+        { token: getToken(extra), workItemId, targetProjectId }
       );
       return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
@@ -586,26 +647,27 @@ function registerCreateDocument(server) {
   server.registerTool(
     "create_document",
     {
-      description: "Create a markdown project document. Use type 'prd' for project docs or 'fd' for feature/work-item documents.",
+      description: "Create a markdown document in a project: a spec, a design, a report, research. Pass workItemId to link it to the item it is about. Leave type alone unless the document is THE project brief.",
       inputSchema: {
         projectId: z11.string().describe("projectId from list_projects"),
         title: z11.string().min(1),
-        type: z11.enum(["prd", "fd"]).describe(
-          "Document type. 'fd' is stored as the app's feature document type."
+        type: z11.enum(["note", "prd", "fd"]).optional().describe(
+          "Defaults to 'note', which is right for almost everything. 'prd' is reserved for the project's own product requirements brief, one per project, never linked to a work item. 'fd' is an older spelling of 'note' and still accepted."
         ),
-        workItemId: z11.string().optional().describe("Required for fd documents; omitted for prd."),
+        workItemId: z11.string().optional().describe("The work item this document is about, so it shows on that item. Not allowed with type 'prd'."),
         content: z11.string().optional().describe("Optional initial markdown content.")
       },
       annotations: {
+        title: "Create a document",
         readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: false,
         openWorldHint: false
       }
     },
-    async (args) => {
+    async (args, extra) => {
       const result = await getConvexClient().action(api.mcp.createDocument, {
-        token: getToken(),
+        token: getToken(extra),
         ...args
       });
       return {
@@ -630,15 +692,16 @@ function registerUpdateDocument(server) {
         title: z12.string().min(1).optional().describe("New title (optional).")
       },
       annotations: {
+        title: "Update a document",
         readOnlyHint: false,
         destructiveHint: true,
         idempotentHint: true,
         openWorldHint: false
       }
     },
-    async (args) => {
+    async (args, extra) => {
       const result = await getConvexClient().action(api.mcp.updateDocument, {
-        token: getToken(),
+        token: getToken(extra),
         ...args
       });
       return {
@@ -660,13 +723,14 @@ function registerListDocuments(server) {
         workItemId: z13.string().optional().describe("Optional workItemId to list linked FD documents.")
       },
       annotations: {
+        title: "List documents",
         readOnlyHint: true,
         openWorldHint: false
       }
     },
-    async (args) => {
+    async (args, extra) => {
       const result = await getConvexClient().action(api.mcp.listDocuments, {
-        token: getToken(),
+        token: getToken(extra),
         ...args
       });
       return {
@@ -699,15 +763,16 @@ function registerCreateProjectLink(server) {
         category: projectLinkCategory.optional().describe("Defaults to other.")
       },
       annotations: {
+        title: "Add a project link",
         readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: false,
         openWorldHint: false
       }
     },
-    async (args) => {
+    async (args, extra) => {
       const result = await getConvexClient().action(api.mcp.createProjectLink, {
-        token: getToken(),
+        token: getToken(extra),
         ...args
       });
       return {
@@ -728,13 +793,14 @@ function registerListProjectLinks(server) {
         projectId: z15.string().describe("projectId from list_projects")
       },
       annotations: {
+        title: "List project links",
         readOnlyHint: true,
         openWorldHint: false
       }
     },
-    async ({ projectId }) => {
+    async ({ projectId }, extra) => {
       const result = await getConvexClient().action(api.mcp.listProjectLinks, {
-        token: getToken(),
+        token: getToken(extra),
         projectId
       });
       return {
@@ -744,24 +810,85 @@ function registerListProjectLinks(server) {
   );
 }
 
-// src/tools/list-scratch-notes.ts
+// src/tools/list-project-members.ts
 import { z as z16 } from "zod";
+function registerListProjectMembers(server) {
+  server.registerTool(
+    "list_project_members",
+    {
+      description: "Who can open a project: userId, name, email and role for everyone with access, the same list the app's assignee picker shows. Use it to turn a name into the userId that update_work_item's assigneeId and reviewerId take, and to build a mention \u2014 [@Name](user:<userId>) in a comment notifies that person.",
+      inputSchema: {
+        projectId: z16.string().describe("projectId from list_projects")
+      },
+      annotations: {
+        title: "List project members",
+        readOnlyHint: true,
+        openWorldHint: false
+      }
+    },
+    async ({ projectId }, extra) => {
+      const result = await getConvexClient().action(api.mcp.listProjectMembers, {
+        token: getToken(extra),
+        projectId
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    }
+  );
+}
+
+// src/tools/unlink-pr.ts
+import { z as z17 } from "zod";
+function registerUnlinkPr(server) {
+  server.registerTool(
+    "unlink_pr",
+    {
+      description: "Take a pull request off a work item. PRs link themselves when their title or body names a display id, so a sample id in a PR description attaches that PR to a real item; this undoes it. Returns what was removed and what is still linked, so a wrong number can be corrected without another read. Removing the link does not touch the PR itself.",
+      inputSchema: {
+        workItemId: z17.string().describe("workItemId of the item the PR is wrongly on"),
+        prNumber: z17.number().int().positive().describe("The PR number, e.g. 354 for #354")
+      },
+      annotations: {
+        title: "Unlink a pull request",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async ({ workItemId, prNumber }, extra) => {
+      const result = await getConvexClient().action(api.mcp.unlinkPR, {
+        token: getToken(extra),
+        workItemId,
+        prNumber
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    }
+  );
+}
+
+// src/tools/list-scratch-notes.ts
+import { z as z18 } from "zod";
 function registerListScratchNotes(server) {
   server.registerTool(
     "list_scratch_notes",
     {
       description: "The token owner's OPEN scratch notes: thoughts and ideas they captured in the app with the `s` shortcut before deciding what to do with them. Returns the notes that belong with this project (tagged with it, or tagged with nothing), oldest first, each with noteId, body, projectId and createdAt. These are raw: a note may be one line or a paragraph, may describe one task or three, and may not be a task at all. Read each, decide what it should become (usually one or more work items via create_work_item, sometimes a comment on an existing item, sometimes nothing), do that, then call resolve_scratch_note with the noteId and the workItemId it became so the person sees where their note went. Ask in a comment rather than guess when a note is too thin to act on. Call list_projects first for the projectId.",
       inputSchema: {
-        projectId: z16.string().describe("projectId from list_projects")
+        projectId: z18.string().describe("projectId from list_projects")
       },
       annotations: {
+        title: "List scratch notes",
         readOnlyHint: true,
         openWorldHint: false
       }
     },
-    async ({ projectId }) => {
+    async ({ projectId }, extra) => {
       const notes = await getConvexClient().action(api.mcp.listScratchNotes, {
-        token: getToken(),
+        token: getToken(extra),
         projectId
       });
       return {
@@ -772,26 +899,27 @@ function registerListScratchNotes(server) {
 }
 
 // src/tools/resolve-scratch-note.ts
-import { z as z17 } from "zod";
+import { z as z19 } from "zod";
 function registerResolveScratchNote(server) {
   server.registerTool(
     "resolve_scratch_note",
     {
       description: "Mark a scratch note as used, recording the work item it became. Call this after acting on a note from list_scratch_notes: pass the noteId and the workItemId you created or updated from it (omit workItemId only when the note needed no item). The note leaves the person's open list and shows where it went. Only the token owner's own notes.",
       inputSchema: {
-        noteId: z17.string().describe("noteId from list_scratch_notes"),
-        workItemId: z17.string().optional().describe("The workItemId the note became, from create_work_item or list_work_items.")
+        noteId: z19.string().describe("noteId from list_scratch_notes"),
+        workItemId: z19.string().optional().describe("The workItemId the note became, from create_work_item or list_work_items.")
       },
       annotations: {
+        title: "Resolve a scratch note",
         readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false
       }
     },
-    async ({ noteId, workItemId }) => {
+    async ({ noteId, workItemId }, extra) => {
       const result = await getConvexClient().action(api.mcp.resolveScratchNote, {
-        token: getToken(),
+        token: getToken(extra),
         noteId,
         workItemId
       });
@@ -803,26 +931,27 @@ function registerResolveScratchNote(server) {
 }
 
 // src/tools/heartbeat-work-item.ts
-import { z as z18 } from "zod";
+import { z as z20 } from "zod";
 function registerHeartbeatWorkItem(server) {
   server.registerTool(
     "heartbeat_work_item",
     {
       description: 'Say you are still working on an item. Renews (or starts) its 15-minute "agent working" lease and does nothing else: no comment, no activity event, no change to the item. The app lights the row while the lease is live, so on a long task call this every few minutes or every handful of tool calls \u2014 otherwise the row goes quiet while you are still at it. Reads of the item (get_work_items, list_work_item_comments) also renew a live lease, and any update or comment does; this is for the stretches where you do none of those. Cheap and idempotent.',
       inputSchema: {
-        workItemId: z18.string().describe("workItemId of the item you are working on"),
-        model: z18.string().optional().describe("The model you are running as, e.g. claude-opus-5 or gpt-5, so the app can say which agent is on this. Your harness is reported automatically.")
+        workItemId: z20.string().describe("workItemId of the item you are working on"),
+        model: z20.string().optional().describe("The model you are running as, e.g. claude-opus-5 or gpt-5, so the app can say which agent is on this. Your harness is reported automatically.")
       },
       annotations: {
+        title: "Keep an agent lease alive",
         readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false
       }
     },
-    async ({ workItemId, model }) => {
+    async ({ workItemId, model }, extra) => {
       const result = await getConvexClient().action(api.mcp.heartbeatWorkItem, {
-        token: getToken(),
+        token: getToken(extra),
         workItemId,
         agent: agentArg(model)
       });
@@ -834,26 +963,27 @@ function registerHeartbeatWorkItem(server) {
 }
 
 // src/tools/watch-work-item.ts
-import { z as z19 } from "zod";
+import { z as z21 } from "zod";
 function registerWatchWorkItem(server) {
   server.registerTool(
     "watch_work_item",
     {
       description: "Put the token owner on (or take them off) an item's watch list. A watcher is notified when the item changes status, gets a comment, gets a reviewer, is archived or moved \u2014 not on title or description edits. The item's assignee and reviewer already hear about it. Use this when you start work the person will want to follow, or when they ask to keep an eye on something.",
       inputSchema: {
-        workItemId: z19.string().describe("workItemId of the item"),
-        watching: z19.boolean().default(true).describe("true to watch, false to stop")
+        workItemId: z21.string().describe("workItemId of the item"),
+        watching: z21.boolean().default(true).describe("true to watch, false to stop")
       },
       annotations: {
+        title: "Watch a work item",
         readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false
       }
     },
-    async ({ workItemId, watching }) => {
+    async ({ workItemId, watching }, extra) => {
       const result = await getConvexClient().action(api.mcp.watchWorkItem, {
-        token: getToken(),
+        token: getToken(extra),
         workItemId,
         watching
       });
@@ -865,28 +995,29 @@ function registerWatchWorkItem(server) {
 }
 
 // src/tools/add-work-item-image.ts
-import { z as z20 } from "zod";
+import { z as z22 } from "zod";
 function registerAddWorkItemImage(server) {
   server.registerTool(
     "add_work_item_image",
     {
       description: "Attach an externally hosted image URL to a work item. Use this when an MCP client has a screenshot, mockup, or generated image URL to preserve with the task.",
       inputSchema: {
-        workItemId: z20.string().describe("workItemId from list_work_items"),
-        imageUrl: z20.string().url().describe("Public or otherwise fetchable http(s) image URL"),
-        filename: z20.string().optional().describe("Optional display filename"),
-        altText: z20.string().optional().describe("Optional description/caption for the image")
+        workItemId: z22.string().describe("workItemId from list_work_items"),
+        imageUrl: z22.string().url().describe("Public or otherwise fetchable http(s) image URL"),
+        filename: z22.string().optional().describe("Optional display filename"),
+        altText: z22.string().optional().describe("Optional description/caption for the image")
       },
       annotations: {
+        title: "Attach an image to a work item",
         readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: false,
         openWorldHint: false
       }
     },
-    async (args) => {
+    async (args, extra) => {
       const result = await getConvexClient().action(api.mcp.addWorkItemImage, {
-        token: getToken(),
+        token: getToken(extra),
         ...args
       });
       return {
@@ -897,25 +1028,26 @@ function registerAddWorkItemImage(server) {
 }
 
 // src/tools/list-work-item-images.ts
-import { z as z21 } from "zod";
+import { z as z23 } from "zod";
 function registerListWorkItemImages(server) {
   server.registerTool(
     "list_work_item_images",
     {
       description: "List image attachments for a work item, including uploaded images and externally attached MCP images. Call list_work_items first to find the workItemId.",
       inputSchema: {
-        workItemId: z21.string().describe("workItemId from list_work_items")
+        workItemId: z23.string().describe("workItemId from list_work_items")
       },
       annotations: {
+        title: "List work item images",
         readOnlyHint: true,
         openWorldHint: false
       }
     },
-    async ({ workItemId }) => {
+    async ({ workItemId }, extra) => {
       const result = await getConvexClient().action(
         api.mcp.listWorkItemImages,
         {
-          token: getToken(),
+          token: getToken(extra),
           workItemId
         }
       );
@@ -927,31 +1059,32 @@ function registerListWorkItemImages(server) {
 }
 
 // src/tools/add-work-item-comment.ts
-import { z as z22 } from "zod";
+import { z as z24 } from "zod";
 function registerAddWorkItemComment(server) {
   server.registerTool(
     "add_work_item_comment",
     {
       description: "Add a timestamped comment to a work item. Use this to record notes, updates, or an 'AI touched' entry instead of editing the description. Comments are stamped with the current time automatically and never overwrite each other.",
       inputSchema: {
-        workItemId: z22.string().describe("workItemId from list_work_items"),
-        body: z22.string().min(1).describe(
+        workItemId: z24.string().describe("workItemId from list_work_items"),
+        body: z24.string().min(1).describe(
           "Comment text (markdown supported). To pull a person into the thread, mention them as [@Name](user:<userId>) \u2014 they are notified and the app renders it as a chip. userIds come from an item's assigneeId/reviewerId; there is no member lookup tool yet, so only mention ids you have seen."
         ),
-        source: z22.enum(["user", "ai"]).optional().describe('Who authored it; defaults to "ai" for MCP callers')
+        source: z24.enum(["user", "ai"]).optional().describe('Who authored it; defaults to "ai" for MCP callers')
       },
       annotations: {
+        title: "Comment on a work item",
         readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: false,
         openWorldHint: false
       }
     },
-    async (args) => {
+    async (args, extra) => {
       const result = await getConvexClient().action(
         api.mcp.addWorkItemComment,
         {
-          token: getToken(),
+          token: getToken(extra),
           ...args,
           agent: agentArg()
         }
@@ -964,25 +1097,26 @@ function registerAddWorkItemComment(server) {
 }
 
 // src/tools/list-work-item-comments.ts
-import { z as z23 } from "zod";
+import { z as z25 } from "zod";
 function registerListWorkItemComments(server) {
   server.registerTool(
     "list_work_item_comments",
     {
       description: "List the timestamped comments on a work item, oldest first. Use this to check whether the item was already touched/commented before adding a new comment.",
       inputSchema: {
-        workItemId: z23.string().describe("workItemId from list_work_items")
+        workItemId: z25.string().describe("workItemId from list_work_items")
       },
       annotations: {
+        title: "List work item comments",
         readOnlyHint: true,
         openWorldHint: false
       }
     },
-    async (args) => {
+    async (args, extra) => {
       const result = await getConvexClient().action(
         api.mcp.listWorkItemComments,
         {
-          token: getToken(),
+          token: getToken(extra),
           ...args
         }
       );
@@ -994,24 +1128,25 @@ function registerListWorkItemComments(server) {
 }
 
 // src/tools/list-validations.ts
-import { z as z24 } from "zod";
+import { z as z26 } from "zod";
 function registerListValidations(server) {
   server.registerTool(
     "list_validations",
     {
       description: "List a project's validation graph: core systems and validation/test tasks with their DERIVED state (passing, failing, stale, unvalidated). A task is 'stale' when a system it covers changed since it was last validated, or an upstream dependency is no longer passing. Call list_projects first to find the projectId.",
       inputSchema: {
-        projectId: z24.string().describe("projectId from list_projects")
+        projectId: z26.string().describe("projectId from list_projects")
       },
       annotations: {
+        title: "List validations",
         readOnlyHint: true,
         openWorldHint: false
       }
     },
-    async ({ projectId }) => {
+    async ({ projectId }, extra) => {
       const client = getConvexClient();
       const graph = await client.action(api.mcp.listValidations, {
-        token: getToken(),
+        token: getToken(extra),
         projectId
       });
       return {
@@ -1022,27 +1157,28 @@ function registerListValidations(server) {
 }
 
 // src/tools/record-validation.ts
-import { z as z25 } from "zod";
+import { z as z27 } from "zod";
 function registerRecordValidation(server) {
   server.registerTool(
     "record_validation",
     {
       description: "Check off a validation task by recording a pass or fail. Stamps the task as validated 'now', clearing any stale flag until a covered system changes or an upstream dependency moves again. Get validationTaskId from list_validations.",
       inputSchema: {
-        validationTaskId: z25.string().describe("validationTaskId from list_validations"),
-        result: z25.enum(["pass", "fail"]).describe("Outcome of running the test")
+        validationTaskId: z27.string().describe("validationTaskId from list_validations"),
+        result: z27.enum(["pass", "fail"]).describe("Outcome of running the test")
       },
       annotations: {
+        title: "Record a validation result",
         readOnlyHint: false,
         destructiveHint: true,
         idempotentHint: true,
         openWorldHint: false
       }
     },
-    async ({ validationTaskId, result }) => {
+    async ({ validationTaskId, result }, extra) => {
       const client = getConvexClient();
       const res = await client.action(api.mcp.recordValidation, {
-        token: getToken(),
+        token: getToken(extra),
         validationTaskId,
         result
       });
@@ -1054,26 +1190,27 @@ function registerRecordValidation(server) {
 }
 
 // src/tools/mark-system-changed.ts
-import { z as z26 } from "zod";
+import { z as z28 } from "zod";
 function registerMarkSystemChanged(server) {
   server.registerTool(
     "mark_system_changed",
     {
       description: "Mark a core system as changed. This is the single action that invalidates testing: every validation task that covers this system (and everything transitively depending on those tasks) immediately becomes 'stale' and needs revalidation. Get systemId from list_validations.",
       inputSchema: {
-        systemId: z26.string().describe("systemId from list_validations")
+        systemId: z28.string().describe("systemId from list_validations")
       },
       annotations: {
+        title: "Mark a system as changed",
         readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: false,
         openWorldHint: false
       }
     },
-    async ({ systemId }) => {
+    async ({ systemId }, extra) => {
       const client = getConvexClient();
       const res = await client.action(api.mcp.markSystemChanged, {
-        token: getToken(),
+        token: getToken(extra),
         systemId
       });
       return {
@@ -1084,28 +1221,29 @@ function registerMarkSystemChanged(server) {
 }
 
 // src/tools/create-system.ts
-import { z as z27 } from "zod";
+import { z as z29 } from "zod";
 function registerCreateSystem(server) {
   server.registerTool(
     "create_system",
     {
       description: "Create a core system in a project \u2014 a subsystem (e.g. Auth, Payments, Sync) whose change should invalidate the validation tasks that cover it. Returns the new systemId.",
       inputSchema: {
-        projectId: z27.string().describe("projectId from list_projects"),
-        name: z27.string().min(1).describe("Short system name, e.g. 'Auth'"),
-        description: z27.string().optional().describe("Optional details")
+        projectId: z29.string().describe("projectId from list_projects"),
+        name: z29.string().min(1).describe("Short system name, e.g. 'Auth'"),
+        description: z29.string().optional().describe("Optional details")
       },
       annotations: {
+        title: "Create a system",
         readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: false,
         openWorldHint: false
       }
     },
-    async (args) => {
+    async (args, extra) => {
       const client = getConvexClient();
       const res = await client.action(api.mcp.createSystem, {
-        token: getToken(),
+        token: getToken(extra),
         ...args
       });
       return {
@@ -1116,34 +1254,35 @@ function registerCreateSystem(server) {
 }
 
 // src/tools/create-validation-task.ts
-import { z as z28 } from "zod";
+import { z as z30 } from "zod";
 function registerCreateValidationTask(server) {
   server.registerTool(
     "create_validation_task",
     {
       description: "Create a validation/test task in a project. After creating it, use add_system_to_task to declare which systems it exercises (so it goes stale when they change) and add_validation_dependency to order it after other tasks. Returns the new validationTaskId.",
       inputSchema: {
-        projectId: z28.string().describe("projectId from list_projects"),
-        title: z28.string().min(1).describe("What this test validates"),
-        description: z28.string().optional().describe("Optional steps / details"),
-        kind: z28.enum(["auto", "manual"]).optional().describe(
+        projectId: z30.string().describe("projectId from list_projects"),
+        title: z30.string().min(1).describe("What this test validates"),
+        description: z30.string().optional().describe("Optional steps / details"),
+        kind: z30.enum(["auto", "manual"]).optional().describe(
           "'auto' if runnable by a test runner, 'manual' if a human checks it. Defaults to manual."
         ),
-        workItemId: z28.string().optional().describe(
+        workItemId: z30.string().optional().describe(
           "Optional workItemId to link this test to a feature for traceability"
         )
       },
       annotations: {
+        title: "Create a validation task",
         readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: false,
         openWorldHint: false
       }
     },
-    async (args) => {
+    async (args, extra) => {
       const client = getConvexClient();
       const res = await client.action(api.mcp.createValidationTask, {
-        token: getToken(),
+        token: getToken(extra),
         ...args
       });
       return {
@@ -1154,27 +1293,28 @@ function registerCreateValidationTask(server) {
 }
 
 // src/tools/add-system-to-task.ts
-import { z as z29 } from "zod";
+import { z as z31 } from "zod";
 function registerAddSystemToTask(server) {
   server.registerTool(
     "add_system_to_task",
     {
       description: "Declare that a validation task COVERS (exercises) a system. Once linked, the task becomes 'stale' whenever that system is marked changed. Idempotent. Both IDs come from list_validations and must be in the same project.",
       inputSchema: {
-        validationTaskId: z29.string().describe("validationTaskId from list_validations"),
-        systemId: z29.string().describe("systemId from list_validations")
+        validationTaskId: z31.string().describe("validationTaskId from list_validations"),
+        systemId: z31.string().describe("systemId from list_validations")
       },
       annotations: {
+        title: "Link a system to a task",
         readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false
       }
     },
-    async ({ validationTaskId, systemId }) => {
+    async ({ validationTaskId, systemId }, extra) => {
       const client = getConvexClient();
       const res = await client.action(api.mcp.addSystemToTask, {
-        token: getToken(),
+        token: getToken(extra),
         validationTaskId,
         systemId
       });
@@ -1186,27 +1326,28 @@ function registerAddSystemToTask(server) {
 }
 
 // src/tools/add-validation-dependency.ts
-import { z as z30 } from "zod";
+import { z as z32 } from "zod";
 function registerAddValidationDependency(server) {
   server.registerTool(
     "add_validation_dependency",
     {
       description: "Make one validation task depend on another (validationTaskId depends on dependsOnTaskId). The dependent goes 'stale' whenever the upstream task is not passing or gets revalidated. Cycles and self-dependencies are rejected. Idempotent. Both IDs come from list_validations and must be in the same project.",
       inputSchema: {
-        validationTaskId: z30.string().describe("The dependent (downstream) task"),
-        dependsOnTaskId: z30.string().describe("The dependency (upstream) task it relies on")
+        validationTaskId: z32.string().describe("The dependent (downstream) task"),
+        dependsOnTaskId: z32.string().describe("The dependency (upstream) task it relies on")
       },
       annotations: {
+        title: "Add a validation dependency",
         readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false
       }
     },
-    async ({ validationTaskId, dependsOnTaskId }) => {
+    async ({ validationTaskId, dependsOnTaskId }, extra) => {
       const client = getConvexClient();
       const res = await client.action(api.mcp.addValidationDependency, {
-        token: getToken(),
+        token: getToken(extra),
         validationTaskId,
         dependsOnTaskId
       });
@@ -1218,23 +1359,24 @@ function registerAddValidationDependency(server) {
 }
 
 // src/tools/list-labels.ts
-import { z as z31 } from "zod";
+import { z as z33 } from "zod";
 function registerListLabels(server) {
   server.registerTool(
     "list_labels",
     {
       description: "List all labels defined in a project. Returns each label's id, name, and color. Use the labelId with add_label_to_work_item / remove_label_from_work_item.",
       inputSchema: {
-        projectId: z31.string().describe("projectId from list_projects")
+        projectId: z33.string().describe("projectId from list_projects")
       },
       annotations: {
+        title: "List labels",
         readOnlyHint: true,
         openWorldHint: false
       }
     },
-    async (args) => {
+    async (args, extra) => {
       const result = await getConvexClient().action(api.mcp.listLabels, {
-        token: getToken(),
+        token: getToken(extra),
         ...args
       });
       return {
@@ -1245,27 +1387,28 @@ function registerListLabels(server) {
 }
 
 // src/tools/create-label.ts
-import { z as z32 } from "zod";
+import { z as z34 } from "zod";
 function registerCreateLabel(server) {
   server.registerTool(
     "create_label",
     {
       description: "Apply-or-seed a label. Returns the existing label if the name is already taken (idempotent), and otherwise creates it ONLY if the name is one of the curated ones. Any other new name is REFUSED \u2014 the reply carries `refused: true`, the reason, and `available`, the project's existing labels. Agents apply labels; they do not invent them, because a near-duplicate of an existing label splits the vocabulary silently. Prefer list_labels first. Colors are ignored for curated names so the vocabulary looks the same in every project.",
       inputSchema: {
-        projectId: z32.string().describe("projectId from list_projects"),
-        name: z32.string().min(1).describe("Label name, unique within the project"),
-        color: z32.string().regex(/^#[0-9a-fA-F]{6}$/).optional().describe("Hex color like #2563eb. Defaults to a neutral slate.")
+        projectId: z34.string().describe("projectId from list_projects"),
+        name: z34.string().min(1).describe("Label name, unique within the project"),
+        color: z34.string().regex(/^#[0-9a-fA-F]{6}$/).optional().describe("Hex color like #2563eb. Defaults to a neutral slate.")
       },
       annotations: {
+        title: "Create a label",
         readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false
       }
     },
-    async (args) => {
+    async (args, extra) => {
       const result = await getConvexClient().action(api.mcp.createLabel, {
-        token: getToken(),
+        token: getToken(extra),
         ...args
       });
       return {
@@ -1276,26 +1419,27 @@ function registerCreateLabel(server) {
 }
 
 // src/tools/add-label-to-work-item.ts
-import { z as z33 } from "zod";
+import { z as z35 } from "zod";
 function registerAddLabelToWorkItem(server) {
   server.registerTool(
     "add_label_to_work_item",
     {
       description: "Attach a label to a work item (idempotent). The label and work item must be in the same project. Get labelIds from list_labels / create_label.",
       inputSchema: {
-        workItemId: z33.string().describe("workItemId from list_work_items"),
-        labelId: z33.string().describe("labelId from list_labels or create_label")
+        workItemId: z35.string().describe("workItemId from list_work_items"),
+        labelId: z35.string().describe("labelId from list_labels or create_label")
       },
       annotations: {
+        title: "Add a label to a work item",
         readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false
       }
     },
-    async (args) => {
+    async (args, extra) => {
       const result = await getConvexClient().action(api.mcp.setWorkItemLabel, {
-        token: getToken(),
+        token: getToken(extra),
         ...args,
         attached: true
       });
@@ -1307,26 +1451,27 @@ function registerAddLabelToWorkItem(server) {
 }
 
 // src/tools/remove-label-from-work-item.ts
-import { z as z34 } from "zod";
+import { z as z36 } from "zod";
 function registerRemoveLabelFromWorkItem(server) {
   server.registerTool(
     "remove_label_from_work_item",
     {
       description: "Remove a label from a work item (idempotent \u2014 a no-op if it wasn't attached).",
       inputSchema: {
-        workItemId: z34.string().describe("workItemId from list_work_items"),
-        labelId: z34.string().describe("labelId from list_labels")
+        workItemId: z36.string().describe("workItemId from list_work_items"),
+        labelId: z36.string().describe("labelId from list_labels")
       },
       annotations: {
+        title: "Remove a label from a work item",
         readOnlyHint: false,
         destructiveHint: true,
         idempotentHint: true,
         openWorldHint: false
       }
     },
-    async (args) => {
+    async (args, extra) => {
       const result = await getConvexClient().action(api.mcp.setWorkItemLabel, {
-        token: getToken(),
+        token: getToken(extra),
         ...args,
         attached: false
       });
@@ -1338,23 +1483,24 @@ function registerRemoveLabelFromWorkItem(server) {
 }
 
 // src/tools/list-milestones.ts
-import { z as z35 } from "zod";
+import { z as z37 } from "zod";
 function registerListMilestones(server) {
   server.registerTool(
     "list_milestones",
     {
       description: "List all milestones in a project. Returns each milestone's id, name, description, dueDate (unix ms), and status. Use the milestoneId with add_item_to_milestone / remove_item_from_milestone.",
       inputSchema: {
-        projectId: z35.string().describe("projectId from list_projects")
+        projectId: z37.string().describe("projectId from list_projects")
       },
       annotations: {
+        title: "List milestones",
         readOnlyHint: true,
         openWorldHint: false
       }
     },
-    async (args) => {
+    async (args, extra) => {
       const result = await getConvexClient().action(api.mcp.listMilestones, {
-        token: getToken(),
+        token: getToken(extra),
         ...args
       });
       return {
@@ -1365,28 +1511,29 @@ function registerListMilestones(server) {
 }
 
 // src/tools/create-milestone.ts
-import { z as z36 } from "zod";
+import { z as z38 } from "zod";
 function registerCreateMilestone(server) {
   server.registerTool(
     "create_milestone",
     {
       description: "Create a milestone in a project. Returns the milestoneId. Good for grouping work into phases (e.g. 'Phase 1 \u2014 Web', 'Phase 2 \u2014 Native').",
       inputSchema: {
-        projectId: z36.string().describe("projectId from list_projects"),
-        name: z36.string().min(1).describe("Milestone name"),
-        description: z36.string().optional().describe("Optional markdown description"),
-        dueDate: z36.number().optional().describe("Optional due date as a unix timestamp in milliseconds")
+        projectId: z38.string().describe("projectId from list_projects"),
+        name: z38.string().min(1).describe("Milestone name"),
+        description: z38.string().optional().describe("Optional markdown description"),
+        dueDate: z38.number().optional().describe("Optional due date as a unix timestamp in milliseconds")
       },
       annotations: {
+        title: "Create a milestone",
         readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: false,
         openWorldHint: false
       }
     },
-    async (args) => {
+    async (args, extra) => {
       const result = await getConvexClient().action(api.mcp.createMilestone, {
-        token: getToken(),
+        token: getToken(extra),
         ...args
       });
       return {
@@ -1397,28 +1544,29 @@ function registerCreateMilestone(server) {
 }
 
 // src/tools/add-item-to-milestone.ts
-import { z as z37 } from "zod";
+import { z as z39 } from "zod";
 function registerAddItemToMilestone(server) {
   server.registerTool(
     "add_item_to_milestone",
     {
       description: "Associate a work item with a milestone (idempotent). Both must be in the same project.",
       inputSchema: {
-        milestoneId: z37.string().describe("milestoneId from list_milestones or create_milestone"),
-        workItemId: z37.string().describe("workItemId from list_work_items")
+        milestoneId: z39.string().describe("milestoneId from list_milestones or create_milestone"),
+        workItemId: z39.string().describe("workItemId from list_work_items")
       },
       annotations: {
+        title: "Add an item to a milestone",
         readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false
       }
     },
-    async (args) => {
+    async (args, extra) => {
       const result = await getConvexClient().action(
         api.mcp.setWorkItemMilestone,
         {
-          token: getToken(),
+          token: getToken(extra),
           ...args,
           attached: true
         }
@@ -1431,28 +1579,29 @@ function registerAddItemToMilestone(server) {
 }
 
 // src/tools/remove-item-from-milestone.ts
-import { z as z38 } from "zod";
+import { z as z40 } from "zod";
 function registerRemoveItemFromMilestone(server) {
   server.registerTool(
     "remove_item_from_milestone",
     {
       description: "Remove a work item's association with a milestone (idempotent \u2014 a no-op if it wasn't associated).",
       inputSchema: {
-        milestoneId: z38.string().describe("milestoneId from list_milestones"),
-        workItemId: z38.string().describe("workItemId from list_work_items")
+        milestoneId: z40.string().describe("milestoneId from list_milestones"),
+        workItemId: z40.string().describe("workItemId from list_work_items")
       },
       annotations: {
+        title: "Remove an item from a milestone",
         readOnlyHint: false,
         destructiveHint: true,
         idempotentHint: true,
         openWorldHint: false
       }
     },
-    async (args) => {
+    async (args, extra) => {
       const result = await getConvexClient().action(
         api.mcp.setWorkItemMilestone,
         {
-          token: getToken(),
+          token: getToken(extra),
           ...args,
           attached: false
         }
@@ -1491,6 +1640,8 @@ function createServer() {
   registerListDocuments(server);
   registerCreateProjectLink(server);
   registerListProjectLinks(server);
+  registerListProjectMembers(server);
+  registerUnlinkPr(server);
   registerListScratchNotes(server);
   registerResolveScratchNote(server);
   registerHeartbeatWorkItem(server);