@nimara-app/mcp 0.1.0 → 0.3.0

package/dist/index.js

@@ -63,7 +63,7 @@ function registerListProjects(server) {
   server.registerTool(
     "list_projects",
     {
-      description: "List projects in a given organization. Call list_orgs first to find the orgId.",
+      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: {
         readOnlyHint: true,
@@ -91,9 +91,22 @@ function registerListWorkItems(server) {
     {
       // The description is the only place a model learns paging exists, so it
       // states the shape of the response and what to do when hasMore is true.
-      description: "List non-archived work items in a project, newest-created last. Returns { items, nextCursor, hasMore }. Long descriptions are previewed \u2014 an item with descriptionTruncated: true has more text, readable via fullDescriptions. When hasMore is true, call again with cursor set to nextCursor to get the next page. Call list_projects first for the projectId.",
+      description: "List non-archived work items in a project, oldest-created first. Returns { items, nextCursor, hasMore }. Long descriptions are previewed \u2014 an item with descriptionTruncated: true has more text, readable via fullDescriptions. When hasMore is true, call again with cursor set to nextCursor to get the next page \u2014 the FIRST page is the OLDEST items, so recently created ones are on the LAST page and you have not seen the project until hasMore is false. Narrow with status/type/parentId/needsReview rather than paging and filtering yourself. If you already know which items you want, use get_work_items instead \u2014 it takes displayIds like NIM-T75 and costs a fraction of a list. Call list_projects first for the projectId.",
       inputSchema: {
         projectId: z2.string().describe("projectId from list_projects"),
+        status: z2.union([z2.string(), z2.array(z2.string())]).optional().describe(
+          "Only items in these statuses. Names come from the project's statusOrder (e.g. 'In Progress'). One name or a list."
+        ),
+        type: z2.union([
+          z2.enum(["epic", "feature", "task", "subtask"]),
+          z2.array(z2.enum(["epic", "feature", "task", "subtask"]))
+        ]).optional().describe("Only items of these types. One type or a list."),
+        parentId: z2.string().optional().describe(
+          "Only direct children of this workItemId. One level, not the whole subtree."
+        ),
+        needsReview: z2.boolean().optional().describe(
+          "true returns only items flagged needsReview; false only unflagged ones. Omit for both."
+        ),
         limit: z2.number().int().min(1).max(200).optional().describe("Items per page (default 50, max 200)."),
         cursor: z2.number().optional().describe(
           "nextCursor from the previous page. Omit for the first page."
@@ -107,13 +120,28 @@ function registerListWorkItems(server) {
         openWorldHint: false
       }
     },
-    async ({ projectId, limit, cursor, fullDescriptions }) => {
+    async ({
+      projectId,
+      limit,
+      cursor,
+      fullDescriptions,
+      status,
+      type,
+      parentId,
+      needsReview
+    }) => {
       const page = await getConvexClient().action(api.mcp.listWorkItems, {
         token: getToken(),
         projectId,
         limit,
         cursor,
-        fullDescriptions
+        fullDescriptions,
+        // Accepting a bare string as well as a list is what keeps a model from
+        // failing validation on the overwhelmingly common single-value case.
+        status: status === void 0 ? void 0 : Array.isArray(status) ? status : [status],
+        type: type === void 0 ? void 0 : Array.isArray(type) ? type : [type],
+        parentId,
+        needsReview
       });
       return {
         content: [{ type: "text", text: JSON.stringify(page, null, 2) }]
@@ -122,17 +150,91 @@ function registerListWorkItems(server) {
   );
 }
 
-// src/tools/list-ai-review-queue.ts
+// src/tools/get-work-items.ts
 import { z as z3 } from "zod";
+function registerGetWorkItems(server) {
+  server.registerTool(
+    "get_work_items",
+    {
+      // Written to be chosen *over* list_work_items whenever the caller already
+      // knows which items it wants — that is the whole point of the tool, and
+      // the description is the only place a model learns it.
+      description: "Read specific work items by id \u2014 the cheap way to re-read items you already know about. Prefer this over list_work_items whenever you have a displayId (e.g. NIM-T75) or a workItemId: listing a project returns every item and its description, which is orders of magnitude more data. Accepts up to 50 ids per call and always returns descriptions in full. Returns { items, notFound }; ids in notFound either do not exist or are not readable by this token. displayIds require projectId (they are unique per project, not globally); workItemIds do not.",
+      inputSchema: {
+        displayIds: z3.array(z3.string()).optional().describe(
+          "Human-facing ids like ['NIM-T75', 'NIM-F27']. Case-insensitive. Requires projectId."
+        ),
+        workItemIds: z3.array(z3.string()).optional().describe(
+          "Raw workItemIds, as returned by create_work_item or list_work_items."
+        ),
+        projectId: z3.string().optional().describe(
+          "projectId from list_projects. Required only when passing displayIds."
+        )
+      },
+      annotations: {
+        readOnlyHint: true,
+        openWorldHint: false
+      }
+    },
+    async ({ displayIds, workItemIds, projectId }) => {
+      const result = await getConvexClient().action(api.mcp.getWorkItems, {
+        token: getToken(),
+        displayIds,
+        workItemIds,
+        projectId
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    }
+  );
+}
+
+// src/tools/search-work-items.ts
+import { z as z4 } from "zod";
+function registerSearchWorkItems(server) {
+  server.registerTool(
+    "search_work_items",
+    {
+      // The point of this description is to stop a model reaching for
+      // list_work_items when it is looking for something by name. Listing a
+      // project to find one item is the expensive mistake this tool exists to
+      // prevent.
+      description: "Find work items in a project by title. Use this to answer 'does an item for X already exist?' \u2014 listing the whole project and filtering yourself is far more expensive and, because the first page is the OLDEST items, easy to get wrong. Matches TITLES only, not descriptions. Returns { items, query } with descriptions previewed; once you know which item you want, get_work_items returns it in full. Capped at 25 results \u2014 narrow the query rather than paging. Call list_projects first for the projectId.",
+      inputSchema: {
+        projectId: z4.string().describe("projectId from list_projects"),
+        q: z4.string().min(1).describe(
+          "Words to match against item titles, e.g. 'mobile modal' or 'shortcut'. Matching is full-text, so word order does not matter."
+        ),
+        limit: z4.number().int().min(1).max(25).optional().describe("Maximum results (default and maximum 25).")
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ projectId, q, limit }) => {
+      const result = await getConvexClient().action(api.mcp.searchWorkItems, {
+        token: getToken(),
+        projectId,
+        q,
+        limit
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    }
+  );
+}
+
+// src/tools/list-ai-review-queue.ts
+import { z as z5 } from "zod";
 function registerListAiReviewQueue(server) {
   server.registerTool(
     "list_ai_review_queue",
     {
-      description: "List work items in a project that a human has flagged for AI review (aiReviewRequested). Descriptions come back in full here, since enrichment needs the whole text. Returns { items, nextCursor, hasMore } \u2014 when hasMore is true, call again with cursor set to nextCursor. Process each item, then clear its flag by calling update_work_item with aiReviewRequested: false. Call list_projects first to find the projectId.",
+      description: "List work items in a project that a human has flagged for AI review (aiReviewRequested). Descriptions come back in full here, since enrichment needs the whole text. Each item also carries recentComments (the last few, oldest first) and, when a person has written one, `answer`: the newest human comment. READ `answer` FIRST. When you flagged an item with a question and it is back in this queue, `answer` is the person's reply to that question; act on it rather than asking again. Returns { items, nextCursor, hasMore } \u2014 when hasMore is true, call again with cursor set to nextCursor. Process each item, then clear its flag by calling update_work_item with aiReviewRequested: false. Call list_projects first to find the projectId.",
       inputSchema: {
-        projectId: z3.string().describe("projectId from list_projects"),
-        limit: z3.number().int().min(1).max(200).optional().describe("Items per page (default 50, max 200)."),
-        cursor: z3.number().optional().describe(
+        projectId: z5.string().describe("projectId from list_projects"),
+        limit: z5.number().int().min(1).max(200).optional().describe("Items per page (default 50, max 200)."),
+        cursor: z5.number().optional().describe(
           "nextCursor from the previous page. Omit for the first page."
         )
       },
@@ -155,25 +257,68 @@ function registerListAiReviewQueue(server) {
   );
 }
 
+// src/tools/get-active-block.ts
+import { z as z6 } from "zod";
+function registerGetActiveBlock(server) {
+  server.registerTool(
+    "get_active_block",
+    {
+      description: "The project's ACTIVE BLOCK: the small, ordered set of work a person has committed to right now. Call this BEFORE list_work_items when deciding what to work on \u2014 position 0 is the next thing to do, and the wider backlog is not on the table until the block is empty. Each item carries a lane: 'person' means a human owes it (flagged for review, or parked in a Review status) and you should not touch it; 'agent' means a human asked an agent to act on it, so it is yours first, and it carries recentComments and `answer` (the newest human comment: read it before anything else); 'open' is uncommitted-to-anyone work in priority order; 'done' is finished. Returns null when the project has no active block, in which case fall back to list_work_items. Descriptions are previewed; use get_work_items for the full text of an item you pick up. Call list_projects first for the projectId.",
+      inputSchema: {
+        projectId: z6.string().describe("projectId from list_projects")
+      },
+      annotations: {
+        readOnlyHint: true,
+        openWorldHint: false
+      }
+    },
+    async ({ projectId }) => {
+      const block = await getConvexClient().action(api.mcp.getActiveBlock, {
+        token: getToken(),
+        projectId
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(block, null, 2) }]
+      };
+    }
+  );
+}
+
+// src/tools/create-work-item.ts
+import { z as z7 } from "zod";
+
+// src/tools/titleGuidance.ts
+var TITLE_GUIDANCE = 'A title a teammate can understand at a glance, without opening the item or knowing the codebase. Say what is wrong or what changes FOR A PERSON, in plain words \u2014 not the mechanism, the file, or the symbol. Good: "Sorted list shows an expand arrow that does nothing". Bad: "Fix hasChildren computation in list.tsx". Good: "Long titles wrap to three lines and are hard to read". Bad: "Adjust COLUMNS.title min-width constant". Prefer ordinary words over internal abbreviations, and only name a file, function or identifier when it genuinely is the clearest way to say it (a tool or endpoint the user calls by name, for instance). No ticket prefixes or status markers \u2014 the board renders those already. Root cause, file paths, and reproduction steps belong in the description, which has room for them. Keep it to one plain clause. Do NOT use an em dash, and do not use the "Area: thing, other thing" shape \u2014 both are ways of stapling a second title on and they are what makes these hard to read. Bad: "Gantt: tighten row density, match app typography, stop the chart falling short of its container". Good: "Gantt chart looks nothing like the rest of the app". If the title needs a comma-spliced list to be accurate, that is a sign the item is really several items, not a sign it needs a longer title.';
+
+// src/tools/statusGuidance.ts
+var STATUS_GUIDANCE = 'Must be one of the names in the project\'s `statuses`, returned by list_projects. Read it rather than guessing \u2014 a status is the board column, so a name the workflow does not have is rejected, and before that check existed such items rendered in the first column while claiming otherwise. Match the existing name exactly, including its wording: if the workflow says "Review", do not write "In Review". Do NOT invent a status to capture something about an item. Statuses are shared across the whole project and aggregated on the dashboard, so each new one is a permanent extra band there. Anything that describes an item rather than locating it in the flow belongs in a LABEL \u2014 see create_label and add_label_to_work_item. Defaults to the first status when omitted.';
+
+// ../convex/convex/lib/descriptionLimits.ts
+var DESCRIPTION_MAX_CHARS = 32e3;
+var DESCRIPTION_TOO_LONG = `A description can be at most ${DESCRIPTION_MAX_CHARS.toLocaleString("en-US")} characters. Put specs, research and long reports in a document and link it to the item.`;
+
+// src/tools/descriptionGuidance.ts
+var DESCRIPTION_MAX = DESCRIPTION_MAX_CHARS;
+var DESCRIPTION_GUIDANCE = `Markdown. The what and the why: the problem, acceptance criteria, reproduction steps, file paths, root cause. Keep it to what someone picking the item up needs. A spec, a design, research, or a long report goes in a document (create_document) linked from here, not inline. At most ${DESCRIPTION_MAX_CHARS.toLocaleString("en-US")} characters.`;
+
 // src/tools/create-work-item.ts
-import { z as z4 } from "zod";
 function registerCreateWorkItem(server) {
   server.registerTool(
     "create_work_item",
     {
       description: "Create a new work item in a project. Hierarchy rules: epics live at the root; features go under epics; tasks go under epics or features (or root); subtasks must go under a task. Returns the new workItemId and its display ID (e.g. NIM-42).",
       inputSchema: {
-        projectId: z4.string().describe("projectId from list_projects"),
-        type: z4.enum(["epic", "feature", "task", "subtask"]).describe("Item type \u2014 drives hierarchy validation"),
-        title: z4.string().min(1).describe("Short, descriptive title"),
-        description: z4.string().optional().describe("Optional markdown body"),
-        parentId: z4.string().optional().describe(
+        projectId: z7.string().describe("projectId from list_projects"),
+        type: z7.enum(["epic", "feature", "task", "subtask"]).describe("Item type \u2014 drives hierarchy validation"),
+        title: z7.string().min(1).describe(TITLE_GUIDANCE),
+        description: z7.string().max(DESCRIPTION_MAX).optional().describe(DESCRIPTION_GUIDANCE),
+        parentId: z7.string().optional().describe(
           "workItemId of the parent. Required for subtask, optional otherwise."
         ),
-        status: z4.string().optional().describe(
-          "Status name from the project's statusOrder. Defaults to first status (e.g. 'Backlog')."
+        status: z7.string().optional().describe(
+          STATUS_GUIDANCE
         ),
-        priority: z4.enum(["p0", "p1", "p2", "p3"]).optional().describe("p0 highest, p3 lowest. Defaults to p2.")
+        priority: z7.enum(["p0", "p1", "p2", "p3"]).optional().describe("p0 highest, p3 lowest. Defaults to p2.")
       },
       annotations: {
         readOnlyHint: false,
@@ -196,23 +341,23 @@ function registerCreateWorkItem(server) {
 }
 
 // src/tools/create-project.ts
-import { z as z5 } from "zod";
+import { z as z8 } from "zod";
 function registerCreateProject(server) {
   server.registerTool(
     "create_project",
     {
       description: "Create a new project in an org. Prefix must be unique within the org and is uppercased (e.g. 'NIM' yields work items NIM-1, NIM-2\u2026). Caller becomes the project admin. Returns the new projectId.",
       inputSchema: {
-        orgId: z5.string().describe("orgId from list_orgs"),
-        name: z5.string().min(1).describe("Project name"),
-        prefix: z5.string().min(1).max(8).describe(
+        orgId: z8.string().describe("orgId from list_orgs"),
+        name: z8.string().min(1).describe("Project name"),
+        prefix: z8.string().min(1).max(8).describe(
           "Short uppercase prefix for work item IDs (e.g. 'NIM'). Unique per org."
         ),
-        description: z5.string().optional().describe("Optional markdown description"),
-        isPrivate: z5.boolean().optional().describe(
+        description: z8.string().optional().describe("Optional markdown description"),
+        isPrivate: z8.boolean().optional().describe(
           "If true, only explicitly added members see it. Defaults to false."
         ),
-        workflowTemplate: z5.enum(["default", "simple", "kanban", "bug"]).optional().describe(
+        workflowTemplate: z8.enum(["default", "simple", "kanban", "bug"]).optional().describe(
           "Status workflow. Defaults to 'default' (Backlog/Todo/In Progress/Review/Done)."
         )
       },
@@ -237,27 +382,61 @@ function registerCreateProject(server) {
 }
 
 // src/tools/update-work-item.ts
-import { z as z6 } from "zod";
+import { z as z9 } from "zod";
+
+// src/tools/researchFormat.ts
+var RESEARCH_FORMAT = `When appending automated research to a description, use EXACTLY this format, after the human-written text:
+
+---
+## Research (auto)
+
+### Findings
+- One bullet per verified fact, each naming what you checked.
+
+### Dependencies
+- Items this blocks or is blocked by, by displayId. Omit the section if none.
+
+### Duplicates
+- Existing items covering the same work, by displayId. Omit if none.
+
+### Suggested priority
+One line. Say "No change" when it is already right.
+
+Rules:
+- The "## Research (auto)" heading is EXACT and is what the app keys on to show this in its own tab. Do not reword it, renumber its level, or translate it.
+- NO EMOJI anywhere in the block, in headings or in bullets. Older items carry emoji headings; do not copy them.
+- Omit a section rather than writing "None found" in it. An empty section is noise the reader still has to read.
+- Never edit or delete the human-written text above the rule. Append only.
+- Markdown only. GFM tables are supported and are the right choice for comparisons. Raw HTML is NOT rendered by the app and must not be used.
+- For a workflow, sequence or state machine, use a \\\`\\\`\\\`mermaid fenced block. That is the supported way to draw one.
+- Say what you verified and how. "Confirmed X still returns Y (file:line)" is worth more than a conclusion with no trail.`;
+
+// src/tools/update-work-item.ts
 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.",
       inputSchema: {
-        workItemId: z6.string().describe("workItemId from list_work_items"),
-        title: z6.string().min(1).optional(),
-        description: z6.string().optional(),
-        status: z6.string().optional(),
-        priority: z6.enum(["p0", "p1", "p2", "p3"]).optional(),
-        parentId: z6.string().nullable().optional().describe("New parent workItemId, null to move to root."),
-        needsReview: z6.boolean().optional().describe(
+        workItemId: z9.string().describe("workItemId from list_work_items"),
+        title: z9.string().min(1).optional().describe(TITLE_GUIDANCE),
+        description: z9.string().max(DESCRIPTION_MAX).optional().describe(
+          "Full markdown body, replacing what is there. " + DESCRIPTION_GUIDANCE + " " + RESEARCH_FORMAT
+        ),
+        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."),
+        needsReview: z9.boolean().optional().describe(
           "Flag the item for manual human review \u2014 set true when your enrichment was thin or uncertain."
         ),
-        reviewReason: z6.string().optional().describe(
+        reviewReason: z9.string().optional().describe(
           "Short reason the item needs manual review (shown to the human)."
         ),
-        aiReviewRequested: z6.boolean().optional().describe(
+        aiReviewRequested: z9.boolean().optional().describe(
           "The human\u2192AI review flag. Set false to clear it after you have reviewed/enriched an item from list_ai_review_queue."
+        ),
+        agentWorking: z9.boolean().optional().describe(
+          "Set true when you start working on this item: the app lights its row so the person can see it is in flight. It is a 15-minute lease that every later MCP write on the item (updates, comments) renews, so you only need to set it once at the start; set false when you stop without finishing, and moving the item to the last status clears it for you."
         )
       },
       annotations: {
@@ -279,21 +458,62 @@ function registerUpdateWorkItem(server) {
   );
 }
 
+// src/tools/move-work-item.ts
+import { z as z10 } from "zod";
+function registerMoveWorkItem(server) {
+  server.registerTool(
+    "move_work_item",
+    {
+      // Everything a model needs to predict the damage has to be stated here —
+      // the description is the only channel it has. The consequences that are
+      // NOT obvious from the name are the ones worth the tokens: the display ID
+      // changes, and labels/milestones do not survive.
+      description: "Move a work item to a different project, taking its whole subtree with it \u2014 children and grandchildren move too, and the hierarchy is preserved. Both projects must be in the same organization, and you need write access to both. Not reversible by calling this again: the item is renumbered in the destination, so NIM-T44 might become SKA-T18 and the old ID stops resolving. Labels and milestone assignments are dropped, because both belong to the project being left; a status the destination doesn't define falls back to its first status. The response reports every old \u2192 new ID plus everything that was dropped or remapped. Comments, images, attached documents, PR links and history all follow the item. Call list_projects first for the target projectId.",
+      inputSchema: {
+        workItemId: z10.string().describe("workItemId from list_work_items \u2014 the item to move."),
+        targetProjectId: z10.string().describe(
+          "projectId from list_projects \u2014 the destination. Must be in the same org as the item's current project."
+        )
+      },
+      annotations: {
+        readOnlyHint: false,
+        // Renumbering display IDs and deleting label/milestone links are
+        // overwrites, not additions — this belongs with the tools a client
+        // should prompt on rather than auto-approve.
+        destructiveHint: true,
+        // Calling it twice does not land in the same place: the second call
+        // either errors as already-there or moves the item on again.
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    async ({ workItemId, targetProjectId }) => {
+      const result = await getConvexClient().action(
+        api.mcp.moveWorkItemToProject,
+        { token: getToken(), workItemId, targetProjectId }
+      );
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    }
+  );
+}
+
 // src/tools/create-document.ts
-import { z as z7 } from "zod";
+import { z as z11 } from "zod";
 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.",
       inputSchema: {
-        projectId: z7.string().describe("projectId from list_projects"),
-        title: z7.string().min(1),
-        type: z7.enum(["prd", "fd"]).describe(
+        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."
         ),
-        workItemId: z7.string().optional().describe("Required for fd documents; omitted for prd."),
-        content: z7.string().optional().describe("Optional initial markdown content.")
+        workItemId: z11.string().optional().describe("Required for fd documents; omitted for prd."),
+        content: z11.string().optional().describe("Optional initial markdown content.")
       },
       annotations: {
         readOnlyHint: false,
@@ -315,18 +535,18 @@ function registerCreateDocument(server) {
 }
 
 // src/tools/update-document.ts
-import { z as z8 } from "zod";
+import { z as z12 } from "zod";
 function registerUpdateDocument(server) {
   server.registerTool(
     "update_document",
     {
       description: "Update an existing document's markdown content and/or title. Use this to fill in or revise a document created earlier (e.g. backfill content into an empty doc). documentId comes from list_documents. Provided content fully replaces the existing content.",
       inputSchema: {
-        documentId: z8.string().describe("documentId from list_documents"),
-        content: z8.string().optional().describe(
+        documentId: z12.string().describe("documentId from list_documents"),
+        content: z12.string().optional().describe(
           "New markdown content. Replaces the document's existing content."
         ),
-        title: z8.string().min(1).optional().describe("New title (optional).")
+        title: z12.string().min(1).optional().describe("New title (optional).")
       },
       annotations: {
         readOnlyHint: false,
@@ -348,15 +568,15 @@ function registerUpdateDocument(server) {
 }
 
 // src/tools/list-documents.ts
-import { z as z9 } from "zod";
+import { z as z13 } from "zod";
 function registerListDocuments(server) {
   server.registerTool(
     "list_documents",
     {
       description: "List PRD/FD markdown documents for a project, optionally filtered to one work item.",
       inputSchema: {
-        projectId: z9.string().describe("projectId from list_projects"),
-        workItemId: z9.string().optional().describe("Optional workItemId to list linked FD documents.")
+        projectId: z13.string().describe("projectId from list_projects"),
+        workItemId: z13.string().optional().describe("Optional workItemId to list linked FD documents.")
       },
       annotations: {
         readOnlyHint: true,
@@ -376,8 +596,8 @@ function registerListDocuments(server) {
 }
 
 // src/tools/create-project-link.ts
-import { z as z10 } from "zod";
-var projectLinkCategory = z10.enum([
+import { z as z14 } from "zod";
+var projectLinkCategory = z14.enum([
   "api",
   "dashboard",
   "documentation",
@@ -391,10 +611,10 @@ function registerCreateProjectLink(server) {
     {
       description: "Save a link on a project for resources like APIs, dashboards, documentation, repositories, or services.",
       inputSchema: {
-        projectId: z10.string().describe("projectId from list_projects"),
-        title: z10.string().min(1).max(120),
-        url: z10.string().url().describe("http(s) URL to save"),
-        description: z10.string().max(500).optional(),
+        projectId: z14.string().describe("projectId from list_projects"),
+        title: z14.string().min(1).max(120),
+        url: z14.string().url().describe("http(s) URL to save"),
+        description: z14.string().max(500).optional(),
         category: projectLinkCategory.optional().describe("Defaults to other.")
       },
       annotations: {
@@ -417,14 +637,14 @@ function registerCreateProjectLink(server) {
 }
 
 // src/tools/list-project-links.ts
-import { z as z11 } from "zod";
+import { z as z15 } from "zod";
 function registerListProjectLinks(server) {
   server.registerTool(
     "list_project_links",
     {
       description: "List saved links for a project, such as APIs, dashboards, docs, repositories, and services.",
       inputSchema: {
-        projectId: z11.string().describe("projectId from list_projects")
+        projectId: z15.string().describe("projectId from list_projects")
       },
       annotations: {
         readOnlyHint: true,
@@ -443,18 +663,76 @@ function registerListProjectLinks(server) {
   );
 }
 
+// src/tools/list-scratch-notes.ts
+import { z as z16 } 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")
+      },
+      annotations: {
+        readOnlyHint: true,
+        openWorldHint: false
+      }
+    },
+    async ({ projectId }) => {
+      const notes = await getConvexClient().action(api.mcp.listScratchNotes, {
+        token: getToken(),
+        projectId
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(notes, null, 2) }]
+      };
+    }
+  );
+}
+
+// src/tools/resolve-scratch-note.ts
+import { z as z17 } 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.")
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async ({ noteId, workItemId }) => {
+      const result = await getConvexClient().action(api.mcp.resolveScratchNote, {
+        token: getToken(),
+        noteId,
+        workItemId
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    }
+  );
+}
+
 // src/tools/add-work-item-image.ts
-import { z as z12 } from "zod";
+import { z as z18 } 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: z12.string().describe("workItemId from list_work_items"),
-        imageUrl: z12.string().url().describe("Public or otherwise fetchable http(s) image URL"),
-        filename: z12.string().optional().describe("Optional display filename"),
-        altText: z12.string().optional().describe("Optional description/caption for the image")
+        workItemId: z18.string().describe("workItemId from list_work_items"),
+        imageUrl: z18.string().url().describe("Public or otherwise fetchable http(s) image URL"),
+        filename: z18.string().optional().describe("Optional display filename"),
+        altText: z18.string().optional().describe("Optional description/caption for the image")
       },
       annotations: {
         readOnlyHint: false,
@@ -476,14 +754,14 @@ function registerAddWorkItemImage(server) {
 }
 
 // src/tools/list-work-item-images.ts
-import { z as z13 } from "zod";
+import { z as z19 } 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: z13.string().describe("workItemId from list_work_items")
+        workItemId: z19.string().describe("workItemId from list_work_items")
       },
       annotations: {
         readOnlyHint: true,
@@ -506,16 +784,16 @@ function registerListWorkItemImages(server) {
 }
 
 // src/tools/add-work-item-comment.ts
-import { z as z14 } from "zod";
+import { z as z20 } 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: z14.string().describe("workItemId from list_work_items"),
-        body: z14.string().min(1).describe("Comment text (markdown supported)"),
-        source: z14.enum(["user", "ai"]).optional().describe('Who authored it; defaults to "ai" for MCP callers')
+        workItemId: z20.string().describe("workItemId from list_work_items"),
+        body: z20.string().min(1).describe("Comment text (markdown supported)"),
+        source: z20.enum(["user", "ai"]).optional().describe('Who authored it; defaults to "ai" for MCP callers')
       },
       annotations: {
         readOnlyHint: false,
@@ -540,14 +818,14 @@ function registerAddWorkItemComment(server) {
 }
 
 // src/tools/list-work-item-comments.ts
-import { z as z15 } from "zod";
+import { z as z21 } 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: z15.string().describe("workItemId from list_work_items")
+        workItemId: z21.string().describe("workItemId from list_work_items")
       },
       annotations: {
         readOnlyHint: true,
@@ -570,14 +848,14 @@ function registerListWorkItemComments(server) {
 }
 
 // src/tools/list-validations.ts
-import { z as z16 } from "zod";
+import { z as z22 } 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: z16.string().describe("projectId from list_projects")
+        projectId: z22.string().describe("projectId from list_projects")
       },
       annotations: {
         readOnlyHint: true,
@@ -598,15 +876,15 @@ function registerListValidations(server) {
 }
 
 // src/tools/record-validation.ts
-import { z as z17 } from "zod";
+import { z as z23 } 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: z17.string().describe("validationTaskId from list_validations"),
-        result: z17.enum(["pass", "fail"]).describe("Outcome of running the test")
+        validationTaskId: z23.string().describe("validationTaskId from list_validations"),
+        result: z23.enum(["pass", "fail"]).describe("Outcome of running the test")
       },
       annotations: {
         readOnlyHint: false,
@@ -630,14 +908,14 @@ function registerRecordValidation(server) {
 }
 
 // src/tools/mark-system-changed.ts
-import { z as z18 } from "zod";
+import { z as z24 } 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: z18.string().describe("systemId from list_validations")
+        systemId: z24.string().describe("systemId from list_validations")
       },
       annotations: {
         readOnlyHint: false,
@@ -660,16 +938,16 @@ function registerMarkSystemChanged(server) {
 }
 
 // src/tools/create-system.ts
-import { z as z19 } from "zod";
+import { z as z25 } 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: z19.string().describe("projectId from list_projects"),
-        name: z19.string().min(1).describe("Short system name, e.g. 'Auth'"),
-        description: z19.string().optional().describe("Optional details")
+        projectId: z25.string().describe("projectId from list_projects"),
+        name: z25.string().min(1).describe("Short system name, e.g. 'Auth'"),
+        description: z25.string().optional().describe("Optional details")
       },
       annotations: {
         readOnlyHint: false,
@@ -692,20 +970,20 @@ function registerCreateSystem(server) {
 }
 
 // src/tools/create-validation-task.ts
-import { z as z20 } from "zod";
+import { z as z26 } 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: z20.string().describe("projectId from list_projects"),
-        title: z20.string().min(1).describe("What this test validates"),
-        description: z20.string().optional().describe("Optional steps / details"),
-        kind: z20.enum(["auto", "manual"]).optional().describe(
+        projectId: z26.string().describe("projectId from list_projects"),
+        title: z26.string().min(1).describe("What this test validates"),
+        description: z26.string().optional().describe("Optional steps / details"),
+        kind: z26.enum(["auto", "manual"]).optional().describe(
           "'auto' if runnable by a test runner, 'manual' if a human checks it. Defaults to manual."
         ),
-        workItemId: z20.string().optional().describe(
+        workItemId: z26.string().optional().describe(
           "Optional workItemId to link this test to a feature for traceability"
         )
       },
@@ -730,15 +1008,15 @@ function registerCreateValidationTask(server) {
 }
 
 // src/tools/add-system-to-task.ts
-import { z as z21 } from "zod";
+import { z as z27 } 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: z21.string().describe("validationTaskId from list_validations"),
-        systemId: z21.string().describe("systemId from list_validations")
+        validationTaskId: z27.string().describe("validationTaskId from list_validations"),
+        systemId: z27.string().describe("systemId from list_validations")
       },
       annotations: {
         readOnlyHint: false,
@@ -762,15 +1040,15 @@ function registerAddSystemToTask(server) {
 }
 
 // src/tools/add-validation-dependency.ts
-import { z as z22 } from "zod";
+import { z as z28 } 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: z22.string().describe("The dependent (downstream) task"),
-        dependsOnTaskId: z22.string().describe("The dependency (upstream) task it relies on")
+        validationTaskId: z28.string().describe("The dependent (downstream) task"),
+        dependsOnTaskId: z28.string().describe("The dependency (upstream) task it relies on")
       },
       annotations: {
         readOnlyHint: false,
@@ -794,14 +1072,14 @@ function registerAddValidationDependency(server) {
 }
 
 // src/tools/list-labels.ts
-import { z as z23 } from "zod";
+import { z as z29 } 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: z23.string().describe("projectId from list_projects")
+        projectId: z29.string().describe("projectId from list_projects")
       },
       annotations: {
         readOnlyHint: true,
@@ -821,16 +1099,16 @@ function registerListLabels(server) {
 }
 
 // src/tools/create-label.ts
-import { z as z24 } from "zod";
+import { z as z30 } from "zod";
 function registerCreateLabel(server) {
   server.registerTool(
     "create_label",
     {
-      description: "Create a label in a project (or return the existing one if the name is already taken \u2014 idempotent). Returns the labelId. Colors are optional; a neutral default is used when omitted.",
+      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: z24.string().describe("projectId from list_projects"),
-        name: z24.string().min(1).describe("Label name, unique within the project"),
-        color: z24.string().regex(/^#[0-9a-fA-F]{6}$/).optional().describe("Hex color like #2563eb. Defaults to a neutral slate.")
+        projectId: z30.string().describe("projectId from list_projects"),
+        name: z30.string().min(1).describe("Label name, unique within the project"),
+        color: z30.string().regex(/^#[0-9a-fA-F]{6}$/).optional().describe("Hex color like #2563eb. Defaults to a neutral slate.")
       },
       annotations: {
         readOnlyHint: false,
@@ -852,15 +1130,15 @@ function registerCreateLabel(server) {
 }
 
 // src/tools/add-label-to-work-item.ts
-import { z as z25 } from "zod";
+import { z as z31 } 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: z25.string().describe("workItemId from list_work_items"),
-        labelId: z25.string().describe("labelId from list_labels or create_label")
+        workItemId: z31.string().describe("workItemId from list_work_items"),
+        labelId: z31.string().describe("labelId from list_labels or create_label")
       },
       annotations: {
         readOnlyHint: false,
@@ -883,15 +1161,15 @@ function registerAddLabelToWorkItem(server) {
 }
 
 // src/tools/remove-label-from-work-item.ts
-import { z as z26 } from "zod";
+import { z as z32 } 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: z26.string().describe("workItemId from list_work_items"),
-        labelId: z26.string().describe("labelId from list_labels")
+        workItemId: z32.string().describe("workItemId from list_work_items"),
+        labelId: z32.string().describe("labelId from list_labels")
       },
       annotations: {
         readOnlyHint: false,
@@ -914,14 +1192,14 @@ function registerRemoveLabelFromWorkItem(server) {
 }
 
 // src/tools/list-milestones.ts
-import { z as z27 } from "zod";
+import { z as z33 } 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: z27.string().describe("projectId from list_projects")
+        projectId: z33.string().describe("projectId from list_projects")
       },
       annotations: {
         readOnlyHint: true,
@@ -941,17 +1219,17 @@ function registerListMilestones(server) {
 }
 
 // src/tools/create-milestone.ts
-import { z as z28 } from "zod";
+import { z as z34 } 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: z28.string().describe("projectId from list_projects"),
-        name: z28.string().min(1).describe("Milestone name"),
-        description: z28.string().optional().describe("Optional markdown description"),
-        dueDate: z28.number().optional().describe("Optional due date as a unix timestamp in milliseconds")
+        projectId: z34.string().describe("projectId from list_projects"),
+        name: z34.string().min(1).describe("Milestone name"),
+        description: z34.string().optional().describe("Optional markdown description"),
+        dueDate: z34.number().optional().describe("Optional due date as a unix timestamp in milliseconds")
       },
       annotations: {
         readOnlyHint: false,
@@ -973,15 +1251,15 @@ function registerCreateMilestone(server) {
 }
 
 // src/tools/add-item-to-milestone.ts
-import { z as z29 } from "zod";
+import { z as z35 } 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: z29.string().describe("milestoneId from list_milestones or create_milestone"),
-        workItemId: z29.string().describe("workItemId from list_work_items")
+        milestoneId: z35.string().describe("milestoneId from list_milestones or create_milestone"),
+        workItemId: z35.string().describe("workItemId from list_work_items")
       },
       annotations: {
         readOnlyHint: false,
@@ -1007,15 +1285,15 @@ function registerAddItemToMilestone(server) {
 }
 
 // src/tools/remove-item-from-milestone.ts
-import { z as z30 } from "zod";
+import { z as z36 } 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: z30.string().describe("milestoneId from list_milestones"),
-        workItemId: z30.string().describe("workItemId from list_work_items")
+        milestoneId: z36.string().describe("milestoneId from list_milestones"),
+        workItemId: z36.string().describe("workItemId from list_work_items")
       },
       annotations: {
         readOnlyHint: false,
@@ -1049,15 +1327,21 @@ function createServer() {
   registerListOrgs(server);
   registerListProjects(server);
   registerListWorkItems(server);
+  registerGetWorkItems(server);
+  registerSearchWorkItems(server);
   registerListAiReviewQueue(server);
+  registerGetActiveBlock(server);
   registerCreateProject(server);
   registerCreateWorkItem(server);
   registerUpdateWorkItem(server);
+  registerMoveWorkItem(server);
   registerCreateDocument(server);
   registerUpdateDocument(server);
   registerListDocuments(server);
   registerCreateProjectLink(server);
   registerListProjectLinks(server);
+  registerListScratchNotes(server);
+  registerResolveScratchNote(server);
   registerAddWorkItemImage(server);
   registerListWorkItemImages(server);
   registerAddWorkItemComment(server);