@opsee/mcp-server 0.5.7 → 0.6.1

package/src/server.ts

@@ -8,6 +8,9 @@ import { registerCycleTools } from "./tools/cycles.js";
 import { registerDocTools } from "./tools/docs.js";
 import { registerRepositoryTools } from "./tools/repositories.js";
 import { registerMilestoneTools } from "./tools/milestones.js";
+import { registerLabelTools } from "./tools/labels.js";
+import { registerCommentTools } from "./tools/comments.js";
+import { registerTaskDependencyTools } from "./tools/task-dependencies.js";
 
 export function createServer(clientFactory?: () => ApiClients): McpServer {
   const factory = clientFactory ?? getClients;
@@ -25,6 +28,9 @@ export function createServer(clientFactory?: () => ApiClients): McpServer {
   registerDocTools(server, factory);
   registerRepositoryTools(server, factory);
   registerMilestoneTools(server, factory);
+  registerLabelTools(server, factory);
+  registerCommentTools(server, factory);
+  registerTaskDependencyTools(server, factory);
 
   return server;
 }

package/src/tools/comments.ts

@@ -0,0 +1,96 @@
+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." }] };
+        }
+
+        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_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/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.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." }] };
+        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." }] };
+        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/task-dependencies.ts

@@ -0,0 +1,96 @@
+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." }] };
+        }
+
+        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 };
+      }
+    },
+  );
+}

package/src/tools/tasks.ts

@@ -16,17 +16,18 @@ export function registerTaskTools(
 ): void {
   server.tool(
     "opsee_list_tasks",
-    "List tasks in an Opsee project. Supports filtering by status, assignee, board column, and cycle.",
+    "List tasks in an Opsee project. Supports filtering by status, assignee, board column, cycle, and labels.",
     {
       projectId: z.number().describe("The project ID"),
       columnId: z.number().optional().describe("Filter by board column ID (status)"),
       assigneeId: z.number().optional().describe("Filter by assigned user ID"),
       cycleId: z.number().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)"),
       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, columnId, assigneeId, cycleId, page, pageSize }) => {
+    async ({ projectId, columnId, assigneeId, cycleId, labelIds, page, pageSize }) => {
       try {
         const clients = getClients();
 
@@ -45,6 +46,7 @@ export function registerTaskTools(
           projectId,
           pagination: defaultPagination(page || 1, pageSize || 50),
           filterOptions,
+          labelIds: labelIds ?? [],
         });
 
         return { content: [{ type: "text", text: formatTaskList(res.tasks) }] };
@@ -77,15 +79,17 @@ export function registerTaskTools(
     {
       projectId: z.number().describe("The project ID"),
       title: z.string().describe("Task title"),
-      description: z.string().optional().describe("Task description"),
+      description: z.string().optional().describe("Task description. Backend may transform plain text or markdown into BlockNote JSON on write; check returned task to see exact stored form. See README \"Task description format\" for details."),
       taskTypeId: z.number().optional().describe("Task type ID (from opsee_list_task_types)"),
       priorityId: z.number().optional().describe("Priority ID (from opsee_list_task_priorities)"),
       boardColumnId: z.number().optional().describe("Board column ID (from opsee_list_board_columns)"),
       assigneeId: z.number().optional().describe("Assigned user ID"),
       cycleId: z.number().optional().describe("Cycle/sprint ID"),
+      storyPoints: z.number().int().min(1).optional().describe("Story points estimate (positive integer)"),
+      estimatedHours: z.number().min(0).optional().describe("Estimated effort in hours"),
     },
     { readOnlyHint: false, destructiveHint: false },
-    async ({ projectId, title, description, taskTypeId, priorityId, boardColumnId, assigneeId, cycleId }) => {
+    async ({ projectId, title, description, taskTypeId, priorityId, boardColumnId, assigneeId, cycleId, storyPoints, estimatedHours }) => {
       try {
         const clients = getClients();
 
@@ -151,6 +155,8 @@ export function registerTaskTools(
           displayOrder: 0,
           aiModeEnabled: false,
           cycleId,
+          storyPoints,
+          estimatedHours,
           repositoryIds: [],
         });
 
@@ -174,15 +180,17 @@ export function registerTaskTools(
     {
       taskId: z.number().describe("The task ID to update"),
       title: z.string().optional().describe("New title"),
-      description: z.string().optional().describe("New description"),
+      description: z.string().optional().describe("New description. Backend may transform plain text or markdown into BlockNote JSON on write; check returned task to see exact stored form. See README \"Task description format\" for details."),
       taskTypeId: z.number().optional().describe("New task type ID"),
       priorityId: z.number().optional().describe("New priority ID"),
       boardColumnId: z.number().optional().describe("New board column ID (status)"),
       assigneeId: z.number().optional().describe("New assigned user ID"),
       cycleId: z.number().optional().describe("New cycle/sprint ID"),
+      storyPoints: z.number().int().min(1).optional().describe("Story points estimate (positive integer)"),
+      estimatedHours: z.number().min(0).optional().describe("Estimated effort in hours"),
     },
     { readOnlyHint: false, destructiveHint: false },
-    async ({ taskId, title, description, taskTypeId, priorityId, boardColumnId, assigneeId, cycleId }) => {
+    async ({ taskId, title, description, taskTypeId, priorityId, boardColumnId, assigneeId, cycleId, storyPoints, estimatedHours }) => {
       try {
         const clients = getClients();
 
@@ -199,8 +207,8 @@ export function registerTaskTools(
           title: title ?? task.title,
           description: description ?? task.description,
           displayOrder: task.displayOrder,
-          storyPoints: task.storyPoints,
-          estimatedHours: task.estimatedHours,
+          storyPoints: storyPoints ?? task.storyPoints,
+          estimatedHours: estimatedHours ?? task.estimatedHours,
           actualHours: task.actualHours,
           dueDate: task.dueDate,
           aiModeEnabled: task.aiModeEnabled,
@@ -229,4 +237,44 @@ export function registerTaskTools(
       }
     },
   );
+
+  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.",
+    {
+      projectId: z.number().describe("Project ID - all tasks must belong to this project"),
+      taskIds: z.array(z.number()).min(1).describe("Task IDs to update (at least one)"),
+      boardColumnId: z.number().optional().describe("New board column ID (status)"),
+      taskPriorityId: z.number().optional().describe("New priority ID"),
+      taskTypeId: z.number().optional().describe("New task type ID"),
+      assignedUserId: z.number().optional().describe("New assigned user ID"),
+      cycleId: z.number().optional().describe("New cycle/sprint ID"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ projectId, taskIds, boardColumnId, taskPriorityId, taskTypeId, assignedUserId, cycleId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.tasks.bulkEditTasks({
+          projectId,
+          taskIds,
+          boardColumnId,
+          taskPriorityId,
+          taskTypeId,
+          assignedUserId,
+          cycleId,
+          repositoryIds: [],
+        });
+
+        const requested = taskIds.length;
+        const updated = res.updatedCount;
+        let text = `Updated ${updated} of ${requested} task(s).`;
+        if (updated < requested) {
+          text += " (Tasks not visible to your company or not found were skipped.)";
+        }
+        return { content: [{ type: "text", text }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
 }

package/src/tools/user.ts

@@ -1,6 +1,8 @@
+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";
+import { defaultPagination } from "../client/api.js";
+import { formatError, formatUser, formatUserList } from "../utils/format.js";
 
 export function registerUserTools(
   server: McpServer,
@@ -31,4 +33,42 @@ export function registerUserTools(
       }
     },
   );
+
+  server.tool(
+    "opsee_list_users",
+    "Lists users in the authenticated company. Opsee scopes users at the Company level — there is no project-scoped user listing because Users do not have a per-project relation. Use this to resolve assignee names to IDs.",
+    {
+      page: z.number().optional().describe("Page number (default: 1)"),
+      pageSize: z.number().optional().describe("Items per page (default: 50)"),
+    },
+    { readOnlyHint: true, destructiveHint: false },
+    async ({ page, pageSize }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.users.getUsers({
+          pagination: defaultPagination(page || 1, pageSize || 50),
+        });
+        return { content: [{ type: "text", text: formatUserList(res.users) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_get_user",
+    "Get full details of a specific user by ID.",
+    { userId: z.number().describe("The user ID") },
+    { readOnlyHint: true, destructiveHint: false },
+    async ({ userId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.users.getUser({ id: userId });
+        if (!res.user) return { content: [{ type: "text", text: "User not found. Use opsee_list_users to see available users." }] };
+        return { content: [{ type: "text", text: formatUser(res.user) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
 }