@opsee/mcp-server 0.5.7 → 0.6.3

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

@@ -0,0 +1,138 @@
+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 {
+  formatTaskDependency,
+  formatTaskDependencyList,
+  formatError,
+} from "../utils/format.js";
+import { TaskDependencyType } from "../../gen/api/v1/models_pb.js";
+
+const dependencyTypeSchema = z.enum(["BLOCKS", "BLOCKED_BY", "DUPLICATES", "RELATES_TO"]);
+
+const typeMap: Record<string, TaskDependencyType> = {
+  BLOCKS: TaskDependencyType.BLOCKS,
+  BLOCKED_BY: TaskDependencyType.BLOCKED_BY,
+  DUPLICATES: TaskDependencyType.DUPLICATES,
+  RELATES_TO: TaskDependencyType.RELATES_TO,
+};
+
+export function registerTaskDependencyTools(
+  server: McpServer,
+  getClients: () => ApiClients,
+): void {
+  server.tool(
+    "opsee_create_task_dependency",
+    "Create a dependency relationship between two tasks. Use BLOCKS when the from-task must be completed before the to-task. Use BLOCKED_BY for the inverse. Use DUPLICATES when tasks are duplicates. Use RELATES_TO for a general association.",
+    {
+      fromTaskId: z.number().describe("The ID of the source task"),
+      toTaskId: z.number().describe("The ID of the target task"),
+      type: dependencyTypeSchema.describe("Dependency type: BLOCKS, BLOCKED_BY, DUPLICATES, or RELATES_TO"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ fromTaskId, toTaskId, type }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.taskDependencies.addTaskDependency({
+          fromTaskId,
+          toTaskId,
+          type: typeMap[type],
+        });
+
+        if (!res.taskDependency) {
+          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 {
+          content: [{ type: "text", text: `Task dependency created:\n${formatTaskDependency(res.taskDependency)}` }],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_list_task_dependencies",
+    "List all dependencies for a task — returns both outgoing (task blocks others) and incoming (task is blocked by others) relationships.",
+    {
+      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.taskDependencies.getTaskDependencies({
+          taskId,
+          pagination: defaultPagination(page || 1, pageSize || 50),
+        });
+        return {
+          content: [{ type: "text", text: formatTaskDependencyList(res.taskDependencies) }],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_delete_task_dependency",
+    "Delete a task dependency by its ID. This is permanent.",
+    { dependencyId: z.number().describe("The task dependency ID") },
+    { readOnlyHint: false, destructiveHint: true },
+    async ({ dependencyId }) => {
+      try {
+        const clients = getClients();
+        await clients.taskDependencies.deleteTaskDependency({ id: dependencyId });
+        return { content: [{ type: "text", text: "Task dependency deleted." }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  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 };
+      }
+    },
+  );
+}