@mandujs/mcp 0.37.1 → 0.37.3

package/src/tools/guard.ts

@@ -1,10 +1,13 @@
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
 import { type ManduError } from "@mandujs/core/error";
-import {
-  loadManifest,
-  runGuardCheck,
-  runAutoCorrect,
-  type GeneratedMap,
+import {
+  checkDirectory,
+  getDefaultFsRoutesGuardPolicy,
+  validateAndReport,
+  loadManifest,
+  runGuardCheck,
+  runAutoCorrect,
+  type GeneratedMap,
   // Self-Healing Guard imports
   checkWithHealing,
   healAll,
@@ -12,16 +15,19 @@ import {
   // Follow-up E — type-aware lint bridge
   runTsgolint,
   type GuardConfig,
-  type ViolationType,
-  type GuardPreset,
-} from "@mandujs/core";
-import { getProjectPaths, readJsonFile, readConfig } from "../utils/project.js";
+  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 guard checks to validate spec integrity, generated files, and slot files. 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,
     },
@@ -120,8 +126,37 @@ export const guardToolDefinitions: Tool[] = [
   },
 ];
 
-export function guardTools(projectRoot: string) {
-  const paths = getProjectPaths(projectRoot);
+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>) => {
@@ -137,25 +172,44 @@ export function guardTools(projectRoot: string) {
           error: "Failed to load manifest",
           details: manifestResult.errors,
         };
-      }
-
-      // 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 projectConfig: Awaited<ReturnType<typeof readConfig>> | undefined;
-      try {
-        projectConfig = await readConfig(projectRoot);
-      } catch {
-        projectConfig = undefined;
-      }
-      const typeAwareCfg = (
-        projectConfig?.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;
 
@@ -175,21 +229,40 @@ export function guardTools(projectRoot: string) {
           skipped: bridge.skipped,
           summary: bridge.summary,
           violations: bridge.violations,
-        };
-      }
-
-      if (checkResult.passed) {
-        return {
-          passed: typeAwareResponse
-            ? (typeAwareResponse.violations as Array<{ severity: string }>).filter(
-                (v) => v.severity === "error",
-              ).length === 0
-            : true,
-          violations: [],
-          message: "All guard checks passed",
-          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
@@ -200,33 +273,54 @@ export function guardTools(projectRoot: string) {
           projectRoot
         );
 
-        return {
-          passed: autoCorrectResult.fixed,
-          violations: autoCorrectResult.remainingViolations,
-          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,
-          },
-          ...(typeAwareResponse ? { typeAware: typeAwareResponse } : {}),
-        };
-      }
-
-      return {
-        passed: false,
-        violations: checkResult.violations.map((v) => ({
-          ruleId: v.ruleId,
-          file: v.file,
-          message: v.message,
-          suggestion: v.suggestion,
-        })),
-        message: `Found ${checkResult.violations.length} violation(s)`,
-        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/index.ts

@@ -162,10 +162,10 @@ import {
 /**
  * 도구 모듈 정보
  */
-interface ToolModule {
-  category: string;
-  definitions: Tool[];
-  handlers: (
+export interface ToolModule {
+  category: string;
+  definitions: Tool[];
+  handlers: (
     projectRoot: string,
     server?: Server,
     monitor?: ActivityMonitor
@@ -188,7 +188,7 @@ interface ToolModule {
 /**
  * 빌트인 도구 모듈 목록
  */
-const TOOL_MODULES: ToolModule[] = [
+export const TOOL_MODULES: ToolModule[] = [
   { category: "spec", definitions: specToolDefinitions, handlers: specTools },
   { category: "generate", definitions: generateToolDefinitions, handlers: generateTools },
   { category: "transaction", definitions: transactionToolDefinitions, handlers: transactionTools },
@@ -200,18 +200,18 @@ 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 as ToolModule["handlers"], 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 as ToolModule["handlers"], 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 as ToolModule["handlers"], acceptsServer: true },
-  { category: "ate-phase5", definitions: atePhase5ToolDefinitions, handlers: createAtePhase5Handlers as unknown as ToolModule["handlers"] },
+  { 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 as ToolModule["handlers"], 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 },
@@ -282,10 +282,41 @@ 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;
+}
+
+/**
+ * 빌트인 도구들을 레지스트리에 등록
  *
  * @param projectRoot - 프로젝트 루트 경로
  * @param server - MCP Server 인스턴스 (선택, brain/project 도구에 필요)
@@ -306,11 +337,15 @@ export function registerBuiltinTools(
   monitor?: ActivityMonitor,
   options?: { profile?: McpProfile }
 ): void {
-  const allowedCategories = options?.profile
-    ? getProfileCategories(options.profile)
-    : null;
-
-  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;
@@ -321,17 +356,13 @@ export function registerBuiltinTools(
       continue;
     }
 
-    try {
-      let handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>>;
-      if (module.requiresServer) {
-        handlers = (module.handlers as (root: string, srv: Server, mon: ActivityMonitor) => Record<string, (args: Record<string, unknown>) => Promise<unknown>>)(
-          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/kitchen.ts

@@ -4,9 +4,10 @@
  * 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";
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { loadManduConfig } from "@mandujs/core";
+import { getDevServerState } from "./project.js";
+import { readRuntimeControl } from "../utils/runtime-control.js";
 
 export const kitchenToolDefinitions: Tool[] = [
   {
@@ -19,10 +20,18 @@ export const kitchenToolDefinitions: Tool[] = [
     inputSchema: {
       type: "object",
       properties: {
-        clear: {
-          type: "boolean",
-          description: "Clear errors after reading (default: false)",
-        },
+        clear: {
+          type: "boolean",
+          description: "Clear errors after reading (default: false)",
+        },
+        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.",
+        },
       },
       required: [],
     },
@@ -47,11 +56,19 @@ export const kitchenToolDefinitions: Tool[] = [
           description:
             "Include the extended diagnose report. Default true. Set false to lower latency when a11y_hints / package_export_gaps are noisy.",
         },
-        includeDiff: {
-          type: "boolean",
-          description:
-            "Include git diff against MANDU_DIFF_BASE (default HEAD). Default true. Set false to skip when git is unavailable.",
-        },
+        includeDiff: {
+          type: "boolean",
+          description:
+            "Include git diff against MANDU_DIFF_BASE (default HEAD). Default true. Set false to skip when git is unavailable.",
+        },
+        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.",
+        },
       },
       required: [],
     },
@@ -59,15 +76,32 @@ export const kitchenToolDefinitions: Tool[] = [
 ];
 
 /**
- * Resolve the dev server base URL. Prefers the port parsed from the
- * currently running `mandu dev` stdout; falls back to mandu config; final
- * default is 3333. Shared by every Kitchen-backed MCP tool so they all
- * agree on where to fetch from.
+ * Resolve the dev server base URL. Prefers explicit args, then
+ * `.mandu/runtime-control.json` from the running dev/start process, then
+ * captured stdout, then config/default 3333. Shared by every Kitchen-backed
+ * MCP tool so they all agree on where to fetch from.
  */
-async function resolveDevServerBaseUrl(projectRoot: string): Promise<string> {
-  let port: number | undefined;
-
-  const serverState = getDevServerState();
+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+)/);
@@ -81,15 +115,21 @@ async function resolveDevServerBaseUrl(projectRoot: string): Promise<string> {
     const config = await loadManduConfig(projectRoot);
     port = config.server?.port ?? 3333;
   }
-
-  return `http://localhost:${port}`;
-}
+
+  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;
+}
 
 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 };
-      const baseUrl = await resolveDevServerBaseUrl(projectRoot);
+    "mandu.kitchen.errors": async (args: Record<string, unknown>) => {
+      const { clear = false } = args as { clear?: boolean };
+      const baseUrl = await resolveDevServerBaseUrl(projectRoot, args);
 
       try {
         // Fetch errors from Kitchen API
@@ -145,12 +185,12 @@ export function kitchenTools(projectRoot: string) {
      */
     "mandu.devtools.context": async (args: Record<string, unknown>) => {
       const {
-        includeBundle = true,
-        includeDiagnose = true,
-        includeDiff = true,
-      } = args as { includeBundle?: boolean; includeDiagnose?: boolean; includeDiff?: boolean };
-
-      const baseUrl = await resolveDevServerBaseUrl(projectRoot);
+        includeBundle = true,
+        includeDiagnose = true,
+        includeDiff = true,
+      } = args as { includeBundle?: boolean; includeDiagnose?: boolean; includeDiff?: boolean };
+
+      const baseUrl = await resolveDevServerBaseUrl(projectRoot, args);
       const params = new URLSearchParams();
       if (!includeBundle) params.set("bundle", "0");
       if (!includeDiagnose) params.set("diagnose", "0");