@mandujs/mcp 0.24.0 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/mcp",
-  "version": "0.24.0",
+  "version": "0.27.0",
   "description": "Mandu MCP Server - Agent-native interface for Mandu framework operations",
   "type": "module",
   "main": "./src/index.ts",
@@ -34,9 +34,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@mandujs/core": "^0.37.0",
-    "@mandujs/ate": "^0.21.0",
-    "@mandujs/skills": "^16.0.0",
+    "@mandujs/core": "^0.39.0",
+    "@mandujs/ate": "^0.24.0",
+    "@mandujs/skills": "^17.0.0",
     "@modelcontextprotocol/sdk": "^1.25.3"
   },
   "engines": {

package/src/tools/ate-boundary-probe.ts

@@ -0,0 +1,109 @@
+/**
+ * `mandu_ate_boundary_probe` — Phase B.1 deterministic boundary-value
+ * generator for Zod contracts.
+ *
+ * See docs/ate/phase-b-spec.md §B.1 for the full I/O shape. Agents
+ * feed the returned probe set into `mandu_ate_prompt({ kind:
+ * "property_based" })` to produce adversarial specs.
+ *
+ * Snake_case tool name (§11 decision #4). Read-only.
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { generateBoundaryProbes } from "@mandujs/ate";
+
+export const ateBoundaryProbeToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_boundary_probe",
+    annotations: {
+      readOnlyHint: true,
+    },
+    description:
+      "Phase B.1 deterministic boundary probe for Zod contracts. Reads a " +
+      "*.contract.ts file, parses request-body schemas per HTTP method, and " +
+      "returns a deterministic set of probe values per field — one per " +
+      "category (valid / invalid_format / boundary_min / boundary_max / " +
+      "empty / null / type_mismatch / enum_reject / missing_required). " +
+      "Every probe also carries the expectedStatus code derived from the " +
+      "contract's response map (400/422 for invalid, 200/201 for valid). " +
+      "The output is stamped with graphVersion for agent cache " +
+      "invalidation. No LLM. No runtime Zod evaluation — source text is " +
+      "parsed directly. Default depth 1, max 3.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: {
+          type: "string",
+          description: "Absolute path to the Mandu project root.",
+        },
+        contractName: {
+          type: "string",
+          description:
+            "Contract identifier. Usually the basename of the contract file (e.g. 'SignupContract' or 'api-signup').",
+        },
+        contractFile: {
+          type: "string",
+          description: "Direct absolute path to the contract file (bypasses name resolution).",
+        },
+        method: {
+          type: "string",
+          enum: ["GET", "POST", "PUT", "PATCH", "DELETE"],
+          description: "Optional HTTP method filter. Omit to probe every declared method.",
+        },
+        depth: {
+          type: "number",
+          description: "Recursion depth for nested z.object() fields. Default 1, max 3.",
+        },
+      },
+      required: ["repoRoot"],
+    },
+  },
+];
+
+export function ateBoundaryProbeTools(_projectRoot: string) {
+  return {
+    mandu_ate_boundary_probe: async (args: Record<string, unknown>) => {
+      const repoRoot = args.repoRoot as string | undefined;
+      const contractName = args.contractName as string | undefined;
+      const contractFile = args.contractFile as string | undefined;
+      const method = args.method as
+        | "GET"
+        | "POST"
+        | "PUT"
+        | "PATCH"
+        | "DELETE"
+        | undefined;
+      const depth = typeof args.depth === "number" ? args.depth : undefined;
+
+      if (!repoRoot || typeof repoRoot !== "string") {
+        return { ok: false, error: "repoRoot is required" };
+      }
+      if (!contractName && !contractFile) {
+        return { ok: false, error: "contractName or contractFile is required" };
+      }
+
+      try {
+        const result = await generateBoundaryProbes({
+          repoRoot,
+          contractName,
+          contractFile,
+          ...(method ? { method } : {}),
+          ...(depth !== undefined ? { depth } : {}),
+        });
+        return {
+          ok: true,
+          contractName: result.contractName,
+          contractFile: result.contractFile,
+          graphVersion: result.graphVersion,
+          probes: result.probes,
+          warnings: result.warnings,
+        };
+      } catch (err) {
+        return {
+          ok: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    },
+  };
+}

package/src/tools/ate-context.ts

@@ -1,96 +1,173 @@
-/**
- * `mandu_ate_context` — Phase A.1 agent-native context tool.
- *
- * See `docs/ate/roadmap-v2-agent-native.md` §4.1 for the full design
- * and §11 decision 4 for the naming convention (snake_case).
- *
- * Semantics: return a single JSON blob that an LLM-driven agent
- * (Cursor / Claude Code / Codex) can read *before* generating a test.
- * The blob fuses:
- *
- *   1. Route metadata (pattern, file, isRedirect, static params)
- *   2. Contract surface (request/response schemas + examples)
- *   3. Middleware chain (canonical name + options + file)
- *   4. Guard preset + suggested data-route-id selectors
- *   5. Fixture recommendations (createTestSession, createTestDb, ...)
- *   6. Existing specs (user-written vs ate-generated, last-run status)
- *   7. Related routes (siblings + ui-entry-point pairing)
- *
- * The handler itself is deliberately thin — almost all work is done
- * inside `@mandujs/ate`'s `buildContext` so the same logic is
- * importable from non-MCP callers (CLI, tests).
- */
-import type { Tool } from "@modelcontextprotocol/sdk/types.js";
-import { ateContext } from "@mandujs/ate";
-
-export const ateContextToolDefinitions: Tool[] = [
-  {
-    name: "mandu_ate_context",
-    annotations: {
-      readOnlyHint: true,
-    },
-    description:
-      "Phase A.1 agent-native context. Returns a single JSON blob containing the " +
-      "Mandu-specific semantic context an LLM needs to write a correct test: " +
-      "route metadata, contract (with examples), middleware chain, guard preset + " +
-      "suggested [data-route-id] selectors, recommended @mandujs/core/testing fixtures, " +
-      "existing specs (with last-run status when .mandu/ate-last-run.json is present), " +
-      "and related routes (sibling + ui-entry-point pairing). " +
-      "Scope values: " +
-      "'project' = repo summary with route + coverage counts; " +
-      "'route' = single-route deep view (requires id or route); " +
-      "'filling' = server-handler view with middleware + actions (requires id); " +
-      "'contract' = request/response + examples for a contract definition. " +
-      "Run mandu.ate.extract first — this tool reads .mandu/interaction-graph.json.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        repoRoot: {
-          type: "string",
-          description: "Absolute path to the Mandu project root",
-        },
-        scope: {
-          type: "string",
-          enum: ["project", "route", "filling", "contract"],
-          description:
-            "project (summary) | route (single route deep view) | filling (handler view) | contract (contract definition view)",
-        },
-        id: {
-          type: "string",
-          description:
-            "Route id ('api-signup'), filling id ('filling:api-signup'), or contract name. Optional — supply id OR route.",
-        },
-        route: {
-          type: "string",
-          description:
-            "Route pattern match (e.g. '/api/signup'). Optional — supply id OR route.",
-        },
-      },
-      required: ["repoRoot", "scope"],
-    },
-  },
-];
-
-export function ateContextTools(_projectRoot: string) {
-  return {
-    mandu_ate_context: async (args: Record<string, unknown>) => {
-      const { repoRoot, scope, id, route } = args as {
-        repoRoot: string;
-        scope: "project" | "route" | "filling" | "contract";
-        id?: string;
-        route?: string;
-      };
-      // Minimal validation — the MCP SDK already enforces the schema,
-      // but we guard repoRoot explicitly so mis-invocations surface a
-      // loud error rather than a cascading filesystem failure.
-      if (!repoRoot || typeof repoRoot !== "string") {
-        return { ok: false, error: "repoRoot is required" };
-      }
-      if (!scope) {
-        return { ok: false, error: "scope is required" };
-      }
-      const blob = await ateContext({ repoRoot, scope, id, route });
-      return { ok: true, context: blob };
-    },
-  };
-}
+/**
+ * `mandu_ate_context` — Phase A.1 agent-native context tool.
+ *
+ * See `docs/ate/roadmap-v2-agent-native.md` §4.1 for the full design
+ * and §11 decision 4 for the naming convention (snake_case).
+ *
+ * Semantics: return a single JSON blob that an LLM-driven agent
+ * (Cursor / Claude Code / Codex) can read *before* generating a test.
+ * The blob fuses:
+ *
+ *   1. Route metadata (pattern, file, isRedirect, static params)
+ *   2. Contract surface (request/response schemas + examples)
+ *   3. Middleware chain (canonical name + options + file)
+ *   4. Guard preset + suggested data-route-id selectors
+ *   5. Fixture recommendations (createTestSession, createTestDb, ...)
+ *   6. Existing specs (user-written vs ate-generated, last-run status)
+ *   7. Related routes (siblings + ui-entry-point pairing)
+ *
+ * The handler itself is deliberately thin — almost all work is done
+ * inside `@mandujs/ate`'s `buildContext` so the same logic is
+ * importable from non-MCP callers (CLI, tests).
+ */
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import {
+  ateContext,
+  appendMemoryEvent,
+  nowTimestamp,
+  readMemoryEvents,
+  buildRpcContext,
+} from "@mandujs/ate";
+
+export const ateContextToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_context",
+    annotations: {
+      readOnlyHint: true,
+    },
+    description:
+      "Phase A.1 agent-native context. Returns a single JSON blob containing the " +
+      "Mandu-specific semantic context an LLM needs to write a correct test: " +
+      "route metadata, contract (with examples), middleware chain, guard preset + " +
+      "suggested [data-route-id] selectors, recommended @mandujs/core/testing fixtures, " +
+      "existing specs (with last-run status when .mandu/ate-last-run.json is present), " +
+      "and related routes (sibling + ui-entry-point pairing). " +
+      "Scope values: " +
+      "'project' = repo summary with route + coverage counts; " +
+      "'route' = single-route deep view (requires id or route); " +
+      "'filling' = server-handler view with middleware + actions (requires id); " +
+      "'contract' = request/response + examples for a contract definition. " +
+      "Run mandu.ate.extract first — this tool reads .mandu/interaction-graph.json.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: {
+          type: "string",
+          description: "Absolute path to the Mandu project root",
+        },
+        scope: {
+          type: "string",
+          enum: ["project", "route", "filling", "contract", "rpc"],
+          description:
+            "project (summary) | route (single route deep view) | filling (handler view) | contract (contract definition view) | rpc (typed RPC procedure view — Phase C.3)",
+        },
+        id: {
+          type: "string",
+          description:
+            "Route id ('api-signup'), filling id ('filling:api-signup'), or contract name. Optional — supply id OR route.",
+        },
+        route: {
+          type: "string",
+          description:
+            "Route pattern match (e.g. '/api/signup'). Optional — supply id OR route.",
+        },
+      },
+      required: ["repoRoot", "scope"],
+    },
+  },
+];
+
+export function ateContextTools(_projectRoot: string) {
+  return {
+    mandu_ate_context: async (args: Record<string, unknown>) => {
+      const { repoRoot, scope, id, route } = args as {
+        repoRoot: string;
+        scope: "project" | "route" | "filling" | "contract" | "rpc";
+        id?: string;
+        route?: string;
+      };
+      // Minimal validation — the MCP SDK already enforces the schema,
+      // but we guard repoRoot explicitly so mis-invocations surface a
+      // loud error rather than a cascading filesystem failure.
+      if (!repoRoot || typeof repoRoot !== "string") {
+        return { ok: false, error: "repoRoot is required" };
+      }
+      if (!scope) {
+        return { ok: false, error: "scope is required" };
+      }
+
+      // Phase C.3 — `scope: "rpc"` delegates to the RPC extractor + context builder.
+      if (scope === "rpc") {
+        if (!id) {
+          return {
+            ok: false,
+            error: "scope='rpc' requires `id` (e.g. 'users.signup' or 'signup')",
+          };
+        }
+        const blob = await buildRpcContext({ repoRoot, id });
+        return { ok: true, context: blob };
+      }
+
+      const blob = await ateContext({ repoRoot, scope, id, route });
+
+      // Phase B.2 — first `mandu_ate_context` call of the day writes a
+      // `coverage_snapshot` event (best-effort). The snapshot is derived
+      // from the `project`-scope blob summary; for other scopes we still
+      // fire the snapshot (using scope==='project' would require an
+      // extra call — the project summary's field presence is enough).
+      try {
+        if (!snapshottedToday(repoRoot)) {
+          const withSpec = countWithSpec(blob);
+          const withProperty = 0; // Phase B — property-test detection is part of `mandu_ate_coverage`.
+          const totalRoutes = countTotalRoutes(blob);
+          appendMemoryEvent(repoRoot, {
+            kind: "coverage_snapshot",
+            timestamp: nowTimestamp(),
+            routes: totalRoutes,
+            withSpec,
+            withProperty,
+          });
+        }
+      } catch {
+        // swallow — snapshot is best-effort.
+      }
+
+      return { ok: true, context: blob };
+    },
+  };
+}
+
+function snapshottedToday(repoRoot: string): boolean {
+  try {
+    const events = readMemoryEvents(repoRoot);
+    const today = new Date().toISOString().slice(0, 10);
+    return events.some(
+      (e) => e.kind === "coverage_snapshot" && e.timestamp.slice(0, 10) === today,
+    );
+  } catch {
+    return false;
+  }
+}
+
+function countTotalRoutes(blob: unknown): number {
+  if (!blob || typeof blob !== "object") return 0;
+  const b = blob as { scope?: string; summary?: { routes?: number }; route?: unknown };
+  if (b.scope === "project" && b.summary && typeof b.summary.routes === "number") {
+    return b.summary.routes;
+  }
+  // Non-project scope — we can't meaningfully count; leave 0 so the snapshot
+  // still records the timestamp without lying about totals.
+  return 0;
+}
+
+function countWithSpec(blob: unknown): number {
+  if (!blob || typeof blob !== "object") return 0;
+  const b = blob as {
+    scope?: string;
+    routes?: Array<{ existingSpecCount: number }>;
+  };
+  if (b.scope === "project" && Array.isArray(b.routes)) {
+    return b.routes.filter((r) => (r.existingSpecCount ?? 0) > 0).length;
+  }
+  return 0;
+}

package/src/tools/ate-coverage.ts

@@ -0,0 +1,71 @@
+/**
+ * `mandu_ate_coverage` — Phase B.4 quantified gap report.
+ *
+ * See docs/ate/phase-b-spec.md §B.5 for the output shape. Agents call
+ * this to discover `topGaps` and prioritize spec generation work.
+ *
+ * Snake_case (§11 decision #4). Read-only.
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { computeCoverage } from "@mandujs/ate";
+
+export const ateCoverageToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_coverage",
+    annotations: {
+      readOnlyHint: true,
+    },
+    description:
+      "Phase B.4 coverage metrics. Returns the 3-axis coverage report: " +
+      "(1) routes with unit / integration / e2e spec; (2) contracts with " +
+      "full / partial / no boundary-probe coverage; (3) middleware " +
+      "invariants (csrf / rate-limit / session / auth / i18n) tagged as " +
+      "covered / partial / missing. Also returns a `topGaps` list sorted " +
+      "high → medium → low severity. Stamped with graphVersion for " +
+      "agent cache invalidation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: {
+          type: "string",
+          description: "Absolute path to the Mandu project root.",
+        },
+        scope: {
+          type: "string",
+          enum: ["project", "route", "contract"],
+          description:
+            "Default 'project'. Use 'route' (with target=routeId) or 'contract' (with target=contractName) for narrow scans.",
+        },
+        target: {
+          type: "string",
+          description: "Route id or contract basename when scope is not 'project'.",
+        },
+      },
+      required: ["repoRoot"],
+    },
+  },
+];
+
+export function ateCoverageTools(_projectRoot: string) {
+  return {
+    mandu_ate_coverage: async (args: Record<string, unknown>) => {
+      const repoRoot = args.repoRoot as string | undefined;
+      if (!repoRoot || typeof repoRoot !== "string") {
+        return { ok: false, error: "repoRoot is required" };
+      }
+      const scope = args.scope as "project" | "route" | "contract" | undefined;
+      const target = typeof args.target === "string" ? args.target : undefined;
+
+      try {
+        const metrics = await computeCoverage(repoRoot, {
+          scope: scope ?? "project",
+          ...(target ? { target } : {}),
+        });
+        return { ok: true, ...metrics };
+      } catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+      }
+    },
+  };
+}

package/src/tools/ate-mutate.ts

@@ -0,0 +1,103 @@
+/**
+ * `mandu_ate_mutate` — Phase C.2 contract-semantic mutation runner.
+ *
+ * Runs up to 9 mutation operators on a single target file and executes
+ * the repo's test command against each mutation. Classifies results as
+ * killed / survived / timeout / error and persists
+ * `.mandu/ate-mutations/last-run.json` for `mandu_ate_mutation_report`.
+ *
+ * Spec: docs/ate/phase-c-spec.md §C.2.
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { runMutations } from "@mandujs/ate";
+
+export const ateMutateToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_mutate",
+    annotations: {
+      readOnlyHint: false,
+    },
+    description:
+      "Phase C.2 — run contract-semantic mutation testing on a target file. " +
+      "9 operators: remove_required_field, narrow_type, widen_enum, flip_nullable, " +
+      "rename_field, swap_sibling_type, skip_middleware, early_return, bypass_validation. " +
+      "Each mutation is written to the target file, the repo's test command runs " +
+      "against it, and the result is classified killed / survived / timeout / error. " +
+      "Default cap 50 mutations per invocation; pass `--all` or maxMutations to lift. " +
+      "The original file is always restored. Persists .mandu/ate-mutations/last-run.json.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: {
+          type: "string",
+          description: "Absolute path to the Mandu project root.",
+        },
+        targetFile: {
+          type: "string",
+          description:
+            "Absolute or repo-relative path to the file to mutate (contract, handler, or filling).",
+        },
+        testCommand: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Optional override for the test command (argv form). Default: resolved from spec-indexer.",
+        },
+        timeoutMs: {
+          type: "number",
+          description: "Per-mutation timeout in ms. Default 120000.",
+        },
+        maxMutations: {
+          type: "number",
+          description: "Cap on the number of mutations executed. Default 50.",
+        },
+        operators: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Optional subset of operator names. Default = all 9. Pass [] to skip execution.",
+        },
+      },
+      required: ["repoRoot", "targetFile"],
+    },
+  },
+];
+
+export function ateMutateTools(_projectRoot: string) {
+  return {
+    mandu_ate_mutate: async (args: Record<string, unknown>) => {
+      const repoRoot = args.repoRoot as string | undefined;
+      const targetFile = args.targetFile as string | undefined;
+      if (!repoRoot || typeof repoRoot !== "string") {
+        return { ok: false, error: "repoRoot is required" };
+      }
+      if (!targetFile || typeof targetFile !== "string") {
+        return { ok: false, error: "targetFile is required" };
+      }
+      try {
+        const result = await runMutations({
+          repoRoot,
+          targetFile,
+          ...(Array.isArray(args.testCommand) ? { testCommand: args.testCommand as string[] } : {}),
+          ...(typeof args.timeoutMs === "number" ? { timeoutMs: args.timeoutMs } : {}),
+          ...(typeof args.maxMutations === "number" ? { maxMutations: args.maxMutations } : {}),
+          ...(Array.isArray(args.operators) ? { operators: args.operators as never } : {}),
+        });
+        return {
+          ok: true,
+          targetFile: result.targetFile,
+          totalGenerated: result.totalGenerated,
+          totalExecuted: result.totalExecuted,
+          reportPath: result.reportPath,
+          results: result.results,
+        };
+      } catch (err) {
+        return {
+          ok: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    },
+  };
+}

package/src/tools/ate-mutation-report.ts

@@ -0,0 +1,64 @@
+/**
+ * `mandu_ate_mutation_report` — Phase C.2.
+ *
+ * Read the persisted last mutation run and compute an aggregate report:
+ * killed / survived / timeout counts, mutationScore, survivors ranked by
+ * severity + reason.
+ *
+ * Read-only. Never spawns a child process.
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { computeMutationReport, loadLastMutationRun } from "@mandujs/ate";
+
+export const ateMutationReportToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_mutation_report",
+    annotations: {
+      readOnlyHint: true,
+    },
+    description:
+      "Phase C.2 — aggregate the last `mandu_ate_mutate` run into a summary report. " +
+      "Returns { totalMutations, killed, survived, timeout, mutationScore, " +
+      "survivorsBySeverity, byOperator }. Severity: skip_middleware + " +
+      "bypass_validation = high; narrow_type / swap_sibling_type / rename_field = " +
+      "medium; everything else = low.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: {
+          type: "string",
+          description: "Absolute path to the Mandu project root.",
+        },
+      },
+      required: ["repoRoot"],
+    },
+  },
+];
+
+export function ateMutationReportTools(_projectRoot: string) {
+  return {
+    mandu_ate_mutation_report: async (args: Record<string, unknown>) => {
+      const repoRoot = args.repoRoot as string | undefined;
+      if (!repoRoot || typeof repoRoot !== "string") {
+        return { ok: false, error: "repoRoot is required" };
+      }
+      const loaded = loadLastMutationRun(repoRoot);
+      if (!loaded) {
+        return {
+          ok: false,
+          error:
+            "No mutation run found. Run mandu_ate_mutate first — the persisted report lives at .mandu/ate-mutations/last-run.json.",
+        };
+      }
+      const report = computeMutationReport(loaded.results);
+      return {
+        ok: true,
+        targetFile: loaded.targetFile,
+        generatedAt: loaded.generatedAt,
+        totalGenerated: loaded.totalGenerated,
+        report,
+      };
+    },
+  };
+}