@opsee/mcp-server 0.5.7 → 0.6.3

package/src/tools/tasks.ts

@@ -4,7 +4,14 @@ 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, formatError } from "../utils/format.js";
+import {
+  formatTaskList,
+  formatTask,
+  formatTaskDependencyList,
+  formatCommentList,
+  formatTaskLabelList,
+  formatError,
+} from "../utils/format.js";
 import {
   FilterOptionsSchema,
   FilterSchema,
@@ -16,17 +23,33 @@ 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, labels, priority, type, milestone, parent, due date, and update/create recency. labelIds uses AND semantics; multi-id filters (priorityIds/taskTypeIds/milestoneIds) use OR semantics.",
     {
       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)"),
+      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)"),
       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,
+      priorityIds, taskTypeIds, milestoneIds, parentTaskId, hasParent,
+      unassigned, updatedSince, createdSince, dueBefore, dueAfter,
+      page, pageSize,
+    }) => {
       try {
         const clients = getClients();
 
@@ -34,6 +57,16 @@ export function registerTaskTools(
         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, {
@@ -45,6 +78,7 @@ export function registerTaskTools(
           projectId,
           pagination: defaultPagination(page || 1, pageSize || 50),
           filterOptions,
+          labelIds: labelIds ?? [],
         });
 
         return { content: [{ type: "text", text: formatTaskList(res.tasks) }] };
@@ -71,21 +105,86 @@ export function registerTaskTools(
     },
   );
 
+  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().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));
+
+        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().describe("The project ID"),
       title: z.string().describe("Task title"),
-      description: z.string().optional().describe("Task description"),
+      description: z.string().optional().describe("Task description. Markdown is supported — headings (##), bullets (-), code fences, inline **bold** / *italic* / `code` / links all render as proper formatted blocks in the UI. For ACCEPTANCE CRITERIA, write them inline in this description as a `## Acceptance criteria` heading followed by markdown checkbox lines: `- [ ] criterion text` and `- [x] done item`. The UI renders those as clickable checkboxes (BlockNote checkListItem) and users can toggle them. Do NOT use the structured opsee_add_acceptance_criterion tool for typical AC — it writes to a separate DB table that does not surface in the task detail UI; it's reserved for automation paths (PR-to-criterion mapping etc.). Written as-is to the backend; the frontend BlockEditor parses markdown on read and saves the parsed BlockNote JSON on the next edit, so the round-trip preserves structure."),
       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"),
+      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 }) => {
+    async ({ projectId, title, description, taskTypeId, priorityId, boardColumnId, assigneeId, cycleId, storyPoints, estimatedHours, labelIds }) => {
       try {
         const clients = getClients();
 
@@ -151,11 +250,14 @@ export function registerTaskTools(
           displayOrder: 0,
           aiModeEnabled: false,
           cycleId,
+          storyPoints,
+          estimatedHours,
           repositoryIds: [],
+          labelIds: labelIds ?? [],
         });
 
         if (!res.task)
-          return { content: [{ type: "text", text: "Failed to create 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: [
@@ -174,15 +276,18 @@ 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. Markdown is supported — headings (##), bullets (-), code fences, inline **bold** / *italic* / `code` / links all render as proper formatted blocks in the UI. For ACCEPTANCE CRITERIA, write them inline in this description as a `## Acceptance criteria` heading followed by markdown checkbox lines: `- [ ] criterion text` and `- [x] done item`. The UI renders those as clickable checkboxes (BlockNote checkListItem) and users can toggle them. Do NOT use the structured opsee_add_acceptance_criterion tool for typical AC — it writes to a separate DB table that does not surface in the task detail UI; it's reserved for automation paths (PR-to-criterion mapping etc.). Written as-is to the backend; the frontend BlockEditor parses markdown on read and saves the parsed BlockNote JSON on the next edit, so the round-trip preserves structure."),
       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"),
+      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."),
     },
     { readOnlyHint: false, destructiveHint: false },
-    async ({ taskId, title, description, taskTypeId, priorityId, boardColumnId, assigneeId, cycleId }) => {
+    async ({ taskId, title, description, taskTypeId, priorityId, boardColumnId, assigneeId, cycleId, storyPoints, estimatedHours, labelIds }) => {
       try {
         const clients = getClients();
 
@@ -199,8 +304,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,
@@ -214,10 +319,11 @@ export function registerTaskTools(
           assignedUserId: assigneeId ?? task.assignedUser?.id,
           cycleId: 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." }] };
+          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: [
@@ -229,4 +335,251 @@ 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. labelIds with a non-empty list replaces each task's labels; empty/omitted leaves them alone.",
+    {
+      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"),
+      storyPoints: z.number().int().min(1).optional().describe("Story points to set on every task"),
+      estimatedHours: z.number().min(0).optional().describe("Estimated hours to set on every task"),
+      parentTaskId: z.number().int().min(0).optional().describe("Parent task ID for every task (pass 0 to clear)"),
+      labelIds: z.array(z.number().int().min(1)).optional().describe("Replace label attachments on every task with this set. Empty / omitted leaves labels untouched."),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ projectId, taskIds, boardColumnId, taskPriorityId, taskTypeId, assignedUserId, cycleId, storyPoints, estimatedHours, parentTaskId, labelIds }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.tasks.bulkEditTasks({
+          projectId,
+          taskIds,
+          boardColumnId,
+          taskPriorityId,
+          taskTypeId,
+          assignedUserId,
+          cycleId,
+          storyPoints,
+          estimatedHours,
+          parentTaskId,
+          repositoryIds: [],
+          labelIds: labelIds ?? [],
+        });
+
+        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 };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_bulk_move_to_cycle",
+    "Convenience wrapper: move many tasks to the same cycle in one call. Equivalent to opsee_bulk_update_tasks with only cycleId set.",
+    {
+      projectId: z.number().describe("Project ID - all tasks must belong to this project"),
+      taskIds: z.array(z.number()).min(1).describe("Task IDs to move"),
+      cycleId: z.number().describe("Target cycle/sprint ID"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ projectId, taskIds, cycleId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.tasks.bulkEditTasks({
+          projectId,
+          taskIds,
+          cycleId,
+          repositoryIds: [],
+          labelIds: [],
+        });
+        const text = `Moved ${res.updatedCount} of ${taskIds.length} task(s) to cycle ${cycleId}.`;
+        return { content: [{ type: "text", text }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_bulk_move_to_column",
+    "Convenience wrapper: move many tasks to the same board column (status) in one call.",
+    {
+      projectId: z.number().describe("Project ID - all tasks must belong to this project"),
+      taskIds: z.array(z.number()).min(1).describe("Task IDs to move"),
+      boardColumnId: z.number().describe("Target board column ID (status)"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ projectId, taskIds, boardColumnId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.tasks.bulkEditTasks({
+          projectId,
+          taskIds,
+          boardColumnId,
+          repositoryIds: [],
+          labelIds: [],
+        });
+        const text = `Moved ${res.updatedCount} of ${taskIds.length} task(s) to column ${boardColumnId}.`;
+        return { content: [{ type: "text", text }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_bulk_assign",
+    "Convenience wrapper: assign many tasks to the same user in one call.",
+    {
+      projectId: z.number().describe("Project ID - all tasks must belong to this project"),
+      taskIds: z.array(z.number()).min(1).describe("Task IDs to reassign"),
+      assigneeId: z.number().describe("Target user ID"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ projectId, taskIds, assigneeId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.tasks.bulkEditTasks({
+          projectId,
+          taskIds,
+          assignedUserId: assigneeId,
+          repositoryIds: [],
+          labelIds: [],
+        });
+        const text = `Assigned ${res.updatedCount} of ${taskIds.length} task(s) to user ${assigneeId}.`;
+        return { content: [{ type: "text", text }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_bulk_set_priority",
+    "Convenience wrapper: set the same priority on many tasks in one call.",
+    {
+      projectId: z.number().describe("Project ID - all tasks must belong to this project"),
+      taskIds: z.array(z.number()).min(1).describe("Task IDs to reprioritize"),
+      priorityId: z.number().describe("Target priority ID (from opsee_list_task_priorities)"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ projectId, taskIds, priorityId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.tasks.bulkEditTasks({
+          projectId,
+          taskIds,
+          taskPriorityId: priorityId,
+          repositoryIds: [],
+          labelIds: [],
+        });
+        const text = `Set priority ${priorityId} on ${res.updatedCount} of ${taskIds.length} task(s).`;
+        return { content: [{ type: "text", text }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  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().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_delete_task",
+    "Delete a task by ID. This is permanent.",
+    { taskId: z.number().describe("The task ID to delete") },
+    { readOnlyHint: false, destructiveHint: true },
+    async ({ taskId }) => {
+      try {
+        const clients = getClients();
+        await clients.tasks.deleteTask({ id: taskId });
+        return { content: [{ type: "text", text: "Task deleted." }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_bulk_delete_tasks",
+    "Delete multiple tasks in one call. Tasks not visible to your company or not found are silently skipped — compare deletedCount against taskIds.length to detect partial application. This is permanent.",
+    {
+      projectId: z.number().describe("Project ID - all tasks must belong to this project"),
+      taskIds: z.array(z.number()).min(1).describe("Task IDs to delete (at least one)"),
+    },
+    { readOnlyHint: false, destructiveHint: true },
+    async ({ projectId, taskIds }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.tasks.bulkDeleteTasks({ projectId, taskIds });
+        const requested = taskIds.length;
+        const deleted = res.deletedCount;
+        let text = `Deleted ${deleted} of ${requested} task(s).`;
+        if (deleted < 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 };
+      }
+    },
+  );
 }

package/src/tools/work-logs.ts

@@ -0,0 +1,123 @@
+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";
+
+// Work log RPCs live on TaskService (AddWorkLog / DeleteWorkLog). There is
+// no list endpoint — work logs are preloaded onto the Task by GetTask, so
+// we surface them by hitting GetTask and projecting the embedded work_logs.
+
+export function registerWorkLogTools(
+  server: McpServer,
+  getClients: () => ApiClients,
+): void {
+  server.tool(
+    "opsee_list_work_logs",
+    "List all work-log entries for a task, oldest first. Includes the user who logged each entry, hours, and optional description.",
+    { taskId: z.number().describe("The task ID") },
+    { readOnlyHint: true, destructiveHint: false },
+    async ({ taskId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.tasks.getTask({ id: taskId });
+        const task = res.task;
+        if (!task) {
+          return { content: [{ type: "text", text: "Task not found." }] };
+        }
+        const logs = task.workLogs ?? [];
+        if (logs.length === 0) {
+          return { content: [{ type: "text", text: `No work logs on ${task.identifier}.` }] };
+        }
+        const lines = logs.map((wl: { id: number; userId: number; user?: { fullName?: string }; hours: number; description?: string; createdAt?: { seconds: bigint | number } }) => {
+          const who = wl.user?.fullName || `User #${wl.userId}`;
+          const when = wl.createdAt
+            ? new Date((typeof wl.createdAt.seconds === "bigint" ? Number(wl.createdAt.seconds) : wl.createdAt.seconds) * 1000).toISOString().split("T")[0]
+            : "—";
+          const desc = wl.description ? ` — ${wl.description}` : "";
+          return `${who} @ ${when}: ${wl.hours}h${desc} (ID: ${wl.id})`;
+        });
+        const total = logs.reduce((sum: number, wl: { hours: number }) => sum + wl.hours, 0);
+        return {
+          content: [
+            { type: "text", text: `Work logs for ${task.identifier} (total ${total}h):\n` + lines.join("\n") },
+          ],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_log_work",
+    "Log time against a task. Posts as the authenticated user. Hours must be > 0.",
+    {
+      taskId: z.number().describe("The task ID"),
+      hours: z.number().min(0.1).describe("Hours worked (>= 0.1)"),
+      description: z.string().optional().describe("Optional note describing what was done"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ taskId, hours, description }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.tasks.addWorkLog({ taskId, hours, description });
+        if (!res.workLog) {
+          return { content: [{ type: "text", text: "Failed to log work. 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: `Logged ${res.workLog.hours}h on task ${taskId} (work_log ID ${res.workLog.id}).` },
+          ],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_delete_work_log",
+    "Delete a work-log entry by ID. This is permanent.",
+    {
+      taskId: z.number().describe("The task ID the work log belongs to"),
+      workLogId: z.number().describe("The work log ID to delete"),
+    },
+    { readOnlyHint: false, destructiveHint: true },
+    async ({ taskId, workLogId }) => {
+      try {
+        const clients = getClients();
+        await clients.tasks.deleteWorkLog({ taskId, id: workLogId });
+        return { content: [{ type: "text", text: "Work log deleted." }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_get_task_actual_hours",
+    "Sum of all work_log hours on a task. Use this to compare against opsee_get_task's estimatedHours when assessing whether a task is over budget.",
+    { taskId: z.number().describe("The task ID") },
+    { readOnlyHint: true, destructiveHint: false },
+    async ({ taskId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.tasks.getTask({ id: taskId });
+        const task = res.task;
+        if (!task) {
+          return { content: [{ type: "text", text: "Task not found." }] };
+        }
+        const total = (task.workLogs ?? []).reduce((sum: number, wl: { hours: number }) => sum + wl.hours, 0);
+        const estimated = task.estimatedHours ?? 0;
+        const delta = estimated > 0 ? ` (estimated ${estimated}h, ${total > estimated ? "over by " + (total - estimated) : "under by " + (estimated - total)} h)` : "";
+        return {
+          content: [
+            { type: "text", text: `${task.identifier}: ${total}h logged${delta}.` },
+          ],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+}