@mandujs/mcp 0.22.4 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/mcp",
-  "version": "0.22.4",
+  "version": "0.23.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.20.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/index.ts

@@ -28,6 +28,7 @@ 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 { resourceTools, resourceToolDefinitions } from "./resource.js";
 export { componentTools, componentToolDefinitions } from "./component.js";
 export { kitchenTools, kitchenToolDefinitions } from "./kitchen.js";
@@ -68,6 +69,7 @@ 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 { resourceTools, resourceToolDefinitions } from "./resource.js";
 import { componentTools, componentToolDefinitions } from "./component.js";
 import { kitchenTools, kitchenToolDefinitions } from "./kitchen.js";
@@ -125,6 +127,7 @@ 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: "resource", definitions: resourceToolDefinitions, handlers: resourceTools },
   { category: "component", definitions: componentToolDefinitions, handlers: componentTools },
   { category: "kitchen", definitions: kitchenToolDefinitions, handlers: kitchenTools },