@nimara-app/mcp 0.7.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.7.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"
@@ -78,9 +85,29 @@ People are userIds from list_project_members: mention one in a comment as [@Name
 
 // 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 {
@@ -526,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)
       });
@@ -563,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
@@ -574,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) }]
@@ -592,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 {
@@ -636,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 {
@@ -666,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 {
@@ -705,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 {
@@ -734,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 {
@@ -761,13 +821,14 @@ function registerListProjectMembers(server) {
         projectId: z16.string().describe("projectId from list_projects")
       },
       annotations: {
+        title: "List project members",
         readOnlyHint: true,
         openWorldHint: false
       }
     },
-    async ({ projectId }) => {
+    async ({ projectId }, extra) => {
       const result = await getConvexClient().action(api.mcp.listProjectMembers, {
-        token: getToken(),
+        token: getToken(extra),
         projectId
       });
       return {
@@ -789,15 +850,16 @@ function registerUnlinkPr(server) {
         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 }) => {
+    async ({ workItemId, prNumber }, extra) => {
       const result = await getConvexClient().action(api.mcp.unlinkPR, {
-        token: getToken(),
+        token: getToken(extra),
         workItemId,
         prNumber
       });
@@ -819,13 +881,14 @@ function registerListScratchNotes(server) {
         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 {
@@ -847,15 +910,16 @@ function registerResolveScratchNote(server) {
         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
       });
@@ -878,15 +942,16 @@ function registerHeartbeatWorkItem(server) {
         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)
       });
@@ -909,15 +974,16 @@ function registerWatchWorkItem(server) {
         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
       });
@@ -942,15 +1008,16 @@ function registerAddWorkItemImage(server) {
         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 {
@@ -971,15 +1038,16 @@ function registerListWorkItemImages(server) {
         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
         }
       );
@@ -1005,17 +1073,18 @@ function registerAddWorkItemComment(server) {
         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()
         }
@@ -1038,15 +1107,16 @@ function registerListWorkItemComments(server) {
         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
         }
       );
@@ -1068,14 +1138,15 @@ function registerListValidations(server) {
         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 {
@@ -1097,16 +1168,17 @@ function registerRecordValidation(server) {
         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
       });
@@ -1128,16 +1200,17 @@ function registerMarkSystemChanged(server) {
         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 {
@@ -1160,16 +1233,17 @@ function registerCreateSystem(server) {
         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 {
@@ -1198,16 +1272,17 @@ function registerCreateValidationTask(server) {
         )
       },
       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 {
@@ -1229,16 +1304,17 @@ function registerAddSystemToTask(server) {
         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
       });
@@ -1261,16 +1337,17 @@ function registerAddValidationDependency(server) {
         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
       });
@@ -1292,13 +1369,14 @@ function registerListLabels(server) {
         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 {
@@ -1321,15 +1399,16 @@ function registerCreateLabel(server) {
         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 {
@@ -1351,15 +1430,16 @@ function registerAddLabelToWorkItem(server) {
         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
       });
@@ -1382,15 +1462,16 @@ function registerRemoveLabelFromWorkItem(server) {
         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
       });
@@ -1412,13 +1493,14 @@ function registerListMilestones(server) {
         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 {
@@ -1442,15 +1524,16 @@ function registerCreateMilestone(server) {
         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 {
@@ -1472,17 +1555,18 @@ function registerAddItemToMilestone(server) {
         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
         }
@@ -1506,17 +1590,18 @@ function registerRemoveItemFromMilestone(server) {
         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
         }