@opsee/mcp-server 0.6.1 → 0.6.3

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

@@ -40,7 +40,7 @@ export function registerLabelTools(
     "opsee_get_label",
     "Get full details of a specific label by ID.",
     {
-      labelId: z.number().describe("The label ID"),
+      labelId: z.coerce.number().describe("The label ID"),
     },
     { readOnlyHint: true, destructiveHint: false },
     async ({ labelId }) => {
@@ -76,7 +76,7 @@ export function registerLabelTools(
           description,
           isActive,
         });
-        if (!res.label) return { content: [{ type: "text", text: "Failed to create label." }] };
+        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 };
@@ -108,7 +108,7 @@ export function registerLabelTools(
           description: description ?? label.description,
           isActive: isActive ?? label.isActive,
         });
-        if (!res.label) return { content: [{ type: "text", text: "Failed to update label." }] };
+        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 };

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)}` }],
         };

package/src/tools/notifications.ts

@@ -0,0 +1,171 @@
+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 { formatError } from "../utils/format.js";
+import {
+  FilterOptionsSchema,
+  FilterSchema,
+} from "../../gen/api/v1/filter_pb.js";
+
+// Notifications are user-scoped server-side (the GetNotifications RPC reads
+// the user_id off the auth context), so there's no per-call user parameter.
+// notification_type values are free-form strings produced by the backend
+// (e.g. "task_assigned", "comment_added", "task_blocked_unblocked",
+// "mention", "ai_workflow_status_change"). Treat them as opaque tags;
+// callers can filter via the unreadOnly param or post-process by type.
+
+function formatNotification(n: {
+  id: number;
+  title: string;
+  message?: string;
+  notificationType: string;
+  entityType?: string;
+  entityId?: number;
+  actionUrl?: string;
+  isRead: boolean;
+}): string {
+  const flag = n.isRead ? "" : " [unread]";
+  const target =
+    n.entityType && n.entityId ? ` → ${n.entityType} #${n.entityId}` : "";
+  const link = n.actionUrl ? `\n  Link: ${n.actionUrl}` : "";
+  const msg = n.message ? `\n  ${n.message}` : "";
+  return `${n.title} (${n.notificationType})${flag}${target}${msg}${link}\n  ID: ${n.id}`;
+}
+
+export function registerNotificationTools(
+  server: McpServer,
+  getClients: () => ApiClients,
+): void {
+  server.tool(
+    "opsee_list_my_notifications",
+    "Inbox-style listing of the authenticated user's notifications, newest first. Common notification_type values: task_assigned, comment_added, mention, task_blocked_unblocked, ai_workflow_status_change. Pass unreadOnly:true to see just the inbox.",
+    {
+      unreadOnly: z.boolean().optional().describe("If true, only return notifications where is_read=false"),
+      page: z.number().optional().describe("Page number (default: 1)"),
+      pageSize: z.number().optional().describe("Items per page (default: 50)"),
+    },
+    { readOnlyHint: true, destructiveHint: false },
+    async ({ unreadOnly, page, pageSize }) => {
+      try {
+        const clients = getClients();
+        const filterOptions = unreadOnly
+          ? create(FilterOptionsSchema, {
+              filters: [create(FilterSchema, { key: "IsRead", value: "false" })],
+            })
+          : undefined;
+        const res = await clients.notifications.getNotifications({
+          pagination: defaultPagination(page || 1, pageSize || 50),
+          filterOptions,
+        });
+        const items = res.notifications ?? [];
+        if (items.length === 0) {
+          return { content: [{ type: "text", text: unreadOnly ? "Inbox zero." : "No notifications." }] };
+        }
+        const header = unreadOnly
+          ? `${items.length} unread notification(s):`
+          : `${items.length} notification(s):`;
+        const body = items.map((n: Parameters<typeof formatNotification>[0], i: number) => `${i + 1}. ${formatNotification(n)}`).join("\n\n");
+        return { content: [{ type: "text", text: `${header}\n${body}` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_mark_notification_read",
+    "Mark a notification as read. Read-modify-write: fetches the current notification and re-issues EditNotification with is_read=true so other fields aren't clobbered.",
+    {
+      notificationId: z.number().describe("The notification ID"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ notificationId }) => {
+      try {
+        const clients = getClients();
+        const getRes = await clients.notifications.getNotification({ id: notificationId });
+        const existing = getRes.notification;
+        if (!existing) {
+          return { content: [{ type: "text", text: "Notification not found." }] };
+        }
+        if (existing.isRead) {
+          return { content: [{ type: "text", text: `Notification ${notificationId} was already read.` }] };
+        }
+        const editRes = await clients.notifications.editNotification({
+          id: existing.id,
+          title: existing.title,
+          message: existing.message,
+          notificationType: existing.notificationType,
+          entityType: existing.entityType,
+          entityId: existing.entityId,
+          actionUrl: existing.actionUrl,
+          isRead: true,
+          sentViaEmail: existing.sentViaEmail,
+          metadataJson: existing.metadataJson,
+          userId: existing.userId,
+        });
+        if (!editRes.notification) {
+          return { content: [{ type: "text", text: "Failed to mark notification read." }], isError: true };
+        }
+        return { content: [{ type: "text", text: `Notification ${notificationId} marked read.` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_mark_all_notifications_read",
+    "Loop through every unread notification and mark each read. Best-effort: per-notification failures are reported in the summary but don't abort the call. Caller can pass a maximum to bound the call.",
+    {
+      max: z.number().int().min(1).max(500).optional().describe("Maximum number of unread notifications to mark read in this call (default: 100, hard cap 500)"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ max }) => {
+      try {
+        const clients = getClients();
+        const limit = Math.min(max ?? 100, 500);
+        const listRes = await clients.notifications.getNotifications({
+          pagination: defaultPagination(1, limit),
+          filterOptions: create(FilterOptionsSchema, {
+            filters: [create(FilterSchema, { key: "IsRead", value: "false" })],
+          }),
+        });
+        const items = listRes.notifications ?? [];
+        if (items.length === 0) {
+          return { content: [{ type: "text", text: "Inbox zero — nothing to mark read." }] };
+        }
+        let succeeded = 0;
+        const failed: number[] = [];
+        for (const n of items) {
+          try {
+            await clients.notifications.editNotification({
+              id: n.id,
+              title: n.title,
+              message: n.message,
+              notificationType: n.notificationType,
+              entityType: n.entityType,
+              entityId: n.entityId,
+              actionUrl: n.actionUrl,
+              isRead: true,
+              sentViaEmail: n.sentViaEmail,
+              metadataJson: n.metadataJson,
+              userId: n.userId,
+            });
+            succeeded++;
+          } catch {
+            failed.push(n.id);
+          }
+        }
+        let text = `Marked ${succeeded} of ${items.length} notification(s) read.`;
+        if (failed.length > 0) {
+          text += ` Failed IDs: ${failed.join(", ")}.`;
+        }
+        return { content: [{ type: "text", text }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+}

package/src/tools/task-dependencies.ts

@@ -41,7 +41,7 @@ export function registerTaskDependencyTools(
         });
 
         if (!res.taskDependency) {
-          return { content: [{ type: "text", text: "Failed to create task dependency." }] };
+          return { content: [{ type: "text", text: "Failed to create task dependency. The backend returned an empty response (no error). Retry; if it persists, surface the call to the Opsee team." }], isError: true };
         }
 
         return {
@@ -93,4 +93,46 @@ export function registerTaskDependencyTools(
       }
     },
   );
+
+  server.tool(
+    "opsee_get_dependency_chain",
+    "Server-side BFS over the BLOCKS/BLOCKED_BY graph from a task. Returns the reachable tasks and the edges that connect them. Use direction='blocks' for downstream (what does this task unblock), 'blocked_by' for upstream (what is this task waiting on), 'both' for the full neighborhood. Depth caps at 10.",
+    {
+      taskId: z.number().describe("The starting task ID"),
+      direction: z.enum(["blocks", "blocked_by", "both"]).optional().describe("Direction to walk (default: both)"),
+      depth: z.number().int().min(1).max(10).optional().describe("Max hops from the source (default: 5, capped at 10)"),
+    },
+    { readOnlyHint: true, destructiveHint: false },
+    async ({ taskId, direction, depth }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.taskDependencies.getDependencyChain({
+          taskId,
+          direction: direction ?? "both",
+          depth: depth ?? 5,
+        });
+        const nodes = res.nodes ?? [];
+        const edges = res.edges ?? [];
+        const lines = [
+          `Dependency chain from task ${taskId} (direction: ${direction ?? "both"}, depth: ${depth ?? 5}):`,
+          `  ${nodes.length} task(s), ${edges.length} edge(s)`,
+        ];
+        if (nodes.length > 0) {
+          lines.push("\nTasks:");
+          for (const n of nodes as Array<{ identifier?: string; id: number; title?: string }>) {
+            lines.push(`  [${n.identifier ?? `#${n.id}`}] ${n.title ?? ""}`);
+          }
+        }
+        if (edges.length > 0) {
+          lines.push("\nEdges:");
+          for (const e of edges as Array<{ fromTaskId: number; toTaskId: number; type: number }>) {
+            lines.push(`  task ${e.fromTaskId} → task ${e.toTaskId} (type ${e.type})`);
+          }
+        }
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
 }