@mandujs/mcp 0.22.4 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/mcp",
-  "version": "0.22.4",
+  "version": "0.24.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.19.2",
+    "@mandujs/ate": "^0.21.0",
     "@mandujs/skills": "^16.0.0",
     "@modelcontextprotocol/sdk": "^1.25.3"
   },

package/src/tools/ate-context.ts

@@ -0,0 +1,96 @@
+/**
+ * `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 };
+    },
+  };
+}

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)}`,
+        };
+      }
+    },
+  };
+}

package/src/tools/ate-prompt.ts

@@ -0,0 +1,146 @@
+/**
+ * `mandu_ate_prompt` — Phase A.3 prompt catalog tool.
+ *
+ * See `docs/ate/roadmap-v2-agent-native.md` §4.2 and §7 (A.3 extension
+ * "Pre-composed prompts") for the design.
+ *
+ * Semantics:
+ *   - If `context` is provided, the handler composes the full prompt
+ *     (template + matched exemplars + serialized context) and returns
+ *     a single ready-to-send-to-LLM string.
+ *   - If `context` is omitted, the handler returns the raw template body +
+ *     sha256 + a peek at available exemplars — the agent composes.
+ *
+ * Snake_case tool name (§11 decision #4). Read-only.
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import {
+  loadPrompt,
+  scanExemplars,
+  composePrompt,
+  type Exemplar,
+} from "@mandujs/ate";
+
+export const atePromptToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_prompt",
+    annotations: {
+      readOnlyHint: true,
+    },
+    description:
+      "Phase A.3 agent-native prompt catalog. Returns the system prompt for a " +
+      "given test kind, with Mandu-specific primitives, anti-patterns, and the " +
+      "selector convention baked in. When `context` is passed, the handler " +
+      "also injects up-to-3 matching exemplars (tagged with @ate-exemplar:) " +
+      "plus the JSON context block and returns a fully composed, ready-to-" +
+      "send-to-LLM string. When `context` is omitted, the handler returns the " +
+      "raw template + the separate exemplar list so the agent can compose. " +
+      "Kinds available in v1: filling_unit, filling_integration, e2e_playwright. " +
+      "The returned sha256 is stable per-version and safe as a cache key.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: {
+          type: "string",
+          description:
+            "Absolute path to the Mandu project root. Required when context is " +
+            "omitted so we can scan exemplars from the repo.",
+        },
+        kind: {
+          type: "string",
+          description:
+            "Prompt kind. v1 catalog: filling_unit | filling_integration | e2e_playwright.",
+        },
+        version: {
+          type: "number",
+          description:
+            "Pin to a specific template version. Defaults to the highest available.",
+        },
+        context: {
+          type: "object",
+          description:
+            "Optional semantic context (usually the output of mandu_ate_context). " +
+            "When present, the returned `prompt` is pre-composed.",
+          additionalProperties: true,
+        },
+        maxPositive: {
+          type: "number",
+          description: "Max positive exemplars to inject. Default 3.",
+        },
+        maxAnti: {
+          type: "number",
+          description: "Max anti-exemplars to inject. Default 1.",
+        },
+      },
+      required: ["kind"],
+    },
+  },
+];
+
+export function atePromptTools(_projectRoot: string) {
+  return {
+    mandu_ate_prompt: async (args: Record<string, unknown>) => {
+      const kind = args.kind as string | undefined;
+      if (!kind || typeof kind !== "string") {
+        return { ok: false, error: "'kind' is required and must be a string" };
+      }
+
+      const version = typeof args.version === "number" ? args.version : undefined;
+      const repoRoot = typeof args.repoRoot === "string" ? args.repoRoot : undefined;
+      const context = args.context;
+      const maxPositive = typeof args.maxPositive === "number" ? args.maxPositive : undefined;
+      const maxAnti = typeof args.maxAnti === "number" ? args.maxAnti : undefined;
+
+      try {
+        // When context is given, return a pre-composed prompt.
+        if (context !== undefined) {
+          const composed = await composePrompt({
+            kind,
+            version,
+            context,
+            repoRoot,
+            ...(maxPositive !== undefined ? { maxPositive } : {}),
+            ...(maxAnti !== undefined ? { maxAnti } : {}),
+          });
+          return {
+            ok: true,
+            prompt: composed.prompt,
+            sha256: composed.sha256,
+            version: composed.version,
+            kind: composed.kind,
+            exemplarCount: composed.exemplarCount,
+            antiCount: composed.antiCount,
+            tokenEstimate: composed.tokenEstimate,
+          };
+        }
+
+        // Otherwise: raw template + exemplar peek so the agent composes.
+        const loaded = loadPrompt(kind, version);
+        let exemplars: Exemplar[] = [];
+        if (repoRoot) {
+          try {
+            const all = await scanExemplars(repoRoot);
+            exemplars = all.filter((e) => e.kind === kind).slice(0, 5);
+          } catch {
+            // non-fatal — caller may invoke without a repoRoot
+          }
+        }
+        return {
+          ok: true,
+          prompt: loaded.raw,
+          sha256: loaded.sha256,
+          version: loaded.frontmatter.version,
+          kind: loaded.frontmatter.kind,
+          exemplars,
+          exemplarCount: exemplars.filter((e) => !e.anti).length,
+          antiCount: exemplars.filter((e) => e.anti).length,
+          tokenEstimate: Math.ceil(loaded.raw.length / 4),
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: msg };
+      }
+    },
+  };
+}

package/src/tools/ate-run.ts

@@ -0,0 +1,154 @@
+/**
+ * `mandu_ate_run` — Phase A.2 agent-facing spec runner.
+ *
+ * Wraps `@mandujs/ate`'s `runSpec` behind the MCP tool surface.
+ *
+ * Semantics: execute a single spec file (Playwright or bun:test,
+ * auto-detected from the path), then return the failure.v1-shaped
+ * JSON — `{ status: "pass", ... }` on green, full failure envelope
+ * on red. Shard argument is forwarded transparently.
+ *
+ * The handler validates the returned shape against the failure.v1
+ * Zod schema on failure (cheap, catches translator regressions).
+ * On pass we return the pass envelope as-is.
+ *
+ * Snake_case naming per §11 decision 4.
+ */
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { runSpec, failureV1Schema, type RunResult } from "@mandujs/ate";
+
+export const ateRunToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_run",
+    annotations: {
+      readOnlyHint: false,
+    },
+    description:
+      "Phase A.2 agent-native spec runner. Executes ONE spec file " +
+      "(Playwright if the path matches tests/e2e/** or *.e2e.ts, otherwise bun:test) " +
+      "and returns structured JSON. On pass: { status: 'pass', durationMs, assertions, graphVersion, runId }. " +
+      "On fail: a failure.v1 envelope with discriminated `kind` (one of: selector_drift, " +
+      "contract_mismatch, redirect_unexpected, hydration_timeout, rate_limit_exceeded, " +
+      "csrf_invalid, fixture_missing, semantic_divergence), kind-specific `detail`, " +
+      "`healing.auto[]` (deterministic replacements when confidence >= threshold), " +
+      "`healing.requires_llm` (true for shape-level failures), `flakeScore`, `lastPassedAt`, " +
+      "`graphVersion` (agent cache invalidation key), and trace/screenshot/dom artifacts " +
+      "staged under .mandu/ate-artifacts/<runId>/. Use `shard: { current, total }` to " +
+      "distribute across CI workers.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: {
+          type: "string",
+          description: "Absolute path to the Mandu project root",
+        },
+        spec: {
+          oneOf: [
+            { type: "string" },
+            {
+              type: "object",
+              properties: {
+                path: { type: "string" },
+              },
+              required: ["path"],
+            },
+          ],
+          description:
+            "Spec file — either a path string (relative to repoRoot) or { path }. " +
+            "Runner is auto-detected from the path (Playwright vs bun:test).",
+        },
+        headed: {
+          type: "boolean",
+          description: "Playwright only — run headed. Default: false (headless).",
+        },
+        trace: {
+          type: "boolean",
+          description: "Playwright only — capture trace. Default: true.",
+        },
+        shard: {
+          type: "object",
+          properties: {
+            current: { type: "number", minimum: 1 },
+            total: { type: "number", minimum: 1 },
+          },
+          required: ["current", "total"],
+          description:
+            "CI sharding — `current` is 1-based. Playwright receives --shard=current/total; " +
+            "bun:test falls back to hash-based partitioning.",
+        },
+      },
+      required: ["repoRoot", "spec"],
+    },
+  },
+];
+
+export function ateRunTools(_projectRoot: string) {
+  return {
+    mandu_ate_run: async (args: Record<string, unknown>) => {
+      const { repoRoot, spec, headed, trace, shard } = args as {
+        repoRoot: string;
+        spec: string | { path: string };
+        headed?: boolean;
+        trace?: boolean;
+        shard?: { current: number; total: number };
+      };
+      if (!repoRoot || typeof repoRoot !== "string") {
+        return { ok: false, error: "repoRoot is required" };
+      }
+      if (!spec) {
+        return { ok: false, error: "spec is required" };
+      }
+      const specPath = typeof spec === "string" ? spec : spec?.path;
+      if (!specPath || typeof specPath !== "string") {
+        return { ok: false, error: "spec.path or spec string is required" };
+      }
+      if (shard) {
+        if (
+          typeof shard.current !== "number" ||
+          typeof shard.total !== "number" ||
+          shard.current < 1 ||
+          shard.total < 1 ||
+          shard.current > shard.total
+        ) {
+          return {
+            ok: false,
+            error: `invalid shard: ${JSON.stringify(shard)} (current must be 1..total)`,
+          };
+        }
+      }
+
+      let result: RunResult;
+      try {
+        result = await runSpec({
+          repoRoot,
+          spec: specPath,
+          headed,
+          trace,
+          shard,
+        });
+      } catch (err) {
+        return {
+          ok: false,
+          error: `runSpec failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+      }
+
+      // On failure, re-validate the shape against failure.v1. The
+      // runSpec path already does this, but re-checking at the MCP
+      // boundary means a buggy translator is caught before the
+      // payload crosses the wire.
+      if (result.status === "fail") {
+        const parsed = failureV1Schema.safeParse(result);
+        if (!parsed.success) {
+          return {
+            ok: false,
+            error: `runSpec emitted invalid failure.v1: ${parsed.error.issues[0]?.message ?? "schema mismatch"}`,
+            result,
+          };
+        }
+        return { ok: true, result: parsed.data };
+      }
+      return { ok: true, result };
+    },
+  };
+}

package/src/tools/ate-save.ts

@@ -0,0 +1,139 @@
+/**
+ * `mandu_ate_save` — Phase A.3 spec persistence with lint-before-write.
+ *
+ * See `docs/ate/roadmap-v2-agent-native.md` §4.7 and the §7 extension
+ * ("mandu_ate_save lint-before-write").
+ *
+ * Semantics:
+ *   1. Run `lintSpecContent` (from @mandujs/ate) which:
+ *        - parses with ts-morph (syntax errors block),
+ *        - walks import declarations (banned typos, unknown @mandujs/* barrels),
+ *        - detects anti-patterns (bare localhost, hand-rolled CSRF, DB mocks).
+ *   2. If any *blocking* diagnostic fires, return { saved: false, ... } WITHOUT
+ *      writing. Otherwise write and return { saved: true, path }.
+ *
+ * Snake_case tool name (§11 decision #4).
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { writeFileSync, mkdirSync, existsSync, statSync } from "node:fs";
+import { dirname, isAbsolute } from "node:path";
+import { lintSpecContent, type LintDiagnostic } from "@mandujs/ate";
+
+// Re-export the diagnostic shape so callers can type-check against it without
+// pulling @mandujs/ate directly.
+export type { LintDiagnostic, LintSeverity } from "@mandujs/ate";
+
+export const ateSaveToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_save",
+    description:
+      "Phase A.3 persist-with-lint. Writes an agent-generated test file to " +
+      "disk, but first runs a small lint pass that blocks common LLM mistakes: " +
+      "ts-morph syntax errors, unresolved / banned import paths, hand-rolled " +
+      "CSRF cookies, DB mocks when createTestDb is available, and bare " +
+      "`localhost:<port>` URLs (prefer 127.0.0.1 per roadmap §9.2). Returns " +
+      "{ saved: true, path, lintDiagnostics: [warnings...] } on success or " +
+      "{ saved: false, blockingErrors: [...], lintDiagnostics: [...] } when " +
+      "a blocker fires (in which case no file is written).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description:
+            "Absolute path where the spec will be written. Parent directories are created if needed.",
+        },
+        content: {
+          type: "string",
+          description: "The full TypeScript test source to write.",
+        },
+        intent: {
+          type: "string",
+          description:
+            "Optional short description of what the test is verifying (logged to ATE memory).",
+        },
+        kind: {
+          type: "string",
+          description:
+            "Optional prompt kind this spec was generated for (filling_unit, filling_integration, e2e_playwright).",
+        },
+        sourcePrompt: {
+          type: "object",
+          description:
+            "Optional { kind, version } back-reference to the prompt that produced this spec (used by future memory queries).",
+          additionalProperties: true,
+        },
+        allowWarnings: {
+          type: "boolean",
+          description:
+            "When true, non-blocking warnings still allow the write (default true). When false, even warnings block.",
+        },
+      },
+      required: ["path", "content"],
+    },
+  },
+];
+
+export function ateSaveTools(_projectRoot: string) {
+  return {
+    mandu_ate_save: async (args: Record<string, unknown>) => {
+      const path = args.path as string | undefined;
+      const content = args.content as string | undefined;
+      const allowWarnings = args.allowWarnings !== false;
+
+      if (!path || typeof path !== "string") {
+        return { saved: false, error: "'path' is required" };
+      }
+      if (!isAbsolute(path)) {
+        return {
+          saved: false,
+          error: "'path' must be absolute — relative paths are rejected to prevent cwd drift.",
+        };
+      }
+      if (typeof content !== "string") {
+        return { saved: false, error: "'content' is required and must be a string" };
+      }
+
+      const diagnostics = await lintSpecContent(path, content);
+
+      const blocking = diagnostics.filter((d) => d.blocking);
+      const warnings = diagnostics.filter((d) => !d.blocking);
+
+      if (blocking.length > 0 || (!allowWarnings && warnings.length > 0)) {
+        return {
+          saved: false,
+          path,
+          blockingErrors: blocking,
+          lintDiagnostics: diagnostics,
+        };
+      }
+
+      const parent = dirname(path);
+      if (!existsSync(parent)) {
+        mkdirSync(parent, { recursive: true });
+      }
+      if (!statSync(parent).isDirectory()) {
+        return { saved: false, path, error: `Parent path is not a directory: ${parent}` };
+      }
+
+      writeFileSync(path, content, "utf8");
+
+      return {
+        saved: true,
+        path,
+        bytes: Buffer.byteLength(content, "utf8"),
+        lintDiagnostics: diagnostics,
+      };
+    },
+  };
+}
+
+// Re-export for tests that need direct access (package.json test patterns
+// already reach here).
+export async function lintContent(
+  path: string,
+  content: string,
+): Promise<LintDiagnostic[]> {
+  return lintSpecContent(path, content);
+}

package/src/tools/index.ts

@@ -28,6 +28,12 @@ export { runtimeTools, runtimeToolDefinitions } from "./runtime.js";
 export { seoTools, seoToolDefinitions } from "./seo.js";
 export { projectTools, projectToolDefinitions, getDevServerState } from "./project.js";
 export { ateTools, ateToolDefinitions, atePhase5ToolDefinitions, createAtePhase5Handlers } from "./ate.js";
+export { ateContextTools, ateContextToolDefinitions } from "./ate-context.js";
+export { ateRunTools, ateRunToolDefinitions } from "./ate-run.js";
+export { ateFlakesTools, ateFlakesToolDefinitions } from "./ate-flakes.js";
+export { atePromptTools, atePromptToolDefinitions } from "./ate-prompt.js";
+export { ateExemplarTools, ateExemplarToolDefinitions } from "./ate-exemplar.js";
+export { ateSaveTools, ateSaveToolDefinitions } from "./ate-save.js";
 export { resourceTools, resourceToolDefinitions } from "./resource.js";
 export { componentTools, componentToolDefinitions } from "./component.js";
 export { kitchenTools, kitchenToolDefinitions } from "./kitchen.js";
@@ -68,6 +74,12 @@ import { runtimeTools, runtimeToolDefinitions } from "./runtime.js";
 import { seoTools, seoToolDefinitions } from "./seo.js";
 import { projectTools, projectToolDefinitions } from "./project.js";
 import { ateTools, ateToolDefinitions, atePhase5ToolDefinitions, createAtePhase5Handlers } from "./ate.js";
+import { ateContextTools, ateContextToolDefinitions } from "./ate-context.js";
+import { ateRunTools, ateRunToolDefinitions } from "./ate-run.js";
+import { ateFlakesTools, ateFlakesToolDefinitions } from "./ate-flakes.js";
+import { atePromptTools, atePromptToolDefinitions } from "./ate-prompt.js";
+import { ateExemplarTools, ateExemplarToolDefinitions } from "./ate-exemplar.js";
+import { ateSaveTools, ateSaveToolDefinitions } from "./ate-save.js";
 import { resourceTools, resourceToolDefinitions } from "./resource.js";
 import { componentTools, componentToolDefinitions } from "./component.js";
 import { kitchenTools, kitchenToolDefinitions } from "./kitchen.js";
@@ -125,6 +137,12 @@ const TOOL_MODULES: ToolModule[] = [
   { category: "project", definitions: projectToolDefinitions, handlers: projectTools as ToolModule["handlers"], requiresServer: true },
   { category: "ate", definitions: ateToolDefinitions, handlers: ateTools as ToolModule["handlers"] },
   { category: "ate-phase5", definitions: atePhase5ToolDefinitions, handlers: createAtePhase5Handlers as unknown as ToolModule["handlers"] },
+  { category: "ate-context", definitions: ateContextToolDefinitions, handlers: ateContextTools },
+  { category: "ate-run", definitions: ateRunToolDefinitions, handlers: ateRunTools },
+  { category: "ate-flakes", definitions: ateFlakesToolDefinitions, handlers: ateFlakesTools },
+  { category: "ate-prompt", definitions: atePromptToolDefinitions, handlers: atePromptTools },
+  { category: "ate-exemplar", definitions: ateExemplarToolDefinitions, handlers: ateExemplarTools },
+  { category: "ate-save", definitions: ateSaveToolDefinitions, handlers: ateSaveTools },
   { category: "resource", definitions: resourceToolDefinitions, handlers: resourceTools },
   { category: "component", definitions: componentToolDefinitions, handlers: componentTools },
   { category: "kitchen", definitions: kitchenToolDefinitions, handlers: kitchenTools },