@opsee/mcp-server 0.9.47 → 0.9.49

package/README.md

@@ -41,15 +41,10 @@ Ask Claude things like:
 | `opsee_list_projects` | List all projects |
 | `opsee_get_project` | Get project details |
 | `opsee_list_tasks` | List tasks with filters |
-| `opsee_get_task` | Get task details |
-| `opsee_get_task_with_context` | Get task plus labels, comments, dependencies, parent, subtasks in one call |
+| `opsee_get_task` | Get task details; `includeContext: true` adds labels, comments, dependencies, parent, subtasks in the same call |
 | `opsee_create_task` | Create a new task (accepts inline labelIds[] to skip follow-up attach calls) |
 | `opsee_update_task` | Update task fields (accepts labelIds[] with replace-set semantics) |
-| `opsee_bulk_update_tasks` | Update many tasks in one transaction (storyPoints, estimatedHours, parentTaskId, labelIds all supported) |
-| `opsee_bulk_move_to_cycle` | Move many tasks to the same cycle in one call |
-| `opsee_bulk_move_to_column` | Move many tasks to the same status column in one call |
-| `opsee_bulk_assign` | Assign many tasks to the same user in one call |
-| `opsee_bulk_set_priority` | Set the same priority on many tasks in one call |
+| `opsee_bulk_update_tasks` | Update many tasks in one transaction — assignee, priority, column, cycle, storyPoints, estimatedHours, parentTaskId, labelIds |
 | `opsee_replace_task_labels` | Replace a single task's full set of labels |
 | `opsee_delete_task` | Delete a task by ID |
 | `opsee_bulk_delete_tasks` | Delete many tasks in one call |
@@ -93,11 +88,9 @@ Ask Claude things like:
 | `opsee_update_doc_template` | Update a doc template |
 | `opsee_delete_doc_template` | Delete a doc template |
 | `opsee_list_task_doc_pages` | List doc pages attached to a task |
-| `opsee_attach_doc_page_to_task` | Attach a doc page to a task |
-| `opsee_detach_doc_page_from_task` | Detach a doc page from a task |
 | `opsee_list_milestone_doc_pages` | List doc pages attached to a milestone |
-| `opsee_attach_doc_page_to_milestone` | Attach a doc page to a milestone |
-| `opsee_detach_doc_page_from_milestone` | Detach a doc page from a milestone |
+| `opsee_attach_doc_page` | Attach a doc page to a task or a milestone |
+| `opsee_detach_doc_page` | Detach a doc page from a task or a milestone |
 | `opsee_list_repositories` | List connected repositories |
 
 ## Task description format

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opsee/mcp-server",
-  "version": "0.9.47",
+  "version": "0.9.49",
   "description": "Opsee MCP server — manage projects, tasks, docs, and cycles from AI coding environments",
   "type": "module",
   "bin": {

package/src/server.ts

@@ -18,6 +18,7 @@ import { registerInitiativeTools } from "./tools/initiatives.js";
 import { registerDocSpaceWriteTools } from "./tools/doc-spaces.js";
 import { registerDocTemplateTools } from "./tools/doc-templates.js";
 import { registerDocLinkTools } from "./tools/doc-links.js";
+import { compactToolDefinitions } from "./utils/tool-schema.js";
 
 export function createServer(clientFactory?: () => ApiClients): McpServer {
   const factory = clientFactory ?? getClients;
@@ -46,5 +47,7 @@ export function createServer(clientFactory?: () => ApiClients): McpServer {
   registerDocTemplateTools(server, factory);
   registerDocLinkTools(server, factory);
 
+  compactToolDefinitions(server);
+
   return server;
 }

package/src/tools/doc-links.ts

@@ -13,6 +13,31 @@ function toDocPages<T extends { docPage?: DocPage }>(rows: T[]): DocPage[] {
   return rows.map((r) => r.docPage).filter((p): p is DocPage => !!p);
 }
 
+type LinkTarget =
+  | { kind: "task" | "milestone"; id: number }
+  | { error: { content: [{ type: "text"; text: string }]; isError: true } };
+
+// OPS-203: attach/detach used to be four tools (task and milestone variants of
+// each). They are now one pair with the target passed as a parameter, so the
+// exactly-one-of rule has to be enforced here rather than by the tool split.
+function resolveTarget(taskId?: number, milestoneId?: number): LinkTarget {
+  if ((taskId === undefined) === (milestoneId === undefined)) {
+    return {
+      error: {
+        content: [{ type: "text", text: "Pass exactly one of taskId or milestoneId." }],
+        isError: true,
+      },
+    };
+  }
+  return taskId !== undefined
+    ? { kind: "task", id: taskId }
+    : { kind: "milestone", id: milestoneId as number };
+}
+
+function attachedText(docPage?: DocPage): string {
+  return docPage ? `Doc page attached:\n${formatDocPage(docPage)}` : "Doc page attached.";
+}
+
 export function registerDocLinkTools(
   server: McpServer,
   getClients: () => ApiClients,
@@ -37,20 +62,26 @@ export function registerDocLinkTools(
   );
 
   server.tool(
-    "opsee_attach_doc_page_to_task",
-    "Attach an existing doc page to a task.",
+    "opsee_attach_doc_page",
+    "Attach an existing doc page to a task or a milestone. Pass exactly one of taskId / milestoneId.",
     {
-      taskId: z.number().int().min(1).describe("The task ID"),
       docPageId: z.number().int().min(1).describe("The doc page ID to attach"),
+      taskId: z.number().int().min(1).optional().describe("Attach to this task"),
+      milestoneId: z.number().int().min(1).optional().describe("Attach to this milestone"),
     },
     { readOnlyHint: false, destructiveHint: false },
-    async ({ taskId, docPageId }) => {
+    async ({ docPageId, taskId, milestoneId }) => {
+      const target = resolveTarget(taskId, milestoneId);
+      if ("error" in target) return target.error;
+
       try {
         const clients = getClients();
-        const res = await clients.taskDocPages.addTaskDocPage({ taskId, docPageId });
-        if (!res.taskDocPage?.docPage)
-          return { content: [{ type: "text", text: "Doc page attached." }] };
-        return { content: [{ type: "text", text: `Doc page attached:\n${formatDocPage(res.taskDocPage.docPage)}` }] };
+        if (target.kind === "task") {
+          const res = await clients.taskDocPages.addTaskDocPage({ taskId: target.id, docPageId });
+          return { content: [{ type: "text", text: attachedText(res.taskDocPage?.docPage) }] };
+        }
+        const res = await clients.milestoneDocPages.addMilestoneDocPage({ milestoneId: target.id, docPageId });
+        return { content: [{ type: "text", text: attachedText(res.milestoneDocPage?.docPage) }] };
       } catch (error) {
         return { content: [{ type: "text", text: formatError(error) }], isError: true };
       }
@@ -58,32 +89,45 @@ export function registerDocLinkTools(
   );
 
   server.tool(
-    "opsee_detach_doc_page_from_task",
-    "Detach a doc page from a task. The DeleteTaskDocPage RPC takes the join-row id, which callers never have — this tool resolves it by listing the task's doc pages and matching on docPageId.",
+    "opsee_detach_doc_page",
+    "Detach a doc page from a task or a milestone. Pass exactly one of taskId / milestoneId. The delete RPCs take the join-row id, which callers never have — this tool resolves it by listing the links and matching on docPageId.",
     {
-      taskId: z.number().int().min(1).describe("The task ID"),
       docPageId: z.number().int().min(1).describe("The doc page ID to detach"),
+      taskId: z.number().int().min(1).optional().describe("Detach from this task"),
+      milestoneId: z.number().int().min(1).optional().describe("Detach from this milestone"),
     },
     { readOnlyHint: false, destructiveHint: false },
-    async ({ taskId, docPageId }) => {
+    async ({ docPageId, taskId, milestoneId }) => {
+      const target = resolveTarget(taskId, milestoneId);
+      if ("error" in target) return target.error;
+
+      const notAttached = {
+        content: [{
+          type: "text" as const,
+          text: `Doc page ${docPageId} is not attached to ${target.kind} ${target.id}.`,
+        }],
+      };
+
       try {
         const clients = getClients();
-        const listRes = await clients.taskDocPages.getTaskDocPages({
-          taskId,
-          pagination: overridePagination(),
-        });
-        const row = listRes.taskDocPages.find((r) => r.docPageId === docPageId);
-        if (!row)
-          return { content: [{ type: "text", text: `Doc page ${docPageId} is not attached to task ${taskId}.` }] };
+        const rowId = target.kind === "task"
+          ? (await clients.taskDocPages.getTaskDocPages({ taskId: target.id, pagination: overridePagination() }))
+              .taskDocPages.find((r) => r.docPageId === docPageId)?.id
+          : (await clients.milestoneDocPages.getMilestoneDocPages({ milestoneId: target.id, pagination: overridePagination() }))
+              .milestoneDocPages.find((r) => r.docPageId === docPageId)?.id;
+        if (rowId === undefined) return notAttached;
 
         try {
-          await clients.taskDocPages.deleteTaskDocPage({ id: row.id });
+          if (target.kind === "task") {
+            await clients.taskDocPages.deleteTaskDocPage({ id: rowId });
+          } else {
+            await clients.milestoneDocPages.deleteMilestoneDocPage({ id: rowId });
+          }
         } catch (deleteError) {
           // A concurrent detach can remove the row between the list above and
           // this delete. The caller's intent (link gone) is already
           // satisfied, so report the same outcome instead of a raw NotFound.
-          if (deleteError instanceof ConnectError && deleteError.code === Code.NotFound)
-            return { content: [{ type: "text", text: `Doc page ${docPageId} is not attached to task ${taskId}.` }] };
+          if (deleteError instanceof ConnectError && deleteError.code === Code.NotFound) return notAttached;
           throw deleteError;
         }
         return { content: [{ type: "text", text: "Doc page detached." }] };
@@ -112,59 +156,4 @@ export function registerDocLinkTools(
     },
   );
 
-  server.tool(
-    "opsee_attach_doc_page_to_milestone",
-    "Attach an existing doc page to a milestone.",
-    {
-      milestoneId: z.number().int().min(1).describe("The milestone ID"),
-      docPageId: z.number().int().min(1).describe("The doc page ID to attach"),
-    },
-    { readOnlyHint: false, destructiveHint: false },
-    async ({ milestoneId, docPageId }) => {
-      try {
-        const clients = getClients();
-        const res = await clients.milestoneDocPages.addMilestoneDocPage({ milestoneId, docPageId });
-        if (!res.milestoneDocPage?.docPage)
-          return { content: [{ type: "text", text: "Doc page attached." }] };
-        return { content: [{ type: "text", text: `Doc page attached:\n${formatDocPage(res.milestoneDocPage.docPage)}` }] };
-      } catch (error) {
-        return { content: [{ type: "text", text: formatError(error) }], isError: true };
-      }
-    },
-  );
-
-  server.tool(
-    "opsee_detach_doc_page_from_milestone",
-    "Detach a doc page from a milestone. The DeleteMilestoneDocPage RPC takes the join-row id, which callers never have — this tool resolves it by listing the milestone's doc pages and matching on docPageId.",
-    {
-      milestoneId: z.number().int().min(1).describe("The milestone ID"),
-      docPageId: z.number().int().min(1).describe("The doc page ID to detach"),
-    },
-    { readOnlyHint: false, destructiveHint: false },
-    async ({ milestoneId, docPageId }) => {
-      try {
-        const clients = getClients();
-        const listRes = await clients.milestoneDocPages.getMilestoneDocPages({
-          milestoneId,
-          pagination: overridePagination(),
-        });
-        const row = listRes.milestoneDocPages.find((r) => r.docPageId === docPageId);
-        if (!row)
-          return { content: [{ type: "text", text: `Doc page ${docPageId} is not attached to milestone ${milestoneId}.` }] };
-
-        try {
-          await clients.milestoneDocPages.deleteMilestoneDocPage({ id: row.id });
-        } catch (deleteError) {
-          // Same TOCTOU as the task variant above: a concurrent detach can
-          // remove the row between the list and this delete.
-          if (deleteError instanceof ConnectError && deleteError.code === Code.NotFound)
-            return { content: [{ type: "text", text: `Doc page ${docPageId} is not attached to milestone ${milestoneId}.` }] };
-          throw deleteError;
-        }
-        return { content: [{ type: "text", text: "Doc page detached." }] };
-      } catch (error) {
-        return { content: [{ type: "text", text: formatError(error) }], isError: true };
-      }
-    },
-  );
 }

package/src/tools/docs.ts

@@ -162,7 +162,7 @@ export function registerDocTools(
 
   server.tool(
     "opsee_update_doc_page",
-    "Update a documentation page's title, content, or contentType. Performs a read-merge-write: any field you don't pass is preserved from the existing page (EditDocPageRequest has no field mask, so an incomplete request would blank the rest). No optimistic lock -- a concurrent edit from the web UI can be silently lost. Cannot clear content to an empty string: the backend's struct-based update silently skips empty-string fields, so that call is rejected up front instead of reporting a false success. Does not take a display-order argument -- ordering is owned by opsee_move_doc_page (MoveDocPage), a separate endpoint. By default, changing the title or content also snapshots the prior version into page history -- pass snapshotVersion: false to skip that.",
+    "Update a documentation page's title, content, or contentType. Read-merge-write: fields you don't pass are preserved. No optimistic lock -- a concurrent edit from the web UI can be silently lost. Content cannot be cleared to an empty string; that call is rejected up front rather than reporting a false success. Ordering is not settable here -- it belongs to opsee_move_doc_page. Changing title or content snapshots the prior version into page history unless snapshotVersion: false.",
     {
       pageId: z.number().int().min(1).describe("The doc page ID"),
       title: z.string().optional().describe("New title. When provided, the slug is regenerated from it."),
@@ -284,7 +284,7 @@ export function registerDocTools(
 
   server.tool(
     "opsee_delete_doc_page",
-    "Delete a documentation page. This is a soft delete with no cascade: child pages are neither deleted nor reparented, so they keep their parent_page_id pointing at the now-deleted page. They still exist and are returned by opsee_list_doc_pages / opsee_get_doc_page, but they disappear from the page tree since their parent no longer resolves there. There is no undo exposed through this API. Requires the Admin or Owner role -- the User role can add/edit/read doc pages but not delete them, and this call fails with a permission error for a User-role caller. To hide a page reversibly instead, use opsee_set_doc_page_archived.",
+    "Delete a documentation page. Soft delete with no cascade: child pages are neither deleted nor reparented, so they keep pointing at the deleted parent -- still listable, but gone from the page tree. No undo through this API. Requires Admin or Owner; a User-role caller gets a permission error. To hide a page reversibly instead, use opsee_set_doc_page_archived.",
     { pageId: z.number().int().min(1).describe("The doc page ID") },
     { readOnlyHint: false, destructiveHint: true },
     async ({ pageId }) => {

package/src/tools/initiatives.ts

@@ -214,7 +214,7 @@ export function registerInitiativeTools(
 
   server.tool(
     "opsee_decompose_initiative",
-    "Materialize a proposed breakdown as real Tasks under the Initiative. PROPOSE FIRST: present the proposed task tree (titles, structure, dependencies) to the human and get their approval BEFORE calling this — that approval is the \"confirm\" step. Nothing is created until you call it, so to let the human decline, simply don't call it. Calling it materializes the tasks onto the board in one atomic operation and moves a draft Initiative to active (the conclude→execute transition). Wire the tree with temporary `ref` ids: set `parentRef` to nest a subtask, and add `edges` (from_ref blocks to_ref) to express sequencing — tasks with no blocking edge between them become parallel slices. All-or-nothing: a bad ref rolls the whole thing back.",
+    "Materialize a proposed breakdown as real Tasks under the Initiative. PROPOSE FIRST: present the task tree (titles, structure, dependencies) to the human and get approval BEFORE calling — that approval is the confirm step, and not calling is how the human declines. One atomic operation; also moves a draft Initiative to active. Wire the tree with temporary `ref` ids: `parentRef` nests a subtask, `edges` (from_ref blocks to_ref) express sequencing, and tasks with no blocking edge run in parallel. All-or-nothing: a bad ref rolls the whole thing back.",
     {
       initiativeId: z.number().int().min(1).describe("The initiative ID"),
       tasks: z.array(z.object({
@@ -270,21 +270,16 @@ export function registerInitiativeTools(
   server.tool(
     "opsee_reconcile_initiative",
     [
-      "Reconcile a proposed task tree against the current Initiative — diff, flag, and optionally apply.",
+      "Diff a proposed task tree against an Initiative that already has tasks, and optionally apply it.",
+      "For first-time task creation on a fresh Initiative use opsee_decompose_initiative instead.",
       "",
-      "Use this when the Initiative already has tasks (from opsee_decompose_initiative) and the plan has changed.",
-      "For first-time task creation on a fresh Initiative, use opsee_decompose_initiative instead.",
-      "",
-      "Workflow (follow this every time):",
-      "1. Call opsee_get_initiative_context to load the current task tree. Note each task's ID.",
-      "2. Build your proposed task list. For tasks that already exist and should be kept, set existingTaskId",
-      "   to the task's real ID (from the context). Omit existingTaskId for brand-new tasks.",
-      "3. Call opsee_reconcile_initiative with dryRun:true to preview the changeset.",
-      "4. Present the changeset to the human — ESPECIALLY the flagged items. Flagged tasks carry real",
-      "   execution state (linked PRs, worklogs, in-progress status) and will NOT be deleted. They stay",
-      "   on the board unchanged; the human must decide what to do with them.",
-      "5. Get explicit human approval before applying.",
-      "6. Call opsee_reconcile_initiative with dryRun:false to apply the approved plan.",
+      "Workflow (follow every time):",
+      "1. opsee_get_initiative_context to load the current tree; note each task's ID.",
+      "2. Build the proposed list. Set existingTaskId to a real ID to keep that task; omit it for new tasks.",
+      "3. Call with dryRun:true to preview the changeset.",
+      "4. Present it to the human, ESPECIALLY flagged items: those carry execution state (PRs, worklogs,",
+      "   in-progress) and are never deleted — they stay on the board and the human decides their fate.",
+      "5. Only after explicit approval, call again with dryRun:false.",
     ].join("\n"),
     {
       initiativeId: z.number().int().min(1).describe("The initiative ID"),

package/src/tools/tasks-bulk.ts

@@ -4,16 +4,21 @@ import type { ApiClients } from "../client/api.js";
 import { formatError } from "../utils/format.js";
 import { BULK_PROJECT_ID } from "./descriptions.js";
 
-// Multi-task edits. All of these go through the backend BulkEditTasks RPC,
-// which applies every change in one transaction and silently skips task ids
-// the caller cannot see - hence the "n of m" wording in every response.
+// Multi-task edits. These go through the backend BulkEditTasks RPC, which
+// applies every change in one transaction and silently skips task ids the
+// caller cannot see - hence the "n of m" wording in the response.
+//
+// OPS-203: the per-field convenience wrappers (bulk_assign, bulk_set_priority,
+// bulk_move_to_column, bulk_move_to_cycle) were removed. Each was a strict
+// subset of opsee_bulk_update_tasks with a single field set, and four extra
+// tool definitions cost more context on every request than they saved.
 export function registerTaskBulkTools(
   server: McpServer,
   getClients: () => ApiClients,
 ): void {
   server.tool(
     "opsee_bulk_update_tasks",
-    "Atomicity: backend wraps all updates in one DB transaction. Per-task lookup failures (task not visible to your company, or unknown ID) are silently skipped — compare updated_count against taskIds.length to detect partial application. Omitted fields are not touched. labelIds with a non-empty list replaces each task's labels; empty/omitted leaves them alone.",
+    "Apply the same field changes to many tasks at once — reassign, reprioritize, move to a column or cycle, or any combination. Backend wraps all updates in one DB transaction. Per-task lookup failures (task not visible to your company, or unknown ID) are silently skipped — compare updated_count against taskIds.length to detect partial application. Omitted fields are not touched. labelIds with a non-empty list replaces each task's labels; empty/omitted leaves them alone.",
     {
       projectId: z.number().int().min(1).describe(BULK_PROJECT_ID),
       taskIds: z.array(z.number().int().min(1)).min(1).describe("Task IDs to update (at least one)"),
@@ -60,112 +65,4 @@ export function registerTaskBulkTools(
       }
     },
   );
-
-  server.tool(
-    "opsee_bulk_move_to_cycle",
-    "Convenience wrapper: move many tasks to the same cycle in one call. Equivalent to opsee_bulk_update_tasks with only cycleId set.",
-    {
-      projectId: z.number().int().min(1).describe(BULK_PROJECT_ID),
-      taskIds: z.array(z.number().int().min(1)).min(1).describe("Task IDs to move"),
-      cycleId: z.number().int().min(1).describe("Target cycle/sprint ID"),
-    },
-    { readOnlyHint: false, destructiveHint: false },
-    async ({ projectId, taskIds, cycleId }) => {
-      try {
-        const clients = getClients();
-        const res = await clients.tasks.bulkEditTasks({
-          projectId,
-          taskIds,
-          cycleId,
-          repositoryIds: [],
-          labelIds: [],
-        });
-        const text = `Moved ${res.updatedCount} of ${taskIds.length} task(s) to cycle ${cycleId}.`;
-        return { content: [{ type: "text", text }] };
-      } catch (error) {
-        return { content: [{ type: "text", text: formatError(error) }], isError: true };
-      }
-    },
-  );
-
-  server.tool(
-    "opsee_bulk_move_to_column",
-    "Convenience wrapper: move many tasks to the same board column (status) in one call.",
-    {
-      projectId: z.number().int().min(1).describe(BULK_PROJECT_ID),
-      taskIds: z.array(z.number().int().min(1)).min(1).describe("Task IDs to move"),
-      boardColumnId: z.number().int().min(1).describe("Target board column ID (status)"),
-    },
-    { readOnlyHint: false, destructiveHint: false },
-    async ({ projectId, taskIds, boardColumnId }) => {
-      try {
-        const clients = getClients();
-        const res = await clients.tasks.bulkEditTasks({
-          projectId,
-          taskIds,
-          boardColumnId,
-          repositoryIds: [],
-          labelIds: [],
-        });
-        const text = `Moved ${res.updatedCount} of ${taskIds.length} task(s) to column ${boardColumnId}.`;
-        return { content: [{ type: "text", text }] };
-      } catch (error) {
-        return { content: [{ type: "text", text: formatError(error) }], isError: true };
-      }
-    },
-  );
-
-  server.tool(
-    "opsee_bulk_assign",
-    "Convenience wrapper: assign many tasks to the same user in one call.",
-    {
-      projectId: z.number().int().min(1).describe(BULK_PROJECT_ID),
-      taskIds: z.array(z.number().int().min(1)).min(1).describe("Task IDs to reassign"),
-      assigneeId: z.number().int().min(1).describe("Target user ID"),
-    },
-    { readOnlyHint: false, destructiveHint: false },
-    async ({ projectId, taskIds, assigneeId }) => {
-      try {
-        const clients = getClients();
-        const res = await clients.tasks.bulkEditTasks({
-          projectId,
-          taskIds,
-          assignedUserId: assigneeId,
-          repositoryIds: [],
-          labelIds: [],
-        });
-        const text = `Assigned ${res.updatedCount} of ${taskIds.length} task(s) to user ${assigneeId}.`;
-        return { content: [{ type: "text", text }] };
-      } catch (error) {
-        return { content: [{ type: "text", text: formatError(error) }], isError: true };
-      }
-    },
-  );
-
-  server.tool(
-    "opsee_bulk_set_priority",
-    "Convenience wrapper: set the same priority on many tasks in one call.",
-    {
-      projectId: z.number().int().min(1).describe(BULK_PROJECT_ID),
-      taskIds: z.array(z.number().int().min(1)).min(1).describe("Task IDs to reprioritize"),
-      priorityId: z.number().int().min(1).describe("Target priority ID (from opsee_list_task_priorities)"),
-    },
-    { readOnlyHint: false, destructiveHint: false },
-    async ({ projectId, taskIds, priorityId }) => {
-      try {
-        const clients = getClients();
-        const res = await clients.tasks.bulkEditTasks({
-          projectId,
-          taskIds,
-          taskPriorityId: priorityId,
-          repositoryIds: [],
-          labelIds: [],
-        });
-        const text = `Set priority ${priorityId} on ${res.updatedCount} of ${taskIds.length} task(s).`;
-        return { content: [{ type: "text", text }] };
-      } catch (error) {
-        return { content: [{ type: "text", text: formatError(error) }], isError: true };
-      }
-    },
-  );
 }

package/src/tools/tasks-read-write.ts

@@ -114,27 +114,13 @@ export function registerTaskReadWriteTools(
 
   server.tool(
     "opsee_get_task",
-    "Get full details of a specific task by ID.",
-    { taskId: z.number().int().min(1).describe("The task ID") },
-    { readOnlyHint: true, destructiveHint: false },
-    async ({ taskId }) => {
-      try {
-        const clients = getClients();
-        const res = await clients.tasks.getTask({ id: taskId });
-        if (!res.task) return { content: [{ type: "text", text: "Task not found. Use opsee_list_tasks to see available tasks." }] };
-        return { content: [{ type: "text", text: formatTask(res.task, { full: true }) }] };
-      } catch (error) {
-        return { content: [{ type: "text", text: formatError(error) }], isError: true };
-      }
+    "Get full details of a specific task by ID. Pass includeContext=true when picking up a ticket to also get its labels, comments, dependencies (both directions), parent task, and subtasks in the same call — saves ~5 round-trips.",
+    {
+      taskId: z.number().int().min(1).describe("The task ID"),
+      includeContext: z.boolean().optional().describe("Also return labels, comments, dependencies, parent task, and subtasks (default false)"),
     },
-  );
-
-  server.tool(
-    "opsee_get_task_with_context",
-    "One-shot composer that returns a task plus all its related context: labels, comments, dependencies (both directions), parent task, and subtasks. Use this when picking up a ticket — saves ~5 round-trips compared to calling each tool separately.",
-    { taskId: z.number().int().min(1).describe("The task ID") },
     { readOnlyHint: true, destructiveHint: false },
-    async ({ taskId }) => {
+    async ({ taskId, includeContext }) => {
       try {
         const clients = getClients();
 
@@ -144,6 +130,10 @@ export function registerTaskReadWriteTools(
           return { content: [{ type: "text", text: "Task not found. Use opsee_list_tasks to see available tasks." }] };
         }
 
+        if (!includeContext) {
+          return { content: [{ type: "text", text: formatTask(task, { full: true }) }] };
+        }
+
         const [labelsRes, depsRes, commentsRes, subtasksRes, parentRes] = await Promise.all([
           clients.taskLabels.getTaskLabels({
             taskId,

package/src/utils/tool-schema.ts

@@ -0,0 +1,90 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+
+// Every tool definition is re-sent on every AI request, so the tools/list
+// payload is a permanent tax on the context window. Three constructs the SDK
+// emits carry no information for a caller:
+//
+//   "$schema": "http://json-schema.org/draft-07/schema#"   (once per tool)
+//   "maximum": 9007199254740991                            (per unbounded int)
+//   "minimum": -9007199254740991                           (per unbounded int)
+//   "execution": {"taskSupport": "forbidden"}              (once per tool)
+//
+// The bounds are Number.MAX/MIN_SAFE_INTEGER, which `z.number().int()` records
+// on any int field that doesn't declare its own; no caller is going to pass an
+// id near 2^53, and the server-side Zod schema still rejects one if they do.
+// Stripping them leaves the advertised schema a valid, strictly weaker JSON
+// Schema — an explicit bound like `.min(1)` is left alone.
+//
+// `execution.taskSupport` is optional in the protocol and clients only act on
+// "required"/"optional" (see the SDK client's callTool path) — an absent field
+// and an explicit "forbidden" are the same thing to them.
+function stripSafeIntBounds(node: unknown): void {
+  if (Array.isArray(node)) {
+    for (const child of node) stripSafeIntBounds(child);
+    return;
+  }
+  if (typeof node !== "object" || node === null) return;
+
+  const obj = node as Record<string, unknown>;
+  if (obj.maximum === Number.MAX_SAFE_INTEGER) delete obj.maximum;
+  if (obj.minimum === Number.MIN_SAFE_INTEGER) delete obj.minimum;
+  for (const value of Object.values(obj)) stripSafeIntBounds(value);
+}
+
+function compactInputSchema(schema: unknown): unknown {
+  if (typeof schema !== "object" || schema === null) return schema;
+  const copy = structuredClone(schema) as Record<string, unknown>;
+  delete copy.$schema;
+  stripSafeIntBounds(copy);
+  return copy;
+}
+
+type ToolDefinition = {
+  inputSchema?: unknown;
+  execution?: { taskSupport?: string };
+};
+
+function compactTool(tool: ToolDefinition): void {
+  tool.inputSchema = compactInputSchema(tool.inputSchema);
+
+  const keys = Object.keys(tool.execution ?? {});
+  if (tool.execution?.taskSupport === "forbidden" && keys.length === 1) {
+    delete tool.execution;
+  }
+}
+
+/**
+ * Wrap the SDK's tools/list handler so every advertised tool definition is
+ * compacted on the way out. The SDK builds the JSON Schema internally (tools
+ * are registered as Zod shapes and converted inside its list handler), so
+ * post-processing the response is the only place this can happen.
+ *
+ * Degrades to a no-op if the SDK ever stops storing handlers where we look for
+ * them — the definitions go back to being verbose, nothing breaks. The test in
+ * tool-schema.test.ts asserts the compaction is live so that degradation is
+ * caught in CI rather than in production token bills.
+ */
+export function compactToolDefinitions(server: McpServer): void {
+  const handlers = (
+    server.server as unknown as {
+      _requestHandlers?: Map<
+        string,
+        (request: unknown, extra: unknown) => Promise<unknown>
+      >;
+    }
+  )._requestHandlers;
+  const original = handlers?.get("tools/list");
+  if (!original) return;
+
+  server.server.setRequestHandler(
+    ListToolsRequestSchema,
+    async (request, extra) => {
+      const result = (await original(request, extra)) as {
+        tools?: ToolDefinition[];
+      };
+      for (const tool of result.tools ?? []) compactTool(tool);
+      return result;
+    },
+  );
+}