@mandujs/mcp 0.38.3 → 0.38.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/mcp",
-  "version": "0.38.3",
+  "version": "0.38.4",
   "description": "Mandu MCP Server - Agent-native interface for Mandu framework operations",
   "type": "module",
   "main": "./src/index.ts",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@mandujs/core": "^0.54.9",
+    "@mandujs/core": "^0.54.10",
     "@mandujs/ate": "^0.26.1",
     "@mandujs/skills": "^0.20.1",
     "@modelcontextprotocol/sdk": "^1.25.3"

package/src/executor/error-handler.ts

@@ -35,6 +35,23 @@ export interface McpErrorResponse {
 export interface McpToolResponse {
   content: Array<{ type: string; text: string }>;
   isError?: boolean;
+  _meta?: McpResponseMeta;
+}
+
+export type McpNextActionKind = "none" | "inspect" | "verify" | "repair" | "retry";
+
+export interface McpNextAction {
+  kind: McpNextActionKind;
+  reason: string;
+  command?: string;
+  tool?: string;
+  input?: unknown;
+}
+
+export interface McpResponseMeta {
+  toolName: string;
+  ok: boolean;
+  nextAction: McpNextAction;
 }
 
 /**
@@ -186,6 +203,51 @@ function isSoftErrorResult(result: unknown): boolean {
   return false;
 }
 
+function inferNextAction(toolName: string, result: unknown, errorResponse?: McpErrorResponse): McpNextAction {
+  if (errorResponse) {
+    return {
+      kind: errorResponse.retryable ? "retry" : "repair",
+      reason: errorResponse.suggestion ?? errorResponse.error,
+    };
+  }
+
+  if (result && typeof result === "object") {
+    const obj = result as Record<string, unknown>;
+    if (isSoftErrorResult(result)) {
+      return { kind: "repair", reason: String(obj.error ?? "Tool returned an error result.") };
+    }
+    if (typeof obj.nextVerifyCommand === "string") {
+      return { kind: "verify", reason: "Tool returned an explicit verification command.", command: obj.nextVerifyCommand };
+    }
+    if (typeof obj.nextRepairInput === "string") {
+      return {
+        kind: "repair",
+        reason: "Tool returned a repair input artifact.",
+        command: `mandu agent repair --from ${obj.nextRepairInput}`,
+        input: obj.nextRepairInput,
+      };
+    }
+    if (obj.dryRun === true) {
+      return { kind: "inspect", reason: "Dry-run completed; review the preview before applying changes." };
+    }
+    if (Array.isArray(obj.nextSteps) && obj.nextSteps.length > 0) {
+      return { kind: "inspect", reason: "Tool returned follow-up steps.", input: obj.nextSteps };
+    }
+    if (typeof obj.tip === "string") {
+      return { kind: "inspect", reason: obj.tip };
+    }
+  }
+
+  return { kind: "none", reason: `${toolName} completed successfully.` };
+}
+
+function attachMeta(payload: unknown, meta: McpResponseMeta): unknown {
+  if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+    return { ...(payload as Record<string, unknown>), _meta: meta };
+  }
+  return { data: payload, _meta: meta };
+}
+
 export function createToolResponse(
   toolName: string,
   result: unknown,
@@ -193,28 +255,40 @@ export function createToolResponse(
 ): McpToolResponse {
   if (error) {
     const errorResponse = formatMcpError(error, toolName);
+    const meta: McpResponseMeta = {
+      toolName,
+      ok: false,
+      nextAction: inferNextAction(toolName, null, errorResponse),
+    };
     return {
       content: [
         {
           type: "text",
-          text: JSON.stringify(errorResponse, null, 2),
+          text: JSON.stringify(attachMeta(errorResponse, meta), null, 2),
         },
       ],
       isError: true,
+      _meta: meta,
     };
   }
 
   // Detect soft errors returned by handlers (e.g. { error: "Route not found" })
   const softError = isSoftErrorResult(result);
+  const meta: McpResponseMeta = {
+    toolName,
+    ok: !softError,
+    nextAction: inferNextAction(toolName, result),
+  };
 
   return {
     content: [
       {
         type: "text",
-        text: JSON.stringify(result, null, 2),
+        text: JSON.stringify(attachMeta(result, meta), null, 2),
       },
     ],
     ...(softError && { isError: true }),
+    _meta: meta,
   };
 }
 

package/src/profiles.ts

@@ -1,57 +1,119 @@
-/**
- * MCP Tool Profiles
- *
- * Controls how many tool categories are exposed to AI agents.
- * - agent-core: Canonical agent workflow plus docs grounding (default)
- * - agent-full: Agent workflow plus Mandu domain tools
- * - internal: All categories, no filtering
- */
-
-export type McpProfile = "agent-core" | "agent-full" | "internal";
-
-export const PROFILE_CATEGORIES: Record<McpProfile, string[] | null> = {
-  "agent-core": ["agent", "docs"],
-  "agent-full": [
-    "agent",
-    "docs",
-    "spec",
-    "generate",
-    "slot",
-    "slot-validation",
-    "hydration",
-    "contract",
-    "guard",
-    "run-tests",
-    "lint",
-  ],
-  internal: null,
-};
+/**
+ * MCP Tool Profiles
+ *
+ * Controls how many tool categories are exposed to AI agents.
+ * - agent-core: Canonical agent workflow plus docs grounding (default)
+ * - agent-full: Agent workflow plus Mandu domain tools
+ * - internal: All categories, no filtering
+ */
+
+export type McpProfile = "agent-core" | "agent-full" | "internal";
+
+export const PROFILE_CATEGORIES: Record<McpProfile, string[] | null> = {
+  "agent-core": ["agent", "docs"],
+  "agent-full": [
+    // Official agent loop
+    "agent",
+    "docs",
+    // Code generation / scaffolding
+    "spec",
+    "generate",
+    "composite",
+    // Domain primitives
+    "slot",
+    "slot-validation",
+    "hydration",
+    "contract",
+    "design",
+    "seo",
+    // Quality / validation
+    "guard",
+    "lint",
+    "run-tests",
+    "ate",
+    // Deploy
+    "deploy-plan",
+    "deploy-preview",
+    // AI refactor
+    "refactor-barrel",
+    "refactor-routes",
+    "refactor-contract",
+  ],
+  internal: null,
+};
+
+/**
+ * Categories intentionally hidden from every agent-facing profile.
+ *
+ * Every new tool category in `TOOL_MODULES` MUST be classified into one of:
+ *   - `PROFILE_CATEGORIES["agent-core"]` — canonical agent loop
+ *   - `PROFILE_CATEGORIES["agent-full"]` — domain work for agents
+ *   - `EXPERT_ONLY_CATEGORIES`           — internal plumbing
+ *
+ * `profile-coverage.test.ts` fails CI if a new category is left unclassified,
+ * preventing silent default-profile bloat over time.
+ */
+export const EXPERT_ONLY_CATEGORIES: ReadonlySet<string> = new Set([
+  // Transactional state / framework internals
+  "transaction",
+  "history",
+  "decisions",
+  "negotiate",
+  // Runtime / project introspection
+  "brain",
+  "runtime",
+  "project",
+  "resource",
+  // Devtools / kitchen
+  "kitchen",
+  "component",
+  // Agent loop internal helpers (used by mandu.agent.*, not by agents directly)
+  "ai-brief",
+  "loop-close",
+  // Specialized ATE phases (core "ate" is exposed in agent-full)
+  "ate-phase5",
+  "ate-context",
+  "ate-run",
+  "ate-flakes",
+  "ate-prompt",
+  "ate-exemplar",
+  "ate-save",
+  "ate-boundary-probe",
+  "ate-recall",
+  "ate-remember",
+  "ate-coverage",
+  "ate-mutate",
+  "ate-mutation-report",
+  "ate-oracle-pending",
+  "ate-oracle-verdict",
+  "ate-oracle-replay",
+]);
 
 /**
  * Returns allowed category names for a profile, or null if all categories are allowed.
  */
-export function getProfileCategories(profile: McpProfile): string[] | null {
-  return PROFILE_CATEGORIES[profile] ?? null;
-}
-
+export function getProfileCategories(profile: McpProfile): string[] | null {
+  return PROFILE_CATEGORIES[profile] ?? null;
+}
+
 /**
  * Type guard for valid profile strings.
  */
-export function isValidProfile(value: string): value is McpProfile {
-  return value === "agent-core" || value === "agent-full" || value === "internal";
-}
-
-/**
- * Resolve current and legacy profile names to the new official profile set.
- */
-export function resolveMcpProfile(
-  value: string | undefined,
-  fallback: McpProfile = "agent-core",
-): McpProfile {
-  if (!value) return fallback;
-  if (isValidProfile(value)) return value;
-  if (value === "minimal") return "agent-core";
-  if (value === "standard") return "agent-full";
-  if (value === "full") return "internal";
-  return fallback;
-}
+export function isValidProfile(value: string): value is McpProfile {
+  return value === "agent-core" || value === "agent-full" || value === "internal";
+}
+
+/**
+ * Resolve current and legacy profile names to the new official profile set.
+ */
+export function resolveMcpProfile(
+  value: string | undefined,
+  fallback: McpProfile = "agent-core",
+): McpProfile {
+  if (!value) return fallback;
+  if (isValidProfile(value)) return value;
+  if (value === "minimal") return "agent-core";
+  if (value === "standard") return "agent-full";
+  if (value === "full") return "internal";
+  return fallback;
+}

package/src/tools/guard.ts

@@ -138,7 +138,25 @@ export function guardTools(projectRoot: string) {
     }
   };
 
+  const guardViolationCode = (ruleId: string | undefined, type?: string) =>
+    `MANDU_GUARD_${(ruleId || type || "VIOLATION").toUpperCase().replace(/[^A-Z0-9]+/g, "_")}`;
+
+  const explainViolation = (input: {
+    type?: string;
+    ruleId?: string;
+    fromLayer?: string;
+    toLayer?: string;
+    suggestion?: string;
+  }): string => {
+    const source = input.fromLayer ? ` from ${input.fromLayer}` : "";
+    const target = input.toLayer ? ` to ${input.toLayer}` : "";
+    const rule = input.ruleId ?? input.type ?? "architecture rule";
+    const fix = input.suggestion ? ` Suggested fix: ${input.suggestion}` : "";
+    return `Violation of ${rule}${source}${target}.${fix}`.trim();
+  };
+
   const summarizeArchitectureViolation = (violation: Violation) => ({
+    code: guardViolationCode(violation.ruleName, violation.type),
     ruleId: violation.ruleName,
     type: violation.type,
     file: path.relative(projectRoot, violation.filePath).replace(/\\/g, "/") || violation.filePath,
@@ -146,16 +164,25 @@ export function guardTools(projectRoot: string) {
     column: violation.column,
     message: violation.ruleDescription,
     suggestion: violation.suggestions[0],
+    explanation: explainViolation({
+      type: violation.type,
+      ruleId: violation.ruleName,
+      fromLayer: violation.fromLayer,
+      toLayer: violation.toLayer,
+      suggestion: violation.suggestions[0],
+    }),
     fromLayer: violation.fromLayer,
     toLayer: violation.toLayer,
     importStatement: violation.importStatement,
   });
 
   const summarizeLegacyViolation = (v: Awaited<ReturnType<typeof runGuardCheck>>["violations"][number]) => ({
+    code: guardViolationCode(v.ruleId),
     ruleId: v.ruleId,
     file: v.file,
     message: v.message,
     suggestion: v.suggestion,
+    explanation: explainViolation({ ruleId: v.ruleId, suggestion: v.suggestion }),
   });
 
   const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
@@ -521,10 +548,18 @@ export function guardTools(projectRoot: string) {
         preset: config.preset,
         violations: items.map((item) => ({
           // Violation info
+          code: guardViolationCode(item.violation.ruleName, item.violation.type),
           type: item.violation.type,
           file: item.violation.filePath,
           line: item.violation.line,
           message: item.violation.ruleDescription,
+          explanation: explainViolation({
+            type: item.violation.type,
+            ruleId: item.violation.ruleName,
+            fromLayer: item.violation.fromLayer,
+            toLayer: item.violation.toLayer,
+            suggestion: item.healing.primary.explanation,
+          }),
           fromLayer: item.violation.fromLayer,
           toLayer: item.violation.toLayer,
           importStatement: item.violation.importStatement,

package/src/tools/index.ts

@@ -290,9 +290,10 @@ export const TOOL_MODULES: ToolModule[] = [
 export function validateBuiltinToolModules(
   modules: readonly ToolModule[] = TOOL_MODULES
 ): string[] {
-  const issues: string[] = [];
-  const categories = new Set<string>();
-  const toolNames = new Map<string, string>();
+  const issues: string[] = [];
+  const categories = new Set<string>();
+  const toolNames = new Map<string, string>();
+  const descriptions = new Map<string, string>();
 
   for (const module of modules) {
     if (categories.has(module.category)) {
@@ -305,7 +306,20 @@ export function validateBuiltinToolModules(
     }
 
     for (const definition of module.definitions) {
-      const previousCategory = toolNames.get(definition.name);
+      if (!definition.description?.trim()) {
+        issues.push(`tool definition is missing description: ${definition.name} in ${module.category}`);
+      }
+      const normalizedDescription = definition.description?.trim().replace(/\s+/g, " ").toLowerCase();
+      if (normalizedDescription) {
+        const previousTool = descriptions.get(normalizedDescription);
+        if (previousTool) {
+          issues.push(
+            `duplicate tool description: ${definition.name} and ${previousTool} both describe the same action`
+          );
+        }
+        descriptions.set(normalizedDescription, definition.name);
+      }
+      const previousCategory = toolNames.get(definition.name);
       if (previousCategory) {
         issues.push(
           `duplicate tool definition: ${definition.name} in ${previousCategory} and ${module.category}`

package/src/tools/transaction.ts

@@ -6,7 +6,7 @@ import {
   getTransactionStatus,
   hasActiveTransaction,
 } from "@mandujs/core";
-import { acquireLock, releaseLock, checkLock } from "../tx-lock.js";
+import { acquireLock, releaseLock, checkLock, requireLock } from "../tx-lock.js";
 
 export const transactionToolDefinitions: Tool[] = [
   {
@@ -99,9 +99,15 @@ export function transactionTools(projectRoot: string) {
         return { error: lock.error };
       }
 
-      const change = await beginChange(projectRoot, {
-        message: message || "MCP transaction",
-      });
+      let change: Awaited<ReturnType<typeof beginChange>>;
+      try {
+        change = await beginChange(projectRoot, {
+          message: message || "MCP transaction",
+        });
+      } catch (error) {
+        if (lock.lockId) releaseLock(lock.lockId);
+        return { error: error instanceof Error ? error.message : String(error) };
+      }
 
       return {
         success: true,
@@ -122,6 +128,10 @@ export function transactionTools(projectRoot: string) {
           error: "No active transaction to commit",
         };
       }
+      const lockCheck = requireLock(lockId);
+      if (!lockCheck.allowed) {
+        return { error: lockCheck.error };
+      }
 
       const result = await commitChange(projectRoot);
       if (lockId) releaseLock(lockId);
@@ -142,6 +152,10 @@ export function transactionTools(projectRoot: string) {
           error: "No active transaction to rollback. Provide a changeId to rollback a specific change.",
         };
       }
+      const lockCheck = requireLock(lockId);
+      if (!lockCheck.allowed) {
+        return { error: lockCheck.error };
+      }
 
       const result = await rollbackChange(projectRoot, changeId);
       if (lockId) releaseLock(lockId);