@opsee/mcp-server 0.9.31 → 0.9.33

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

@@ -0,0 +1,372 @@
+import { z } from "zod";
+import { create } from "@bufbuild/protobuf";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClients } from "../client/api.js";
+import { defaultPagination } from "../client/api.js";
+import { authManager } from "../auth/manager.js";
+import {
+  formatTaskList,
+  formatTask,
+  formatTaskDependencyList,
+  formatCommentList,
+  formatTaskLabelList,
+  formatError,
+} from "../utils/format.js";
+import {
+  CREATE_TASK_DESCRIPTION,
+  STORY_POINTS_ESTIMATE,
+  UPDATE_TASK_DESCRIPTION,
+} from "./descriptions.js";
+import {
+  FilterOptionsSchema,
+  FilterSchema,
+} from "../../gen/api/v1/filter_pb.js";
+
+// Single-task reads and the create/update writes behind them.
+export function registerTaskReadWriteTools(
+  server: McpServer,
+  getClients: () => ApiClients,
+): void {
+  server.tool(
+    "opsee_list_tasks",
+    "List tasks in an Opsee project. Supports filtering by status, assignee, board column, cycle, labels, priority, type, milestone, parent, due date, and update/create recency. labelIds uses AND semantics; multi-id filters (priorityIds/taskTypeIds/milestoneIds) use OR semantics. Supports sorting via sortBy (created_at|updated_at|due_date|priority|title|id|display_order) and sortDir (asc|desc).",
+    {
+      projectId: z.number().int().min(1).describe("The project ID"),
+      columnId: z.number().int().min(1).optional().describe("Filter by board column ID (status)"),
+      assigneeId: z.number().int().min(1).optional().describe("Filter by assigned user ID"),
+      cycleId: z.number().int().min(1).optional().describe("Filter by cycle/sprint ID"),
+      labelIds: z.array(z.number().int().min(1)).optional().describe("Filter by label IDs (AND semantics — task must have all listed labels)"),
+      priorityIds: z.array(z.number().int().min(1)).optional().describe("Filter by one or more priority IDs (OR semantics)"),
+      taskTypeIds: z.array(z.number().int().min(1)).optional().describe("Filter by one or more task type IDs (OR semantics)"),
+      milestoneIds: z.array(z.number().int().min(1)).optional().describe("Filter by one or more milestone IDs (OR semantics)"),
+      parentTaskId: z.number().int().min(1).optional().describe("Filter to subtasks of this task ID"),
+      hasParent: z.boolean().optional().describe("true = only subtasks, false = only top-level tasks"),
+      unassigned: z.boolean().optional().describe("true = only unassigned tasks (triage queue)"),
+      updatedSince: z.string().optional().describe("Only tasks updated at or after this timestamp (RFC3339 or YYYY-MM-DD)"),
+      createdSince: z.string().optional().describe("Only tasks created at or after this timestamp (RFC3339 or YYYY-MM-DD)"),
+      dueBefore: z.string().optional().describe("Only tasks due at or before this date (RFC3339 or YYYY-MM-DD)"),
+      dueAfter: z.string().optional().describe("Only tasks due at or after this date (RFC3339 or YYYY-MM-DD)"),
+      sortBy: z.enum(["created_at", "updated_at", "due_date", "priority", "title", "id", "display_order"]).optional().describe("Sort column. NULLs sort last."),
+      sortDir: z.enum(["asc", "desc"]).optional().describe("Sort direction (default: desc)"),
+      page: z.number().int().min(1).optional().describe("Page number (default: 1)"),
+      pageSize: z.number().int().min(1).optional().describe("Items per page (default: 50)"),
+    },
+    { readOnlyHint: true, destructiveHint: false },
+    async ({
+      projectId, columnId, assigneeId, cycleId, labelIds,
+      priorityIds, taskTypeIds, milestoneIds, parentTaskId, hasParent,
+      unassigned, updatedSince, createdSince, dueBefore, dueAfter,
+      sortBy, sortDir, page, pageSize,
+    }) => {
+      try {
+        const clients = getClients();
+
+        const filters: Array<{ key: string; value: string }> = [];
+        if (columnId) filters.push({ key: "BoardColumnId", value: String(columnId) });
+        if (assigneeId) filters.push({ key: "AssignedUserId", value: String(assigneeId) });
+        if (cycleId) filters.push({ key: "CycleId", value: String(cycleId) });
+        if (priorityIds?.length) filters.push({ key: "TaskPriorityId", value: priorityIds.join(",") });
+        if (taskTypeIds?.length) filters.push({ key: "TaskTypeId", value: taskTypeIds.join(",") });
+        if (milestoneIds?.length) filters.push({ key: "MilestoneId", value: milestoneIds.join(",") });
+        if (parentTaskId) filters.push({ key: "ParentTaskId", value: String(parentTaskId) });
+        if (hasParent !== undefined) filters.push({ key: "HasParent", value: hasParent ? "true" : "false" });
+        if (unassigned) filters.push({ key: "Unassigned", value: "true" });
+        if (updatedSince) filters.push({ key: "UpdatedSince", value: updatedSince });
+        if (createdSince) filters.push({ key: "CreatedSince", value: createdSince });
+        if (dueBefore) filters.push({ key: "DueBefore", value: dueBefore });
+        if (dueAfter) filters.push({ key: "DueAfter", value: dueAfter });
+
+        const filterOptions = filters.length > 0
+          ? create(FilterOptionsSchema, {
+              filters: filters.map((f) => create(FilterSchema, f)),
+            })
+          : undefined;
+
+        const res = await clients.tasks.getTasks({
+          projectId,
+          pagination: defaultPagination(page || 1, pageSize || 50),
+          filterOptions,
+          labelIds: labelIds ?? [],
+          sortBy,
+          sortDir,
+        });
+
+        const pagination = res.pagination;
+        const currentPage = page || 1;
+        const hasMore = (pagination?.nextPage ?? 0) > 0;
+
+        return {
+          content: [{
+            type: "text",
+            text: formatTaskList(res.tasks, {
+              totalCount: pagination?.total,
+              page: currentPage,
+              hasMore,
+              nextPage: hasMore ? currentPage + 1 : undefined,
+            }),
+          }],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  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 };
+      }
+    },
+  );
+
+  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 }) => {
+      try {
+        const clients = getClients();
+
+        const taskRes = await clients.tasks.getTask({ id: taskId });
+        const task = taskRes.task;
+        if (!task) {
+          return { content: [{ type: "text", text: "Task not found. Use opsee_list_tasks to see available tasks." }] };
+        }
+
+        const [labelsRes, depsRes, commentsRes, subtasksRes, parentRes] = await Promise.all([
+          clients.taskLabels.getTaskLabels({
+            taskId,
+            pagination: defaultPagination(1, 50),
+          }),
+          clients.taskDependencies.getTaskDependencies({
+            taskId,
+            pagination: defaultPagination(1, 50),
+          }),
+          clients.comments.getComments({
+            taskId,
+            pagination: defaultPagination(1, 50),
+          }),
+          clients.tasks.getTasks({
+            projectId: task.project?.id ?? 0,
+            pagination: defaultPagination(1, 50),
+            filterOptions: create(FilterOptionsSchema, {
+              filters: [
+                create(FilterSchema, { key: "ParentTaskId", value: String(task.id) }),
+              ],
+            }),
+          }),
+          task.parentTaskId
+            ? clients.tasks.getTask({ id: task.parentTaskId })
+            : Promise.resolve(null),
+        ]);
+
+        const sections: string[] = [];
+        sections.push(formatTask(task, { full: true }));
+
+        const parentTask = parentRes?.task;
+        if (parentTask) {
+          sections.push(`\n--- Parent Task ---\n[${parentTask.identifier}] ${parentTask.title} (ID: ${parentTask.id})`);
+        }
+
+        sections.push(`\n--- Labels ---\n${formatTaskLabelList(labelsRes.taskLabels)}`);
+        sections.push(`\n--- Dependencies ---\n${formatTaskDependencyList(depsRes.taskDependencies)}`);
+        sections.push(`\n--- Subtasks ---\n${formatTaskList(subtasksRes.tasks)}`);
+        sections.push(`\n--- Comments ---\n${formatCommentList(commentsRes.comments)}`);
+
+        return { content: [{ type: "text", text: sections.join("\n") }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_create_task",
+    "Create a new task in an Opsee project. Use opsee_list_task_types, opsee_list_task_priorities, and opsee_list_board_columns first to get valid values for optional fields.",
+    {
+      projectId: z.number().int().min(1).describe("The project ID"),
+      title: z.string().describe("Task title"),
+      description: z.string().optional().describe(CREATE_TASK_DESCRIPTION),
+      taskTypeId: z.number().int().min(1).optional().describe("Task type ID (from opsee_list_task_types)"),
+      priorityId: z.number().int().min(1).optional().describe("Priority ID (from opsee_list_task_priorities)"),
+      boardColumnId: z.number().int().min(1).optional().describe("Board column ID (from opsee_list_board_columns)"),
+      assigneeId: z.number().int().min(1).optional().describe("Assigned user ID"),
+      cycleId: z.number().int().min(1).optional().describe("Cycle/sprint ID"),
+      milestoneId: z.number().int().min(1).optional().describe("Milestone ID — attaches this task to the milestone."),
+      parentTaskId: z.number().int().min(1).optional().describe("Parent task ID — makes this task a subtask of the given task."),
+      storyPoints: z.number().int().min(1).optional().describe(STORY_POINTS_ESTIMATE),
+      estimatedHours: z.number().min(0).optional().describe("Estimated effort in hours"),
+      labelIds: z.array(z.number().int().min(1)).optional().describe("Label IDs to attach to the new task. Saves a follow-up opsee_attach_label_to_task call per label."),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ projectId, title, description, taskTypeId, priorityId, boardColumnId, assigneeId, cycleId, milestoneId, parentTaskId, storyPoints, estimatedHours, labelIds }) => {
+      try {
+        const clients = getClients();
+
+        // Auto-resolve defaults
+        let resolvedBoardId = 0;
+        let resolvedColumnId = boardColumnId || 0;
+        let resolvedTaskTypeId = taskTypeId || 0;
+        let resolvedPriorityId = priorityId || 0;
+
+        // Get default board
+        const boardsRes = await clients.boards.getBoards({ projectId });
+        if (boardsRes.boards?.length) {
+          resolvedBoardId = boardsRes.boards[0].id;
+
+          // Get first column if not specified
+          if (!boardColumnId) {
+            const colsRes = await clients.boardColumns.getBoardColumns({
+              boardId: resolvedBoardId,
+            });
+            if (colsRes.boardColumns?.length) {
+              resolvedColumnId = colsRes.boardColumns[0].id;
+            }
+          }
+        }
+
+        // Get first task type if not specified
+        if (!taskTypeId) {
+          const typesRes = await clients.taskTypes.getTaskTypes({ projectId });
+          if (typesRes.taskTypes?.length) {
+            resolvedTaskTypeId = typesRes.taskTypes[0].id;
+          }
+        }
+
+        // Get first priority if not specified
+        if (!priorityId) {
+          const priRes = await clients.taskPriorities.getTaskPriorities({ projectId });
+          if (priRes.taskPriorities?.length) {
+            resolvedPriorityId = priRes.taskPriorities[0].id;
+          }
+        }
+
+        // Get reporter (current user)
+        let reporterUserId = 0;
+        const userId = authManager.getUserId();
+        if (userId) {
+          reporterUserId = Number(userId);
+        }
+        if (!reporterUserId) {
+          const meRes = await clients.users.getMe({});
+          if (meRes.user) reporterUserId = meRes.user.id;
+        }
+
+        const res = await clients.tasks.addTask({
+          projectId,
+          title,
+          description,
+          boardId: resolvedBoardId,
+          boardColumnId: resolvedColumnId,
+          taskTypeId: resolvedTaskTypeId,
+          taskPriorityId: resolvedPriorityId,
+          reporterUserId,
+          assignedUserId: assigneeId,
+          parentTaskId,
+          displayOrder: "",
+          aiModeEnabled: false,
+          cycleId,
+          milestoneId,
+          storyPoints,
+          estimatedHours,
+          repositoryIds: [],
+          labelIds: labelIds ?? [],
+        });
+
+        if (!res.task)
+          return { content: [{ type: "text", text: "Failed to create task. The backend returned an empty response (no error). Retry; if it persists, surface the call to the Opsee team." }], isError: true };
+
+        return {
+          content: [
+            { type: "text", text: `Task created:\n${formatTask(res.task, { full: true })}` },
+          ],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_update_task",
+    "Update a task's fields (patch semantics - only provided fields are changed). Fetches the current task first, merges your changes, and sends the full update.",
+    {
+      taskId: z.number().int().min(1).describe("The task ID to update"),
+      title: z.string().optional().describe("New title"),
+      description: z.string().optional().describe(UPDATE_TASK_DESCRIPTION),
+      taskTypeId: z.number().int().min(1).optional().describe("New task type ID"),
+      priorityId: z.number().int().min(1).optional().describe("New priority ID"),
+      boardColumnId: z.number().int().min(1).optional().describe("New board column ID (status)"),
+      assigneeId: z.number().int().min(1).optional().describe("New assigned user ID"),
+      cycleId: z.number().int().min(1).optional().describe("New cycle/sprint ID"),
+      milestoneId: z.number().int().min(0).optional().describe("New milestone ID (0 detaches from the current milestone)."),
+      parentTaskId: z.number().int().min(0).optional().describe("New parent task ID (0 clears the parent and promotes to a top-level task)."),
+      storyPoints: z.number().int().min(1).optional().describe(STORY_POINTS_ESTIMATE),
+      estimatedHours: z.number().min(0).optional().describe("Estimated effort in hours"),
+      labelIds: z.array(z.number().int().min(0)).optional().describe("Replace this task's labels with this set. Omit to leave labels unchanged. Empty array clears all labels."),
+      initiativeId: z.number().int().min(0).optional().describe("Initiative ID to link this task to. >0 links the task to that Initiative, 0 detaches."),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ taskId, title, description, taskTypeId, priorityId, boardColumnId, assigneeId, cycleId, milestoneId, parentTaskId, storyPoints, estimatedHours, labelIds, initiativeId }) => {
+      try {
+        const clients = getClients();
+
+        // Read current task
+        const getRes = await clients.tasks.getTask({ id: taskId });
+        const task = getRes.task;
+        if (!task)
+          return { content: [{ type: "text", text: "Task not found. Use opsee_list_tasks to see available tasks." }] };
+
+        // Merge changes into full EditTaskRequest
+        const res = await clients.tasks.editTask({
+          id: task.id,
+          identifier: task.identifier,
+          title: title ?? task.title,
+          description: description ?? task.description,
+          displayOrder: task.displayOrder,
+          storyPoints: storyPoints ?? task.storyPoints,
+          estimatedHours: estimatedHours ?? task.estimatedHours,
+          actualHours: task.actualHours,
+          dueDate: task.dueDate,
+          aiModeEnabled: task.aiModeEnabled,
+          metadataJson: task.metadataJson,
+          boardId: task.board?.id ?? 0,
+          boardColumnId: boardColumnId ?? task.boardColumn?.id ?? 0,
+          projectId: task.project?.id ?? 0,
+          taskTypeId: taskTypeId ?? task.taskType?.id ?? 0,
+          taskPriorityId: priorityId ?? task.taskPriority?.id ?? 0,
+          reporterUserId: task.reporterUser?.id ?? 0,
+          assignedUserId: assigneeId ?? task.assignedUser?.id,
+          cycleId: cycleId ?? task.cycle?.id,
+          milestoneId: milestoneId ?? task.milestoneId,
+          parentTaskId: parentTaskId ?? task.parentTaskId,
+          repositoryIds: task.taskRepositories?.map((r: { id: number }) => r.id) ?? [],
+          labelIds,
+          initiativeId: initiativeId !== undefined ? initiativeId : task.initiativeId,
+        });
+
+        if (!res.task)
+          return { content: [{ type: "text", text: "Failed to update task. The backend returned an empty response (no error). Retry; if it persists, surface the call to the Opsee team." }], isError: true };
+
+        return {
+          content: [
+            { type: "text", text: `Task updated:\n${formatTask(res.task, { full: true })}` },
+          ],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+}

package/src/tools/tasks-relations.ts

@@ -0,0 +1,159 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClients } from "../client/api.js";
+import { formatError } from "../utils/format.js";
+
+// Single-task relation edits (labels, initiative membership). Each one reads
+// the task first and resends every field, because EditTask is a full replace:
+// sending only the changed relation would blank everything else.
+export function registerTaskRelationTools(
+  server: McpServer,
+  getClients: () => ApiClients,
+): void {
+  server.tool(
+    "opsee_replace_task_labels",
+    "Replace the entire set of labels on a single task. Use opsee_update_task with labelIds for the same effect, but this tool is more discoverable for the common 'set my labels to [...]' flow.",
+    {
+      taskId: z.number().int().min(1).describe("The task ID"),
+      labelIds: z.array(z.number().int().min(1)).describe("Label IDs to set (empty array clears all labels)"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ taskId, labelIds }) => {
+      try {
+        const clients = getClients();
+        const getRes = await clients.tasks.getTask({ id: taskId });
+        const task = getRes.task;
+        if (!task) {
+          return { content: [{ type: "text", text: "Task not found." }] };
+        }
+        const res = await clients.tasks.editTask({
+          id: task.id,
+          identifier: task.identifier,
+          title: task.title,
+          description: task.description,
+          displayOrder: task.displayOrder,
+          storyPoints: task.storyPoints,
+          estimatedHours: task.estimatedHours,
+          actualHours: task.actualHours,
+          dueDate: task.dueDate,
+          aiModeEnabled: task.aiModeEnabled,
+          metadataJson: task.metadataJson,
+          boardId: task.board?.id ?? 0,
+          boardColumnId: task.boardColumn?.id ?? 0,
+          projectId: task.project?.id ?? 0,
+          taskTypeId: task.taskType?.id ?? 0,
+          taskPriorityId: task.taskPriority?.id ?? 0,
+          reporterUserId: task.reporterUser?.id ?? 0,
+          assignedUserId: task.assignedUser?.id,
+          cycleId: task.cycle?.id,
+          repositoryIds: task.taskRepositories?.map((r: { id: number }) => r.id) ?? [],
+          labelIds,
+        });
+        if (!res.task) {
+          return { content: [{ type: "text", text: "Failed to update task labels. The backend returned an empty response (no error). Retry; if it persists, surface the call to the Opsee team." }], isError: true };
+        }
+        const verb = labelIds.length === 0 ? "Cleared all labels on" : `Set ${labelIds.length} label(s) on`;
+        return { content: [{ type: "text", text: `${verb} ${res.task.identifier}.` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_link_task_to_initiative",
+    "Link an existing task to an Initiative — use this to bring an already-existing task into an initiative's scope. To create NEW tasks under an initiative, use opsee_decompose_initiative (first time) or opsee_reconcile_initiative (re-planning) instead. Fetches the task first so no other fields are blanked.",
+    {
+      taskId: z.number().int().min(1).describe("The task ID to link"),
+      initiativeId: z.number().int().min(1).describe("The initiative ID to link the task to"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ taskId, initiativeId }) => {
+      try {
+        const clients = getClients();
+        const getRes = await clients.tasks.getTask({ id: taskId });
+        const task = getRes.task;
+        if (!task)
+          return { content: [{ type: "text", text: "Task not found. Use opsee_list_tasks to see available tasks." }] };
+        const res = await clients.tasks.editTask({
+          id: task.id,
+          identifier: task.identifier,
+          title: task.title,
+          description: task.description,
+          displayOrder: task.displayOrder,
+          storyPoints: task.storyPoints,
+          estimatedHours: task.estimatedHours,
+          actualHours: task.actualHours,
+          dueDate: task.dueDate,
+          aiModeEnabled: task.aiModeEnabled,
+          metadataJson: task.metadataJson,
+          boardId: task.board?.id ?? 0,
+          boardColumnId: task.boardColumn?.id ?? 0,
+          projectId: task.project?.id ?? 0,
+          taskTypeId: task.taskType?.id ?? 0,
+          taskPriorityId: task.taskPriority?.id ?? 0,
+          reporterUserId: task.reporterUser?.id ?? 0,
+          assignedUserId: task.assignedUser?.id,
+          cycleId: task.cycle?.id,
+          milestoneId: task.milestoneId,
+          parentTaskId: task.parentTaskId,
+          repositoryIds: task.taskRepositories?.map((r: { id: number }) => r.id) ?? [],
+          initiativeId,
+        });
+        if (!res.task)
+          return { content: [{ type: "text", text: "Failed to link task. The backend returned an empty response (no error). Retry; if it persists, surface the call to the Opsee team." }], isError: true };
+        return { content: [{ type: "text", text: `Task ${res.task.identifier} linked to initiative ${initiativeId}.` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_unlink_task_from_initiative",
+    "Detach a task from its current Initiative. Fetches the task first so no other fields are blanked.",
+    {
+      taskId: z.number().int().min(1).describe("The task ID to unlink"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ taskId }) => {
+      try {
+        const clients = getClients();
+        const getRes = await clients.tasks.getTask({ id: taskId });
+        const task = getRes.task;
+        if (!task)
+          return { content: [{ type: "text", text: "Task not found. Use opsee_list_tasks to see available tasks." }] };
+        const res = await clients.tasks.editTask({
+          id: task.id,
+          identifier: task.identifier,
+          title: task.title,
+          description: task.description,
+          displayOrder: task.displayOrder,
+          storyPoints: task.storyPoints,
+          estimatedHours: task.estimatedHours,
+          actualHours: task.actualHours,
+          dueDate: task.dueDate,
+          aiModeEnabled: task.aiModeEnabled,
+          metadataJson: task.metadataJson,
+          boardId: task.board?.id ?? 0,
+          boardColumnId: task.boardColumn?.id ?? 0,
+          projectId: task.project?.id ?? 0,
+          taskTypeId: task.taskType?.id ?? 0,
+          taskPriorityId: task.taskPriority?.id ?? 0,
+          reporterUserId: task.reporterUser?.id ?? 0,
+          assignedUserId: task.assignedUser?.id,
+          cycleId: task.cycle?.id,
+          milestoneId: task.milestoneId,
+          parentTaskId: task.parentTaskId,
+          repositoryIds: task.taskRepositories?.map((r: { id: number }) => r.id) ?? [],
+          initiativeId: 0,
+        });
+        if (!res.task)
+          return { content: [{ type: "text", text: "Failed to unlink task. The backend returned an empty response (no error). Retry; if it persists, surface the call to the Opsee team." }], isError: true };
+        return { content: [{ type: "text", text: `Task ${res.task.identifier} unlinked from initiative.` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+}