@sprintdock/backend 0.4.2

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

@@ -0,0 +1,396 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: MCP plugin — sprint CRUD, list with counts, and status updates.
+ */
+import { z } from "zod";
+import {
+  countByTaskStatus,
+  getSprintForPlan,
+  resolvePlanOrActive
+} from "../mcp-query-helpers.js";
+import { formatSprintList, 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";
+
+export const sprintToolsPlugin: SprintdockMcpToolPlugin = {
+  id: "sprintdock/sprint-tools",
+  register(server, ctx) {
+    const { deps, kit } = ctx;
+    const {
+      jsonStructured,
+      applyPagination,
+      paginationNote,
+      optionalPlanSlug,
+      paginationSchema
+    } = kit;
+    const { planService, sprintService, taskService } = deps.services;
+
+    server.registerTool(
+      "create_sprint",
+      {
+        description:
+          "Creates a sprint under the active or named plan with slug, name, goal, and optional start/end dates. New sprints start in planned status.",
+        inputSchema: z
+          .object({
+            sprintSlug: z.string().min(1),
+            name: z.string().min(1),
+            goal: z.string().min(1),
+            markdownContent: z.string().nullable().optional(),
+            startDate: z.string().datetime().nullable().optional(),
+            endDate: z.string().datetime().nullable().optional(),
+            planSlug: optionalPlanSlug
+          })
+          .strict()
+      },
+      async (input) => {
+        try {
+          const guard = await guardToolExecution(
+            deps.authContextResolver,
+            deps.requestCorrelation,
+            deps.rateLimiter,
+            "create_sprint"
+          );
+          const plan = await resolvePlanOrActive(planService, input.planSlug);
+          const sprint = await sprintService.createSprint(plan.slug, {
+            slug: input.sprintSlug,
+            planId: plan.id,
+            name: input.name,
+            goal: input.goal,
+            markdownContent: input.markdownContent ?? null,
+            startDate: input.startDate ?? null,
+            endDate: input.endDate ?? null
+          });
+          writeToolAudit(
+            deps.auditLog,
+            "create_sprint",
+            guard.principalId,
+            guard.correlationId,
+            sprint.id
+          );
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Created sprint '${sprint.name}' (${sprint.slug}, id: ${shortId(sprint.id)}).`
+              }
+            ],
+            structuredContent: jsonStructured(sprint)
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+
+    server.registerTool(
+      "list_sprints",
+      {
+        description:
+          "Lists sprints for the resolved plan with slug, status, name, and live task counts by status. Optional limit/offset paginate; omit both for the full list.",
+        inputSchema: z
+          .object({ planSlug: optionalPlanSlug, ...paginationSchema })
+          .strict()
+      },
+      async (input) => {
+        try {
+          const plan = await resolvePlanOrActive(planService, input.planSlug);
+          const sprints = await sprintService.listSprints(plan.id);
+          const withCounts = [];
+          for (const s of sprints) {
+            const tasks = await taskService.listTasks(s.id);
+            withCounts.push({
+              ...s,
+              sprintSlug: s.slug,
+              taskCounts: countByTaskStatus(tasks)
+            });
+          }
+          const { page, total } = applyPagination(
+            withCounts,
+            input.limit,
+            input.offset
+          );
+          const text =
+            formatSprintList(plan.slug, page) +
+            paginationNote(total, input.limit, input.offset) +
+            "\nPass each line's slug or `sprintId:<uuid>` as create_task / bulk_create_tasks **sprintIdOrSlug** (with the same planSlug). Full UUIDs are in structuredContent.sprints[].id.";
+          return {
+            content: [{ type: "text", text }],
+            structuredContent: jsonStructured({ sprints: page, total })
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+
+    server.registerTool(
+      "get_sprint",
+      {
+        description:
+          "Loads sprint metadata (name, goal, dates, status) by UUID or sprint slug under the resolved plan. Does not include tasks; use get_sprint_detail for tasks.",
+        inputSchema: z
+          .object({
+            sprintIdOrSlug: z.string().min(1),
+            planSlug: optionalPlanSlug
+          })
+          .strict()
+      },
+      async (input) => {
+        try {
+          const plan = await resolvePlanOrActive(planService, input.planSlug);
+          const sprint = await getSprintForPlan(
+            sprintService,
+            plan,
+            input.sprintIdOrSlug
+          );
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Sprint '${sprint.name}' (${sprint.slug}) is in status '${sprint.status}' (id: ${shortId(sprint.id)}).`
+              }
+            ],
+            structuredContent: jsonStructured({
+              ...sprint,
+              sprintSlug: sprint.slug
+            })
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+
+    server.registerTool(
+      "update_sprint_status",
+      {
+        description:
+          "Moves a sprint through its lifecycle (planned, active, completed, archived) with domain validation. Accepts sprint UUID or slug scoped to the plan.",
+        inputSchema: z
+          .object({
+            sprintIdOrSlug: z.string().min(1),
+            status: z.enum(["planned", "active", "completed", "archived"]),
+            planSlug: optionalPlanSlug
+          })
+          .strict()
+      },
+      async (input) => {
+        try {
+          const guard = await guardToolExecution(
+            deps.authContextResolver,
+            deps.requestCorrelation,
+            deps.rateLimiter,
+            "update_sprint_status"
+          );
+          const plan = await resolvePlanOrActive(planService, input.planSlug);
+          const resolved = await getSprintForPlan(
+            sprintService,
+            plan,
+            input.sprintIdOrSlug
+          );
+          const sprint = await sprintService.updateSprintStatus(
+            resolved.id,
+            input.status
+          );
+          writeToolAudit(
+            deps.auditLog,
+            "update_sprint_status",
+            guard.principalId,
+            guard.correlationId,
+            sprint.id,
+            { status: sprint.status }
+          );
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Sprint '${sprint.name}' (${sprint.slug}) updated to '${sprint.status}'.`
+              }
+            ],
+            structuredContent: jsonStructured(sprint)
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+
+    server.registerTool(
+      "delete_sprint",
+      {
+        description:
+          "Deletes a sprint and all of its tasks (cascade). Accepts sprint UUID or slug under the resolved plan. Guarded mutation.",
+        inputSchema: z
+          .object({
+            sprintIdOrSlug: z.string().min(1),
+            planSlug: optionalPlanSlug
+          })
+          .strict()
+      },
+      async (input) => {
+        try {
+          const guard = await guardToolExecution(
+            deps.authContextResolver,
+            deps.requestCorrelation,
+            deps.rateLimiter,
+            "delete_sprint"
+          );
+          const plan = await resolvePlanOrActive(planService, input.planSlug);
+          const sprint = await getSprintForPlan(
+            sprintService,
+            plan,
+            input.sprintIdOrSlug
+          );
+          await sprintService.deleteSprint(sprint.id);
+          writeToolAudit(
+            deps.auditLog,
+            "delete_sprint",
+            guard.principalId,
+            guard.correlationId,
+            sprint.id,
+            { slug: sprint.slug }
+          );
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Sprint '${sprint.name}' (${sprint.slug}, id: ${shortId(sprint.id)}) deleted.`
+              }
+            ],
+            structuredContent: jsonStructured({
+              deleted: true,
+              sprintId: sprint.id
+            })
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+
+    server.registerTool(
+      "update_sprint",
+      {
+        description:
+          "Updates sprint name, goal, start/end dates, or order without changing lifecycle status (use update_sprint_status for status). Accepts sprint UUID or slug. Guarded mutation.",
+        inputSchema: z
+          .object({
+            sprintIdOrSlug: z.string().min(1),
+            name: z.string().min(1).optional(),
+            goal: z.string().min(1).optional(),
+            markdownContent: z.string().nullable().optional(),
+            startDate: z.string().datetime().nullable().optional(),
+            endDate: z.string().datetime().nullable().optional(),
+            order: z.number().int().optional(),
+            planSlug: optionalPlanSlug
+          })
+          .strict()
+          .refine(
+            (v) =>
+              v.name !== undefined ||
+              v.goal !== undefined ||
+              v.markdownContent !== undefined ||
+              v.startDate !== undefined ||
+              v.endDate !== undefined ||
+              v.order !== undefined,
+            { message: "Provide at least one field to update." }
+          )
+      },
+      async (input) => {
+        try {
+          const guard = await guardToolExecution(
+            deps.authContextResolver,
+            deps.requestCorrelation,
+            deps.rateLimiter,
+            "update_sprint"
+          );
+          const plan = await resolvePlanOrActive(planService, input.planSlug);
+          const sprint = await getSprintForPlan(
+            sprintService,
+            plan,
+            input.sprintIdOrSlug
+          );
+          const updated = await sprintService.updateSprint(sprint.id, {
+            ...(input.name !== undefined ? { name: input.name } : {}),
+            ...(input.goal !== undefined ? { goal: input.goal } : {}),
+            ...(input.markdownContent !== undefined
+              ? { markdownContent: input.markdownContent }
+              : {}),
+            ...(input.startDate !== undefined
+              ? { startDate: input.startDate }
+              : {}),
+            ...(input.endDate !== undefined ? { endDate: input.endDate } : {}),
+            ...(input.order !== undefined ? { order: input.order } : {})
+          });
+          writeToolAudit(
+            deps.auditLog,
+            "update_sprint",
+            guard.principalId,
+            guard.correlationId,
+            updated.id
+          );
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Sprint '${updated.name}' (${updated.slug}) updated. (id: ${shortId(updated.id)})`
+              }
+            ],
+            structuredContent: jsonStructured(updated)
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+
+    server.registerTool(
+      "update_sprint_markdown",
+      {
+        description:
+          "Overwrites sprint markdown notes (GFM) in SQLite for a sprint under the active or named plan. Use list_sprints / get_sprint_detail to resolve slugs. Guarded mutation.",
+        inputSchema: z
+          .object({
+            sprintIdOrSlug: z.string().min(1),
+            content: z.string(),
+            planSlug: optionalPlanSlug
+          })
+          .strict()
+      },
+      async (input) => {
+        try {
+          const guard = await guardToolExecution(
+            deps.authContextResolver,
+            deps.requestCorrelation,
+            deps.rateLimiter,
+            "update_sprint_markdown"
+          );
+          const plan = await resolvePlanOrActive(planService, input.planSlug);
+          const sprint = await getSprintForPlan(
+            sprintService,
+            plan,
+            input.sprintIdOrSlug
+          );
+          const updated = await sprintService.updateSprint(sprint.id, {
+            markdownContent: input.content
+          });
+          writeToolAudit(
+            deps.auditLog,
+            "update_sprint_markdown",
+            guard.principalId,
+            guard.correlationId,
+            updated.id
+          );
+          return {
+            content: [{ type: "text", text: "Sprint markdown updated." }],
+            structuredContent: jsonStructured({ ok: true, sprint: updated })
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+  }
+};