@mandujs/mcp 0.18.9 → 0.19.0

package/src/tools/brain.ts

@@ -2,12 +2,12 @@
  * Mandu MCP - Brain Tools
  *
  * MCP tools for Brain functionality:
- * - mandu_doctor: Guard failure analysis + patch suggestions
- * - mandu_watch_start: Start file watching
- * - mandu_watch_status: Get watch status
- * - mandu_check_location: Check if file location is valid (v0.2)
- * - mandu_check_import: Check if imports are valid (v0.2)
- * - mandu_get_architecture: Get project architecture rules (v0.2)
+ * - mandu.brain.doctor: Guard failure analysis + patch suggestions
+ * - mandu.watch.start: Start file watching
+ * - mandu.watch.status: Get watch status
+ * - mandu.brain.checkLocation: Check if file location is valid (v0.2)
+ * - mandu.brain.checkImport: Check if imports are valid (v0.2)
+ * - mandu.brain.architecture: Get project architecture rules (v0.2)
  */
 
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
@@ -31,9 +31,12 @@ import { getProjectPaths } from "../utils/project.js";
 
 export const brainToolDefinitions: Tool[] = [
   {
-    name: "mandu_doctor",
+    name: "mandu.brain.doctor",
     description:
       "Analyze Guard failures and suggest patches. Works with or without LLM - template-based analysis is always available.",
+    annotations: {
+      readOnlyHint: true,
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -47,9 +50,12 @@ export const brainToolDefinitions: Tool[] = [
     },
   },
   {
-    name: "mandu_watch_start",
+    name: "mandu.watch.start",
     description:
       "Start file watching with architecture rule warnings. Watches for common mistakes and emits warnings (no blocking).",
+    annotations: {
+      readOnlyHint: false,
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -62,9 +68,12 @@ export const brainToolDefinitions: Tool[] = [
     },
   },
   {
-    name: "mandu_watch_status",
+    name: "mandu.watch.status",
     description:
       "Get the current watch status including recent warnings and active rules.",
+    annotations: {
+      readOnlyHint: true,
+    },
     inputSchema: {
       type: "object",
       properties: {},
@@ -72,9 +81,12 @@ export const brainToolDefinitions: Tool[] = [
     },
   },
   {
-    name: "mandu_watch_stop",
+    name: "mandu.watch.stop",
     description:
       "Stop file watching and clean up MCP notification subscriptions.",
+    annotations: {
+      readOnlyHint: false,
+    },
     inputSchema: {
       type: "object",
       properties: {},
@@ -83,9 +95,12 @@ export const brainToolDefinitions: Tool[] = [
   },
   // Architecture tools (v0.2)
   {
-    name: "mandu_check_location",
+    name: "mandu.brain.checkLocation",
     description:
       "Check if a file location follows project architecture rules. Call this BEFORE creating or moving files to ensure proper placement.",
+    annotations: {
+      readOnlyHint: true,
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -102,9 +117,12 @@ export const brainToolDefinitions: Tool[] = [
     },
   },
   {
-    name: "mandu_check_import",
+    name: "mandu.brain.checkImport",
     description:
       "Check if imports in a file follow architecture rules. Call this to validate imports before adding them.",
+    annotations: {
+      readOnlyHint: true,
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -122,9 +140,12 @@ export const brainToolDefinitions: Tool[] = [
     },
   },
   {
-    name: "mandu_get_architecture",
+    name: "mandu.brain.architecture",
     description:
       "Get the project architecture rules and folder structure. Use this to understand where to place new files.",
+    annotations: {
+      readOnlyHint: true,
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -144,8 +165,8 @@ let mcpWarningUnsubscribe: (() => void) | null = null;
 export function brainTools(projectRoot: string, server?: Server, monitor?: ActivityMonitor) {
   const paths = getProjectPaths(projectRoot);
 
-  return {
-    mandu_doctor: async (args: Record<string, unknown>) => {
+  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
+    "mandu.brain.doctor": async (args: Record<string, unknown>) => {
       const { useLLM = false } = args as { useLLM?: boolean };
 
       try {
@@ -213,7 +234,7 @@ export function brainTools(projectRoot: string, server?: Server, monitor?: Activ
       }
     },
 
-    mandu_watch_start: async (args: Record<string, unknown>) => {
+    "mandu.watch.start": async (args: Record<string, unknown>) => {
       const { debounceMs } = args as { debounceMs?: number };
 
       try {
@@ -256,7 +277,7 @@ export function brainTools(projectRoot: string, server?: Server, monitor?: Activ
               );
             }
 
-            // Push logging message (Claude Code receives in real-time)
+            // Push logging message (MCP client receives in real-time)
             server.sendLoggingMessage({
               level: "warning",
               logger: "mandu-watch",
@@ -313,7 +334,7 @@ export function brainTools(projectRoot: string, server?: Server, monitor?: Activ
       }
     },
 
-    mandu_watch_status: async () => {
+    "mandu.watch.status": async () => {
       try {
         const watcher = getWatcher();
 
@@ -321,7 +342,7 @@ export function brainTools(projectRoot: string, server?: Server, monitor?: Activ
           return {
             active: false,
             message: "Watch is not running",
-            tip: "Use mandu_watch_start to begin watching",
+            tip: "Use mandu.watch.start to begin watching",
           };
         }
 
@@ -352,7 +373,7 @@ export function brainTools(projectRoot: string, server?: Server, monitor?: Activ
       }
     },
 
-    mandu_watch_stop: async () => {
+    "mandu.watch.stop": async () => {
       try {
         // Clean up MCP notification subscription
         if (mcpWarningUnsubscribe) {
@@ -375,7 +396,7 @@ export function brainTools(projectRoot: string, server?: Server, monitor?: Activ
     },
 
     // Architecture tools (v0.2)
-    mandu_check_location: async (args: Record<string, unknown>) => {
+    "mandu.brain.checkLocation": async (args: Record<string, unknown>) => {
       const { path: filePath, content } = args as {
         path: string;
         content?: string;
@@ -423,7 +444,7 @@ export function brainTools(projectRoot: string, server?: Server, monitor?: Activ
       }
     },
 
-    mandu_check_import: async (args: Record<string, unknown>) => {
+    "mandu.brain.checkImport": async (args: Record<string, unknown>) => {
       const { sourceFile, imports } = args as {
         sourceFile: string;
         imports: string[];
@@ -466,7 +487,7 @@ export function brainTools(projectRoot: string, server?: Server, monitor?: Activ
       }
     },
 
-    mandu_get_architecture: async (args: Record<string, unknown>) => {
+    "mandu.brain.architecture": async (args: Record<string, unknown>) => {
       const { includeStructure = true } = args as {
         includeStructure?: boolean;
       };
@@ -515,7 +536,7 @@ export function brainTools(projectRoot: string, server?: Server, monitor?: Activ
                 indexedAt: structure.indexedAt,
               }
             : null,
-          tip: "이 규칙을 따라 파일을 생성하세요. mandu_check_location으로 검증할 수 있습니다.",
+          tip: "이 규칙을 따라 파일을 생성하세요. mandu.brain.checkLocation으로 검증할 수 있습니다.",
         };
       } catch (error) {
         return {
@@ -525,4 +546,15 @@ export function brainTools(projectRoot: string, server?: Server, monitor?: Activ
       }
     },
   };
+
+  // Backward-compatible aliases (deprecated)
+  handlers["mandu_doctor"] = handlers["mandu.brain.doctor"];
+  handlers["mandu_watch_start"] = handlers["mandu.watch.start"];
+  handlers["mandu_watch_stop"] = handlers["mandu.watch.stop"];
+  handlers["mandu_watch_status"] = handlers["mandu.watch.status"];
+  handlers["mandu_check_location"] = handlers["mandu.brain.checkLocation"];
+  handlers["mandu_check_import"] = handlers["mandu.brain.checkImport"];
+  handlers["mandu_get_architecture"] = handlers["mandu.brain.architecture"];
+
+  return handlers;
 }

package/src/tools/component.ts

@@ -1,185 +1,194 @@
-import type { Tool } from "@modelcontextprotocol/sdk/types.js";
-import path from "path";
-import fs from "fs/promises";
-
-export const componentToolDefinitions: Tool[] = [
-  {
-    name: "mandu_add_component",
-    description:
-      "Scaffold a new client-side component in the correct FSD (Feature-Sliced Design) layer. " +
-      "Mandu projects organize client components under src/client/ following FSD layers: " +
-      "shared (reusable primitives), entities (domain objects), features (user interactions), " +
-      "widgets (composite blocks), pages (page-level controllers). " +
-      "Creates the component file and updates the layer's public API index.ts. " +
-      "Use this instead of manually creating files in app/ to maintain FSD architecture.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        name: {
-          type: "string",
-          description: "Component name in PascalCase (e.g., 'ReactionBar', 'UserAvatar')",
-        },
-        layer: {
-          type: "string",
-          enum: ["shared", "entities", "features", "widgets", "pages"],
-          description:
-            "FSD layer: " +
-            "'shared' (reusable UI primitives, utils — no business logic), " +
-            "'entities' (domain models and their UI — User, Message, Post), " +
-            "'features' (user interactions that change state — like, comment, follow), " +
-            "'widgets' (composite sections combining entities+features), " +
-            "'pages' (page-level client components — use sparingly, prefer features/entities)",
-        },
-        slice: {
-          type: "string",
-          description:
-            "Feature slice name in kebab-case (required for features/entities/widgets). " +
-            "Examples: 'chat-reaction', 'user-profile', 'post-feed'. " +
-            "For 'shared' layer, use segment name like 'ui', 'lib', 'api'.",
-        },
-        segment: {
-          type: "string",
-          enum: ["ui", "model", "api", "lib", "config"],
-          description: "Segment within the slice (default: 'ui'). 'ui' for React components, 'model' for hooks/store, 'api' for data fetching.",
-        },
-        description: {
-          type: "string",
-          description: "Brief description of what this component does (added as a comment)",
-        },
-      },
-      required: ["name", "layer"],
-    },
-  },
-];
-
-function toKebabCase(name: string): string {
-  return name
-    .replace(/([A-Z])/g, "-$1")
-    .toLowerCase()
-    .replace(/^-/, "");
-}
-
-export function componentTools(projectRoot: string) {
-  return {
-    mandu_add_component: async (args: Record<string, unknown>) => {
-      const {
-        name,
-        layer,
-        slice,
-        segment = "ui",
-        description = "",
-      } = args as {
-        name: string;
-        layer: "shared" | "entities" | "features" | "widgets" | "pages";
-        slice?: string;
-        segment?: string;
-        description?: string;
-      };
-
-      // Validate: features/entities/widgets require a slice
-      if (["features", "entities", "widgets"].includes(layer) && !slice) {
-        return {
-          success: false,
-          error: `The '${layer}' layer requires a 'slice' name (e.g., 'chat-reaction', 'user-profile').`,
-        };
-      }
-
-      // Build the file path
-      const clientBase = path.join(projectRoot, "src", "client");
-      let componentDir: string;
-      let indexPath: string;
-
-      if (layer === "shared") {
-        const sliceName = slice || "ui";
-        componentDir = path.join(clientBase, "shared", sliceName);
-        indexPath = path.join(clientBase, "shared", sliceName, "index.ts");
-      } else if (layer === "pages") {
-        componentDir = path.join(clientBase, "pages");
-        indexPath = path.join(clientBase, "pages", "index.ts");
-      } else {
-        const sliceName = slice!;
-        componentDir = path.join(clientBase, layer, sliceName, segment);
-        indexPath = path.join(clientBase, layer, sliceName, "index.ts");
-      }
-
-      const kebabName = toKebabCase(name);
-      const componentFile = path.join(componentDir, `${kebabName}.tsx`);
-      const relativePath = path.relative(projectRoot, componentFile).replace(/\\/g, "/");
-
-      // Check if file already exists
-      try {
-        await fs.access(componentFile);
-        return {
-          success: false,
-          error: `Component file already exists: ${relativePath}`,
-        };
-      } catch {
-        // Good - file doesn't exist
-      }
-
-      // Create directory
-      await fs.mkdir(componentDir, { recursive: true });
-
-      // Generate component template
-      const descComment = description ? `\n * ${description}` : "";
-      const template = `/**
- * ${name} Component${descComment}
- * Layer: ${layer}${slice ? ` / ${slice}` : ""}
- */
-
-import { useState } from "react";
-
-interface ${name}Props {
-  // TODO: Define props
-  className?: string;
-}
-
-export function ${name}({ className }: ${name}Props) {
-  return (
-    <div className={className}>
-      {/* TODO: Implement ${name} */}
-    </div>
-  );
-}
-`;
-
-      await fs.writeFile(componentFile, template, "utf-8");
-
-      // Update index.ts (create or append export)
-      const exportLine = `export { ${name} } from "./${segment}/${kebabName}.js";\n`;
-      const simpleExportLine = `export { ${name} } from "./${kebabName}.js";\n`;
-
-      try {
-        let indexContent = "";
-        try {
-          indexContent = await fs.readFile(indexPath, "utf-8");
-        } catch {
-          // index.ts doesn't exist yet
-        }
-
-        const exportToAdd = layer === "shared" || layer === "pages" ? simpleExportLine : exportLine;
-
-        if (!indexContent.includes(`{ ${name} }`)) {
-          await fs.writeFile(indexPath, indexContent + exportToAdd, "utf-8");
-        }
-      } catch {
-        // index update failed - not critical
-      }
-
-      return {
-        success: true,
-        component: name,
-        layer,
-        slice: slice || null,
-        segment,
-        createdFiles: [relativePath],
-        updatedFiles: [path.relative(projectRoot, indexPath).replace(/\\/g, "/")],
-        message: `Created ${name} in ${layer}${slice ? `/${slice}` : ""}/${segment}`,
-        nextSteps: [
-          `Edit ${relativePath} to implement the component`,
-          `Import with: import { ${name} } from "@/client/${layer}${slice ? `/${slice}` : ""}"`,
-        ],
-      };
-    },
-  };
-}
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import path from "path";
+import fs from "fs/promises";
+
+export const componentToolDefinitions: Tool[] = [
+  {
+    name: "mandu.component.add",
+    annotations: {
+      destructiveHint: false,
+      readOnlyHint: false,
+    },
+    description:
+      "Scaffold a new client-side component in the correct FSD (Feature-Sliced Design) layer. " +
+      "Mandu projects organize client components under src/client/ following FSD layers: " +
+      "shared (reusable primitives), entities (domain objects), features (user interactions), " +
+      "widgets (composite blocks), pages (page-level controllers). " +
+      "Creates the component file and updates the layer's public API index.ts. " +
+      "Use this instead of manually creating files in app/ to maintain FSD architecture.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "Component name in PascalCase (e.g., 'ReactionBar', 'UserAvatar')",
+        },
+        layer: {
+          type: "string",
+          enum: ["shared", "entities", "features", "widgets", "pages"],
+          description:
+            "FSD layer: " +
+            "'shared' (reusable UI primitives, utils — no business logic), " +
+            "'entities' (domain models and their UI — User, Message, Post), " +
+            "'features' (user interactions that change state — like, comment, follow), " +
+            "'widgets' (composite sections combining entities+features), " +
+            "'pages' (page-level client components — use sparingly, prefer features/entities)",
+        },
+        slice: {
+          type: "string",
+          description:
+            "Feature slice name in kebab-case (required for features/entities/widgets). " +
+            "Examples: 'chat-reaction', 'user-profile', 'post-feed'. " +
+            "For 'shared' layer, use segment name like 'ui', 'lib', 'api'.",
+        },
+        segment: {
+          type: "string",
+          enum: ["ui", "model", "api", "lib", "config"],
+          description: "Segment within the slice (default: 'ui'). 'ui' for React components, 'model' for hooks/store, 'api' for data fetching.",
+        },
+        description: {
+          type: "string",
+          description: "Brief description of what this component does (added as a comment)",
+        },
+      },
+      required: ["name", "layer"],
+    },
+  },
+];
+
+function toKebabCase(name: string): string {
+  return name
+    .replace(/([A-Z])/g, "-$1")
+    .toLowerCase()
+    .replace(/^-/, "");
+}
+
+export function componentTools(projectRoot: string) {
+  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
+    "mandu.component.add": async (args: Record<string, unknown>) => {
+      const {
+        name,
+        layer,
+        slice,
+        segment = "ui",
+        description = "",
+      } = args as {
+        name: string;
+        layer: "shared" | "entities" | "features" | "widgets" | "pages";
+        slice?: string;
+        segment?: string;
+        description?: string;
+      };
+
+      // Validate: features/entities/widgets require a slice
+      if (["features", "entities", "widgets"].includes(layer) && !slice) {
+        return {
+          success: false,
+          error: `The '${layer}' layer requires a 'slice' name (e.g., 'chat-reaction', 'user-profile').`,
+        };
+      }
+
+      // Build the file path
+      const clientBase = path.join(projectRoot, "src", "client");
+      let componentDir: string;
+      let indexPath: string;
+
+      if (layer === "shared") {
+        const sliceName = slice || "ui";
+        componentDir = path.join(clientBase, "shared", sliceName);
+        indexPath = path.join(clientBase, "shared", sliceName, "index.ts");
+      } else if (layer === "pages") {
+        componentDir = path.join(clientBase, "pages");
+        indexPath = path.join(clientBase, "pages", "index.ts");
+      } else {
+        const sliceName = slice!;
+        componentDir = path.join(clientBase, layer, sliceName, segment);
+        indexPath = path.join(clientBase, layer, sliceName, "index.ts");
+      }
+
+      const kebabName = toKebabCase(name);
+      const componentFile = path.join(componentDir, `${kebabName}.tsx`);
+      const relativePath = path.relative(projectRoot, componentFile).replace(/\\/g, "/");
+
+      // Check if file already exists
+      try {
+        await fs.access(componentFile);
+        return {
+          success: false,
+          error: `Component file already exists: ${relativePath}`,
+        };
+      } catch {
+        // Good - file doesn't exist
+      }
+
+      // Create directory
+      await fs.mkdir(componentDir, { recursive: true });
+
+      // Generate component template
+      const descComment = description ? `\n * ${description}` : "";
+      const template = `/**
+ * ${name} Component${descComment}
+ * Layer: ${layer}${slice ? ` / ${slice}` : ""}
+ */
+
+import { useState } from "react";
+
+interface ${name}Props {
+  // TODO: Define props
+  className?: string;
+}
+
+export function ${name}({ className }: ${name}Props) {
+  return (
+    <div className={className}>
+      {/* TODO: Implement ${name} */}
+    </div>
+  );
+}
+`;
+
+      await fs.writeFile(componentFile, template, "utf-8");
+
+      // Update index.ts (create or append export)
+      const exportLine = `export { ${name} } from "./${segment}/${kebabName}.js";\n`;
+      const simpleExportLine = `export { ${name} } from "./${kebabName}.js";\n`;
+
+      try {
+        let indexContent = "";
+        try {
+          indexContent = await fs.readFile(indexPath, "utf-8");
+        } catch {
+          // index.ts doesn't exist yet
+        }
+
+        const exportToAdd = layer === "shared" || layer === "pages" ? simpleExportLine : exportLine;
+
+        if (!indexContent.includes(`{ ${name} }`)) {
+          await fs.writeFile(indexPath, indexContent + exportToAdd, "utf-8");
+        }
+      } catch {
+        // index update failed - not critical
+      }
+
+      return {
+        success: true,
+        component: name,
+        layer,
+        slice: slice || null,
+        segment,
+        createdFiles: [relativePath],
+        updatedFiles: [path.relative(projectRoot, indexPath).replace(/\\/g, "/")],
+        message: `Created ${name} in ${layer}${slice ? `/${slice}` : ""}/${segment}`,
+        nextSteps: [
+          `Edit ${relativePath} to implement the component`,
+          `Import with: import { ${name} } from "@/client/${layer}${slice ? `/${slice}` : ""}"`,
+        ],
+      };
+    },
+  };
+
+  // Backward-compatible aliases (deprecated)
+  handlers["mandu_add_component"] = handlers["mandu.component.add"];
+
+  return handlers;
+}