@mandujs/mcp 0.37.4 → 0.38.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/mcp",
-  "version": "0.37.4",
+  "version": "0.38.1",
   "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.5",
+    "@mandujs/core": "^0.54.7",
     "@mandujs/ate": "^0.26.1",
     "@mandujs/skills": "^0.20.1",
     "@modelcontextprotocol/sdk": "^1.25.3"

package/src/tools/guard.ts

@@ -1,13 +1,13 @@
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
 import { type ManduError } from "@mandujs/core/error";
-import {
-  checkDirectory,
-  getDefaultFsRoutesGuardPolicy,
-  validateAndReport,
-  loadManifest,
-  runGuardCheck,
-  runAutoCorrect,
-  type GeneratedMap,
+import {
+  checkDirectory,
+  getDefaultFsRoutesGuardPolicy,
+  validateAndReport,
+  loadManifest,
+  runGuardCheck,
+  runAutoCorrect,
+  type GeneratedMap,
   // Self-Healing Guard imports
   checkWithHealing,
   healAll,
@@ -15,19 +15,19 @@ import {
   // Follow-up E — type-aware lint bridge
   runTsgolint,
   type GuardConfig,
-  type ViolationType,
-  type GuardPreset,
-  type Violation,
-} from "@mandujs/core";
-import { getProjectPaths, readJsonFile, readConfig } from "../utils/project.js";
-import fs from "fs/promises";
-import path from "path";
+  type ViolationType,
+  type GuardPreset,
+  type Violation,
+} from "@mandujs/core";
+import { getProjectPaths, readJsonFile, readConfig } from "../utils/project.js";
+import fs from "fs/promises";
+import path from "path";
 
 export const guardToolDefinitions: Tool[] = [
   {
-    name: "mandu.guard.check",
-    description:
-      "Run the same architecture guard used by `mandu guard`, plus legacy spec/generated/slot checks. Set typeAware=true to additionally run `oxlint --type-aware` (tsgolint) and merge its results.",
+    name: "mandu.guard.check",
+    description:
+      "Run the same architecture guard used by `mandu guard`, plus legacy spec/generated/slot checks. Set typeAware=true to additionally run `oxlint --type-aware` (tsgolint) and merge its results.",
     annotations: {
       readOnlyHint: true,
     },
@@ -126,37 +126,37 @@ export const guardToolDefinitions: Tool[] = [
   },
 ];
 
-export function guardTools(projectRoot: string) {
-  const paths = getProjectPaths(projectRoot);
-
-  const pathExists = async (candidate: string): Promise<boolean> => {
-    try {
-      await fs.access(candidate);
-      return true;
-    } catch {
-      return false;
-    }
-  };
-
-  const summarizeArchitectureViolation = (violation: Violation) => ({
-    ruleId: violation.ruleName,
-    type: violation.type,
-    file: path.relative(projectRoot, violation.filePath).replace(/\\/g, "/") || violation.filePath,
-    line: violation.line,
-    column: violation.column,
-    message: violation.ruleDescription,
-    suggestion: violation.suggestions[0],
-    fromLayer: violation.fromLayer,
-    toLayer: violation.toLayer,
-    importStatement: violation.importStatement,
-  });
-
-  const summarizeLegacyViolation = (v: Awaited<ReturnType<typeof runGuardCheck>>["violations"][number]) => ({
-    ruleId: v.ruleId,
-    file: v.file,
-    message: v.message,
-    suggestion: v.suggestion,
-  });
+export function guardTools(projectRoot: string) {
+  const paths = getProjectPaths(projectRoot);
+
+  const pathExists = async (candidate: string): Promise<boolean> => {
+    try {
+      await fs.access(candidate);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  const summarizeArchitectureViolation = (violation: Violation) => ({
+    ruleId: violation.ruleName,
+    type: violation.type,
+    file: path.relative(projectRoot, violation.filePath).replace(/\\/g, "/") || violation.filePath,
+    line: violation.line,
+    column: violation.column,
+    message: violation.ruleDescription,
+    suggestion: violation.suggestions[0],
+    fromLayer: violation.fromLayer,
+    toLayer: violation.toLayer,
+    importStatement: violation.importStatement,
+  });
+
+  const summarizeLegacyViolation = (v: Awaited<ReturnType<typeof runGuardCheck>>["violations"][number]) => ({
+    ruleId: v.ruleId,
+    file: v.file,
+    message: v.message,
+    suggestion: v.suggestion,
+  });
 
   const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
     "mandu.guard.check": async (args: Record<string, unknown>) => {
@@ -172,44 +172,44 @@ export function guardTools(projectRoot: string) {
           error: "Failed to load manifest",
           details: manifestResult.errors,
         };
-      }
-
-      const projectConfig = await validateAndReport(projectRoot);
-      const guardConfigFromFile = (projectConfig?.guard ?? {}) as GuardConfig;
-      const preset = guardConfigFromFile.preset ?? "mandu";
-      const enableFsRoutes = await pathExists(paths.appDir);
-
-      const architectureReport = await checkDirectory(
-        {
-          preset,
-          srcDir: guardConfigFromFile.srcDir ?? "src",
-          exclude: guardConfigFromFile.exclude,
-          fsRoutes: getDefaultFsRoutesGuardPolicy(enableFsRoutes),
-        },
-        projectRoot
-      );
-      const architecturePassed = architectureReport.bySeverity.error === 0;
-      const architectureViolations = architectureReport.violations.map(
-        summarizeArchitectureViolation
-      );
-
-      // Run guard check
-      const checkResult = await runGuardCheck(manifestResult.data, projectRoot);
+      }
+
+      const projectConfig = await validateAndReport(projectRoot);
+      const guardConfigFromFile = (projectConfig?.guard ?? {}) as GuardConfig;
+      const preset = guardConfigFromFile.preset ?? "mandu";
+      const enableFsRoutes = await pathExists(paths.appDir);
+
+      const architectureReport = await checkDirectory(
+        {
+          preset,
+          srcDir: guardConfigFromFile.srcDir ?? "src",
+          exclude: guardConfigFromFile.exclude,
+          fsRoutes: getDefaultFsRoutesGuardPolicy(enableFsRoutes),
+        },
+        projectRoot
+      );
+      const architecturePassed = architectureReport.bySeverity.error === 0;
+      const architectureViolations = architectureReport.violations.map(
+        summarizeArchitectureViolation
+      );
+
+      // Run guard check
+      const checkResult = await runGuardCheck(manifestResult.data, projectRoot);
 
       // Follow-up E — resolve type-aware defaulting from config, then
       // run the bridge when enabled. Result envelope is always included
       // in the tool response so MCP clients have a single stable shape.
-      let rawProjectConfig: Awaited<ReturnType<typeof readConfig>> | undefined;
-      try {
-        rawProjectConfig = projectConfig ?? await readConfig(projectRoot);
-      } catch {
-        rawProjectConfig = projectConfig ?? undefined;
-      }
-      const typeAwareCfg = (
-        rawProjectConfig?.guard as
-          | { typeAware?: Record<string, unknown> }
-          | undefined
-      )?.typeAware;
+      let rawProjectConfig: Awaited<ReturnType<typeof readConfig>> | undefined;
+      try {
+        rawProjectConfig = projectConfig ?? await readConfig(projectRoot);
+      } catch {
+        rawProjectConfig = projectConfig ?? undefined;
+      }
+      const typeAwareCfg = (
+        rawProjectConfig?.guard as
+          | { typeAware?: Record<string, unknown> }
+          | undefined
+      )?.typeAware;
       const typeAwareEnabled =
         typeAwareArg !== undefined ? typeAwareArg : typeAwareCfg !== undefined;
 
@@ -229,40 +229,40 @@ export function guardTools(projectRoot: string) {
           skipped: bridge.skipped,
           summary: bridge.summary,
           violations: bridge.violations,
-        };
-      }
-
-      const typeAwareViolations = typeAwareResponse
-        ? typeAwareResponse.violations as Array<{ severity: string }>
-        : [];
-      const typeAwareErrorCount = typeAwareViolations.filter(
-        (v) => v.severity === "error",
-      ).length;
-      const legacyViolations = checkResult.violations.map(summarizeLegacyViolation);
-      const combinedViolations = [
-        ...architectureViolations,
-        ...legacyViolations,
-      ];
-      const allPassed = checkResult.passed && architecturePassed && typeAwareErrorCount === 0;
-      const blockingViolationCount = combinedViolations.length + typeAwareErrorCount;
-
-      if (allPassed) {
-        return {
-          passed: true,
-          violations: [],
-          message: "All guard checks passed",
-          architecture: {
-            passed: true,
-            totalViolations: architectureReport.totalViolations,
-            bySeverity: architectureReport.bySeverity,
-          },
-          legacy: {
-            passed: true,
-            violations: 0,
-          },
-          relatedSkills: ["mandu-guard-guide", "mandu-debug"],
-          ...(typeAwareResponse ? { typeAware: typeAwareResponse } : {}),
-        };
+        };
+      }
+
+      const typeAwareViolations = typeAwareResponse
+        ? typeAwareResponse.violations as Array<{ severity: string }>
+        : [];
+      const typeAwareErrorCount = typeAwareViolations.filter(
+        (v) => v.severity === "error",
+      ).length;
+      const legacyViolations = checkResult.violations.map(summarizeLegacyViolation);
+      const combinedViolations = [
+        ...architectureViolations,
+        ...legacyViolations,
+      ];
+      const allPassed = checkResult.passed && architecturePassed && typeAwareErrorCount === 0;
+      const blockingViolationCount = combinedViolations.length + typeAwareErrorCount;
+
+      if (allPassed) {
+        return {
+          passed: true,
+          violations: [],
+          message: "All guard checks passed",
+          architecture: {
+            passed: true,
+            totalViolations: architectureReport.totalViolations,
+            bySeverity: architectureReport.bySeverity,
+          },
+          legacy: {
+            passed: true,
+            violations: 0,
+          },
+          relatedSkills: ["mandu-guard-guide", "mandu-debug"],
+          ...(typeAwareResponse ? { typeAware: typeAwareResponse } : {}),
+        };
       }
 
       // If auto-correct requested and there are violations
@@ -273,54 +273,54 @@ export function guardTools(projectRoot: string) {
           projectRoot
         );
 
-        return {
-          passed:
-            autoCorrectResult.fixed &&
-            architecturePassed &&
-            typeAwareErrorCount === 0,
-          violations: [
-            ...architectureViolations,
-            ...autoCorrectResult.remainingViolations.map(summarizeLegacyViolation),
-          ],
-          autoCorrect: {
-            attempted: true,
-            fixed: autoCorrectResult.fixed,
+        return {
+          passed:
+            autoCorrectResult.fixed &&
+            architecturePassed &&
+            typeAwareErrorCount === 0,
+          violations: [
+            ...architectureViolations,
+            ...autoCorrectResult.remainingViolations.map(summarizeLegacyViolation),
+          ],
+          autoCorrect: {
+            attempted: true,
+            fixed: autoCorrectResult.fixed,
             steps: autoCorrectResult.steps,
             retriedCount: autoCorrectResult.retriedCount,
             rolledBack: autoCorrectResult.rolledBack,
-            changeId: autoCorrectResult.changeId,
-          },
-          architecture: {
-            passed: architecturePassed,
-            totalViolations: architectureReport.totalViolations,
-            bySeverity: architectureReport.bySeverity,
-            violations: architectureViolations,
-          },
-          legacy: {
-            passed: autoCorrectResult.fixed,
-            violations: autoCorrectResult.remainingViolations.length,
-          },
-          ...(typeAwareResponse ? { typeAware: typeAwareResponse } : {}),
-        };
-      }
-
-      return {
-        passed: false,
-        violations: combinedViolations,
-        message: `Found ${blockingViolationCount} violation(s)`,
-        architecture: {
-          passed: architecturePassed,
-          totalViolations: architectureReport.totalViolations,
-          bySeverity: architectureReport.bySeverity,
-          violations: architectureViolations,
-        },
-        legacy: {
-          passed: checkResult.passed,
-          violations: legacyViolations.length,
-        },
-        tip: "Use autoCorrect: true to attempt automatic fixes",
-        relatedSkills: ["mandu-guard-guide", "mandu-debug"],
-        ...(typeAwareResponse ? { typeAware: typeAwareResponse } : {}),
+            changeId: autoCorrectResult.changeId,
+          },
+          architecture: {
+            passed: architecturePassed,
+            totalViolations: architectureReport.totalViolations,
+            bySeverity: architectureReport.bySeverity,
+            violations: architectureViolations,
+          },
+          legacy: {
+            passed: autoCorrectResult.fixed,
+            violations: autoCorrectResult.remainingViolations.length,
+          },
+          ...(typeAwareResponse ? { typeAware: typeAwareResponse } : {}),
+        };
+      }
+
+      return {
+        passed: false,
+        violations: combinedViolations,
+        message: `Found ${blockingViolationCount} violation(s)`,
+        architecture: {
+          passed: architecturePassed,
+          totalViolations: architectureReport.totalViolations,
+          bySeverity: architectureReport.bySeverity,
+          violations: architectureViolations,
+        },
+        legacy: {
+          passed: checkResult.passed,
+          violations: legacyViolations.length,
+        },
+        tip: "Use autoCorrect: true to attempt automatic fixes",
+        relatedSkills: ["mandu-guard-guide", "mandu-debug"],
+        ...(typeAwareResponse ? { typeAware: typeAwareResponse } : {}),
       };
     },
 

package/src/tools/hydration.ts

@@ -18,17 +18,17 @@ export const hydrationToolDefinitions: Tool[] = [
     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: {
-        minify: {
-          type: "boolean",
-          description: "Minify the output bundles (default: true in production)",
+    annotations: {
+      destructiveHint: true,
+      readOnlyHint: false,
+      idempotentHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        minify: {
+          type: "boolean",
+          description: "Minify the output bundles (default: true in production)",
         },
         sourcemap: {
           type: "boolean",
@@ -39,50 +39,53 @@ export const hydrationToolDefinitions: Tool[] = [
           items: { type: "string" },
           description:
             "Only rebuild specific islands by routeId. Skips Runtime/Router/Vendor rebuild for faster incremental updates. Omit to rebuild everything.",
-        },
-      },
-      required: [],
-    },
-  },
+        },
+      },
+      required: [],
+      additionalProperties: false,
+    },
+  },
   {
     name: "mandu.build.status",
     description:
       "Get the current build status, bundle manifest, and statistics for client bundles.",
-    annotations: {
-      readOnlyHint: true,
-    },
-    inputSchema: {
-      type: "object",
-      properties: {},
-      required: [],
-    },
-  },
-  {
-    name: "mandu.island.list",
+    annotations: {
+      readOnlyHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+      additionalProperties: false,
+    },
+  },
+  {
+    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: {},
-      required: [],
-    },
-  },
-  {
-    name: "mandu.hydration.set",
+    annotations: {
+      readOnlyHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+      additionalProperties: false,
+    },
+  },
+  {
+    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: {
-        routeId: {
-          type: "string",
-          description: "The route ID to configure",
+    annotations: {
+      readOnlyHint: false,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        routeId: {
+          type: "string",
+          description: "The route ID to configure",
         },
         strategy: {
           type: "string",
@@ -100,24 +103,25 @@ export const hydrationToolDefinitions: Tool[] = [
           type: "boolean",
           description: "Whether to preload the bundle with modulepreload",
         },
-      },
-      required: ["routeId"],
-    },
-  },
-  {
+      },
+      required: ["routeId"],
+      additionalProperties: false,
+    },
+  },
+  {
     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: {
-        routeId: {
-          type: "string",
-          description: "The route ID to add client slot for",
+    annotations: {
+      destructiveHint: false,
+      readOnlyHint: false,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        routeId: {
+          type: "string",
+          description: "The route ID to add client slot for",
         },
         strategy: {
           type: "string",
@@ -129,13 +133,14 @@ export const hydrationToolDefinitions: Tool[] = [
           enum: ["immediate", "visible", "idle", "interaction"],
           description: "Hydration priority (default: visible)",
         },
-      },
-      required: ["routeId"],
-    },
-  },
-];
-
-export function hydrationTools(projectRoot: string) {
+      },
+      required: ["routeId"],
+      additionalProperties: false,
+    },
+  },
+];
+
+export function hydrationTools(projectRoot: string) {
   const paths = getProjectPaths(projectRoot);
 
   const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
@@ -223,20 +228,25 @@ export function hydrationTools(projectRoot: string) {
       }
 
       const islands = manifestResult.data.routes
-        .filter((route) => route.kind === "page")
-        .map((route) => {
-          const hydration = getRouteHydration(route);
-          const isIsland = needsHydration(route);
-
-          return {
-            routeId: route.id,
-            pattern: route.pattern,
-            hasClientModule: !!route.clientModule,
-            clientModule: route.clientModule || null,
-            isIsland,
-            hydration: {
-              strategy: hydration.strategy,
-              priority: hydration.priority,
+        .filter((route) => route.kind === "page")
+        .map((route) => {
+          const hydration = getRouteHydration(route);
+          const isIsland = needsHydration(route);
+          const warning = isIsland && !route.clientModule
+            ? `Route has hydration strategy '${hydration.strategy}' but no clientModule; build would emit no route bundle.`
+            : null;
+
+          return {
+            routeId: route.id,
+            pattern: route.pattern,
+            hasClientModule: !!route.clientModule,
+            clientModule: route.clientModule || null,
+            isIsland,
+            status: isIsland ? (route.clientModule ? "ready" : "broken") : "static",
+            warning,
+            hydration: {
+              strategy: hydration.strategy,
+              priority: hydration.priority,
               preload: hydration.preload,
             },
           };
@@ -252,12 +262,19 @@ export function hydrationTools(projectRoot: string) {
         islands: islands.filter((i) => i.isIsland),
         staticPages: islands.filter((i) => !i.isIsland),
       };
-    },
-
-    "mandu.hydration.set": async (args: Record<string, unknown>) => {
-      const { routeId, strategy, priority, preload } = args as {
-        routeId: string;
-        strategy?: SpecHydrationStrategy;
+    },
+
+    "mandu.hydration.set": async (args: Record<string, unknown>) => {
+      const validationError = validateRouteIdArgs(
+        args,
+        "mandu.hydration.set",
+        ["routeId", "strategy", "priority", "preload"],
+      );
+      if (validationError) return { error: validationError };
+
+      const { routeId, strategy, priority, preload } = args as {
+        routeId: string;
+        strategy?: SpecHydrationStrategy;
         priority?: HydrationPriority;
         preload?: boolean;
       };
@@ -311,12 +328,19 @@ export function hydrationTools(projectRoot: string) {
         newHydration,
         message: `Updated hydration config for ${routeId}`,
       };
-    },
-
-    "mandu.hydration.addClientSlot": async (args: Record<string, unknown>) => {
-      const { routeId, strategy = "island", priority = "visible" } = args as {
-        routeId: string;
-        strategy?: SpecHydrationStrategy;
+    },
+
+    "mandu.hydration.addClientSlot": async (args: Record<string, unknown>) => {
+      const validationError = validateRouteIdArgs(
+        args,
+        "mandu.hydration.addClientSlot",
+        ["routeId", "strategy", "priority"],
+      );
+      if (validationError) return { error: validationError };
+
+      const { routeId, strategy = "island", priority = "visible" } = args as {
+        routeId: string;
+        strategy?: SpecHydrationStrategy;
         priority?: HydrationPriority;
       };
 
@@ -396,14 +420,30 @@ export function hydrationTools(projectRoot: string) {
   };
 
   // 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;
-}
+  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_hydration_set"] = handlers["mandu.hydration.set"];
+  handlers["mandu_add_client_slot"] = handlers["mandu.hydration.addClientSlot"];
+  handlers["mandu_hydration_add_client_slot"] = handlers["mandu.hydration.addClientSlot"];
+
+  return handlers;
+}
+
+function validateRouteIdArgs(
+  args: Record<string, unknown>,
+  toolName: string,
+  allowedKeys: readonly string[],
+): string | null {
+  if (typeof args.routeId !== "string" || args.routeId.trim().length === 0) {
+    const allowed = new Set(allowedKeys);
+    const unknownKeys = Object.keys(args).filter((key) => !allowed.has(key));
+    const got = unknownKeys.length > 0 ? ` (got unknown key${unknownKeys.length === 1 ? "" : "s"} '${unknownKeys.join("', '")}')` : "";
+    return `${toolName}: missing required parameter 'routeId'${got}`;
+  }
+  return null;
+}
 
 /**
  * Generate a client slot template

package/src/tools/index.ts

@@ -11,9 +11,9 @@ import { mcpToolRegistry } from "../registry/mcp-tool-registry.js";
 import { moduleToPlugins } from "../adapters/tool-adapter.js";
 import { type McpProfile, getProfileCategories } from "../profiles.js";
 
-// 도구 모듈 export
-export { agentTools, agentToolDefinitions } from "./agent.js";
-export { specTools, specToolDefinitions } from "./spec.js";
+// 도구 모듈 export
+export { agentTools, agentToolDefinitions } from "./agent.js";
+export { specTools, specToolDefinitions } from "./spec.js";
 export { generateTools, generateToolDefinitions } from "./generate.js";
 export { transactionTools, transactionToolDefinitions } from "./transaction.js";
 export { historyTools, historyToolDefinitions } from "./history.js";
@@ -86,9 +86,9 @@ export {
   extractContractToolDefinitions,
 } from "./extract-contract.js";
 
-// 도구 모듈 import (등록용)
-import { agentTools, agentToolDefinitions } from "./agent.js";
-import { specTools, specToolDefinitions } from "./spec.js";
+// 도구 모듈 import (등록용)
+import { agentTools, agentToolDefinitions } from "./agent.js";
+import { specTools, specToolDefinitions } from "./spec.js";
 import { generateTools, generateToolDefinitions } from "./generate.js";
 import { transactionTools, transactionToolDefinitions } from "./transaction.js";
 import { historyTools, historyToolDefinitions } from "./history.js";
@@ -164,10 +164,10 @@ import {
 /**
  * 도구 모듈 정보
  */
-export interface ToolModule {
-  category: string;
-  definitions: Tool[];
-  handlers: (
+export interface ToolModule {
+  category: string;
+  definitions: Tool[];
+  handlers: (
     projectRoot: string,
     server?: Server,
     monitor?: ActivityMonitor
@@ -190,9 +190,9 @@ export interface ToolModule {
 /**
  * 빌트인 도구 모듈 목록
  */
-export const TOOL_MODULES: ToolModule[] = [
-  { category: "agent", definitions: agentToolDefinitions, handlers: agentTools },
-  { category: "spec", definitions: specToolDefinitions, handlers: specTools },
+export const TOOL_MODULES: ToolModule[] = [
+  { category: "agent", definitions: agentToolDefinitions, handlers: agentTools },
+  { category: "spec", definitions: specToolDefinitions, handlers: specTools },
   { category: "generate", definitions: generateToolDefinitions, handlers: generateTools },
   { category: "transaction", definitions: transactionToolDefinitions, handlers: transactionTools },
   { category: "history", definitions: historyToolDefinitions, handlers: historyTools },
@@ -203,18 +203,18 @@ export const TOOL_MODULES: ToolModule[] = [
   { category: "slot", definitions: slotToolDefinitions, handlers: slotTools },
   { category: "hydration", definitions: hydrationToolDefinitions, handlers: hydrationTools },
   { category: "contract", definitions: contractToolDefinitions, handlers: contractTools },
-  { category: "brain", definitions: brainToolDefinitions, handlers: brainTools, requiresServer: true },
+  { category: "brain", definitions: brainToolDefinitions, handlers: brainTools, requiresServer: true },
   { category: "runtime", definitions: runtimeToolDefinitions, handlers: runtimeTools },
   { category: "seo", definitions: seoToolDefinitions, handlers: seoTools },
-  { category: "project", definitions: projectToolDefinitions, handlers: projectTools, requiresServer: true },
+  { category: "project", definitions: projectToolDefinitions, handlers: projectTools, requiresServer: true },
   // ate + ate-run accept an optional Server so notifications/progress
   // can flow (issue #238). `acceptsServer: true` forwards the server
   // when available but still registers when it isn't — callers that
   // boot without an MCP transport get progress no-oped silently.
-  { category: "ate", definitions: ateToolDefinitions, handlers: ateTools, acceptsServer: true },
-  { category: "ate-phase5", definitions: atePhase5ToolDefinitions, handlers: createAtePhase5Handlers },
+  { category: "ate", definitions: ateToolDefinitions, handlers: ateTools, acceptsServer: true },
+  { category: "ate-phase5", definitions: atePhase5ToolDefinitions, handlers: createAtePhase5Handlers },
   { category: "ate-context", definitions: ateContextToolDefinitions, handlers: ateContextTools },
-  { category: "ate-run", definitions: ateRunToolDefinitions, handlers: ateRunTools, acceptsServer: true },
+  { category: "ate-run", definitions: ateRunToolDefinitions, handlers: ateRunTools, acceptsServer: true },
   { category: "ate-flakes", definitions: ateFlakesToolDefinitions, handlers: ateFlakesTools },
   { category: "ate-prompt", definitions: atePromptToolDefinitions, handlers: atePromptTools },
   { category: "ate-exemplar", definitions: ateExemplarToolDefinitions, handlers: ateExemplarTools },
@@ -285,41 +285,41 @@ export const TOOL_MODULES: ToolModule[] = [
     definitions: extractContractToolDefinitions,
     handlers: extractContractTools,
   },
-];
-
-export function validateBuiltinToolModules(
-  modules: readonly ToolModule[] = TOOL_MODULES
-): string[] {
-  const issues: string[] = [];
-  const categories = new Set<string>();
-  const toolNames = new Map<string, string>();
-
-  for (const module of modules) {
-    if (categories.has(module.category)) {
-      issues.push(`duplicate tool category: ${module.category}`);
-    }
-    categories.add(module.category);
-
-    if (module.definitions.length === 0) {
-      issues.push(`tool category has no definitions: ${module.category}`);
-    }
-
-    for (const definition of module.definitions) {
-      const previousCategory = toolNames.get(definition.name);
-      if (previousCategory) {
-        issues.push(
-          `duplicate tool definition: ${definition.name} in ${previousCategory} and ${module.category}`
-        );
-      }
-      toolNames.set(definition.name, module.category);
-    }
-  }
-
-  return issues;
-}
-
-/**
- * 빌트인 도구들을 레지스트리에 등록
+];
+
+export function validateBuiltinToolModules(
+  modules: readonly ToolModule[] = TOOL_MODULES
+): string[] {
+  const issues: string[] = [];
+  const categories = new Set<string>();
+  const toolNames = new Map<string, string>();
+
+  for (const module of modules) {
+    if (categories.has(module.category)) {
+      issues.push(`duplicate tool category: ${module.category}`);
+    }
+    categories.add(module.category);
+
+    if (module.definitions.length === 0) {
+      issues.push(`tool category has no definitions: ${module.category}`);
+    }
+
+    for (const definition of module.definitions) {
+      const previousCategory = toolNames.get(definition.name);
+      if (previousCategory) {
+        issues.push(
+          `duplicate tool definition: ${definition.name} in ${previousCategory} and ${module.category}`
+        );
+      }
+      toolNames.set(definition.name, module.category);
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * 빌트인 도구들을 레지스트리에 등록
  *
  * @param projectRoot - 프로젝트 루트 경로
  * @param server - MCP Server 인스턴스 (선택, brain/project 도구에 필요)
@@ -340,15 +340,15 @@ export function registerBuiltinTools(
   monitor?: ActivityMonitor,
   options?: { profile?: McpProfile }
 ): void {
-  const allowedCategories = options?.profile
-    ? getProfileCategories(options.profile)
-    : null;
-  const definitionIssues = validateBuiltinToolModules();
-  if (definitionIssues.length > 0) {
-    throw new Error(`Invalid MCP tool module registry:\n${definitionIssues.join("\n")}`);
-  }
-
-  for (const module of TOOL_MODULES) {
+  const allowedCategories = options?.profile
+    ? getProfileCategories(options.profile)
+    : null;
+  const definitionIssues = validateBuiltinToolModules();
+  if (definitionIssues.length > 0) {
+    throw new Error(`Invalid MCP tool module registry:\n${definitionIssues.join("\n")}`);
+  }
+
+  for (const module of TOOL_MODULES) {
     // Profile filtering: skip categories not in the allowed list
     if (allowedCategories && !allowedCategories.includes(module.category)) {
       continue;
@@ -359,13 +359,13 @@ export function registerBuiltinTools(
       continue;
     }
 
-    try {
-      let handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>>;
-      if (module.requiresServer) {
-        handlers = module.handlers(projectRoot, server, monitor);
-      } else if (module.acceptsServer) {
-        // Forward the Server when available; fall back to just projectRoot.
-        handlers = server
+    try {
+      let handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>>;
+      if (module.requiresServer) {
+        handlers = module.handlers(projectRoot, server, monitor);
+      } else if (module.acceptsServer) {
+        // Forward the Server when available; fall back to just projectRoot.
+        handlers = server
           ? module.handlers(projectRoot, server)
           : module.handlers(projectRoot);
       } else {

package/src/tools/runtime.ts

@@ -3,10 +3,12 @@
  * Query and manage runtime configuration: logger settings and contract normalize options.
  */
 
-import type { Tool } from "@modelcontextprotocol/sdk/types.js";
-import { getProjectPaths } from "../utils/project.js";
-import { loadManifest } from "@mandujs/core";
-import path from "path";
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { getProjectPaths } from "../utils/project.js";
+import { loadManduConfig, loadManifest, needsHydration } from "@mandujs/core";
+import { getDevServerState } from "./project.js";
+import { readRuntimeControl } from "../utils/runtime-control.js";
+import path from "path";
 
 
 export const runtimeToolDefinitions: Tool[] = [
@@ -26,8 +28,49 @@ export const runtimeToolDefinitions: Tool[] = [
       required: [],
     },
   },
-  {
-    name: "mandu.runtime.contractOptions",
+  {
+    name: "mandu.runtime.probe",
+    annotations: {
+      readOnlyHint: true,
+    },
+    description:
+      "Probe a running Mandu dev/start server by fetching real page HTML and island bundle URLs. " +
+      "Catches silent runtime failures that static manifest/guard checks miss, especially empty data-mandu-src island markers.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        baseURL: {
+          type: "string",
+          description: "Explicit dev server URL. Overrides runtime-control/config discovery.",
+        },
+        port: {
+          type: "number",
+          description: "Explicit dev server port. Overrides runtime-control/config discovery.",
+        },
+        routeIds: {
+          type: "array",
+          items: { type: "string" },
+          description: "Optional route IDs to probe. Omit to probe all page routes that can be sampled.",
+        },
+        includeDynamic: {
+          type: "boolean",
+          description: "Probe dynamic routes by substituting __mandu_probe__ for params. Defaults to false.",
+        },
+        checkBundleUrls: {
+          type: "boolean",
+          description: "Fetch every non-empty data-mandu-src URL and require a 2xx response. Defaults to true.",
+        },
+        timeoutMs: {
+          type: "number",
+          description: "Per-request timeout in milliseconds. Defaults to 3000.",
+        },
+      },
+      required: [],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "mandu.runtime.contractOptions",
     annotations: {
       readOnlyHint: true,
     },
@@ -150,10 +193,10 @@ async function readFileContent(filePath: string): Promise<string | null> {
   }
 }
 
-export function runtimeTools(projectRoot: string) {
-  const paths = getProjectPaths(projectRoot);
-
-  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
+export function runtimeTools(projectRoot: string) {
+  const paths = getProjectPaths(projectRoot);
+
+  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
     "mandu.runtime.config": async () => {
       return {
         defaults: {
@@ -216,10 +259,78 @@ export default Mandu.contract({
   response: { ... },
 });`,
         },
-      };
-    },
-
-    "mandu.runtime.contractOptions": async (args: Record<string, unknown>) => {
+      };
+    },
+
+    "mandu.runtime.probe": async (args: Record<string, unknown>) => {
+      const baseUrl = await resolveDevServerBaseUrl(projectRoot, args);
+      const timeoutMs = normalizeTimeout(args.timeoutMs);
+      const checkBundleUrls = args.checkBundleUrls !== false;
+      const includeDynamic = args.includeDynamic === true;
+      const routeIdFilter = Array.isArray(args.routeIds)
+        ? new Set(args.routeIds.filter((id): id is string => typeof id === "string"))
+        : null;
+
+      const result = await loadManifest(paths.manifestPath);
+      if (!result.success || !result.data) {
+        return {
+          success: false,
+          baseUrl,
+          error: result.errors,
+        };
+      }
+
+      const pageRoutes = result.data.routes
+        .filter((route) => route.kind === "page")
+        .filter((route) => !routeIdFilter || routeIdFilter.has(route.id))
+        .map((route) => ({
+          route,
+          samplePath: samplePathForPattern(route.pattern, includeDynamic),
+        }));
+
+      const skipped = pageRoutes
+        .filter((entry) => entry.samplePath === null)
+        .map((entry) => ({
+          routeId: entry.route.id,
+          pattern: entry.route.pattern,
+          reason: "dynamic_route",
+        }));
+      const probes = await Promise.all(
+        pageRoutes
+          .filter((entry): entry is typeof entry & { samplePath: string } => entry.samplePath !== null)
+          .map((entry) =>
+            probeRoute({
+              baseUrl,
+              route: entry.route,
+              samplePath: entry.samplePath,
+              timeoutMs,
+              checkBundleUrls,
+            })
+          )
+      );
+
+      const failures = probes.flatMap((probe) =>
+        probe.failures.map((failure) => ({
+          routeId: probe.routeId,
+          pattern: probe.pattern,
+          path: probe.path,
+          ...failure,
+        }))
+      );
+
+      return {
+        success: failures.length === 0,
+        baseUrl,
+        checkedRoutes: probes.length,
+        skippedRoutes: skipped.length,
+        failureCount: failures.length,
+        failures,
+        routes: probes,
+        skipped,
+      };
+    },
+
+    "mandu.runtime.contractOptions": async (args: Record<string, unknown>) => {
       const { routeId } = args as { routeId: string };
 
       const result = await loadManifest(paths.manifestPath);
@@ -521,13 +632,205 @@ export const appLogger = logger(${JSON.stringify(config, null, 2)});
   // Backward-compatible aliases (deprecated)
   handlers["mandu_get_runtime_config"] = handlers["mandu.runtime.config"];
   handlers["mandu_set_contract_normalize"] = handlers["mandu.runtime.setNormalize"];
-  handlers["mandu_get_contract_options"] = handlers["mandu.runtime.contractOptions"];
-  handlers["mandu_list_logger_options"] = handlers["mandu.runtime.loggerOptions"];
-  handlers["mandu_generate_logger_config"] = handlers["mandu.runtime.loggerConfig"];
-
-  return handlers;
-}
-
-function insertAfter(content: string, search: string): boolean {
-  return content.includes(search);
-}
+  handlers["mandu_get_contract_options"] = handlers["mandu.runtime.contractOptions"];
+  handlers["mandu_list_logger_options"] = handlers["mandu.runtime.loggerOptions"];
+  handlers["mandu_generate_logger_config"] = handlers["mandu.runtime.loggerConfig"];
+  handlers["mandu_runtime_probe"] = handlers["mandu.runtime.probe"];
+
+  return handlers;
+}
+
+function insertAfter(content: string, search: string): boolean {
+  return content.includes(search);
+}
+
+async function resolveDevServerBaseUrl(
+  projectRoot: string,
+  args: { baseURL?: unknown; port?: unknown } = {},
+): Promise<string> {
+  if (typeof args.baseURL === "string" && args.baseURL.trim()) {
+    return args.baseURL.trim().replace(/\/+$/, "");
+  }
+
+  const explicitPort = normalizePort(args.port);
+  if (explicitPort) {
+    return `http://localhost:${explicitPort}`;
+  }
+
+  const control = await readRuntimeControl(projectRoot);
+  if (control?.baseUrl) {
+    return control.baseUrl.replace(/\/+$/, "");
+  }
+
+  let port: number | undefined;
+  const serverState = getDevServerState();
+  if (serverState) {
+    for (const line of serverState.output) {
+      const portMatch = line.match(/https?:\/\/localhost:(\d+)/);
+      if (portMatch) {
+        port = Number.parseInt(portMatch[1], 10);
+      }
+    }
+  }
+
+  if (!port) {
+    const config = await loadManduConfig(projectRoot);
+    port = config.server?.port ?? 3333;
+  }
+
+  return `http://localhost:${port}`;
+}
+
+function normalizePort(value: unknown): number | undefined {
+  const raw = typeof value === "number" ? value : typeof value === "string" ? Number.parseInt(value, 10) : NaN;
+  if (!Number.isInteger(raw) || raw < 1 || raw > 65535) return undefined;
+  return raw;
+}
+
+function normalizeTimeout(value: unknown): number {
+  const raw = typeof value === "number" ? value : typeof value === "string" ? Number.parseInt(value, 10) : NaN;
+  if (!Number.isInteger(raw) || raw < 100 || raw > 30_000) return 3000;
+  return raw;
+}
+
+function samplePathForPattern(pattern: string, includeDynamic: boolean): string | null {
+  if (!includeDynamic && /(^|\/):[^/]+/.test(pattern)) return null;
+  const sampled = pattern
+    .replace(/:([A-Za-z0-9_]+)/g, "__mandu_probe__")
+    .replace(/\*+/g, "__mandu_probe__");
+  return sampled.startsWith("/") ? sampled : `/${sampled}`;
+}
+
+interface IslandMarker {
+  id: string | null;
+  src: string | null;
+}
+
+function extractIslandMarkers(html: string): IslandMarker[] {
+  const markers: IslandMarker[] = [];
+  const tagPattern = /<[^>]*\bdata-mandu-island(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+))?[^>]*>/gi;
+  for (const match of html.matchAll(tagPattern)) {
+    const tag = match[0];
+    markers.push({
+      id: readHtmlAttr(tag, "data-mandu-island"),
+      src: readHtmlAttr(tag, "data-mandu-src"),
+    });
+  }
+  return markers;
+}
+
+function readHtmlAttr(tag: string, attr: string): string | null {
+  const pattern = new RegExp(
+    `\\b${attr}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`,
+    "i",
+  );
+  const match = tag.match(pattern);
+  return match ? (match[1] ?? match[2] ?? match[3] ?? "") : null;
+}
+
+async function probeRoute({
+  baseUrl,
+  route,
+  samplePath,
+  timeoutMs,
+  checkBundleUrls,
+}: {
+  baseUrl: string;
+  route: { id: string; pattern: string; clientModule?: string; hydration?: unknown };
+  samplePath: string;
+  timeoutMs: number;
+  checkBundleUrls: boolean;
+}): Promise<{
+  routeId: string;
+  pattern: string;
+  path: string;
+  status: number | null;
+  islandCount: number;
+  failures: Array<{ code: string; message: string; islandId?: string | null; src?: string | null; status?: number | null }>;
+}> {
+  const failures: Array<{ code: string; message: string; islandId?: string | null; src?: string | null; status?: number | null }> = [];
+  const url = new URL(samplePath, `${baseUrl}/`);
+  let response: Response;
+  try {
+    response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+  } catch (error) {
+    return {
+      routeId: route.id,
+      pattern: route.pattern,
+      path: samplePath,
+      status: null,
+      islandCount: 0,
+      failures: [{
+        code: "page_fetch_failed",
+        message: error instanceof Error ? error.message : String(error),
+        status: null,
+      }],
+    };
+  }
+
+  if (!response.ok) {
+    failures.push({
+      code: "page_status",
+      message: `Page responded with HTTP ${response.status}`,
+      status: response.status,
+    });
+  }
+
+  const html = await response.text();
+  const markers = extractIslandMarkers(html);
+  const hasRouteIsland = markers.some((marker) => marker.id === route.id);
+  if (route.clientModule && needsHydration(route as Parameters<typeof needsHydration>[0]) && !hasRouteIsland) {
+    failures.push({
+      code: "missing_route_island_marker",
+      message: `Route has clientModule but HTML does not contain data-mandu-island="${route.id}"`,
+      islandId: route.id,
+    });
+  }
+
+  for (const marker of markers) {
+    if (!marker.src || marker.src.trim().length === 0) {
+      failures.push({
+        code: "empty_island_src",
+        message: "Island marker has empty data-mandu-src",
+        islandId: marker.id,
+        src: marker.src,
+      });
+      continue;
+    }
+    if (!checkBundleUrls) continue;
+
+    const bundleUrl = new URL(marker.src, `${baseUrl}/`);
+    try {
+      const bundleResponse = await fetch(bundleUrl, {
+        method: "GET",
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      if (!bundleResponse.ok) {
+        failures.push({
+          code: "bundle_status",
+          message: `Island bundle responded with HTTP ${bundleResponse.status}`,
+          islandId: marker.id,
+          src: marker.src,
+          status: bundleResponse.status,
+        });
+      }
+    } catch (error) {
+      failures.push({
+        code: "bundle_fetch_failed",
+        message: error instanceof Error ? error.message : String(error),
+        islandId: marker.id,
+        src: marker.src,
+        status: null,
+      });
+    }
+  }
+
+  return {
+    routeId: route.id,
+    pattern: route.pattern,
+    path: samplePath,
+    status: response.status,
+    islandCount: markers.length,
+    failures,
+  };
+}