@sprintdock/backend 0.4.2

package/src/mcp/plugins/mcp-tool-kit.ts

@@ -0,0 +1,90 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Shared Zod schemas and helpers for Sprintdock MCP tool plugins.
+ */
+import { z } from "zod";
+
+export const optionalPlanSlug = z.string().min(1).optional();
+
+export const paginationSchema = {
+  limit: z.number().int().min(1).max(100).optional(),
+  offset: z.number().int().min(0).optional()
+};
+
+export const TASK_STATUS_SCHEMA = z.enum([
+  "todo",
+  "in_progress",
+  "blocked",
+  "done"
+]);
+
+export const TASK_PRIORITY_SCHEMA = z.enum([
+  "low",
+  "medium",
+  "high",
+  "critical"
+]);
+
+export function applyPagination<T>(
+  items: T[],
+  limit?: number,
+  offset?: number
+): { page: T[]; total: number } {
+  const total = items.length;
+  if (limit === undefined && offset === undefined) {
+    return { page: items, total };
+  }
+  const off = offset ?? 0;
+  const lim = limit ?? 50;
+  return { page: items.slice(off, off + lim), total };
+}
+
+export function paginationNote(
+  total: number,
+  limit?: number,
+  offset?: number
+): string {
+  if (limit === undefined && offset === undefined) {
+    return "";
+  }
+  const off = offset ?? 0;
+  const lim = limit ?? 50;
+  if (total === 0) {
+    return " (showing 0 of 0)";
+  }
+  const end = Math.min(off + lim, total);
+  return ` (showing ${off + 1}-${end} of ${total})`;
+}
+
+export function jsonStructured(data: unknown): Record<string, unknown> {
+  return JSON.parse(JSON.stringify(data)) as Record<string, unknown>;
+}
+
+/** Toolkit passed to every plugin so custom plugins reuse the same schemas and helpers. */
+export interface SprintdockMcpToolKit {
+  readonly jsonStructured: typeof jsonStructured;
+  readonly applyPagination: typeof applyPagination;
+  readonly paginationNote: typeof paginationNote;
+  readonly optionalPlanSlug: typeof optionalPlanSlug;
+  readonly paginationSchema: typeof paginationSchema;
+  readonly TASK_STATUS_SCHEMA: typeof TASK_STATUS_SCHEMA;
+  readonly TASK_PRIORITY_SCHEMA: typeof TASK_PRIORITY_SCHEMA;
+}
+
+const kitSingleton: SprintdockMcpToolKit = {
+  jsonStructured,
+  applyPagination,
+  paginationNote,
+  optionalPlanSlug,
+  paginationSchema,
+  TASK_STATUS_SCHEMA,
+  TASK_PRIORITY_SCHEMA
+};
+
+/**
+ * Returns the shared toolkit (immutable singleton) for MCP tool plugins.
+ */
+export function createSprintdockMcpToolKit(): SprintdockMcpToolKit {
+  return kitSingleton;
+}

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

@@ -0,0 +1,426 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: MCP plugin — plan list/create/active, summary, markdown, CRUD, and plan progress.
+ */
+import { z } from "zod";
+import { ValidationError } from "../../errors/backend-errors.js";
+import {
+  countByTaskStatus,
+  resolvePlanOrActive
+} from "../mcp-query-helpers.js";
+import {
+  formatPlanList,
+  formatPlanProgress,
+  formatPlanSummary
+} 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 planToolsPlugin: SprintdockMcpToolPlugin = {
+  id: "sprintdock/plan-tools",
+  register(server, ctx) {
+    const { deps, kit } = ctx;
+    const {
+      jsonStructured,
+      applyPagination,
+      paginationNote,
+      optionalPlanSlug,
+      paginationSchema
+    } = kit;
+    const { planService, sprintService, taskService } = deps.services;
+
+    server.registerTool(
+      "list_plans",
+      {
+        description:
+          "Lists every plan in the SQLite database with slug, title, status, and which plan is active. Use this first to discover planSlug values. Optional limit/offset paginate results; omit both to return the full list.",
+        inputSchema: z.object({ ...paginationSchema }).strict()
+      },
+      async (input) => {
+        try {
+          const plansAll = await planService.listPlans();
+          const { page, total } = applyPagination(
+            plansAll,
+            input.limit,
+            input.offset
+          );
+          let activePlanId: string | null = null;
+          try {
+            activePlanId = (await planService.getActivePlan()).id;
+          } catch {
+            activePlanId = null;
+          }
+          const text =
+            formatPlanList(page, activePlanId) +
+            paginationNote(total, input.limit, input.offset);
+          return {
+            content: [{ type: "text", text }],
+            structuredContent: jsonStructured({ plans: page, total })
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+
+    server.registerTool(
+      "create_plan",
+      {
+        description:
+          "Creates a new plan with a kebab-case slug. The first plan in an empty database becomes the active plan automatically. Returns the new plan record.",
+        inputSchema: z
+          .object({
+            planSlug: z.string().min(1),
+            title: z.string().min(1).optional(),
+            initialBody: z.string().optional()
+          })
+          .strict()
+      },
+      async (input) => {
+        try {
+          const guard = await guardToolExecution(
+            deps.authContextResolver,
+            deps.requestCorrelation,
+            deps.rateLimiter,
+            "create_plan"
+          );
+          const plan = await planService.createPlan({
+            slug: input.planSlug,
+            title: input.title ?? input.planSlug,
+            markdownContent: input.initialBody ?? null
+          });
+          writeToolAudit(
+            deps.auditLog,
+            "create_plan",
+            guard.principalId,
+            guard.correlationId,
+            plan.id
+          );
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Created plan '${plan.slug}' (${plan.id}).`
+              }
+            ],
+            structuredContent: jsonStructured({ planSlug: plan.slug, plan })
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+
+    server.registerTool(
+      "set_active_plan",
+      {
+        description:
+          "Switches the active plan used when tools omit planSlug. Pass the plan slug or UUID. Only one plan can be active at a time.",
+        inputSchema: z.object({ planSlug: z.string().min(1) }).strict()
+      },
+      async (input) => {
+        try {
+          const guard = await guardToolExecution(
+            deps.authContextResolver,
+            deps.requestCorrelation,
+            deps.rateLimiter,
+            "set_active_plan"
+          );
+          await planService.setActivePlan(input.planSlug);
+          writeToolAudit(
+            deps.auditLog,
+            "set_active_plan",
+            guard.principalId,
+            guard.correlationId,
+            input.planSlug
+          );
+          return {
+            content: [
+              { type: "text", text: `Active plan set to '${input.planSlug}'.` }
+            ],
+            structuredContent: jsonStructured({ planSlug: input.planSlug })
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+
+    server.registerTool(
+      "get_active_plan",
+      {
+        description:
+          "Returns the active plan (or the plan matching optional planSlug) with title, id, and the on-disk plan markdown path.",
+        inputSchema: z.object({ planSlug: optionalPlanSlug }).strict()
+      },
+      async (input) => {
+        try {
+          const plan = await resolvePlanOrActive(planService, input.planSlug);
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Plan '${plan.slug}' (${plan.title}).`
+              }
+            ],
+            structuredContent: jsonStructured({
+              planSlug: plan.slug,
+              title: plan.title,
+              planId: plan.id,
+              planMarkdownPath: `.sprintdock/plans/${plan.slug}/plan.md`
+            })
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+
+    server.registerTool(
+      "get_plan_summary",
+      {
+        description:
+          "Returns plan title, updated time, and every sprint with slug, status, id, and task counts by status (todo, in_progress, blocked, done). Use for dashboards before drilling into sprints.",
+        inputSchema: z.object({ planSlug: optionalPlanSlug }).strict()
+      },
+      async (input) => {
+        try {
+          const plan = await resolvePlanOrActive(planService, input.planSlug);
+          const sprints = await sprintService.listSprints(plan.id);
+          const sprintsOut = [];
+          for (const sp of sprints) {
+            const tasks = await taskService.listTasks(sp.id);
+            sprintsOut.push({
+              sprintSlug: sp.slug,
+              sprintId: sp.id,
+              name: sp.name,
+              status: sp.status,
+              taskCounts: countByTaskStatus(tasks)
+            });
+          }
+          return {
+            content: [
+              {
+                type: "text",
+                text: formatPlanSummary(plan, sprintsOut)
+              }
+            ],
+            structuredContent: jsonStructured({
+              planSlug: plan.slug,
+              title: plan.title,
+              updatedAt: plan.updatedAt,
+              sprints: sprintsOut
+            })
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+
+    server.registerTool(
+      "update_plan_markdown",
+      {
+        description:
+          "Overwrites the plan body markdown stored in SQLite for the resolved plan. Requires auth/rate-limit guard; use for syncing plan docs from agents.",
+        inputSchema: z
+          .object({
+            content: z.string(),
+            planSlug: optionalPlanSlug
+          })
+          .strict()
+      },
+      async (input) => {
+        try {
+          const guard = await guardToolExecution(
+            deps.authContextResolver,
+            deps.requestCorrelation,
+            deps.rateLimiter,
+            "update_plan_markdown"
+          );
+          const plan = await resolvePlanOrActive(planService, input.planSlug);
+          const updated = await planService.updatePlan(plan.id, {
+            markdownContent: input.content
+          });
+          writeToolAudit(
+            deps.auditLog,
+            "update_plan_markdown",
+            guard.principalId,
+            guard.correlationId,
+            updated.id
+          );
+          return {
+            content: [{ type: "text", text: "Plan markdown updated." }],
+            structuredContent: jsonStructured({ ok: true, plan: updated })
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+
+    server.registerTool(
+      "delete_plan",
+      {
+        description:
+          "Deletes a plan and cascades all sprints and tasks. Cannot delete the currently active plan; switch active plan first. Guarded mutation.",
+        inputSchema: z.object({ planSlug: z.string().min(1) }).strict()
+      },
+      async (input) => {
+        try {
+          const guard = await guardToolExecution(
+            deps.authContextResolver,
+            deps.requestCorrelation,
+            deps.rateLimiter,
+            "delete_plan"
+          );
+          const plan = await planService.getPlan(input.planSlug);
+          let active: { id: string };
+          try {
+            active = await planService.getActivePlan();
+          } catch {
+            active = { id: "" };
+          }
+          if (active.id === plan.id) {
+            throw new ValidationError(
+              "Cannot delete the active plan; set another plan active first."
+            );
+          }
+          await planService.deletePlan(plan.id);
+          writeToolAudit(
+            deps.auditLog,
+            "delete_plan",
+            guard.principalId,
+            guard.correlationId,
+            plan.id,
+            { slug: plan.slug }
+          );
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Plan '${plan.slug}' ("${plan.title}") deleted.`
+              }
+            ],
+            structuredContent: jsonStructured({
+              deleted: true,
+              planSlug: plan.slug
+            })
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+
+    server.registerTool(
+      "update_plan",
+      {
+        description:
+          "Updates plan title, description, or status with domain validation on status transitions. Resolves the plan from optional planSlug or the active plan; at least one field must be provided.",
+        inputSchema: z
+          .object({
+            planSlug: optionalPlanSlug,
+            title: z.string().min(1).optional(),
+            description: z.string().nullable().optional(),
+            status: z
+              .enum(["draft", "active", "completed", "archived"])
+              .optional()
+          })
+          .strict()
+          .refine(
+            (v) =>
+              v.title !== undefined ||
+              v.description !== undefined ||
+              v.status !== undefined,
+            {
+              message:
+                "Provide at least one of title, description, or status."
+            }
+          )
+      },
+      async (input) => {
+        try {
+          const guard = await guardToolExecution(
+            deps.authContextResolver,
+            deps.requestCorrelation,
+            deps.rateLimiter,
+            "update_plan"
+          );
+          const plan = await resolvePlanOrActive(planService, input.planSlug);
+          const updated = await planService.updatePlan(plan.id, {
+            ...(input.title !== undefined ? { title: input.title } : {}),
+            ...(input.description !== undefined
+              ? { description: input.description }
+              : {}),
+            ...(input.status !== undefined ? { status: input.status } : {})
+          });
+          writeToolAudit(
+            deps.auditLog,
+            "update_plan",
+            guard.principalId,
+            guard.correlationId,
+            updated.id
+          );
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Plan '${updated.slug}' ("${updated.title}") updated [${updated.status}].`
+              }
+            ],
+            structuredContent: jsonStructured({ plan: updated })
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+
+    server.registerTool(
+      "get_plan_progress",
+      {
+        description:
+          "Computes done vs total tasks for the plan and each sprint, with completion percentages. Use for burndown-style snapshots.",
+        inputSchema: z.object({ planSlug: optionalPlanSlug }).strict()
+      },
+      async (input) => {
+        try {
+          const plan = await resolvePlanOrActive(planService, input.planSlug);
+          const sprints = await sprintService.listSprints(plan.id);
+          let doneAll = 0;
+          let totalAll = 0;
+          const rows = [];
+          for (const sp of sprints) {
+            const tasks = await taskService.listTasks(sp.id);
+            const done = tasks.filter((t) => t.status === "done").length;
+            const total = tasks.length;
+            doneAll += done;
+            totalAll += total;
+            rows.push({
+              slug: sp.slug,
+              name: sp.name,
+              status: sp.status,
+              done,
+              total
+            });
+          }
+          const text = formatPlanProgress(plan.slug, doneAll, totalAll, rows);
+          return {
+            content: [{ type: "text", text }],
+            structuredContent: jsonStructured({
+              planSlug: plan.slug,
+              done: doneAll,
+              total: totalAll,
+              sprints: rows
+            })
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+  }
+};