@opsee/mcp-server 0.5.7 → 0.6.3

package/src/tools/comments.ts

@@ -0,0 +1,135 @@
+import { z } from "zod";
+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 {
+  formatComment,
+  formatCommentList,
+  formatError,
+} from "../utils/format.js";
+
+export function registerCommentTools(
+  server: McpServer,
+  getClients: () => ApiClients,
+): void {
+  server.tool(
+    "opsee_list_comments",
+    "List comments on a task, oldest first. Includes both regular and internal comments visible to the caller.",
+    {
+      taskId: z.number().describe("The task ID"),
+      page: z.number().optional().describe("Page number (default: 1)"),
+      pageSize: z.number().optional().describe("Items per page (default: 50)"),
+    },
+    { readOnlyHint: true, destructiveHint: false },
+    async ({ taskId, page, pageSize }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.comments.getComments({
+          taskId,
+          pagination: defaultPagination(page || 1, pageSize || 50),
+        });
+        return { content: [{ type: "text", text: formatCommentList(res.comments) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_add_comment",
+    "Add a comment to a task. Posts as the authenticated user. Set isInternal=true to mark the comment as internal (visibility depends on backend RBAC).",
+    {
+      taskId: z.number().describe("The task ID to comment on"),
+      content: z.string().min(1).describe("Comment body"),
+      isInternal: z.boolean().optional().describe("Mark as internal comment (default: false)"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ taskId, content, isInternal }) => {
+      try {
+        const clients = getClients();
+
+        let userId = 0;
+        const cachedId = authManager.getUserId();
+        if (cachedId) userId = Number(cachedId);
+        if (!userId) {
+          const meRes = await clients.users.getMe({});
+          if (meRes.user) userId = meRes.user.id;
+        }
+        if (!userId) {
+          return { content: [{ type: "text", text: "Could not resolve current user. Authentication may be incomplete." }], isError: true };
+        }
+
+        const res = await clients.comments.addComment({
+          content,
+          isInternal: isInternal ?? false,
+          taskId,
+          userId,
+        });
+
+        if (!res.comment) {
+          return { content: [{ type: "text", text: "Failed to add comment. 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: `Comment added:\n${formatComment(res.comment)}` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_edit_comment",
+    "Edit an existing comment's content and/or internal flag. Posts as the original author. Use opsee_list_comments first to confirm the comment ID.",
+    {
+      commentId: z.number().describe("The comment ID to edit"),
+      content: z.string().min(1).describe("New comment body"),
+      isInternal: z.boolean().optional().describe("Update the internal flag (defaults to the comment's existing value if omitted)"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ commentId, content, isInternal }) => {
+      try {
+        const clients = getClients();
+
+        const getRes = await clients.comments.getComment({ id: commentId });
+        const existing = getRes.comment;
+        if (!existing) {
+          return { content: [{ type: "text", text: "Comment not found. Use opsee_list_comments to see available comments." }] };
+        }
+
+        const res = await clients.comments.editComment({
+          id: existing.id,
+          content,
+          isInternal: isInternal ?? existing.isInternal,
+          taskId: existing.taskId,
+          docPageId: existing.docPageId,
+          userId: existing.userId,
+        });
+
+        if (!res.comment) {
+          return { content: [{ type: "text", text: "Failed to edit comment. 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: `Comment updated:\n${formatComment(res.comment)}` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_delete_comment",
+    "Delete a comment by ID. This is permanent.",
+    { commentId: z.number().describe("The comment ID") },
+    { readOnlyHint: false, destructiveHint: true },
+    async ({ commentId }) => {
+      try {
+        const clients = getClients();
+        await clients.comments.deleteComment({ id: commentId });
+        return { content: [{ type: "text", text: "Comment deleted." }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+}

package/src/tools/cycles.ts

@@ -1,8 +1,14 @@
 import { z } from "zod";
+import { create } from "@bufbuild/protobuf";
 import { timestampFromDate } from "@bufbuild/protobuf/wkt";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { ApiClients } from "../client/api.js";
+import { defaultPagination } from "../client/api.js";
 import { formatCycleList, formatCycle, formatError } from "../utils/format.js";
+import {
+  FilterOptionsSchema,
+  FilterSchema,
+} from "../../gen/api/v1/filter_pb.js";
 
 export function registerCycleTools(
   server: McpServer,
@@ -65,7 +71,7 @@ export function registerCycleTools(
           description,
         });
         if (!res.cycle)
-          return { content: [{ type: "text", text: "Failed to create cycle." }] };
+          return { content: [{ type: "text", text: "Failed to create cycle. The backend returned an empty response (no error). Retry; if it persists, surface the call to the Opsee team." }], isError: true };
 
         return {
           content: [
@@ -77,4 +83,186 @@ export function registerCycleTools(
       }
     },
   );
+
+  server.tool(
+    "opsee_update_cycle",
+    "Update a cycle's fields (patch semantics — only provided fields change). Fetches the current cycle first, merges your changes, sends the full update.",
+    {
+      cycleId: z.number().describe("The cycle ID to update"),
+      name: z.string().optional().describe("New name"),
+      goal: z.string().optional().describe("New goal"),
+      startDate: z.string().optional().describe("New start date (ISO 8601)"),
+      endDate: z.string().optional().describe("New end date (ISO 8601)"),
+      description: z.string().optional().describe("New description"),
+      isActive: z.boolean().optional().describe("Whether the cycle is active"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ cycleId, name, goal, startDate, endDate, description, isActive }) => {
+      try {
+        const clients = getClients();
+        const getRes = await clients.cycles.getCycle({ id: cycleId });
+        const existing = getRes.cycle;
+        if (!existing) {
+          return { content: [{ type: "text", text: "Cycle not found." }] };
+        }
+
+        const res = await clients.cycles.editCycle({
+          id: existing.id,
+          name: name ?? existing.name,
+          goal: goal ?? existing.goal,
+          startDate: startDate ? timestampFromDate(new Date(startDate)) : existing.startDate,
+          endDate: endDate ? timestampFromDate(new Date(endDate)) : existing.endDate,
+          isActive: isActive ?? existing.isActive,
+          description: description ?? existing.description,
+        });
+
+        if (!res.cycle) {
+          return { content: [{ type: "text", text: "Failed to update cycle. 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: `Cycle updated:\n${formatCycle(res.cycle)}` },
+          ],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_close_cycle",
+    "Close a cycle (mark inactive) and optionally carry every remaining task forward to a target cycle. Composes a single bulk_move_to_cycle + EditCycle, so /tpm cycle close becomes one call instead of a loop. Pass createNextCycle:true with name/startDate/endDate to also create the next cycle and carry forward into it in the same call.",
+    {
+      cycleId: z.number().describe("ID of the cycle to close"),
+      nextCycleId: z.number().optional().describe("Existing cycle to carry remaining tasks into. Mutually exclusive with createNextCycle."),
+      createNextCycle: z.boolean().optional().describe("If true, create the next cycle in this project (requires name/startDate/endDate) and carry tasks into it"),
+      nextCycleName: z.string().optional().describe("Name of the cycle to create when createNextCycle:true"),
+      nextCycleStartDate: z.string().optional().describe("ISO 8601 start date when createNextCycle:true"),
+      nextCycleEndDate: z.string().optional().describe("ISO 8601 end date when createNextCycle:true"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ cycleId, nextCycleId, createNextCycle, nextCycleName, nextCycleStartDate, nextCycleEndDate }) => {
+      try {
+        const clients = getClients();
+
+        const cycleRes = await clients.cycles.getCycle({ id: cycleId });
+        const existing = cycleRes.cycle;
+        if (!existing) {
+          return { content: [{ type: "text", text: "Cycle not found." }] };
+        }
+        const projectId = existing.projectId;
+
+        // Resolve the target cycle for carry-forward.
+        let targetCycleId: number | undefined = nextCycleId;
+        let createdNextCycle: { id: number; name: string } | undefined;
+        if (createNextCycle) {
+          if (nextCycleId) {
+            return { content: [{ type: "text", text: "createNextCycle and nextCycleId are mutually exclusive — pick one." }], isError: true };
+          }
+          if (!nextCycleName || !nextCycleStartDate || !nextCycleEndDate) {
+            return { content: [{ type: "text", text: "createNextCycle requires nextCycleName, nextCycleStartDate, nextCycleEndDate." }], isError: true };
+          }
+          const addRes = await clients.cycles.addCycle({
+            projectId,
+            name: nextCycleName,
+            goal: "",
+            startDate: timestampFromDate(new Date(nextCycleStartDate)),
+            endDate: timestampFromDate(new Date(nextCycleEndDate)),
+            isActive: true,
+            description: undefined,
+          });
+          if (!addRes.cycle) {
+            return { content: [{ type: "text", text: "Failed to create next cycle. The backend returned an empty response." }], isError: true };
+          }
+          createdNextCycle = { id: addRes.cycle.id, name: addRes.cycle.name };
+          targetCycleId = addRes.cycle.id;
+        }
+
+        // Carry forward all tasks currently in the cycle, if a target was provided.
+        let carriedForward = 0;
+        if (targetCycleId) {
+          const tasksRes = await clients.tasks.getTasks({
+            projectId,
+            pagination: defaultPagination(1, 500),
+            filterOptions: create(FilterOptionsSchema, {
+              filters: [create(FilterSchema, { key: "CycleId", value: String(cycleId) })],
+            }),
+            labelIds: [],
+          });
+          const taskIds = (tasksRes.tasks ?? []).map((t: { id: number }) => t.id);
+          if (taskIds.length > 0) {
+            const bulkRes = await clients.tasks.bulkEditTasks({
+              projectId,
+              taskIds,
+              cycleId: targetCycleId,
+              repositoryIds: [],
+              labelIds: [],
+            });
+            carriedForward = bulkRes.updatedCount;
+          }
+        }
+
+        // Close the cycle by marking it inactive.
+        const editRes = await clients.cycles.editCycle({
+          id: existing.id,
+          name: existing.name,
+          goal: existing.goal,
+          startDate: existing.startDate,
+          endDate: existing.endDate,
+          isActive: false,
+          description: existing.description,
+        });
+        if (!editRes.cycle) {
+          return { content: [{ type: "text", text: "Failed to close cycle. Carry-forward may have partially applied; check opsee_list_tasks." }], isError: true };
+        }
+
+        const lines = [`Cycle "${existing.name}" (ID ${existing.id}) closed.`];
+        if (carriedForward > 0 && targetCycleId) {
+          lines.push(`Carried ${carriedForward} task(s) forward to cycle ${targetCycleId}${createdNextCycle ? ` ("${createdNextCycle.name}")` : ""}.`);
+        } else if (targetCycleId) {
+          lines.push("No tasks to carry forward.");
+        }
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_get_active_cycle",
+    "Return the currently-active cycle for a project, or 'No active cycle' if none.",
+    { projectId: z.number().describe("The project ID") },
+    { readOnlyHint: true, destructiveHint: false },
+    async ({ projectId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.cycles.getCycles({ projectId });
+        const active = (res.cycles ?? []).find((c: { isActive: boolean }) => c.isActive);
+        if (!active) {
+          return { content: [{ type: "text", text: `No active cycle in project ${projectId}.` }] };
+        }
+        return { content: [{ type: "text", text: formatCycle(active) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_delete_cycle",
+    "Delete a cycle by ID. This is permanent. Tasks assigned to the cycle are not deleted, but their cycle reference is cleared.",
+    { cycleId: z.number().describe("The cycle ID") },
+    { readOnlyHint: false, destructiveHint: true },
+    async ({ cycleId }) => {
+      try {
+        const clients = getClients();
+        await clients.cycles.deleteCycle({ id: cycleId });
+        return { content: [{ type: "text", text: "Cycle deleted." }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
 }

package/src/tools/docs.ts

@@ -134,7 +134,7 @@ export function registerDocTools(
         });
 
         if (!res.docPage)
-          return { content: [{ type: "text", text: "Failed to create doc page." }] };
+          return { content: [{ type: "text", text: "Failed to create doc page. The backend returned an empty response (no error). Retry; if it persists, surface the call to the Opsee team." }], isError: true };
 
         return {
           content: [

package/src/tools/labels.ts

@@ -0,0 +1,199 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClients } from "../client/api.js";
+import { defaultPagination } from "../client/api.js";
+import {
+  formatLabel,
+  formatLabelList,
+  formatTaskLabelList,
+  formatError,
+} from "../utils/format.js";
+
+export function registerLabelTools(
+  server: McpServer,
+  getClients: () => ApiClients,
+): void {
+  server.tool(
+    "opsee_list_labels",
+    "List labels defined in an Opsee project. Use opsee_list_task_labels for labels attached to a specific task.",
+    {
+      projectId: z.number().describe("The project ID"),
+      page: z.number().optional().describe("Page number (default: 1)"),
+      pageSize: z.number().optional().describe("Items per page (default: 50)"),
+    },
+    { readOnlyHint: true, destructiveHint: false },
+    async ({ projectId, page, pageSize }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.labels.getLabels({
+          projectId,
+          pagination: defaultPagination(page || 1, pageSize || 50),
+        });
+        return { content: [{ type: "text", text: formatLabelList(res.labels) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_get_label",
+    "Get full details of a specific label by ID.",
+    {
+      labelId: z.coerce.number().describe("The label ID"),
+    },
+    { readOnlyHint: true, destructiveHint: false },
+    async ({ labelId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.labels.getLabel({ id: labelId });
+        if (!res.label) return { content: [{ type: "text", text: "Label not found. Use opsee_list_labels to see available labels." }] };
+        return { content: [{ type: "text", text: formatLabel(res.label) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_create_label",
+    "Create a new label in an Opsee project.",
+    {
+      projectId: z.number().describe("The project ID"),
+      name: z.string().min(1).max(50).describe("Label name"),
+      color: z.string().regex(/^#?[0-9a-fA-F]{6}$/).optional().describe("Hex color, e.g. #ffaa00 or ffaa00"),
+      description: z.string().optional().describe("Label description"),
+      isActive: z.boolean().optional().describe("Whether the label is active (default: true)"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ projectId, name, color, description, isActive }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.labels.addLabel({
+          name,
+          color,
+          projectId,
+          description,
+          isActive,
+        });
+        if (!res.label) return { content: [{ type: "text", text: "Failed to create label. 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: `Label created:\n${formatLabel(res.label)}` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_update_label",
+    "Update a label's fields (patch semantics - only provided fields are changed). Fetches the current label first, merges your changes, and sends the full update.",
+    {
+      labelId: z.number().describe("The label ID to update"),
+      name: z.string().min(1).max(50).optional().describe("New label name"),
+      color: z.string().regex(/^#?[0-9a-fA-F]{6}$/).optional().describe("New hex color, e.g. #ffaa00 or ffaa00"),
+      description: z.string().optional().describe("New description"),
+      isActive: z.boolean().optional().describe("Whether the label is active"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ labelId, name, color, description, isActive }) => {
+      try {
+        const clients = getClients();
+        const getRes = await clients.labels.getLabel({ id: labelId });
+        const label = getRes.label;
+        if (!label) return { content: [{ type: "text", text: "Label not found. Use opsee_list_labels to see available labels." }] };
+        const res = await clients.labels.editLabel({
+          id: label.id,
+          name: name ?? label.name,
+          color: color ?? label.color,
+          description: description ?? label.description,
+          isActive: isActive ?? label.isActive,
+        });
+        if (!res.label) return { content: [{ type: "text", text: "Failed to update label. 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: `Label updated:\n${formatLabel(res.label)}` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_delete_label",
+    "Delete a label permanently. Attached TaskLabel rows are not cleaned up automatically by this tool — backend behavior dictates whether cascade applies.",
+    {
+      labelId: z.number().describe("The label ID to delete"),
+    },
+    { readOnlyHint: false, destructiveHint: true },
+    async ({ labelId }) => {
+      try {
+        const clients = getClients();
+        await clients.labels.deleteLabel({ id: labelId });
+        return { content: [{ type: "text", text: "Label deleted." }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_attach_label_to_task",
+    "Attach an existing label to a task. Returns the TaskLabel join-row ID needed for opsee_detach_label_from_task.",
+    {
+      taskId: z.number().describe("The task ID"),
+      labelId: z.number().describe("The label ID to attach"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ taskId, labelId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.taskLabels.addTaskLabel({ taskId, labelId });
+        if (!res.taskLabel) return { content: [{ type: "text", text: "Label attached. Use opsee_list_task_labels to see the join-row ID." }] };
+        const tl = res.taskLabel;
+        const labelName = tl.label?.name || `Label #${tl.labelId}`;
+        return { content: [{ type: "text", text: `Label attached: ${labelName} (Label ID: ${tl.labelId} | TaskLabel ID: ${tl.id})` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_detach_label_from_task",
+    "Pass the TaskLabel join-row id (returned from opsee_list_task_labels), not the labelId. Proto DeleteTaskLabelRequest takes the join PK.",
+    {
+      taskLabelId: z.number().describe("The TaskLabel join-row ID (from opsee_list_task_labels), not the label ID"),
+    },
+    { readOnlyHint: false, destructiveHint: true },
+    async ({ taskLabelId }) => {
+      try {
+        const clients = getClients();
+        await clients.taskLabels.deleteTaskLabel({ id: taskLabelId });
+        return { content: [{ type: "text", text: "Label detached." }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_list_task_labels",
+    "List labels attached to a specific task (returns TaskLabel join rows with embedded Label data).",
+    {
+      taskId: z.number().describe("The task ID"),
+      page: z.number().optional().describe("Page number (default: 1)"),
+      pageSize: z.number().optional().describe("Items per page (default: 50)"),
+    },
+    { readOnlyHint: true, destructiveHint: false },
+    async ({ taskId, page, pageSize }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.taskLabels.getTaskLabels({
+          taskId,
+          pagination: defaultPagination(page || 1, pageSize || 50),
+        });
+        return { content: [{ type: "text", text: formatTaskLabelList(res.taskLabels) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+}

package/src/tools/milestones.ts

@@ -77,7 +77,7 @@ export function registerMilestoneTools(
           endDate: endDate ? timestampFromDate(new Date(endDate)) : undefined,
         });
         if (!res.milestone)
-          return { content: [{ type: "text", text: "Failed to create milestone." }] };
+          return { content: [{ type: "text", text: "Failed to create milestone. 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: `Milestone created:\n${formatMilestone(res.milestone)}` }],
         };
@@ -115,7 +115,7 @@ export function registerMilestoneTools(
           endDate: endDate ? timestampFromDate(new Date(endDate)) : m.endDate,
         });
         if (!res.milestone)
-          return { content: [{ type: "text", text: "Failed to update milestone." }] };
+          return { content: [{ type: "text", text: "Failed to update milestone. 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: `Milestone updated:\n${formatMilestone(res.milestone)}` }],
         };
@@ -159,7 +159,7 @@ export function registerMilestoneTools(
         const clients = getClients();
         const res = await clients.milestoneTasks.addMilestoneTask({ milestoneId, taskId });
         if (!res.milestoneTask)
-          return { content: [{ type: "text", text: "Failed to attach task." }] };
+          return { content: [{ type: "text", text: "Failed to attach 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 attached:\n${formatMilestoneTask(res.milestoneTask)}` }],
         };