@mandujs/mcp 0.18.9 → 0.19.0

package/src/tools/slot-validation.ts

@@ -0,0 +1,200 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import {
+  validateSlotConstraints,
+  validateSlots,
+  DEFAULT_SLOT_CONSTRAINTS,
+  API_SLOT_CONSTRAINTS,
+  READONLY_SLOT_CONSTRAINTS,
+  type SlotConstraints,
+} from "@mandujs/core";
+
+export const slotValidationToolDefinitions: Tool[] = [
+  {
+    name: "mandu.slot.validate",
+    description:
+      "Validate a slot file against semantic constraints (lines, complexity, patterns, imports).",
+    annotations: {
+      readOnlyHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        file: {
+          type: "string",
+          description: "Path to the slot file to validate",
+        },
+        preset: {
+          type: "string",
+          enum: ["default", "api", "readonly"],
+          description: "Constraint preset to use (default: 'default')",
+        },
+        constraints: {
+          type: "object",
+          description: "Custom constraints (overrides preset)",
+          properties: {
+            maxLines: { type: "number" },
+            maxCyclomaticComplexity: { type: "number" },
+            requiredPatterns: { type: "array", items: { type: "string" } },
+            forbiddenPatterns: { type: "array", items: { type: "string" } },
+            allowedImports: { type: "array", items: { type: "string" } },
+          },
+        },
+      },
+      required: ["file"],
+    },
+  },
+  {
+    name: "mandu.slot.constraints",
+    description:
+      "Get recommended slot constraint presets (default, api, readonly).",
+    annotations: {
+      readOnlyHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        preset: {
+          type: "string",
+          enum: ["default", "api", "readonly"],
+          description: "Constraint preset to retrieve",
+        },
+      },
+      required: [],
+    },
+  },
+];
+
+export function slotValidationTools(projectRoot: string) {
+  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
+    "mandu.slot.validate": async (args: Record<string, unknown>) => {
+      const { file, preset, constraints: customConstraints } = args as {
+        file: string;
+        preset?: "default" | "api" | "readonly";
+        constraints?: SlotConstraints;
+      };
+
+      if (!file) {
+        return {
+          error: "File path is required",
+          tip: "Provide the path to the slot file to validate",
+        };
+      }
+
+      // 프리셋 선택
+      let constraints: SlotConstraints;
+      if (customConstraints) {
+        constraints = customConstraints;
+      } else {
+        switch (preset) {
+          case "api":
+            constraints = API_SLOT_CONSTRAINTS;
+            break;
+          case "readonly":
+            constraints = READONLY_SLOT_CONSTRAINTS;
+            break;
+          default:
+            constraints = DEFAULT_SLOT_CONSTRAINTS;
+        }
+      }
+
+      // 파일 경로 정규화 및 보안 검증 (LFI 방지)
+      const path = await import("path");
+      const rawPath = file.startsWith("/") || file.includes(":")
+        ? file
+        : path.join(projectRoot, file);
+      const filePath = path.normalize(path.resolve(rawPath));
+      const normalizedRoot = path.normalize(path.resolve(projectRoot));
+
+      // 경로가 프로젝트 루트 내에 있는지 검증
+      if (!filePath.startsWith(normalizedRoot)) {
+        return {
+          error: "Access denied: File path is outside project root",
+          tip: "Only files within the project directory can be validated",
+          requestedPath: file,
+          projectRoot: projectRoot,
+        };
+      }
+
+      const result = await validateSlotConstraints(filePath, constraints);
+
+      return {
+        valid: result.valid,
+        file: result.filePath,
+        stats: result.stats,
+        violations: result.violations.map((v) => ({
+          type: v.type,
+          severity: v.severity,
+          message: v.message,
+          suggestion: v.suggestion,
+          line: v.line,
+        })),
+        suggestions: result.suggestions,
+        constraintsUsed: constraints,
+        tip: result.valid
+          ? "✅ Slot passes all constraints"
+          : "Fix violations before deployment. Use mandu.slot.constraints for guidance.",
+      };
+    },
+
+    "mandu.slot.constraints": async (args: Record<string, unknown>) => {
+      const { preset } = args as { preset?: "default" | "api" | "readonly" };
+
+      const presets = {
+        default: {
+          name: "Default",
+          description: "Basic constraints for general slots",
+          constraints: DEFAULT_SLOT_CONSTRAINTS,
+        },
+        api: {
+          name: "API Slot",
+          description: "Constraints for API handlers with validation requirements",
+          constraints: API_SLOT_CONSTRAINTS,
+        },
+        readonly: {
+          name: "Read-only Slot",
+          description: "Strict constraints for read-only operations (no DB writes)",
+          constraints: READONLY_SLOT_CONSTRAINTS,
+        },
+      };
+
+      if (preset) {
+        const selected = presets[preset];
+        return {
+          preset: preset,
+          ...selected,
+          usage: `
+.constraints(${JSON.stringify(selected.constraints, null, 2)})
+          `.trim(),
+        };
+      }
+
+      return {
+        available: Object.entries(presets).map(([key, value]) => ({
+          preset: key,
+          name: value.name,
+          description: value.description,
+          constraints: value.constraints,
+        })),
+        tip: "Use these constraints with Mandu.filling().constraints({...}) to enforce slot rules.",
+        example: `
+Mandu.filling()
+  .purpose("사용자 목록 조회 API")
+  .constraints({
+    maxLines: 50,
+    maxCyclomaticComplexity: 10,
+    requiredPatterns: ["input-validation", "error-handling"],
+    forbiddenPatterns: ["direct-db-write"],
+    allowedImports: ["server/domain/*", "shared/utils/*"],
+  })
+  .get(async (ctx) => { ... });
+        `.trim(),
+      };
+    },
+  };
+
+  // Backward-compatible aliases
+  handlers["mandu_validate_slot"] = handlers["mandu.slot.validate"];
+  handlers["mandu_get_slot_constraints"] = handlers["mandu.slot.constraints"];
+
+  return handlers;
+}

package/src/tools/slot.ts

@@ -10,18 +10,12 @@ import path from "path";
 
 export const slotToolDefinitions: Tool[] = [
   {
-    name: "mandu_read_slot",
+    name: "mandu.slot.read",
+    annotations: {
+      readOnlyHint: true,
+    },
     description:
-      "Read the TypeScript source of a route's slot file and validate its structure. " +
-      "In Mandu, a 'slot' is the server-side data loader for a route: " +
-      "it runs on every request before rendering and returns a typed object " +
-      "that is injected into the page component as props (for pages) or as handler context (for API routes). " +
-      "The loader receives a ManduContext (ctx) with access to ctx.cookies for reading/setting cookies — " +
-      "cookies set in the loader are automatically applied to the SSR Response via Set-Cookie headers. " +
-      "Advanced: ctx.cookies.getSigned(name, secret) for HMAC-SHA256 signed cookies, " +
-      "ctx.cookies.getParsed(name, zodSchema) for Zod-validated JSON cookies. " +
-      "Slot files live at spec/slots/{routeId}.slot.ts and are auto-linked by generateManifest(). " +
-      "Returns the raw source, line count, and any structural validation issues.",
+      "Read the TypeScript source of a route's slot file and validate its structure.",
     inputSchema: {
       type: "object",
       properties: {
@@ -34,17 +28,12 @@ export const slotToolDefinitions: Tool[] = [
     },
   },
   {
-    name: "mandu_validate_slot",
+    name: "mandu.slot.validate",
+    annotations: {
+      readOnlyHint: true,
+    },
     description:
-      "Validate TypeScript slot content against Mandu's structural rules — without writing any files. " +
-      "A valid slot must export a default function (or use the slot() builder) that accepts a Request " +
-      "and returns a plain serializable object (becomes the typed props injected into the page). " +
-      "Returns: " +
-      "errors (must fix before use), " +
-      "warnings (best-practice suggestions), " +
-      "autoFixable issues (with corrected code preview), " +
-      "manualFixRequired items (issues needing human review). " +
-      "Use this before writing a slot file with the Edit tool to catch structural problems early.",
+      "Validate TypeScript slot content against structural rules without writing files. Returns errors, warnings, and auto-fix previews.",
     inputSchema: {
       type: "object",
       properties: {
@@ -61,8 +50,8 @@ export const slotToolDefinitions: Tool[] = [
 export function slotTools(projectRoot: string) {
   const paths = getProjectPaths(projectRoot);
 
-  return {
-    mandu_read_slot: async (args: Record<string, unknown>) => {
+  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
+    "mandu.slot.read": async (args: Record<string, unknown>) => {
       const { routeId } = args as { routeId: string };
 
       // Load manifest to find the route
@@ -96,7 +85,7 @@ export function slotTools(projectRoot: string) {
           return {
             exists: false,
             slotPath: route.slotModule,
-            message: "Slot file does not exist. Run mandu_generate to create it.",
+            message: "Slot file does not exist. Run mandu.generate to create it.",
           };
         }
 
@@ -123,7 +112,7 @@ export function slotTools(projectRoot: string) {
       }
     },
 
-    mandu_validate_slot: async (args: Record<string, unknown>) => {
+    "mandu.slot.validate": async (args: Record<string, unknown>) => {
       const { content } = args as { content: string };
 
       const validation = validateSlotContent(content);
@@ -171,4 +160,10 @@ export function slotTools(projectRoot: string) {
       };
     },
   };
+
+  // Backward-compatible aliases
+  handlers["mandu_read_slot"] = handlers["mandu.slot.read"];
+  handlers["mandu_validate_slot"] = handlers["mandu.slot.validate"];
+
+  return handlers;
 }

package/src/tools/spec.ts

@@ -2,7 +2,6 @@ import type { Tool } from "@modelcontextprotocol/sdk/types.js";
 import {
   loadManifest,
   validateManifest,
-  writeLock,
   generateManifest,
   GENERATED_RELATIVE_PATHS,
   type RouteSpec,
@@ -14,17 +13,12 @@ import fs from "fs/promises";
 
 export const specToolDefinitions: Tool[] = [
   {
-    name: "mandu_list_routes",
+    name: "mandu.route.list",
     description:
-      "List all routes registered in the Mandu project, read from .mandu/routes.manifest.json. " +
-      "Route kinds: " +
-      "'api' (REST endpoint — app/**/route.ts, exports named GET/POST/PUT/PATCH/DELETE handler functions), " +
-      "'page' (SSR page — app/**/page.tsx, React component supporting client-side hydration islands). " +
-      "Special files auto-detected by the filesystem router (not user-created routes): " +
-      "layout.tsx (shared wrapper rendered around child routes), " +
-      "error.tsx (error boundary for the route subtree), " +
-      "loading.tsx (suspense fallback shown while page data loads). " +
-      "Each route may have an associated slotModule (server data loader) and contractModule (Zod API schema).",
+      "List all routes from .mandu/routes.manifest.json with their kind, pattern, slotModule, and contractModule.",
+    annotations: {
+      readOnlyHint: true,
+    },
     inputSchema: {
       type: "object",
       properties: {},
@@ -32,34 +26,31 @@ export const specToolDefinitions: Tool[] = [
     },
   },
   {
-    name: "mandu_get_route",
+    name: "mandu.route.get",
     description:
-      "Get full details of a specific route by its ID. " +
-      "Returns the complete route spec: kind, URL pattern, module paths (app, slot, contract, component), " +
-      "HTTP methods, and hydration configuration (for page routes with client islands). " +
-      "Use this before modifying a route to understand its current configuration.",
+      "Get full details of a specific route by its ID. Use before modifying a route.",
+    annotations: {
+      readOnlyHint: true,
+    },
     inputSchema: {
       type: "object",
       properties: {
         routeId: {
           type: "string",
-          description: "The route ID to retrieve (use mandu_list_routes to see all IDs)",
+          description: "The route ID to retrieve (use mandu.route.list to see all IDs)",
         },
       },
       required: ["routeId"],
     },
   },
   {
-    name: "mandu_add_route",
+    name: "mandu.route.add",
     description:
-      "Scaffold a new route by creating source files in app/ and registering it in the manifest. " +
-      "For 'api' routes: creates app/{path}/route.ts with a GET handler stub. " +
-      "For 'page' routes: creates app/{path}/page.tsx with a React component stub. " +
-      "withSlot=true (default): also creates spec/slots/{routeId}.slot.ts — " +
-      "the server-side data loader that runs on every request before rendering and injects typed props into the page. " +
-      "withContract=true: also creates spec/contracts/{routeId}.contract.ts — " +
-      "Zod schemas for request/response validation, enabling typed handlers, OpenAPI generation, and ATE L2/L3 testing. " +
-      "Automatically runs generateManifest() after creation to link all files.",
+      "Scaffold a new route in app/ with optional slot and contract files, then regenerate the manifest.",
+    annotations: {
+      destructiveHint: false,
+      readOnlyHint: false,
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -85,30 +76,31 @@ export const specToolDefinitions: Tool[] = [
     },
   },
   {
-    name: "mandu_delete_route",
+    name: "mandu.route.delete",
     description:
-      "Delete a route's app/ source file and regenerate the manifest. " +
-      "Only removes the app/{path}/route.ts or page.tsx file — " +
-      "slot files (spec/slots/) and contract files (spec/contracts/) are intentionally preserved, " +
-      "as they may be reused when the route is recreated. " +
-      "Use mandu_list_routes before deleting to confirm the correct routeId.",
+      "Delete a route's app/ source file and regenerate the manifest. Slot and contract files are preserved.",
+    annotations: {
+      destructiveHint: true,
+      readOnlyHint: false,
+    },
     inputSchema: {
       type: "object",
       properties: {
         routeId: {
           type: "string",
-          description: "The route ID to delete (use mandu_list_routes to find it)",
+          description: "The route ID to delete (use mandu.route.list to find it)",
         },
       },
       required: ["routeId"],
     },
   },
   {
-    name: "mandu_validate_manifest",
+    name: "mandu.manifest.validate",
     description:
-      "Validate the routes manifest (.mandu/routes.manifest.json) for structural integrity. " +
-      "Checks required fields, valid route kinds, correct module paths, and manifest schema version. " +
-      "Run this after manual manifest edits, after upgrading Mandu, or when routes behave unexpectedly.",
+      "Validate the routes manifest for structural integrity. Run after manual edits or when routes behave unexpectedly.",
+    annotations: {
+      readOnlyHint: true,
+    },
     inputSchema: {
       type: "object",
       properties: {},
@@ -120,8 +112,8 @@ export const specToolDefinitions: Tool[] = [
 export function specTools(projectRoot: string) {
   const paths = getProjectPaths(projectRoot);
 
-  return {
-    mandu_list_routes: async () => {
+  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
+    "mandu.route.list": async () => {
       const result = await loadManifest(paths.manifestPath);
       if (!result.success || !result.data) {
         return { error: result.errors };
@@ -141,7 +133,7 @@ export function specTools(projectRoot: string) {
       };
     },
 
-    mandu_get_route: async (args: Record<string, unknown>) => {
+    "mandu.route.get": async (args: Record<string, unknown>) => {
       const { routeId } = args as { routeId: string };
 
       const result = await loadManifest(paths.manifestPath);
@@ -157,7 +149,7 @@ export function specTools(projectRoot: string) {
       return { route };
     },
 
-    mandu_add_route: async (args: Record<string, unknown>) => {
+    "mandu.route.add": async (args: Record<string, unknown>) => {
       const { path: routePath, kind, withSlot = true, withContract = false } = args as {
         path: string;
         kind: "api" | "page";
@@ -213,10 +205,11 @@ export function specTools(projectRoot: string) {
         createdFiles,
         totalRoutes: genResult.manifest.routes.length,
         message: `Route '${routeId}' scaffolded successfully`,
+        relatedSkills: ["mandu-create-feature"],
       };
     },
 
-    mandu_delete_route: async (args: Record<string, unknown>) => {
+    "mandu.route.delete": async (args: Record<string, unknown>) => {
       const { routeId } = args as { routeId: string };
 
       // Load current manifest to find the route
@@ -253,7 +246,7 @@ export function specTools(projectRoot: string) {
       };
     },
 
-    mandu_validate_manifest: async () => {
+    "mandu.manifest.validate": async () => {
       const result = await loadManifest(paths.manifestPath);
       if (!result.success) {
         return {
@@ -269,4 +262,13 @@ export function specTools(projectRoot: string) {
       };
     },
   };
+
+  // Backward-compatible aliases (deprecated)
+  handlers["mandu_list_routes"] = handlers["mandu.route.list"];
+  handlers["mandu_get_route"] = handlers["mandu.route.get"];
+  handlers["mandu_add_route"] = handlers["mandu.route.add"];
+  handlers["mandu_delete_route"] = handlers["mandu.route.delete"];
+  handlers["mandu_validate_manifest"] = handlers["mandu.manifest.validate"];
+
+  return handlers;
 }

package/src/tools/transaction.ts

@@ -6,12 +6,16 @@ import {
   getTransactionStatus,
   hasActiveTransaction,
 } from "@mandujs/core";
+import { acquireLock, releaseLock, checkLock } from "../tx-lock.js";
 
 export const transactionToolDefinitions: Tool[] = [
   {
-    name: "mandu_begin",
+    name: "mandu.tx.begin",
     description:
       "Begin a new transaction. Creates a snapshot of the current spec state for safe rollback.",
+    annotations: {
+      readOnlyHint: false,
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -19,22 +23,35 @@ export const transactionToolDefinitions: Tool[] = [
           type: "string",
           description: "Description of the changes being made",
         },
+        sessionId: {
+          type: "string",
+          description: "Caller session identifier for the concurrency lock",
+        },
       },
       required: [],
     },
   },
   {
-    name: "mandu_commit",
+    name: "mandu.tx.commit",
     description: "Commit the current transaction, finalizing all changes",
+    annotations: {
+      readOnlyHint: false,
+    },
     inputSchema: {
       type: "object",
-      properties: {},
+      properties: {
+        lockId: { type: "string", description: "Lock ID returned by mandu.tx.begin" },
+      },
       required: [],
     },
   },
   {
-    name: "mandu_rollback",
+    name: "mandu.tx.rollback",
     description: "Rollback the current transaction, restoring the previous state",
+    annotations: {
+      destructiveHint: true,
+      readOnlyHint: false,
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -42,13 +59,17 @@ export const transactionToolDefinitions: Tool[] = [
           type: "string",
           description: "Specific change ID to rollback (optional, defaults to active transaction)",
         },
+        lockId: { type: "string", description: "Lock ID returned by mandu.tx.begin" },
       },
       required: [],
     },
   },
   {
-    name: "mandu_tx_status",
+    name: "mandu.tx.status",
     description: "Get the current transaction status",
+    annotations: {
+      readOnlyHint: true,
+    },
     inputSchema: {
       type: "object",
       properties: {},
@@ -58,9 +79,9 @@ export const transactionToolDefinitions: Tool[] = [
 ];
 
 export function transactionTools(projectRoot: string) {
-  return {
-    mandu_begin: async (args: Record<string, unknown>) => {
-      const { message } = args as { message?: string };
+  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
+    "mandu.tx.begin": async (args: Record<string, unknown>) => {
+      const { message, sessionId } = args as { message?: string; sessionId?: string };
 
       // Check if there's already an active transaction
       const isActive = await hasActiveTransaction(projectRoot);
@@ -72,6 +93,12 @@ export function transactionTools(projectRoot: string) {
         };
       }
 
+      // Acquire concurrency lock
+      const lock = acquireLock(sessionId || "anonymous");
+      if (!lock.success) {
+        return { error: lock.error };
+      }
+
       const change = await beginChange(projectRoot, {
         message: message || "MCP transaction",
       });
@@ -79,14 +106,16 @@ export function transactionTools(projectRoot: string) {
       return {
         success: true,
         changeId: change.id,
+        lockId: lock.lockId,
         snapshotId: change.snapshotId,
         message: change.message,
         createdAt: change.createdAt,
-        tip: "Use mandu_commit to finalize or mandu_rollback to revert changes",
+        tip: "Use mandu.tx.commit to finalize or mandu.tx.rollback to revert changes. Pass lockId to subsequent calls.",
       };
     },
 
-    mandu_commit: async () => {
+    "mandu.tx.commit": async (args: Record<string, unknown>) => {
+      const { lockId } = args as { lockId?: string };
       const isActive = await hasActiveTransaction(projectRoot);
       if (!isActive) {
         return {
@@ -95,6 +124,7 @@ export function transactionTools(projectRoot: string) {
       }
 
       const result = await commitChange(projectRoot);
+      if (lockId) releaseLock(lockId);
 
       return {
         success: result.success,
@@ -103,8 +133,8 @@ export function transactionTools(projectRoot: string) {
       };
     },
 
-    mandu_rollback: async (args: Record<string, unknown>) => {
-      const { changeId } = args as { changeId?: string };
+    "mandu.tx.rollback": async (args: Record<string, unknown>) => {
+      const { changeId, lockId } = args as { changeId?: string; lockId?: string };
 
       const isActive = await hasActiveTransaction(projectRoot);
       if (!isActive && !changeId) {
@@ -114,6 +144,7 @@ export function transactionTools(projectRoot: string) {
       }
 
       const result = await rollbackChange(projectRoot, changeId);
+      if (lockId) releaseLock(lockId);
 
       return {
         success: result.success,
@@ -126,13 +157,15 @@ export function transactionTools(projectRoot: string) {
       };
     },
 
-    mandu_tx_status: async () => {
+    "mandu.tx.status": async () => {
       const { state, change } = await getTransactionStatus(projectRoot);
+      const lock = checkLock();
 
       if (!state.active) {
         return {
           hasActiveTransaction: false,
           message: "No active transaction",
+          lock,
         };
       }
 
@@ -140,6 +173,7 @@ export function transactionTools(projectRoot: string) {
         hasActiveTransaction: true,
         changeId: state.changeId,
         snapshotId: state.snapshotId,
+        lock,
         change: change
           ? {
               id: change.id,
@@ -151,4 +185,12 @@ export function transactionTools(projectRoot: string) {
       };
     },
   };
+
+  // Backward-compatible aliases (deprecated)
+  handlers["mandu_begin"] = handlers["mandu.tx.begin"];
+  handlers["mandu_commit"] = handlers["mandu.tx.commit"];
+  handlers["mandu_rollback"] = handlers["mandu.tx.rollback"];
+  handlers["mandu_tx_status"] = handlers["mandu.tx.status"];
+
+  return handlers;
 }