@sprintdock/backend 0.4.2

package/src/mcp/plugins/task-tools.plugin.ts

@@ -0,0 +1,528 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: MCP plugin — core task CRUD, list, assign, move, and field updates.
+ */
+import { z } from "zod";
+import {
+  ensureSprintInPlan,
+  ensureTaskInPlan,
+  getSprintForPlan,
+  resolvePlanOrActive
+} from "../mcp-query-helpers.js";
+import { formatTaskList, shortId } from "../mcp-text-formatters.js";
+import { toMcpToolError } from "../mcp-tool-error.js";
+import { guardToolExecution, writeToolAudit } from "../tool-guard.js";
+import type { SprintdockMcpToolPlugin } from "./types.js";
+
+const TOUCHED_FILE_TYPE = z.enum([
+  "test",
+  "implementation",
+  "doc",
+  "config",
+  "other"
+]);
+
+const touchedFilesSchema = z
+  .array(
+    z.object({
+      path: z.string().min(1).max(2048),
+      fileType: TOUCHED_FILE_TYPE
+    })
+  )
+  .optional();
+
+export const taskToolsPlugin: SprintdockMcpToolPlugin = {
+  id: "sprintdock/task-tools",
+  register(server, ctx) {
+    const { deps, kit } = ctx;
+    const {
+      jsonStructured,
+      applyPagination,
+      paginationNote,
+      optionalPlanSlug,
+      paginationSchema,
+      TASK_STATUS_SCHEMA,
+      TASK_PRIORITY_SCHEMA
+    } = kit;
+    const { planService, sprintService, taskService } = deps.services;
+
+    server.registerTool(
+      "create_task",
+      {
+        description:
+          "Creates a task in a sprint. Pass sprintIdOrSlug: full sprint UUID or sprint slug under the resolved plan (same pattern as get_sprint). Do not read SQLite directly. Order defaults to the end of the sprint. Optional dependsOnTaskIds must reference tasks in the same plan. Optional touchedFiles lists repo paths with file types (test, implementation, doc, config, other). Guarded mutation.",
+        inputSchema: z
+          .object({
+            title: z.string().min(1),
+            description: z.string().default(""),
+            priority: TASK_PRIORITY_SCHEMA.default("medium"),
+            sprintIdOrSlug: z.string().min(1),
+            assignee: z.string().nullable().optional(),
+            tags: z.array(z.string()).default([]),
+            order: z.number().int().optional(),
+            dependsOnTaskIds: z.array(z.string()).optional(),
+            touchedFiles: touchedFilesSchema,
+            planSlug: optionalPlanSlug
+          })
+          .strict()
+      },
+      async (input) => {
+        try {
+          const guard = await guardToolExecution(
+            deps.authContextResolver,
+            deps.requestCorrelation,
+            deps.rateLimiter,
+            "create_task"
+          );
+          const plan = await resolvePlanOrActive(planService, input.planSlug);
+          const sprint = await getSprintForPlan(
+            sprintService,
+            plan,
+            input.sprintIdOrSlug
+          );
+          const task = await taskService.createTask(
+            {
+              title: input.title,
+              description: input.description || null,
+              priority: input.priority ?? "medium",
+              sprintId: sprint.id,
+              assignee: input.assignee ?? null,
+              tags: input.tags ?? [],
+              order: input.order,
+              dependsOnTaskIds: input.dependsOnTaskIds,
+              touchedFiles: input.touchedFiles
+            },
+            input.planSlug
+          );
+          writeToolAudit(
+            deps.auditLog,
+            "create_task",
+            guard.principalId,
+            guard.correlationId,
+            task.id
+          );
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Created task '${task.title}' (id: ${shortId(task.id)}).`
+              }
+            ],
+            structuredContent: jsonStructured(task)
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+
+    server.registerTool(
+      "list_tasks",
+      {
+        description:
+          "Lists tasks for an optional sprint UUID or across the whole plan when sprintId is omitted, with optional filters (status, priority, assignee). Optional limit/offset paginate; omit both for the full filtered list.",
+        inputSchema: z
+          .object({
+            sprintId: z.string().optional(),
+            status: TASK_STATUS_SCHEMA.optional(),
+            priority: TASK_PRIORITY_SCHEMA.optional(),
+            assignee: z.string().optional(),
+            planSlug: optionalPlanSlug,
+            ...paginationSchema
+          })
+          .strict()
+      },
+      async (input) => {
+        try {
+          const filter =
+            input.status || input.priority || input.assignee !== undefined
+              ? {
+                  ...(input.status ? { status: input.status } : {}),
+                  ...(input.priority ? { priority: input.priority } : {}),
+                  ...(input.assignee !== undefined
+                    ? { assignee: input.assignee }
+                    : {})
+                }
+              : undefined;
+          const tasksAll = await taskService.listTasks(
+            input.sprintId,
+            input.planSlug,
+            filter
+          );
+          const { page, total } = applyPagination(
+            tasksAll,
+            input.limit,
+            input.offset
+          );
+          const text =
+            formatTaskList(page) +
+            paginationNote(total, input.limit, input.offset);
+          return {
+            content: [{ type: "text", text }],
+            structuredContent: jsonStructured({ tasks: page, total })
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+
+    server.registerTool(
+      "get_task",
+      {
+        description:
+          "Returns one task by UUID with title, status, priority, assignee, tags, order, and sprint. When planSlug is set, verifies the task belongs to that plan.",
+        inputSchema: z
+          .object({
+            taskId: z.string().min(1),
+            planSlug: optionalPlanSlug
+          })
+          .strict()
+      },
+      async (input) => {
+        try {
+          if (input.planSlug !== undefined && input.planSlug !== "") {
+            const plan = await planService.resolvePlan(input.planSlug);
+            await ensureTaskInPlan(
+              taskService,
+              sprintService,
+              plan,
+              input.taskId
+            );
+          }
+          const task = await taskService.getTask(input.taskId);
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Task '${task.title}' currently has status '${task.status}'.`
+              }
+            ],
+            structuredContent: jsonStructured(task)
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+
+    server.registerTool(
+      "update_task_status",
+      {
+        description:
+          "Updates a task status with domain transition rules (e.g. done cannot jump back arbitrarily). Guarded mutation; returns the updated task.",
+        inputSchema: z
+          .object({
+            taskId: z.string().min(1),
+            status: TASK_STATUS_SCHEMA,
+            planSlug: optionalPlanSlug
+          })
+          .strict()
+      },
+      async (input) => {
+        try {
+          const guard = await guardToolExecution(
+            deps.authContextResolver,
+            deps.requestCorrelation,
+            deps.rateLimiter,
+            "update_task_status"
+          );
+          if (input.planSlug !== undefined && input.planSlug !== "") {
+            const plan = await planService.resolvePlan(input.planSlug);
+            await ensureTaskInPlan(
+              taskService,
+              sprintService,
+              plan,
+              input.taskId
+            );
+          }
+          const task = await taskService.updateTaskStatus(
+            input.taskId,
+            input.status
+          );
+          writeToolAudit(
+            deps.auditLog,
+            "update_task_status",
+            guard.principalId,
+            guard.correlationId,
+            task.id,
+            { status: task.status }
+          );
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Task '${task.title}' updated to '${task.status}'. (id: ${shortId(task.id)})`
+              }
+            ],
+            structuredContent: jsonStructured(task)
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+
+    server.registerTool(
+      "assign_task",
+      {
+        description:
+          "Sets or clears the assignee string on a task (null clears). Guarded mutation; scoped with planSlug when provided.",
+        inputSchema: z
+          .object({
+            taskId: z.string().min(1),
+            assignee: z.string().nullable(),
+            planSlug: optionalPlanSlug
+          })
+          .strict()
+      },
+      async (input) => {
+        try {
+          const guard = await guardToolExecution(
+            deps.authContextResolver,
+            deps.requestCorrelation,
+            deps.rateLimiter,
+            "assign_task"
+          );
+          if (input.planSlug !== undefined && input.planSlug !== "") {
+            const plan = await planService.resolvePlan(input.planSlug);
+            await ensureTaskInPlan(
+              taskService,
+              sprintService,
+              plan,
+              input.taskId
+            );
+          }
+          const task = await taskService.assignTask(
+            input.taskId,
+            input.assignee
+          );
+          writeToolAudit(
+            deps.auditLog,
+            "assign_task",
+            guard.principalId,
+            guard.correlationId,
+            task.id,
+            { assignee: task.assignee }
+          );
+          const who = task.assignee ?? "unassigned";
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Task '${task.title}' assigned to '${who}'. (id: ${shortId(task.id)})`
+              }
+            ],
+            structuredContent: jsonStructured(task)
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+
+    server.registerTool(
+      "move_task",
+      {
+        description:
+          "Moves a task to another sprint in the same plan (target sprint UUID). Guarded mutation; confirms the task and target sprint share a plan when planSlug is provided.",
+        inputSchema: z
+          .object({
+            taskId: z.string().min(1),
+            targetSprintId: z.string().min(1),
+            planSlug: optionalPlanSlug
+          })
+          .strict()
+      },
+      async (input) => {
+        try {
+          const guard = await guardToolExecution(
+            deps.authContextResolver,
+            deps.requestCorrelation,
+            deps.rateLimiter,
+            "move_task"
+          );
+          if (input.planSlug !== undefined && input.planSlug !== "") {
+            const plan = await planService.resolvePlan(input.planSlug);
+            await ensureTaskInPlan(
+              taskService,
+              sprintService,
+              plan,
+              input.taskId
+            );
+            await ensureSprintInPlan(
+              sprintService,
+              plan,
+              input.targetSprintId
+            );
+          }
+          const targetSprint = await sprintService.getSprint(
+            input.targetSprintId
+          );
+          const task = await taskService.moveTask(
+            input.taskId,
+            input.targetSprintId
+          );
+          writeToolAudit(
+            deps.auditLog,
+            "move_task",
+            guard.principalId,
+            guard.correlationId,
+            task.id,
+            { targetSprintId: task.sprintId }
+          );
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Task '${task.title}' moved to sprint '${targetSprint.name}' (${targetSprint.slug}). (id: ${shortId(task.id)})`
+              }
+            ],
+            structuredContent: jsonStructured(task)
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+
+    server.registerTool(
+      "delete_task",
+      {
+        description:
+          "Permanently deletes a task by UUID and removes its dependency edges. Guarded mutation. Use delete_sprint to remove a whole sprint. Returns confirmation with the task title and short id.",
+        inputSchema: z
+          .object({
+            taskId: z.string().min(1),
+            planSlug: optionalPlanSlug
+          })
+          .strict()
+      },
+      async (input) => {
+        try {
+          const guard = await guardToolExecution(
+            deps.authContextResolver,
+            deps.requestCorrelation,
+            deps.rateLimiter,
+            "delete_task"
+          );
+          if (input.planSlug !== undefined && input.planSlug !== "") {
+            const plan = await planService.resolvePlan(input.planSlug);
+            await ensureTaskInPlan(
+              taskService,
+              sprintService,
+              plan,
+              input.taskId
+            );
+          }
+          const before = await taskService.getTask(input.taskId);
+          await taskService.deleteTask(input.taskId);
+          writeToolAudit(
+            deps.auditLog,
+            "delete_task",
+            guard.principalId,
+            guard.correlationId,
+            input.taskId,
+            { title: before.title }
+          );
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Task '${before.title}' (${shortId(before.id)}) deleted.`
+              }
+            ],
+            structuredContent: jsonStructured({
+              deleted: true,
+              taskId: input.taskId
+            })
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+
+    server.registerTool(
+      "update_task",
+      {
+        description:
+          "Updates task title, description, priority, tags, sort order, or touchedFiles (replaces all file rows when set). Does not change status (use update_task_status). Guarded mutation.",
+        inputSchema: z
+          .object({
+            taskId: z.string().min(1),
+            title: z.string().min(1).optional(),
+            description: z.string().nullable().optional(),
+            priority: TASK_PRIORITY_SCHEMA.optional(),
+            tags: z.array(z.string()).optional(),
+            order: z.number().int().optional(),
+            touchedFiles: touchedFilesSchema,
+            planSlug: optionalPlanSlug
+          })
+          .strict()
+          .refine(
+            (v) =>
+              v.title !== undefined ||
+              v.description !== undefined ||
+              v.priority !== undefined ||
+              v.tags !== undefined ||
+              v.order !== undefined ||
+              v.touchedFiles !== undefined,
+            { message: "Provide at least one field to update." }
+          )
+      },
+      async (input) => {
+        try {
+          const guard = await guardToolExecution(
+            deps.authContextResolver,
+            deps.requestCorrelation,
+            deps.rateLimiter,
+            "update_task"
+          );
+          if (input.planSlug !== undefined && input.planSlug !== "") {
+            const plan = await planService.resolvePlan(input.planSlug);
+            await ensureTaskInPlan(
+              taskService,
+              sprintService,
+              plan,
+              input.taskId
+            );
+          }
+          const updated = await taskService.updateTask(input.taskId, {
+            ...(input.title !== undefined ? { title: input.title } : {}),
+            ...(input.description !== undefined
+              ? { description: input.description }
+              : {}),
+            ...(input.priority !== undefined
+              ? { priority: input.priority }
+              : {}),
+            ...(input.tags !== undefined ? { tags: input.tags } : {}),
+            ...(input.order !== undefined ? { order: input.order } : {}),
+            ...(input.touchedFiles !== undefined
+              ? { touchedFiles: input.touchedFiles }
+              : {})
+          });
+          writeToolAudit(
+            deps.auditLog,
+            "update_task",
+            guard.principalId,
+            guard.correlationId,
+            updated.id
+          );
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Task '${updated.title}' updated. (id: ${shortId(updated.id)})`
+              }
+            ],
+            structuredContent: jsonStructured(updated)
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+  }
+};