@sprintdock/backend 0.4.2

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

@@ -0,0 +1,275 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: MCP plugin — bulk task ops and dependency graph tools.
+ */
+import { z } from "zod";
+import { ensureTaskInPlan, getSprintForPlan, resolvePlanOrActive } from "../mcp-query-helpers.js";
+import { 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 taskWorkflowPlugin: SprintdockMcpToolPlugin = {
+  id: "sprintdock/task-workflow",
+  register(server, ctx) {
+    const { deps, kit } = ctx;
+    const { jsonStructured, optionalPlanSlug, TASK_STATUS_SCHEMA, TASK_PRIORITY_SCHEMA } =
+      kit;
+    const { planService, sprintService, taskService } = deps.services;
+
+    server.registerTool(
+      "bulk_create_tasks",
+      {
+        description:
+          "Creates up to 50 tasks in one sprint in a single call. Pass sprintIdOrSlug (full UUID or sprint slug under the resolved plan). Each entry supports title, description, priority, assignee, and tags. Guarded mutation.",
+        inputSchema: z
+          .object({
+            sprintIdOrSlug: z.string().min(1),
+            tasks: z
+              .array(
+                z
+                  .object({
+                    title: z.string().min(1),
+                    description: z.string().default(""),
+                    priority: TASK_PRIORITY_SCHEMA.default("medium"),
+                    assignee: z.string().nullable().optional(),
+                    tags: z.array(z.string()).default([])
+                  })
+                  .strict()
+              )
+              .min(1)
+              .max(50),
+            planSlug: optionalPlanSlug
+          })
+          .strict()
+      },
+      async (input) => {
+        try {
+          const guard = await guardToolExecution(
+            deps.authContextResolver,
+            deps.requestCorrelation,
+            deps.rateLimiter,
+            "bulk_create_tasks"
+          );
+          const plan = await resolvePlanOrActive(planService, input.planSlug);
+          const sprint = await getSprintForPlan(
+            sprintService,
+            plan,
+            input.sprintIdOrSlug
+          );
+          const created = [];
+          for (const t of input.tasks) {
+            const task = await taskService.createTask(
+              {
+                title: t.title,
+                description: t.description || null,
+                priority: t.priority ?? "medium",
+                sprintId: sprint.id,
+                assignee: t.assignee ?? null,
+                tags: t.tags ?? []
+              },
+              input.planSlug
+            );
+            created.push(task);
+          }
+          writeToolAudit(
+            deps.auditLog,
+            "bulk_create_tasks",
+            guard.principalId,
+            guard.correlationId,
+            sprint.id,
+            { count: created.length }
+          );
+          const lines = created.map(
+            (x) => `- '${x.title}' (id: ${shortId(x.id)})`
+          );
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Created ${created.length} task(s):\n${lines.join("\n")}`
+              }
+            ],
+            structuredContent: jsonStructured({ tasks: created })
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+
+    server.registerTool(
+      "bulk_update_task_status",
+      {
+        description:
+          "Updates status on up to 50 tasks in one call. Each pair must include taskId and target status. Guarded mutation.",
+        inputSchema: z
+          .object({
+            updates: z
+              .array(
+                z
+                  .object({
+                    taskId: z.string().min(1),
+                    status: TASK_STATUS_SCHEMA
+                  })
+                  .strict()
+              )
+              .min(1)
+              .max(50),
+            planSlug: optionalPlanSlug
+          })
+          .strict()
+      },
+      async (input) => {
+        try {
+          const guard = await guardToolExecution(
+            deps.authContextResolver,
+            deps.requestCorrelation,
+            deps.rateLimiter,
+            "bulk_update_task_status"
+          );
+          const done = [];
+          for (const u of input.updates) {
+            if (input.planSlug !== undefined && input.planSlug !== "") {
+              const plan = await planService.resolvePlan(input.planSlug);
+              await ensureTaskInPlan(
+                taskService,
+                sprintService,
+                plan,
+                u.taskId
+              );
+            }
+            const task = await taskService.updateTaskStatus(
+              u.taskId,
+              u.status
+            );
+            done.push(task);
+          }
+          writeToolAudit(
+            deps.auditLog,
+            "bulk_update_task_status",
+            guard.principalId,
+            guard.correlationId,
+            "bulk",
+            { count: done.length }
+          );
+          const lines = done.map(
+            (x) => `- '${x.title}' -> ${x.status} (id: ${shortId(x.id)})`
+          );
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Updated ${done.length} task(s):\n${lines.join("\n")}`
+              }
+            ],
+            structuredContent: jsonStructured({ tasks: done })
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+
+    server.registerTool(
+      "get_task_dependencies",
+      {
+        description:
+          "Returns tasks this task depends on (prerequisites) and tasks that depend on it (dependents), scoped to the plan when planSlug is set.",
+        inputSchema: z
+          .object({
+            taskId: z.string().min(1),
+            planSlug: optionalPlanSlug
+          })
+          .strict()
+      },
+      async (input) => {
+        try {
+          const { dependsOn, dependedOnBy } =
+            await taskService.getTaskDependencyInfo(
+              input.taskId,
+              input.planSlug
+            );
+          const task = await taskService.getTask(input.taskId);
+          const preLines = dependsOn.map(
+            (t) => `- '${t.title}' (id: ${shortId(t.id)})`
+          );
+          const postLines = dependedOnBy.map(
+            (t) => `- '${t.title}' (id: ${shortId(t.id)})`
+          );
+          const text = [
+            `Dependencies for '${task.title}' (id: ${shortId(task.id)}):`,
+            "Depends on:",
+            preLines.length ? preLines.join("\n") : "(none)",
+            "Depended on by:",
+            postLines.length ? postLines.join("\n") : "(none)"
+          ].join("\n");
+          return {
+            content: [{ type: "text", text }],
+            structuredContent: jsonStructured({
+              task,
+              dependsOn,
+              dependedOnBy
+            })
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+
+    server.registerTool(
+      "update_task_dependencies",
+      {
+        description:
+          "Replaces the full prerequisite list for a task (depends-on edges). Validates acyclic graph within the plan. Guarded mutation.",
+        inputSchema: z
+          .object({
+            taskId: z.string().min(1),
+            dependsOnTaskIds: z.array(z.string()),
+            planSlug: optionalPlanSlug
+          })
+          .strict()
+      },
+      async (input) => {
+        try {
+          const guard = await guardToolExecution(
+            deps.authContextResolver,
+            deps.requestCorrelation,
+            deps.rateLimiter,
+            "update_task_dependencies"
+          );
+          await taskService.setTaskDependencies(
+            input.taskId,
+            input.dependsOnTaskIds,
+            input.planSlug
+          );
+          const task = await taskService.getTask(input.taskId);
+          writeToolAudit(
+            deps.auditLog,
+            "update_task_dependencies",
+            guard.principalId,
+            guard.correlationId,
+            input.taskId,
+            { count: input.dependsOnTaskIds.length }
+          );
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Task '${task.title}' dependencies set (${input.dependsOnTaskIds.length} edge(s)). (id: ${shortId(task.id)})`
+              }
+            ],
+            structuredContent: jsonStructured({
+              taskId: input.taskId,
+              dependsOnTaskIds: input.dependsOnTaskIds
+            })
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+  }
+};

package/src/mcp/plugins/types.ts

@@ -0,0 +1,45 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Plugin contracts for composing Sprintdock MCP tool registration.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ServiceSet } from "../../application/container.js";
+import type { AuditLog } from "../../infrastructure/observability/audit-log.js";
+import type { RequestCorrelation } from "../../infrastructure/observability/request-correlation.js";
+import type { AuthContextResolver } from "../../infrastructure/security/auth-context.js";
+import type { BackendRateLimiter } from "../../infrastructure/security/rate-limiter.js";
+import type { SprintdockMcpToolKit } from "./mcp-tool-kit.js";
+
+/** Injected services and security hooks for MCP tool handlers. */
+export interface SprintdockMcpToolDependencies {
+  services: ServiceSet;
+  auditLog: AuditLog;
+  rateLimiter: BackendRateLimiter;
+  requestCorrelation: RequestCorrelation;
+  authContextResolver: AuthContextResolver;
+}
+
+/** Context passed to each plugin's `register` method. */
+export interface SprintdockMcpPluginContext {
+  deps: SprintdockMcpToolDependencies;
+  kit: SprintdockMcpToolKit;
+}
+
+/**
+ * A plugin registers one or more MCP tools. Implement `id` for logging;
+ * use `register` to call `server.registerTool` like the built-in plugins.
+ */
+export interface SprintdockMcpToolPlugin {
+  readonly id: string;
+  register(server: McpServer, ctx: SprintdockMcpPluginContext): void;
+}
+
+/** Optional configuration when registering tools on the MCP server. */
+export interface RegisterSprintdockMcpToolsOptions {
+  /**
+   * Plugins to load, in order. Defaults to the full built-in Sprintdock set.
+   * Append custom plugins to add tools; pass a subset to expose only part of the API.
+   */
+  plugins?: SprintdockMcpToolPlugin[];
+}

package/src/mcp/register-sprintdock-mcp-tools.ts

@@ -0,0 +1,50 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Composes Sprintdock MCP tools from plugins (default set + optional extensions).
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  createSprintdockMcpToolKit,
+  defaultSprintdockMcpPlugins
+} from "./plugins/index.js";
+import type {
+  RegisterSprintdockMcpToolsOptions,
+  SprintdockMcpToolDependencies
+} from "./plugins/types.js";
+
+export type {
+  RegisterSprintdockMcpToolsOptions,
+  SprintdockMcpPluginContext,
+  SprintdockMcpToolDependencies,
+  SprintdockMcpToolKit,
+  SprintdockMcpToolPlugin
+} from "./plugins/index.js";
+
+export {
+  createSprintdockMcpToolKit,
+  defaultSprintdockMcpPlugins
+} from "./plugins/index.js";
+
+/**
+ * Registers MCP tools by running each plugin in order against the server.
+ *
+ * @example Add a custom tool plugin after the defaults:
+ * ```ts
+ * registerSprintdockMcpTools(server, deps, {
+ *   plugins: [...defaultSprintdockMcpPlugins, myCustomPlugin]
+ * });
+ * ```
+ */
+export function registerSprintdockMcpTools(
+  server: McpServer,
+  d: SprintdockMcpToolDependencies,
+  options?: RegisterSprintdockMcpToolsOptions
+): void {
+  const kit = createSprintdockMcpToolKit();
+  const ctx = { deps: d, kit };
+  const plugins = options?.plugins ?? [...defaultSprintdockMcpPlugins];
+  for (const plugin of plugins) {
+    plugin.register(server, ctx);
+  }
+}

package/src/mcp/sprintdock-mcp-capabilities.ts

@@ -0,0 +1,14 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: MCP capability flags for Sprintdock SQLite runtime.
+ */
+import type { ServerCapabilities } from "@modelcontextprotocol/sdk/types.js";
+
+/** Declares tool support for the v2 MCP server. */
+export const SPRINTDOCK_MCP_CAPABILITIES: ServerCapabilities = {
+  tools: {
+    listChanged: true
+  },
+  logging: {}
+};

package/src/mcp/sprintdock-mcp-runtime.ts

@@ -0,0 +1,119 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: MCP runtime: SQLite bootstrap, tool registration, stdio or HTTP transport.
+ */
+import { getEnv } from "@sprintdock/env-manager";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { resolveWorkspaceRoot } from "@sprintdock/shared";
+import { ConsoleAuditLog } from "../infrastructure/observability/audit-log.js";
+import { RequestCorrelation } from "../infrastructure/observability/request-correlation.js";
+import { LocalAuthContextResolver } from "../infrastructure/security/auth-context.js";
+import { InMemoryBackendRateLimiter } from "../infrastructure/security/rate-limiter.js";
+import { bootstrapSprintdockSqlite } from "./bootstrap-sprintdock-sqlite.js";
+import { registerSprintdockMcpTools, type SprintdockMcpToolDependencies } from "./register-sprintdock-mcp-tools.js";
+import { SPRINTDOCK_MCP_CAPABILITIES } from "./sprintdock-mcp-capabilities.js";
+import { runHttpTransport } from "./transports/http-entry.js";
+import { runStdioTransport } from "./transports/stdio-entry.js";
+
+export type SprintdockMcpTransportMode = "stdio" | "http";
+
+export interface SprintdockMcpRuntimeOptions {
+  transport?: SprintdockMcpTransportMode;
+  httpHost?: string;
+  httpPort?: number;
+}
+
+/**
+ * Runs Sprintdock MCP against the workspace SQLite database.
+ */
+export class SprintdockMcpRuntime {
+  private readonly options: Required<
+    Pick<SprintdockMcpRuntimeOptions, "transport">
+  > &
+    SprintdockMcpRuntimeOptions;
+
+  private readonly workspaceRoot: string;
+  private toolDeps: SprintdockMcpToolDependencies | null = null;
+
+  public constructor(options?: SprintdockMcpRuntimeOptions) {
+    this.workspaceRoot = resolveWorkspaceRoot();
+    const transportEnv = getEnv("SPRINTDOCK_MCP_TRANSPORT", "stdio", {
+      projectRoot: this.workspaceRoot
+    }) as SprintdockMcpTransportMode;
+    this.options = {
+      transport: options?.transport ?? transportEnv,
+      httpHost: options?.httpHost,
+      httpPort: options?.httpPort
+    };
+  }
+
+  /**
+   * Boots SQLite, registers tools, and starts the selected transport.
+   *
+   * @returns Process-style exit code (0 on success).
+   */
+  public async run(): Promise<number> {
+    const { services, dbPath } = await bootstrapSprintdockSqlite();
+    process.stderr.write(
+      `[sprintdock:backend:mcp] sqlite database: ${dbPath}\n`
+    );
+    this.toolDeps = {
+      services,
+      auditLog: new ConsoleAuditLog(),
+      rateLimiter: new InMemoryBackendRateLimiter(),
+      requestCorrelation: new RequestCorrelation(),
+      authContextResolver: new LocalAuthContextResolver()
+    };
+
+    if (this.options.transport === "http") {
+      const host =
+        this.options.httpHost ??
+        getEnv("SPRINTDOCK_MCP_HTTP_HOST", "127.0.0.1", {
+          projectRoot: this.workspaceRoot
+        });
+      const portRaw =
+        this.options.httpPort ??
+        Number(
+          getEnv("SPRINTDOCK_MCP_HTTP_PORT", "3030", {
+            projectRoot: this.workspaceRoot
+          })
+        );
+      if (!Number.isFinite(portRaw)) {
+        throw new Error("SPRINTDOCK_MCP_HTTP_PORT must be a valid number.");
+      }
+      return runHttpTransport(() => this.createMcpServer(), host, portRaw);
+    }
+
+    return runStdioTransport(this.createMcpServer());
+  }
+
+  private createMcpServer(): McpServer {
+    if (!this.toolDeps) {
+      throw new Error("SprintdockMcpRuntime tool dependencies not initialized");
+    }
+    const server = new McpServer(
+      {
+        name: "sprintdock-backend",
+        version: "0.2.0"
+      },
+      {
+        capabilities: SPRINTDOCK_MCP_CAPABILITIES,
+        instructions:
+          "Sprintdock MCP (SQLite): data lives in .sprintdock/sprintdock.db. Use list_plans / create_plan / set_active_plan. Optional planSlug on sprint/task tools scopes to that plan. Plan/sprint/task tools include update_plan_markdown and update_sprint_markdown for long-form notes."
+      }
+    );
+    registerSprintdockMcpTools(server, this.toolDeps);
+    return server;
+  }
+}
+
+/**
+ * Convenience entrypoint for `apps/server` and scripts.
+ */
+export async function runSprintdockMcpServer(
+  options?: SprintdockMcpRuntimeOptions
+): Promise<number> {
+  const runtime = new SprintdockMcpRuntime(options);
+  return runtime.run();
+}

package/src/mcp/tool-guard.ts

@@ -0,0 +1,58 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: MCP tool authorization guard and audit helpers (stdio transport).
+ */
+import type { AuditLog } from "../infrastructure/observability/audit-log.js";
+import type { RequestCorrelation } from "../infrastructure/observability/request-correlation.js";
+import type { AuthContextResolver } from "../infrastructure/security/auth-context.js";
+import type { BackendRateLimiter } from "../infrastructure/security/rate-limiter.js";
+
+export interface ToolGuardResult {
+  principalId: string;
+  correlationId: string;
+}
+
+/**
+ * Resolves auth context, creates correlation id, and enforces per-principal rate limits.
+ */
+export async function guardToolExecution(
+  authContextResolver: AuthContextResolver,
+  requestCorrelation: RequestCorrelation,
+  rateLimiter: BackendRateLimiter,
+  toolName: string
+): Promise<ToolGuardResult> {
+  const authContext = await authContextResolver.resolve("stdio");
+  const correlationId = requestCorrelation.create();
+  const rateLimit = rateLimiter.check(`${authContext.principalId}:${toolName}`);
+  if (!rateLimit.allowed) {
+    throw new Error(
+      `Rate limit exceeded for tool '${toolName}'. Retry after ${rateLimit.retryAfterSeconds}s.`
+    );
+  }
+  return {
+    principalId: authContext.principalId,
+    correlationId
+  };
+}
+
+/**
+ * Writes an audit record for a tool invocation.
+ */
+export function writeToolAudit(
+  auditLog: AuditLog,
+  action: string,
+  principalId: string,
+  correlationId: string,
+  resourceId?: string,
+  metadata?: Record<string, unknown>
+): void {
+  auditLog.write({
+    action,
+    principalId,
+    transport: "stdio",
+    resourceId,
+    correlationId,
+    metadata
+  });
+}

package/src/mcp/transports/http-app-factory.ts

@@ -0,0 +1,31 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Express app with streamable HTTP MCP endpoint at `/mcp`.
+ */
+import { randomUUID } from "node:crypto";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import type { Request, Response } from "express";
+
+/**
+ * Builds an Express app that serves MCP over streamable HTTP at `/mcp`.
+ */
+export function createSprintdockMcpHttpApp(
+  serverFactory: () => McpServer,
+  host: string
+) {
+  const app = createMcpExpressApp({ host });
+
+  app.use("/mcp", async (request: Request, response: Response) => {
+    const server = serverFactory();
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID()
+    });
+    await server.connect(transport);
+    await transport.handleRequest(request, response);
+  });
+
+  return app;
+}

package/src/mcp/transports/http-entry.ts

@@ -0,0 +1,27 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Streamable HTTP MCP transport bootstrap.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createSprintdockMcpHttpApp } from "./http-app-factory.js";
+
+/**
+ * Listens for MCP HTTP traffic on the given host/port (`/mcp`).
+ */
+export async function runHttpTransport(
+  serverFactory: () => McpServer,
+  host: string,
+  port: number
+): Promise<number> {
+  const app = createSprintdockMcpHttpApp(serverFactory, host);
+  await new Promise<void>((resolve) => {
+    app.listen(port, host, () => {
+      process.stderr.write(
+        `[sprintdock:backend:mcp] streamable-http listening at http://${host}:${port}/mcp\n`
+      );
+      resolve();
+    });
+  });
+  return 0;
+}

package/src/mcp/transports/stdio-entry.ts

@@ -0,0 +1,17 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Stdio MCP transport bootstrap.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+/**
+ * Connects the MCP server to stdio and blocks for the process lifetime.
+ */
+export async function runStdioTransport(server: McpServer): Promise<number> {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write("[sprintdock:backend:mcp] stdio transport connected\n");
+  return 0;
+}

package/tests/application/container.test.ts

@@ -0,0 +1,36 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Tests for createApplicationServices wiring.
+ */
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { createApplicationServices } from "../../src/application/container.js";
+import { createRepositories } from "../../src/infrastructure/repositories/repository-factory.js";
+import { createTestDb } from "../helpers/test-db.js";
+
+test("createApplicationServices returns working plan, sprint, and task services", async () => {
+  const db = await createTestDb();
+  const repos = createRepositories("sqlite", { sqlite: { db } });
+  const { planService, sprintService, taskService } =
+    createApplicationServices(repos);
+
+  const plan = await planService.createPlan({ slug: "c", title: "C" });
+  const sp = await sprintService.createSprint(plan.slug, {
+    slug: "sp",
+    planId: plan.id,
+    name: "S",
+    goal: "G"
+  });
+  const task = await taskService.createTask(
+    {
+      sprintId: sp.id,
+      title: "T",
+      priority: "low"
+    },
+    plan.slug
+  );
+  assert.equal(task.sprintId, sp.id);
+  const listed = await taskService.listTasks(undefined, plan.slug);
+  assert.equal(listed.length, 1);
+});