@mandujs/mcp 0.23.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/mcp",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Mandu MCP Server - Agent-native interface for Mandu framework operations",
   "type": "module",
   "main": "./src/index.ts",
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@mandujs/core": "^0.37.0",
-    "@mandujs/ate": "^0.20.0",
+    "@mandujs/ate": "^0.22.0",
     "@mandujs/skills": "^16.0.0",
     "@modelcontextprotocol/sdk": "^1.25.3"
   },

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,159 @@
-/**
- * `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,
+} 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 });
+
+      // 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-exemplar.ts

@@ -0,0 +1,92 @@
+/**
+ * `mandu_ate_exemplar` — Phase A.3 exemplar browser.
+ *
+ * See `docs/ate/roadmap-v2-agent-native.md` §4.3. Returns the
+ * `@ate-exemplar:` tagged tests for a given kind so an agent can
+ * few-shot against them without paying the "compose the whole prompt"
+ * token cost.
+ *
+ * Snake_case tool name (§11 decision #4). Read-only.
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { scanExemplars, type Exemplar } from "@mandujs/ate";
+
+export const ateExemplarToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_exemplar",
+    annotations: {
+      readOnlyHint: true,
+    },
+    description:
+      "Phase A.3 agent-native exemplar browser. Returns up to `limit` tests " +
+      "tagged with `@ate-exemplar: kind=<kind>` from the repo. Each entry " +
+      "carries the file path, start/end line, tags, and the full source of the " +
+      "test() / it() / describe() call that follows the tag. Set " +
+      "includeAnti:true to also surface `@ate-exemplar-anti:` (DO-NOT-do-this) " +
+      "cases. Exemplars are manually curated (roadmap §11 decision 2) — no " +
+      "auto-heuristic. Use this when you want few-shot examples without paying " +
+      "for the full composed prompt.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: {
+          type: "string",
+          description: "Absolute path to the Mandu project root.",
+        },
+        kind: {
+          type: "string",
+          description:
+            "Match against the tag's `kind=` attribute. Examples: filling_unit, filling_integration, e2e_playwright.",
+        },
+        limit: {
+          type: "number",
+          description: "Max entries to return. Default 5.",
+        },
+        includeAnti: {
+          type: "boolean",
+          description:
+            "Also include @ate-exemplar-anti markers (default false — only positive exemplars).",
+        },
+      },
+      required: ["repoRoot", "kind"],
+    },
+  },
+];
+
+export function ateExemplarTools(_projectRoot: string) {
+  return {
+    mandu_ate_exemplar: async (args: Record<string, unknown>) => {
+      const repoRoot = args.repoRoot as string | undefined;
+      const kind = args.kind as string | undefined;
+      const limit = typeof args.limit === "number" ? args.limit : 5;
+      const includeAnti = args.includeAnti === true;
+
+      if (!repoRoot || typeof repoRoot !== "string") {
+        return { ok: false, error: "'repoRoot' is required" };
+      }
+      if (!kind || typeof kind !== "string") {
+        return { ok: false, error: "'kind' is required" };
+      }
+
+      try {
+        const all = await scanExemplars(repoRoot);
+        const filtered = all.filter((e) => e.kind === kind);
+        const selected: Exemplar[] = [];
+        const positives = filtered.filter((e) => !e.anti).slice(0, limit);
+        selected.push(...positives);
+        if (includeAnti) {
+          // Reserve up to half the limit for antis so positives aren't crowded out.
+          const antiBudget = Math.max(1, Math.floor(limit / 2));
+          const antis = filtered.filter((e) => e.anti).slice(0, antiBudget);
+          selected.push(...antis);
+        }
+
+        return { ok: true, exemplars: selected, total: filtered.length };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: msg };
+      }
+    },
+  };
+}

package/src/tools/ate-flakes.ts

@@ -0,0 +1,90 @@
+/**
+ * `mandu_ate_flakes` — Phase A.2 flake detector surface.
+ *
+ * Returns every spec whose rolling pass/fail transition ratio exceeds
+ * `minScore` (default 0.1) within the last `windowSize` runs
+ * (default 20). Agents use this to prioritize stabilization work.
+ *
+ * Data source: `.mandu/ate-run-history.jsonl`, appended to by
+ * `runSpec`. When no history is present we return an empty array —
+ * not an error.
+ *
+ * Snake_case naming per §11 decision 4.
+ */
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { summarizeFlakes } from "@mandujs/ate";
+
+export const ateFlakesToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_flakes",
+    annotations: {
+      readOnlyHint: true,
+    },
+    description:
+      "Phase A.2 flake detector. Reads `.mandu/ate-run-history.jsonl` and returns specs " +
+      "whose pass/fail status flips often within the rolling window. `flakeScore` = " +
+      "status_transitions / (N - 1) over last `windowSize` non-skipped runs. " +
+      "Pure-pass PPPPP = 0.0 (stable), pure-fail FFFFF = 0.0 (broken, NOT flaky), " +
+      "alternating PFPF = 1.0. Returns an empty list when history is empty or no spec " +
+      "clears `minScore`. Use this to prioritize which flaky tests to fix first — feed " +
+      "a specPath from the result into mandu_ate_run for a re-run + full failure.v1 " +
+      "diagnostic.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: {
+          type: "string",
+          description: "Absolute path to the Mandu project root",
+        },
+        windowSize: {
+          type: "number",
+          minimum: 2,
+          description: "Rolling window size. Default: 20.",
+        },
+        minScore: {
+          type: "number",
+          minimum: 0,
+          maximum: 1,
+          description: "Filter threshold for flakeScore. Default: 0.1.",
+        },
+      },
+      required: ["repoRoot"],
+    },
+  },
+];
+
+export function ateFlakesTools(_projectRoot: string) {
+  return {
+    mandu_ate_flakes: async (args: Record<string, unknown>) => {
+      const { repoRoot, windowSize, minScore } = args as {
+        repoRoot: string;
+        windowSize?: number;
+        minScore?: number;
+      };
+      if (!repoRoot || typeof repoRoot !== "string") {
+        return { ok: false, error: "repoRoot is required" };
+      }
+      if (typeof windowSize === "number" && windowSize < 2) {
+        return { ok: false, error: "windowSize must be >= 2" };
+      }
+      if (
+        typeof minScore === "number" &&
+        (minScore < 0 || minScore > 1 || !Number.isFinite(minScore))
+      ) {
+        return { ok: false, error: "minScore must be in [0, 1]" };
+      }
+      try {
+        const flakyTests = summarizeFlakes(repoRoot, {
+          windowSize,
+          minScore,
+        });
+        return { ok: true, flakyTests };
+      } catch (err) {
+        return {
+          ok: false,
+          error: `summarizeFlakes failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+      }
+    },
+  };
+}