@mandujs/mcp 0.18.9 → 0.18.10

package/src/tools/history.ts

@@ -8,8 +8,11 @@ import {
 
 export const historyToolDefinitions: Tool[] = [
   {
-    name: "mandu_list_history",
+    name: "mandu.history.list",
     description: "List the change history with snapshots",
+    annotations: {
+      readOnlyHint: true,
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -22,8 +25,11 @@ export const historyToolDefinitions: Tool[] = [
     },
   },
   {
-    name: "mandu_get_snapshot",
+    name: "mandu.history.snapshot",
     description: "Get details of a specific snapshot",
+    annotations: {
+      readOnlyHint: true,
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -36,8 +42,12 @@ export const historyToolDefinitions: Tool[] = [
     },
   },
   {
-    name: "mandu_prune_history",
+    name: "mandu.history.prune",
     description: "Remove old snapshots to free up space",
+    annotations: {
+      destructiveHint: true,
+      readOnlyHint: false,
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -52,8 +62,8 @@ export const historyToolDefinitions: Tool[] = [
 ];
 
 export function historyTools(projectRoot: string) {
-  return {
-    mandu_list_history: async (args: Record<string, unknown>) => {
+  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
+    "mandu.history.list": async (args: Record<string, unknown>) => {
       const { limit = 10 } = args as { limit?: number };
 
       const changes = await listChanges(projectRoot);
@@ -83,7 +93,7 @@ export function historyTools(projectRoot: string) {
       };
     },
 
-    mandu_get_snapshot: async (args: Record<string, unknown>) => {
+    "mandu.history.snapshot": async (args: Record<string, unknown>) => {
       const { snapshotId } = args as { snapshotId: string };
 
       const snapshot = await readSnapshotById(projectRoot, snapshotId);
@@ -117,7 +127,7 @@ export function historyTools(projectRoot: string) {
       };
     },
 
-    mandu_prune_history: async (args: Record<string, unknown>) => {
+    "mandu.history.prune": async (args: Record<string, unknown>) => {
       const { keepCount = 5 } = args as { keepCount?: number };
 
       const deletedIds = await pruneHistory(projectRoot, keepCount);
@@ -135,4 +145,11 @@ export function historyTools(projectRoot: string) {
       };
     },
   };
+
+  // Backward-compatible aliases (deprecated)
+  handlers["mandu_list_history"] = handlers["mandu.history.list"];
+  handlers["mandu_get_snapshot"] = handlers["mandu.history.snapshot"];
+  handlers["mandu_prune_history"] = handlers["mandu.history.prune"];
+
+  return handlers;
 }

package/src/tools/hydration.ts

@@ -15,9 +15,14 @@ import path from "path";
 
 export const hydrationToolDefinitions: Tool[] = [
   {
-    name: "mandu_build",
+    name: "mandu.build",
     description:
       "Build client bundles for hydration. Compiles client slots (.client.ts) into browser-ready JavaScript bundles.",
+    annotations: {
+      destructiveHint: true,
+      readOnlyHint: false,
+      idempotentHint: true,
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -40,9 +45,12 @@ export const hydrationToolDefinitions: Tool[] = [
     },
   },
   {
-    name: "mandu_build_status",
+    name: "mandu.build.status",
     description:
       "Get the current build status, bundle manifest, and statistics for client bundles.",
+    annotations: {
+      readOnlyHint: true,
+    },
     inputSchema: {
       type: "object",
       properties: {},
@@ -50,9 +58,12 @@ export const hydrationToolDefinitions: Tool[] = [
     },
   },
   {
-    name: "mandu_list_islands",
+    name: "mandu.island.list",
     description:
       "List all routes that have client-side hydration (islands). Shows hydration strategy and priority for each.",
+    annotations: {
+      readOnlyHint: true,
+    },
     inputSchema: {
       type: "object",
       properties: {},
@@ -60,9 +71,12 @@ export const hydrationToolDefinitions: Tool[] = [
     },
   },
   {
-    name: "mandu_set_hydration",
+    name: "mandu.hydration.set",
     description:
       "Set hydration configuration for a specific route. Updates the route's hydration strategy and priority.",
+    annotations: {
+      readOnlyHint: false,
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -91,9 +105,13 @@ export const hydrationToolDefinitions: Tool[] = [
     },
   },
   {
-    name: "mandu_add_client_slot",
+    name: "mandu.hydration.addClientSlot",
     description:
       "Add a client slot file for a route to enable hydration. Creates the .client.ts file and updates the manifest.",
+    annotations: {
+      destructiveHint: false,
+      readOnlyHint: false,
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -120,8 +138,8 @@ export const hydrationToolDefinitions: Tool[] = [
 export function hydrationTools(projectRoot: string) {
   const paths = getProjectPaths(projectRoot);
 
-  return {
-    mandu_build: async (args: Record<string, unknown>) => {
+  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
+    "mandu.build": async (args: Record<string, unknown>) => {
       const { minify, sourcemap, targetRouteIds } = args as {
         minify?: boolean;
         sourcemap?: boolean;
@@ -163,7 +181,7 @@ export function hydrationTools(projectRoot: string) {
       };
     },
 
-    mandu_build_status: async () => {
+    "mandu.build.status": async () => {
       // Read bundle manifest
       const manifestPath = path.join(projectRoot, ".mandu/manifest.json");
       const manifest = await readJsonFile<BundleManifest>(manifestPath);
@@ -171,7 +189,7 @@ export function hydrationTools(projectRoot: string) {
       if (!manifest) {
         return {
           hasBundles: false,
-          message: "No bundle manifest found. Run mandu_build first.",
+          message: "No bundle manifest found. Run mandu.build first.",
         };
       }
 
@@ -197,7 +215,7 @@ export function hydrationTools(projectRoot: string) {
       };
     },
 
-    mandu_list_islands: async () => {
+    "mandu.island.list": async () => {
       // Load manifest
       const manifestResult = await loadManifest(paths.manifestPath);
       if (!manifestResult.success || !manifestResult.data) {
@@ -236,7 +254,7 @@ export function hydrationTools(projectRoot: string) {
       };
     },
 
-    mandu_set_hydration: async (args: Record<string, unknown>) => {
+    "mandu.hydration.set": async (args: Record<string, unknown>) => {
       const { routeId, strategy, priority, preload } = args as {
         routeId: string;
         strategy?: SpecHydrationStrategy;
@@ -295,7 +313,7 @@ export function hydrationTools(projectRoot: string) {
       };
     },
 
-    mandu_add_client_slot: async (args: Record<string, unknown>) => {
+    "mandu.hydration.addClientSlot": async (args: Record<string, unknown>) => {
       const { routeId, strategy = "island", priority = "visible" } = args as {
         routeId: string;
         strategy?: SpecHydrationStrategy;
@@ -370,12 +388,21 @@ export function hydrationTools(projectRoot: string) {
         message: `Created client slot: ${clientModulePath}`,
         nextSteps: [
           `Edit ${clientModulePath} to add client-side logic`,
-          `Run mandu_build to compile the client bundle`,
+          `Run mandu.build to compile the client bundle`,
           `The page will now hydrate in the browser`,
         ],
       };
     },
   };
+
+  // Backward-compatible aliases (deprecated)
+  handlers["mandu_build"] = handlers["mandu.build"];
+  handlers["mandu_build_status"] = handlers["mandu.build.status"];
+  handlers["mandu_list_islands"] = handlers["mandu.island.list"];
+  handlers["mandu_set_hydration"] = handlers["mandu.hydration.set"];
+  handlers["mandu_add_client_slot"] = handlers["mandu.hydration.addClientSlot"];
+
+  return handlers;
 }
 
 /**

package/src/tools/index.ts

@@ -9,6 +9,7 @@ import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import type { ActivityMonitor } from "../activity-monitor.js";
 import { mcpToolRegistry } from "../registry/mcp-tool-registry.js";
 import { moduleToPlugins } from "../adapters/tool-adapter.js";
+import { type McpProfile, getProfileCategories } from "../profiles.js";
 
 // 도구 모듈 export
 export { specTools, specToolDefinitions } from "./spec.js";
@@ -16,16 +17,21 @@ export { generateTools, generateToolDefinitions } from "./generate.js";
 export { transactionTools, transactionToolDefinitions } from "./transaction.js";
 export { historyTools, historyToolDefinitions } from "./history.js";
 export { guardTools, guardToolDefinitions } from "./guard.js";
+export { decisionTools, decisionToolDefinitions } from "./decisions.js";
+export { negotiateTools, negotiateToolDefinitions } from "./negotiate.js";
+export { slotValidationTools, slotValidationToolDefinitions } from "./slot-validation.js";
 export { slotTools, slotToolDefinitions } from "./slot.js";
 export { hydrationTools, hydrationToolDefinitions } from "./hydration.js";
 export { contractTools, contractToolDefinitions } from "./contract.js";
 export { brainTools, brainToolDefinitions } from "./brain.js";
 export { runtimeTools, runtimeToolDefinitions } from "./runtime.js";
 export { seoTools, seoToolDefinitions } from "./seo.js";
-export { projectTools, projectToolDefinitions } from "./project.js";
+export { projectTools, projectToolDefinitions, getDevServerState } from "./project.js";
 export { ateTools, ateToolDefinitions } from "./ate.js";
 export { resourceTools, resourceToolDefinitions } from "./resource.js";
 export { componentTools, componentToolDefinitions } from "./component.js";
+export { kitchenTools, kitchenToolDefinitions } from "./kitchen.js";
+export { compositeTools, compositeToolDefinitions } from "./composite.js";
 
 // 도구 모듈 import (등록용)
 import { specTools, specToolDefinitions } from "./spec.js";
@@ -33,6 +39,9 @@ import { generateTools, generateToolDefinitions } from "./generate.js";
 import { transactionTools, transactionToolDefinitions } from "./transaction.js";
 import { historyTools, historyToolDefinitions } from "./history.js";
 import { guardTools, guardToolDefinitions } from "./guard.js";
+import { decisionTools, decisionToolDefinitions } from "./decisions.js";
+import { negotiateTools, negotiateToolDefinitions } from "./negotiate.js";
+import { slotValidationTools, slotValidationToolDefinitions } from "./slot-validation.js";
 import { slotTools, slotToolDefinitions } from "./slot.js";
 import { hydrationTools, hydrationToolDefinitions } from "./hydration.js";
 import { contractTools, contractToolDefinitions } from "./contract.js";
@@ -43,6 +52,8 @@ import { projectTools, projectToolDefinitions } from "./project.js";
 import { ateTools, ateToolDefinitions } from "./ate.js";
 import { resourceTools, resourceToolDefinitions } from "./resource.js";
 import { componentTools, componentToolDefinitions } from "./component.js";
+import { kitchenTools, kitchenToolDefinitions } from "./kitchen.js";
+import { compositeTools, compositeToolDefinitions } from "./composite.js";
 
 /**
  * 도구 모듈 정보
@@ -67,6 +78,9 @@ const TOOL_MODULES: ToolModule[] = [
   { category: "transaction", definitions: transactionToolDefinitions, handlers: transactionTools },
   { category: "history", definitions: historyToolDefinitions, handlers: historyTools },
   { category: "guard", definitions: guardToolDefinitions, handlers: guardTools },
+  { category: "decisions", definitions: decisionToolDefinitions, handlers: decisionTools },
+  { category: "negotiate", definitions: negotiateToolDefinitions, handlers: negotiateTools },
+  { category: "slot-validation", definitions: slotValidationToolDefinitions, handlers: slotValidationTools },
   { category: "slot", definitions: slotToolDefinitions, handlers: slotTools },
   { category: "hydration", definitions: hydrationToolDefinitions, handlers: hydrationTools },
   { category: "contract", definitions: contractToolDefinitions, handlers: contractTools },
@@ -77,6 +91,8 @@ const TOOL_MODULES: ToolModule[] = [
   { category: "ate", definitions: ateToolDefinitions, handlers: ateTools as ToolModule["handlers"] },
   { category: "resource", definitions: resourceToolDefinitions, handlers: resourceTools },
   { category: "component", definitions: componentToolDefinitions, handlers: componentTools },
+  { category: "kitchen", definitions: kitchenToolDefinitions, handlers: kitchenTools },
+  { category: "composite", definitions: compositeToolDefinitions, handlers: compositeTools },
 ];
 
 /**
@@ -98,9 +114,19 @@ const TOOL_MODULES: ToolModule[] = [
 export function registerBuiltinTools(
   projectRoot: string,
   server?: Server,
-  monitor?: ActivityMonitor
+  monitor?: ActivityMonitor,
+  options?: { profile?: McpProfile }
 ): void {
+  const allowedCategories = options?.profile
+    ? getProfileCategories(options.profile)
+    : null;
+
   for (const module of TOOL_MODULES) {
+    // Profile filtering: skip categories not in the allowed list
+    if (allowedCategories && !allowedCategories.includes(module.category)) {
+      continue;
+    }
+
     // Server가 필요한 모듈은 Server가 있을 때만 등록
     if (module.requiresServer && !server) {
       continue;

package/src/tools/kitchen.ts

@@ -0,0 +1,107 @@
+/**
+ * Mandu MCP Kitchen Tools
+ * Bridge between Kitchen DevTools (browser) and MCP protocol.
+ * Enables any MCP-compatible agent to read client-side errors in real-time.
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { loadManduConfig } from "@mandujs/core";
+import { getDevServerState } from "./project.js";
+
+export const kitchenToolDefinitions: Tool[] = [
+  {
+    name: "mandu.kitchen.errors",
+    description:
+      "Read client-side errors captured by Kitchen DevTools. Use clear=true to clear after reading.",
+    annotations: {
+      readOnlyHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        clear: {
+          type: "boolean",
+          description: "Clear errors after reading (default: false)",
+        },
+      },
+      required: [],
+    },
+  },
+];
+
+export function kitchenTools(projectRoot: string) {
+  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
+    "mandu.kitchen.errors": async (args: Record<string, unknown>) => {
+      const { clear = false } = args as { clear?: boolean };
+
+      // Detect port from the running dev server output first, then fall back to config
+      let port: number | undefined;
+
+      const serverState = getDevServerState();
+      if (serverState) {
+        // Parse the actual port from dev server stdout (e.g. "http://localhost:3333")
+        for (const line of serverState.output) {
+          const portMatch = line.match(/https?:\/\/localhost:(\d+)/);
+          if (portMatch) {
+            port = parseInt(portMatch[1], 10);
+          }
+        }
+      }
+
+      // Fall back to config if we couldn't detect from running server
+      if (!port) {
+        const config = await loadManduConfig(projectRoot);
+        port = config.server?.port ?? 3333;
+      }
+
+      const baseUrl = `http://localhost:${port}`;
+
+      try {
+        // Fetch errors from Kitchen API
+        const res = await fetch(`${baseUrl}/__kitchen/api/errors`);
+        if (!res.ok) {
+          return {
+            success: false,
+            message: `Dev server not reachable at ${baseUrl}. Is 'mandu dev' running?`,
+            errors: [],
+          };
+        }
+
+        const data = await res.json() as { errors: unknown[]; count: number };
+
+        // Clear if requested
+        if (clear && data.count > 0) {
+          await fetch(`${baseUrl}/__kitchen/api/errors`, { method: "DELETE" });
+        }
+
+        if (data.count === 0) {
+          return {
+            success: true,
+            message: "No client-side errors detected.",
+            errors: [],
+            count: 0,
+          };
+        }
+
+        return {
+          success: true,
+          message: `${data.count} client-side error(s) captured.${clear ? " Errors cleared." : ""}`,
+          errors: data.errors,
+          count: data.count,
+          relatedSkills: ["mandu-debug"],
+        };
+      } catch {
+        return {
+          success: false,
+          message: `Cannot connect to dev server at ${baseUrl}. Make sure 'mandu dev' is running.`,
+          errors: [],
+        };
+      }
+    },
+  };
+
+  // Backward-compatible alias
+  handlers["mandu_kitchen_errors"] = handlers["mandu.kitchen.errors"];
+
+  return handlers;
+}

package/src/tools/negotiate.ts

@@ -0,0 +1,263 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import {
+  negotiate,
+  generateScaffold,
+  analyzeExistingStructure,
+  type NegotiationRequest,
+  type FeatureCategory,
+  type GuardPreset,
+} from "@mandujs/core";
+
+export const negotiateToolDefinitions: Tool[] = [
+  {
+    name: "mandu.negotiate",
+    description:
+      "Negotiate recommended structure and file templates before implementing a feature. " +
+      "IMPORTANT: featureName must be a short English kebab-case slug.",
+    annotations: {
+      readOnlyHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        intent: {
+          type: "string",
+          description: "What you want to implement, in any language (e.g., '사용자 인증 기능 추가', 'Add payment integration')",
+        },
+        featureName: {
+          type: "string",
+          description: "REQUIRED: Short English slug for the feature name (e.g., 'chat', 'user-auth', 'payment', 'file-upload'). " +
+            "You MUST translate the user's intent to a concise English identifier. " +
+            "Use lowercase kebab-case. This becomes the directory/module name.",
+        },
+        requirements: {
+          type: "array",
+          items: { type: "string" },
+          description: "Specific requirements (e.g., ['JWT-based', 'OAuth support'])",
+        },
+        constraints: {
+          type: "array",
+          items: { type: "string" },
+          description: "Constraints to respect (e.g., ['use existing User model', 'Redis sessions'])",
+        },
+        category: {
+          type: "string",
+          enum: ["auth", "crud", "api", "ui", "integration", "data", "util", "config", "other"],
+          description: "Feature category (auto-detected if not specified)",
+        },
+        preset: {
+          type: "string",
+          enum: ["fsd", "clean", "hexagonal", "atomic", "cqrs", "mandu"],
+          description: "Architecture preset (default: mandu). Use 'cqrs' for Command/Query separation.",
+        },
+      },
+      required: ["intent"],
+    },
+  },
+  {
+    name: "mandu.negotiate.scaffold",
+    description:
+      "Generate scaffold files from a negotiation plan. Use after mandu.negotiate.",
+    annotations: {
+      destructiveHint: true,
+      readOnlyHint: false,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        intent: {
+          type: "string",
+          description: "Feature intent (used to get the structure plan)",
+        },
+        category: {
+          type: "string",
+          enum: ["auth", "crud", "api", "ui", "integration", "data", "util", "config", "other"],
+          description: "Feature category",
+        },
+        dryRun: {
+          type: "boolean",
+          description: "If true, only show what would be created without actually creating files",
+        },
+        overwrite: {
+          type: "boolean",
+          description: "If true, overwrite existing files (default: false)",
+        },
+        preset: {
+          type: "string",
+          enum: ["fsd", "clean", "hexagonal", "atomic", "cqrs", "mandu"],
+          description: "Architecture preset (default: mandu)",
+        },
+      },
+      required: ["intent"],
+    },
+  },
+  {
+    name: "mandu.negotiate.analyze",
+    description:
+      "Analyze the existing project structure and return detected layers, features, and recommendations.",
+    annotations: {
+      readOnlyHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+    },
+  },
+];
+
+export function negotiateTools(projectRoot: string) {
+  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
+    "mandu.negotiate": async (args: Record<string, unknown>) => {
+      const { intent, featureName, requirements, constraints, category, preset } = args as {
+        intent: string;
+        featureName?: string;
+        requirements?: string[];
+        constraints?: string[];
+        category?: FeatureCategory;
+        preset?: GuardPreset;
+      };
+
+      if (!intent) {
+        return {
+          error: "Intent is required",
+          tip: "Describe what you want to implement (e.g., '사용자 인증 기능 추가')",
+        };
+      }
+
+      const request: NegotiationRequest = {
+        intent,
+        featureName,
+        requirements,
+        constraints,
+        category,
+        preset,
+      };
+
+      const result = await negotiate(request, projectRoot);
+
+      return {
+        approved: result.approved,
+        intent,
+        detectedCategory: category || "auto",
+        preset: result.preset,
+
+        // Structure summary
+        structure: result.structure.map((dir) => ({
+          path: dir.path,
+          purpose: dir.purpose,
+          layer: dir.layer,
+          files: dir.files.map((f) => ({
+            name: f.name,
+            purpose: f.purpose,
+            isSlot: f.isSlot || false,
+          })),
+        })),
+
+        // Slots to implement
+        slots: result.slots,
+
+        // Context
+        relatedDecisions: result.relatedDecisions,
+        warnings: result.warnings,
+        recommendations: result.recommendations,
+
+        // Summary
+        summary: {
+          estimatedFiles: result.estimatedFiles,
+          slotsToImplement: result.slots.length,
+          relatedDecisionsCount: result.relatedDecisions.length,
+        },
+
+        // Next steps
+        nextSteps: result.nextSteps,
+        tip: "Use mandu.negotiate.scaffold to create the file structure, then implement the TODO sections.",
+        relatedSkills: ["mandu-create-feature", "mandu-guard-guide"],
+      };
+    },
+
+    "mandu.negotiate.scaffold": async (args: Record<string, unknown>) => {
+      const { intent, featureName, category, dryRun = false, overwrite = false, preset } = args as {
+        intent: string;
+        featureName?: string;
+        category?: FeatureCategory;
+        dryRun?: boolean;
+        overwrite?: boolean;
+        preset?: GuardPreset;
+      };
+
+      if (!intent) {
+        return {
+          error: "Intent is required",
+          tip: "Provide the same intent you used with mandu.negotiate",
+        };
+      }
+
+      // 먼저 협상하여 구조 계획 얻기
+      const plan = await negotiate({ intent, featureName, category, preset }, projectRoot);
+
+      if (!plan.approved) {
+        return {
+          error: "Negotiation not approved",
+          reason: plan.rejectionReason,
+        };
+      }
+
+      // Scaffold 생성
+      const result = await generateScaffold(plan.structure, projectRoot, {
+        dryRun,
+        overwrite,
+      });
+
+      return {
+        success: result.success,
+        dryRun,
+        created: {
+          directories: result.createdDirs,
+          files: result.createdFiles,
+        },
+        skipped: result.skippedFiles,
+        errors: result.errors,
+        summary: {
+          dirsCreated: result.createdDirs.length,
+          filesCreated: result.createdFiles.length,
+          filesSkipped: result.skippedFiles.length,
+        },
+        nextSteps: [
+          "1. Review the generated files",
+          "2. Implement the TODO sections in each file",
+          "3. Run mandu_guard_heal to verify architecture compliance",
+          "4. Add tests for your implementation",
+        ],
+        tip: dryRun
+          ? "This was a dry run. Remove dryRun: true to actually create files."
+          : "Files created! Start implementing the TODO sections.",
+      };
+    },
+
+    "mandu.negotiate.analyze": async () => {
+      const result = await analyzeExistingStructure(projectRoot);
+
+      return {
+        projectRoot,
+        detected: {
+          layers: result.layers,
+          layerCount: result.layers.length,
+          existingFeatures: result.existingFeatures,
+          featureCount: result.existingFeatures.length,
+        },
+        recommendations: result.recommendations,
+        tip: result.layers.length > 0
+          ? "Use mandu.negotiate to add new features following the existing structure."
+          : "Use mandu.negotiate to establish your project structure.",
+      };
+    },
+  };
+
+  // Backward-compatible aliases
+  handlers["mandu_negotiate"] = handlers["mandu.negotiate"];
+  handlers["mandu_generate_scaffold"] = handlers["mandu.negotiate.scaffold"];
+  handlers["mandu_analyze_structure"] = handlers["mandu.negotiate.analyze"];
+
+  return handlers;
+}