@mandujs/mcp 0.25.0 → 0.27.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/mcp",
-  "version": "0.25.0",
+  "version": "0.27.1",
   "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.22.0",
-    "@mandujs/skills": "^16.0.0",
+    "@mandujs/core": "^0.40.0",
+    "@mandujs/ate": "^0.24.0",
+    "@mandujs/skills": "^0.18.0",
     "@modelcontextprotocol/sdk": "^1.25.3"
   },
   "engines": {

package/src/tools/ate-context.ts

@@ -26,6 +26,7 @@ import {
   appendMemoryEvent,
   nowTimestamp,
   readMemoryEvents,
+  buildRpcContext,
 } from "@mandujs/ate";
 
 export const ateContextToolDefinitions: Tool[] = [
@@ -56,9 +57,9 @@ export const ateContextToolDefinitions: Tool[] = [
         },
         scope: {
           type: "string",
-          enum: ["project", "route", "filling", "contract"],
+          enum: ["project", "route", "filling", "contract", "rpc"],
           description:
-            "project (summary) | route (single route deep view) | filling (handler view) | contract (contract definition view)",
+            "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",
@@ -81,7 +82,7 @@ export function ateContextTools(_projectRoot: string) {
     mandu_ate_context: async (args: Record<string, unknown>) => {
       const { repoRoot, scope, id, route } = args as {
         repoRoot: string;
-        scope: "project" | "route" | "filling" | "contract";
+        scope: "project" | "route" | "filling" | "contract" | "rpc";
         id?: string;
         route?: string;
       };
@@ -94,6 +95,19 @@ export function ateContextTools(_projectRoot: string) {
       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

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

package/src/tools/ate-oracle-pending.ts

@@ -0,0 +1,49 @@
+/**
+ * `mandu_ate_oracle_pending` — Phase C.4.
+ *
+ * List pending semantic oracle entries for agent judgment.
+ * Read-only.
+ */
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { findOraclePending } from "@mandujs/ate";
+
+export const ateOraclePendingToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_oracle_pending",
+    annotations: {
+      readOnlyHint: true,
+    },
+    description:
+      "Phase C.4 — list pending semantic oracle entries. Returns the most recent " +
+      "`status=pending` entries from `.mandu/ate-oracle-queue.jsonl`. Each entry " +
+      "carries an assertionId, the spec path, the claim text, and an artifactPath " +
+      "pointing to screenshot / DOM captures. The agent reviews these and issues a " +
+      "verdict via `mandu_ate_oracle_verdict`. CI never blocks on these — " +
+      "expectSemantic is deterministic-non-blocking by default.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: { type: "string", description: "Absolute path to the Mandu project root." },
+        limit: { type: "number", description: "Maximum entries to return. Default 20." },
+        specPath: { type: "string", description: "Filter to a specific spec file." },
+      },
+      required: ["repoRoot"],
+    },
+  },
+];
+
+export function ateOraclePendingTools(_projectRoot: string) {
+  return {
+    mandu_ate_oracle_pending: 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 entries = findOraclePending(repoRoot, {
+        ...(typeof args.limit === "number" ? { limit: args.limit } : {}),
+        ...(typeof args.specPath === "string" ? { specPath: args.specPath } : {}),
+      });
+      return { ok: true, count: entries.length, entries };
+    },
+  };
+}

package/src/tools/ate-oracle-replay.ts

@@ -0,0 +1,44 @@
+/**
+ * `mandu_ate_oracle_replay` — Phase C.4.
+ *
+ * Read-only. Return every oracle entry (pending + judged) for a spec
+ * path — lets agents review the history of semantic claims for a file
+ * before re-issuing similar assertions.
+ */
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { findOracleEntriesForSpec } from "@mandujs/ate";
+
+export const ateOracleReplayToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_oracle_replay",
+    annotations: {
+      readOnlyHint: true,
+    },
+    description:
+      "Phase C.4 — replay every oracle verdict (pending + passed + failed) for a " +
+      "given spec. Returns the full audit trail sorted newest → oldest. Useful for " +
+      "agents reviewing past `failed` verdicts before re-issuing similar semantic " +
+      "claims, or for human auditors walking the queue history.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: { type: "string", description: "Absolute path to the Mandu project root." },
+        specPath: { type: "string", description: "Spec file path to replay." },
+      },
+      required: ["repoRoot", "specPath"],
+    },
+  },
+];
+
+export function ateOracleReplayTools(_projectRoot: string) {
+  return {
+    mandu_ate_oracle_replay: async (args: Record<string, unknown>) => {
+      const repoRoot = args.repoRoot as string | undefined;
+      const specPath = args.specPath as string | undefined;
+      if (!repoRoot) return { ok: false, error: "repoRoot is required" };
+      if (!specPath) return { ok: false, error: "specPath is required" };
+      const entries = findOracleEntriesForSpec(repoRoot, specPath);
+      return { ok: true, count: entries.length, entries };
+    },
+  };
+}

package/src/tools/ate-oracle-verdict.ts

@@ -0,0 +1,70 @@
+/**
+ * `mandu_ate_oracle_verdict` — Phase C.4.
+ *
+ * Apply an agent / human verdict to a pending oracle entry. Rewrites
+ * matching pending rows with `status = passed|failed` + verdict metadata.
+ */
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { setOracleVerdict } from "@mandujs/ate";
+
+export const ateOracleVerdictToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_oracle_verdict",
+    annotations: {
+      readOnlyHint: false,
+    },
+    description:
+      "Phase C.4 — record an oracle verdict for a pending semantic assertion. " +
+      "`verdict: 'pass' | 'fail'`. `judgedBy`: 'agent' (default) or 'human'. " +
+      "`reason` is the short free-form justification the agent (or human) provides. " +
+      "Every pending queue entry with the matching assertionId transitions to the " +
+      "given verdict — subsequent `promoteVerdicts: true` expectSemantic calls will " +
+      "see past `failed` verdicts and throw deterministically.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: { type: "string", description: "Absolute path to the Mandu project root." },
+        assertionId: { type: "string", description: "Stable assertion id returned by expectSemantic." },
+        verdict: {
+          type: "string",
+          enum: ["pass", "fail"],
+          description: "Whether the agent judges the claim satisfied.",
+        },
+        reason: { type: "string", description: "Free-form justification." },
+        judgedBy: {
+          type: "string",
+          enum: ["agent", "human"],
+          description: "Source of the verdict. Defaults to 'agent'.",
+        },
+      },
+      required: ["repoRoot", "assertionId", "verdict", "reason"],
+    },
+  },
+];
+
+export function ateOracleVerdictTools(_projectRoot: string) {
+  return {
+    mandu_ate_oracle_verdict: async (args: Record<string, unknown>) => {
+      const repoRoot = args.repoRoot as string | undefined;
+      const assertionId = args.assertionId as string | undefined;
+      const verdict = args.verdict as string | undefined;
+      const reason = args.reason as string | undefined;
+      const judgedBy = args.judgedBy as string | undefined;
+      if (!repoRoot) return { ok: false, error: "repoRoot is required" };
+      if (!assertionId) return { ok: false, error: "assertionId is required" };
+      if (verdict !== "pass" && verdict !== "fail") {
+        return { ok: false, error: "verdict must be 'pass' or 'fail'" };
+      }
+      if (!reason || typeof reason !== "string") {
+        return { ok: false, error: "reason is required" };
+      }
+      const res = setOracleVerdict(repoRoot, {
+        assertionId,
+        verdict,
+        reason,
+        ...(judgedBy === "agent" || judgedBy === "human" ? { judgedBy } : {}),
+      });
+      return { ok: true, updated: res.updated, entries: res.entries };
+    },
+  };
+}

package/src/tools/index.ts

@@ -38,6 +38,24 @@ export { ateBoundaryProbeTools, ateBoundaryProbeToolDefinitions } from "./ate-bo
 export { ateRecallTools, ateRecallToolDefinitions } from "./ate-recall.js";
 export { ateRememberTools, ateRememberToolDefinitions } from "./ate-remember.js";
 export { ateCoverageTools, ateCoverageToolDefinitions } from "./ate-coverage.js";
+// Phase C tool suite
+export { ateMutateTools, ateMutateToolDefinitions } from "./ate-mutate.js";
+export {
+  ateMutationReportTools,
+  ateMutationReportToolDefinitions,
+} from "./ate-mutation-report.js";
+export {
+  ateOraclePendingTools,
+  ateOraclePendingToolDefinitions,
+} from "./ate-oracle-pending.js";
+export {
+  ateOracleVerdictTools,
+  ateOracleVerdictToolDefinitions,
+} from "./ate-oracle-verdict.js";
+export {
+  ateOracleReplayTools,
+  ateOracleReplayToolDefinitions,
+} from "./ate-oracle-replay.js";
 export { resourceTools, resourceToolDefinitions } from "./resource.js";
 export { componentTools, componentToolDefinitions } from "./component.js";
 export { kitchenTools, kitchenToolDefinitions } from "./kitchen.js";
@@ -91,6 +109,24 @@ import {
 import { ateRecallTools, ateRecallToolDefinitions } from "./ate-recall.js";
 import { ateRememberTools, ateRememberToolDefinitions } from "./ate-remember.js";
 import { ateCoverageTools, ateCoverageToolDefinitions } from "./ate-coverage.js";
+// Phase C tool suite
+import { ateMutateTools, ateMutateToolDefinitions } from "./ate-mutate.js";
+import {
+  ateMutationReportTools,
+  ateMutationReportToolDefinitions,
+} from "./ate-mutation-report.js";
+import {
+  ateOraclePendingTools,
+  ateOraclePendingToolDefinitions,
+} from "./ate-oracle-pending.js";
+import {
+  ateOracleVerdictTools,
+  ateOracleVerdictToolDefinitions,
+} from "./ate-oracle-verdict.js";
+import {
+  ateOracleReplayTools,
+  ateOracleReplayToolDefinitions,
+} from "./ate-oracle-replay.js";
 import { resourceTools, resourceToolDefinitions } from "./resource.js";
 import { componentTools, componentToolDefinitions } from "./component.js";
 import { kitchenTools, kitchenToolDefinitions } from "./kitchen.js";
@@ -167,6 +203,28 @@ const TOOL_MODULES: ToolModule[] = [
     definitions: ateCoverageToolDefinitions,
     handlers: ateCoverageTools,
   },
+  // Phase C tool suite
+  { category: "ate-mutate", definitions: ateMutateToolDefinitions, handlers: ateMutateTools },
+  {
+    category: "ate-mutation-report",
+    definitions: ateMutationReportToolDefinitions,
+    handlers: ateMutationReportTools,
+  },
+  {
+    category: "ate-oracle-pending",
+    definitions: ateOraclePendingToolDefinitions,
+    handlers: ateOraclePendingTools,
+  },
+  {
+    category: "ate-oracle-verdict",
+    definitions: ateOracleVerdictToolDefinitions,
+    handlers: ateOracleVerdictTools,
+  },
+  {
+    category: "ate-oracle-replay",
+    definitions: ateOracleReplayToolDefinitions,
+    handlers: ateOracleReplayTools,
+  },
   { category: "resource", definitions: resourceToolDefinitions, handlers: resourceTools },
   { category: "component", definitions: componentToolDefinitions, handlers: componentTools },
   { category: "kitchen", definitions: kitchenToolDefinitions, handlers: kitchenTools },