@mandujs/mcp 0.18.3 → 0.18.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/mcp",
-  "version": "0.18.3",
+  "version": "0.18.5",
   "description": "Mandu MCP Server - Agent-native interface for Mandu framework operations",
   "type": "module",
   "main": "./src/index.ts",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@mandujs/core": "^0.18.2",
+    "@mandujs/core": "^0.18.8",
     "@mandujs/ate": "^0.17.0",
     "@modelcontextprotocol/sdk": "^1.25.3"
   },

package/src/activity-monitor.ts

@@ -7,7 +7,7 @@
 
 import fs from "fs";
 import path from "path";
-import { spawn, type ChildProcess } from "child_process";
+import type { Subprocess } from "bun";
 
 const TOOL_ICONS: Record<string, string> = {
   // Spec
@@ -266,7 +266,7 @@ function writeDefaultConfig(projectRoot: string, config: Required<MonitorConfig>
 export class ActivityMonitor {
   private logFile = "";
   private logStream: fs.WriteStream | null = null;
-  private tailProcess: ChildProcess | null = null;
+  private tailProcess: Subprocess | null = null;
   private projectRoot: string;
   private config: Required<MonitorConfig>;
   private outputFormat: MonitorOutputFormat;
@@ -813,9 +813,9 @@ export class ActivityMonitor {
   private openTerminal(): void {
     try {
       if (process.platform === "win32") {
-        this.tailProcess = spawn(
-          "cmd",
+        this.tailProcess = Bun.spawn(
           [
+            "cmd",
             "/c",
             "start",
             "Mandu Activity Monitor",
@@ -824,22 +824,19 @@ export class ActivityMonitor {
             "-Command",
             `[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; chcp 65001 | Out-Null; Get-Content '${this.logFile}' -Wait -Encoding UTF8`,
           ],
-          { cwd: this.projectRoot, detached: true, stdio: "ignore" }
+          { cwd: this.projectRoot, stdio: ["ignore", "ignore", "ignore"] }
         );
       } else if (process.platform === "darwin") {
-        this.tailProcess = spawn(
-          "osascript",
-          ["-e", `tell application "Terminal" to do script "tail -f '${this.logFile}'"`],
-          { detached: true, stdio: "ignore" }
+        this.tailProcess = Bun.spawn(
+          ["osascript", "-e", `tell application "Terminal" to do script "tail -f '${this.logFile}'"`],
+          { stdio: ["ignore", "ignore", "ignore"] }
         );
       } else {
-        this.tailProcess = spawn(
-          "x-terminal-emulator",
-          ["-e", `tail -f '${this.logFile}'`],
-          { cwd: this.projectRoot, detached: true, stdio: "ignore" }
+        this.tailProcess = Bun.spawn(
+          ["x-terminal-emulator", "-e", `tail -f '${this.logFile}'`],
+          { cwd: this.projectRoot, stdio: ["ignore", "ignore", "ignore"] }
         );
       }
-      this.tailProcess?.unref();
     } catch {
       // Terminal auto-open failed silently
     }

package/src/server.ts

@@ -322,7 +322,10 @@ export class ManduMcpServer {
  * 리소스 패턴 매칭
  */
 function matchResourcePattern(pattern: string, uri: string): boolean {
-  const regexPattern = pattern.replace(/\{[^}]+\}/g, "([^/]+)");
+  const regexPattern = pattern
+    .split(/\{[^}]+\}/)
+    .map(part => part.replace(/[.+*?^${}()|[\]\\]/g, "\\$&"))
+    .join("([^/]+)");
   const regex = new RegExp(`^${regexPattern}$`);
   return regex.test(uri);
 }
@@ -332,10 +335,16 @@ function matchResourcePattern(pattern: string, uri: string): boolean {
  */
 function extractResourceParams(pattern: string, uri: string): Record<string, string> {
   const paramNames: string[] = [];
-  const regexPattern = pattern.replace(/\{([^}]+)\}/g, (_, name) => {
-    paramNames.push(name);
-    return "([^/]+)";
-  });
+  const regexPattern = pattern
+    .split(/\{([^}]+)\}/)
+    .map((part, index) => {
+      if (index % 2 === 1) {
+        paramNames.push(part);
+        return "([^/]+)";
+      }
+      return part.replace(/[.+*?^${}()|[\]\\]/g, "\\$&");
+    })
+    .join("");
 
   const regex = new RegExp(`^${regexPattern}$`);
   const match = uri.match(regex);

package/src/tools/brain.ts

@@ -26,7 +26,7 @@ import {
   generateJsonStatus,
   initializeArchitectureAnalyzer,
   getArchitectureAnalyzer,
-} from "../../../core/src/index.js";
+} from "@mandujs/core";
 import { getProjectPaths } from "../utils/project.js";
 
 export const brainToolDefinitions: Tool[] = [

package/src/tools/component.ts

@@ -0,0 +1,185 @@
+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}` : ""}"`,
+        ],
+      };
+    },
+  };
+}

package/src/tools/index.ts

@@ -24,6 +24,7 @@ export { seoTools, seoToolDefinitions } from "./seo.js";
 export { projectTools, projectToolDefinitions } from "./project.js";
 export { ateTools, ateToolDefinitions } from "./ate.js";
 export { resourceTools, resourceToolDefinitions } from "./resource.js";
+export { componentTools, componentToolDefinitions } from "./component.js";
 
 // 도구 모듈 import (등록용)
 import { specTools, specToolDefinitions } from "./spec.js";
@@ -40,6 +41,7 @@ import { seoTools, seoToolDefinitions } from "./seo.js";
 import { projectTools, projectToolDefinitions } from "./project.js";
 import { ateTools, ateToolDefinitions } from "./ate.js";
 import { resourceTools, resourceToolDefinitions } from "./resource.js";
+import { componentTools, componentToolDefinitions } from "./component.js";
 
 /**
  * 도구 모듈 정보
@@ -73,6 +75,7 @@ const TOOL_MODULES: ToolModule[] = [
   { category: "project", definitions: projectToolDefinitions, handlers: projectTools as ToolModule["handlers"], requiresServer: true },
   { category: "ate", definitions: ateToolDefinitions as any, handlers: ateTools as any },
   { category: "resource", definitions: resourceToolDefinitions, handlers: resourceTools },
+  { category: "component", definitions: componentToolDefinitions, handlers: componentTools },
 ];
 
 /**

package/src/tools/project.ts

@@ -22,23 +22,36 @@ type DevServerState = {
 };
 
 let devServerState: DevServerState | null = null;
+let devServerStarting = false;
 
 function trimOutput(text: string, maxChars: number = 4000): string {
   if (text.length <= maxChars) return text;
   return text.slice(-maxChars);
 }
 
-async function runCommand(cmd: string[], cwd: string) {
+const COMMAND_TIMEOUT_MS = 120_000; // 2 minutes
+
+async function runCommand(cmd: string[], cwd: string, timeoutMs: number = COMMAND_TIMEOUT_MS) {
   const proc = spawn(cmd, {
     cwd,
     stdout: "pipe",
     stderr: "pipe",
   });
 
-  const [stdout, stderr, exitCode] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-    proc.exited,
+  const timeoutPromise = new Promise<never>((_, reject) =>
+    setTimeout(() => {
+      proc.kill();
+      reject(new Error(`Command timed out after ${timeoutMs}ms: ${cmd.join(" ")}`));
+    }, timeoutMs)
+  );
+
+  const [stdout, stderr, exitCode] = await Promise.race([
+    Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]),
+    timeoutPromise,
   ]);
 
   return {
@@ -192,6 +205,16 @@ export function projectTools(projectRoot: string, server?: Server, monitor?: Act
 
       await fs.mkdir(baseDir, { recursive: true });
 
+      // Runtime whitelist validation for spawn arguments
+      const VALID_CSS = ["tailwind", "panda", "none"];
+      const VALID_UI = ["shadcn", "ark", "none"];
+      if (css !== undefined && !VALID_CSS.includes(css)) {
+        return { success: false, error: `Invalid css value: ${css}. Must be one of: ${VALID_CSS.join(", ")}` };
+      }
+      if (ui !== undefined && !VALID_UI.includes(ui)) {
+        return { success: false, error: `Invalid ui value: ${ui}. Must be one of: ${VALID_UI.join(", ")}` };
+      }
+
       const initArgs = ["@mandujs/cli", "init", name];
       if (minimal) {
         initArgs.push("--minimal");
@@ -201,7 +224,16 @@ export function projectTools(projectRoot: string, server?: Server, monitor?: Act
         if (theme) initArgs.push("--theme");
       }
 
-      const initResult = await runCommand(["bunx", ...initArgs], baseDir);
+      let initResult: { exitCode: number | null; stdout: string; stderr: string };
+      try {
+        initResult = await runCommand(["bunx", ...initArgs], baseDir);
+      } catch (err) {
+        return {
+          success: false,
+          step: "init",
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
       if (initResult.exitCode !== 0) {
         return {
           success: false,
@@ -216,7 +248,16 @@ export function projectTools(projectRoot: string, server?: Server, monitor?: Act
 
       let installResult: { exitCode: number | null; stdout: string; stderr: string } | null = null;
       if (install !== false) {
-        installResult = await runCommand(["bun", "install"], projectDir);
+        try {
+          installResult = await runCommand(["bun", "install"], projectDir);
+        } catch (err) {
+          return {
+            success: false,
+            step: "install",
+            projectDir,
+            error: err instanceof Error ? err.message : String(err),
+          };
+        }
         if (installResult.exitCode !== 0) {
           return {
             success: false,
@@ -253,53 +294,60 @@ export function projectTools(projectRoot: string, server?: Server, monitor?: Act
 
     mandu_dev_start: async (args: Record<string, unknown>) => {
       const { cwd } = args as { cwd?: string };
-      if (devServerState) {
+      if (devServerState || devServerStarting) {
         return {
           success: false,
-          message: "Dev server is already running",
-          pid: devServerState.process.pid,
-          cwd: devServerState.cwd,
+          message: devServerStarting
+            ? "Dev server is starting up, please wait"
+            : "Dev server is already running",
+          pid: devServerState?.process.pid,
+          cwd: devServerState?.cwd,
         };
       }
 
-      const targetDir = cwd ? path.resolve(projectRoot, cwd) : projectRoot;
-
-      const proc = spawn(["bun", "run", "dev"], {
-        cwd: targetDir,
-        stdout: "pipe",
-        stderr: "pipe",
-        stdin: "ignore",
-      });
-
-      const state: DevServerState = {
-        process: proc,
-        cwd: targetDir,
-        startedAt: new Date(),
-        output: [],
-        maxLines: 50,
-      };
-      devServerState = state;
+      devServerStarting = true;
+      try {
+        const targetDir = cwd ? path.resolve(projectRoot, cwd) : projectRoot;
+
+        const proc = spawn(["bun", "run", "dev"], {
+          cwd: targetDir,
+          stdout: "pipe",
+          stderr: "pipe",
+          stdin: "ignore",
+        });
+
+        const state: DevServerState = {
+          process: proc,
+          cwd: targetDir,
+          startedAt: new Date(),
+          output: [],
+          maxLines: 50,
+        };
+        devServerState = state;
+
+        consumeStream(proc.stdout, state, "stdout", server).catch(() => {});
+        consumeStream(proc.stderr, state, "stderr", server).catch(() => {});
 
-      consumeStream(proc.stdout, state, "stdout", server).catch(() => {});
-      consumeStream(proc.stderr, state, "stderr", server).catch(() => {});
+        proc.exited.then(() => {
+          if (devServerState?.process === proc) {
+            devServerState = null;
+          }
+        }).catch(() => {});
 
-      proc.exited.then(() => {
-        if (devServerState?.process === proc) {
-          devServerState = null;
+        if (monitor) {
+          monitor.logEvent("dev", `Dev server started (${targetDir})`);
         }
-      }).catch(() => {});
 
-      if (monitor) {
-        monitor.logEvent("dev", `Dev server started (${targetDir})`);
+        return {
+          success: true,
+          pid: proc.pid,
+          cwd: targetDir,
+          startedAt: state.startedAt.toISOString(),
+          message: "Dev server started",
+        };
+      } finally {
+        devServerStarting = false;
       }
-
-      return {
-        success: true,
-        pid: proc.pid,
-        cwd: targetDir,
-        startedAt: state.startedAt.toISOString(),
-        message: "Dev server started",
-      };
     },
 
     mandu_dev_stop: async () => {

package/src/utils/project.ts

@@ -54,7 +54,7 @@ export function getProjectPaths(rootDir: string) {
 export function isInsideProject(filePath: string, rootDir: string): boolean {
   const resolved = path.resolve(filePath);
   const root = path.resolve(rootDir);
-  return resolved.startsWith(root);
+  return resolved === root || resolved.startsWith(root + path.sep);
 }
 
 /**
@@ -73,7 +73,9 @@ export async function readJsonFile<T>(filePath: string): Promise<T | null> {
 }
 
 /**
- * Write JSON file safely
+ * Write JSON file safely.
+ * Note: Callers are responsible for ensuring filePath is within the project root.
+ * All internal callers use paths derived from getProjectPaths() which are scoped to projectRoot.
  */
 export async function writeJsonFile(filePath: string, data: unknown): Promise<void> {
   const dir = path.dirname(filePath);