@mandujs/mcp 0.9.16 → 0.9.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/mcp",
-  "version": "0.9.16",
+  "version": "0.9.18",
   "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.9.16",
+    "@mandujs/core": "^0.9.25",
     "@modelcontextprotocol/sdk": "^1.25.3"
   },
   "engines": {

package/src/activity-monitor.ts

@@ -1,231 +1,231 @@
-/**
- * Mandu Activity Monitor
- *
- * Real-time terminal dashboard for MCP server activity.
- * Opens automatically when the MCP server starts.
- * Shows all tool calls, watch events, errors, and agent behavior.
- */
-
-import fs from "fs";
-import path from "path";
-import { spawn, type ChildProcess } from "child_process";
-
-const TOOL_ICONS: Record<string, string> = {
-  // Spec
-  mandu_list_routes: "SPEC",
-  mandu_get_route: "SPEC",
-  mandu_add_route: "SPEC+",
-  mandu_update_route: "SPEC~",
-  mandu_delete_route: "SPEC-",
-  mandu_validate_spec: "SPEC?",
-  // Generate
-  mandu_generate: "GEN",
-  mandu_generate_status: "GEN?",
-  // Guard
-  mandu_guard_check: "GUARD",
-  // Slot
-  mandu_read_slot: "SLOT",
-  mandu_write_slot: "SLOT~",
-  mandu_validate_slot: "SLOT?",
-  // Contract
-  mandu_list_contracts: "CONTRACT",
-  mandu_get_contract: "CONTRACT",
-  mandu_create_contract: "CONTRACT+",
-  mandu_validate_contracts: "CONTRACT?",
-  mandu_sync_contract_slot: "SYNC",
-  mandu_generate_openapi: "OPENAPI",
-  mandu_update_route_contract: "CONTRACT~",
-  // Transaction
-  mandu_begin: "TX-BEGIN",
-  mandu_commit: "TX-COMMIT",
-  mandu_rollback: "TX-ROLLBACK",
-  mandu_tx_status: "TX?",
-  // History
-  mandu_list_history: "HISTORY",
-  mandu_get_snapshot: "SNAPSHOT",
-  mandu_prune_history: "PRUNE",
-  // Brain
-  mandu_doctor: "DOCTOR",
-  mandu_watch_start: "WATCH+",
-  mandu_watch_status: "WATCH?",
-  mandu_watch_stop: "WATCH-",
-  mandu_check_location: "ARCH?",
-  mandu_check_import: "IMPORT?",
-  mandu_get_architecture: "ARCH",
-  // Build
-  mandu_build: "BUILD",
-  mandu_build_status: "BUILD?",
-  mandu_list_islands: "ISLAND",
-  mandu_set_hydration: "HYDRA~",
-  mandu_add_client_slot: "CLIENT+",
-  // Error
-  mandu_analyze_error: "ERROR",
-};
-
-function getTime(): string {
-  return new Date().toLocaleTimeString("ko-KR", { hour12: false });
-}
-
-function summarizeArgs(args: Record<string, unknown> | null | undefined): string {
-  if (!args || Object.keys(args).length === 0) return "";
-  const entries = Object.entries(args)
-    .filter(([_, v]) => v !== undefined && v !== null)
-    .map(([k, v]) => {
-      const val = typeof v === "string"
-        ? (v.length > 40 ? v.slice(0, 40) + "..." : v)
-        : JSON.stringify(v);
-      return `${k}=${val}`;
-    });
-  return entries.length > 0 ? ` (${entries.join(", ")})` : "";
-}
-
-function summarizeResult(result: unknown): string {
-  if (!result || typeof result !== "object") return "";
-  const obj = result as Record<string, unknown>;
-
-  // Common patterns
-  if (obj.error) return ` >> ERROR: ${obj.error}`;
-  if (obj.success === true) return obj.message ? ` >> ${obj.message}` : " >> OK";
-  if (obj.success === false) return ` >> FAILED: ${obj.message || "unknown"}`;
-  if (Array.isArray(obj.routes)) return ` >> ${obj.routes.length} routes`;
-  if (obj.passed === true) return obj.message ? ` >> ${obj.message}` : " >> PASSED";
-  if (obj.passed === false) return ` >> FAILED (${(obj.violations as unknown[])?.length || 0} violations)`;
-  if (obj.valid === true) return obj.message ? ` >> ${obj.message}` : " >> VALID";
-  if (obj.valid === false) return ` >> INVALID (${(obj.violations as unknown[])?.length || 0} violations)`;
-  if (obj.generated) return " >> Generated";
-  if (obj.status) return ` >> ${JSON.stringify(obj.status).slice(0, 60)}`;
-
-  return "";
-}
-
-export class ActivityMonitor {
-  private logFile: string;
-  private logStream: fs.WriteStream | null = null;
-  private tailProcess: ChildProcess | null = null;
-  private projectRoot: string;
-  private callCount = 0;
-
-  constructor(projectRoot: string) {
-    this.projectRoot = projectRoot;
-    const manduDir = path.join(projectRoot, ".mandu");
-    if (!fs.existsSync(manduDir)) {
-      fs.mkdirSync(manduDir, { recursive: true });
-    }
-    this.logFile = path.join(manduDir, "activity.log");
-  }
-
-  start(): void {
-    // Create/overwrite log file
-    this.logStream = fs.createWriteStream(this.logFile, { flags: "w" });
-
-    const time = getTime();
-    const header =
-      `\n` +
-      `  ╔══════════════════════════════════════════════╗\n` +
-      `  ║         MANDU MCP Activity Monitor           ║\n` +
-      `  ║                                              ║\n` +
-      `  ║  ${time}                                ║\n` +
-      `  ║  ${this.projectRoot.slice(-40).padEnd(40)}    ║\n` +
-      `  ╚══════════════════════════════════════════════╝\n\n`;
-
-    this.logStream.write(header);
-
-    // Auto-open terminal
-    this.openTerminal();
-  }
-
-  stop(): void {
-    if (this.tailProcess) {
-      this.tailProcess.kill();
-      this.tailProcess = null;
-    }
-    if (this.logStream) {
-      this.logStream.end();
-      this.logStream = null;
-    }
-  }
-
-  /**
-   * Log a tool call (invocation)
-   */
-  logTool(
-    name: string,
-    args?: Record<string, unknown> | null,
-    _result?: unknown,
-    error?: string,
-  ): void {
-    this.callCount++;
-    const time = getTime();
-    const tag = TOOL_ICONS[name] || name.replace("mandu_", "").toUpperCase();
-    const argsStr = summarizeArgs(args);
-
-    let line: string;
-    if (error) {
-      line = `${time} ✗ [${tag}]${argsStr}\n       ERROR: ${error}\n`;
-    } else {
-      line = `${time} → [${tag}]${argsStr}\n`;
-    }
-
-    this.write(line);
-  }
-
-  /**
-   * Log a tool result
-   */
-  logResult(name: string, result: unknown): void {
-    const time = getTime();
-    const tag = TOOL_ICONS[name] || name.replace("mandu_", "").toUpperCase();
-    const summary = summarizeResult(result);
-
-    if (summary) {
-      this.write(`${time} ✓ [${tag}]${summary}\n`);
-    }
-  }
-
-  /**
-   * Log a watch event (called from watcher)
-   */
-  logWatch(level: string, ruleId: string, file: string, message: string): void {
-    const time = getTime();
-    const icon = level === "info" ? "ℹ" : "⚠";
-    this.write(`${time} ${icon} [WATCH:${ruleId}] ${file}\n       ${message}\n`);
-  }
-
-  /**
-   * Log a custom event
-   */
-  logEvent(category: string, message: string): void {
-    const time = getTime();
-    this.write(`${time}   [${category}] ${message}\n`);
-  }
-
-  private write(text: string): void {
-    if (this.logStream) {
-      this.logStream.write(text);
-    }
-  }
-
-  private openTerminal(): void {
-    try {
-      if (process.platform === "win32") {
-        this.tailProcess = spawn("cmd", [
-          "/c", "start",
-          "Mandu Activity Monitor",
-          "powershell", "-NoExit", "-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" });
-      } else if (process.platform === "darwin") {
-        this.tailProcess = spawn("osascript", [
-          "-e", `tell application "Terminal" to do script "tail -f '${this.logFile}'"`,
-        ], { detached: true, stdio: "ignore" });
-      } else {
-        this.tailProcess = spawn("x-terminal-emulator", [
-          "-e", `tail -f '${this.logFile}'`,
-        ], { cwd: this.projectRoot, detached: true, stdio: "ignore" });
-      }
-      this.tailProcess?.unref();
-    } catch {
-      // Terminal auto-open failed silently
-    }
-  }
-}
+/**
+ * Mandu Activity Monitor
+ *
+ * Real-time terminal dashboard for MCP server activity.
+ * Opens automatically when the MCP server starts.
+ * Shows all tool calls, watch events, errors, and agent behavior.
+ */
+
+import fs from "fs";
+import path from "path";
+import { spawn, type ChildProcess } from "child_process";
+
+const TOOL_ICONS: Record<string, string> = {
+  // Spec
+  mandu_list_routes: "SPEC",
+  mandu_get_route: "SPEC",
+  mandu_add_route: "SPEC+",
+  mandu_update_route: "SPEC~",
+  mandu_delete_route: "SPEC-",
+  mandu_validate_spec: "SPEC?",
+  // Generate
+  mandu_generate: "GEN",
+  mandu_generate_status: "GEN?",
+  // Guard
+  mandu_guard_check: "GUARD",
+  // Slot
+  mandu_read_slot: "SLOT",
+  mandu_write_slot: "SLOT~",
+  mandu_validate_slot: "SLOT?",
+  // Contract
+  mandu_list_contracts: "CONTRACT",
+  mandu_get_contract: "CONTRACT",
+  mandu_create_contract: "CONTRACT+",
+  mandu_validate_contracts: "CONTRACT?",
+  mandu_sync_contract_slot: "SYNC",
+  mandu_generate_openapi: "OPENAPI",
+  mandu_update_route_contract: "CONTRACT~",
+  // Transaction
+  mandu_begin: "TX-BEGIN",
+  mandu_commit: "TX-COMMIT",
+  mandu_rollback: "TX-ROLLBACK",
+  mandu_tx_status: "TX?",
+  // History
+  mandu_list_history: "HISTORY",
+  mandu_get_snapshot: "SNAPSHOT",
+  mandu_prune_history: "PRUNE",
+  // Brain
+  mandu_doctor: "DOCTOR",
+  mandu_watch_start: "WATCH+",
+  mandu_watch_status: "WATCH?",
+  mandu_watch_stop: "WATCH-",
+  mandu_check_location: "ARCH?",
+  mandu_check_import: "IMPORT?",
+  mandu_get_architecture: "ARCH",
+  // Build
+  mandu_build: "BUILD",
+  mandu_build_status: "BUILD?",
+  mandu_list_islands: "ISLAND",
+  mandu_set_hydration: "HYDRA~",
+  mandu_add_client_slot: "CLIENT+",
+  // Error
+  mandu_analyze_error: "ERROR",
+};
+
+function getTime(): string {
+  return new Date().toLocaleTimeString("ko-KR", { hour12: false });
+}
+
+function summarizeArgs(args: Record<string, unknown> | null | undefined): string {
+  if (!args || Object.keys(args).length === 0) return "";
+  const entries = Object.entries(args)
+    .filter(([_, v]) => v !== undefined && v !== null)
+    .map(([k, v]) => {
+      const val = typeof v === "string"
+        ? (v.length > 40 ? v.slice(0, 40) + "..." : v)
+        : JSON.stringify(v);
+      return `${k}=${val}`;
+    });
+  return entries.length > 0 ? ` (${entries.join(", ")})` : "";
+}
+
+function summarizeResult(result: unknown): string {
+  if (!result || typeof result !== "object") return "";
+  const obj = result as Record<string, unknown>;
+
+  // Common patterns
+  if (obj.error) return ` >> ERROR: ${obj.error}`;
+  if (obj.success === true) return obj.message ? ` >> ${obj.message}` : " >> OK";
+  if (obj.success === false) return ` >> FAILED: ${obj.message || "unknown"}`;
+  if (Array.isArray(obj.routes)) return ` >> ${obj.routes.length} routes`;
+  if (obj.passed === true) return obj.message ? ` >> ${obj.message}` : " >> PASSED";
+  if (obj.passed === false) return ` >> FAILED (${(obj.violations as unknown[])?.length || 0} violations)`;
+  if (obj.valid === true) return obj.message ? ` >> ${obj.message}` : " >> VALID";
+  if (obj.valid === false) return ` >> INVALID (${(obj.violations as unknown[])?.length || 0} violations)`;
+  if (obj.generated) return " >> Generated";
+  if (obj.status) return ` >> ${JSON.stringify(obj.status).slice(0, 60)}`;
+
+  return "";
+}
+
+export class ActivityMonitor {
+  private logFile: string;
+  private logStream: fs.WriteStream | null = null;
+  private tailProcess: ChildProcess | null = null;
+  private projectRoot: string;
+  private callCount = 0;
+
+  constructor(projectRoot: string) {
+    this.projectRoot = projectRoot;
+    const manduDir = path.join(projectRoot, ".mandu");
+    if (!fs.existsSync(manduDir)) {
+      fs.mkdirSync(manduDir, { recursive: true });
+    }
+    this.logFile = path.join(manduDir, "activity.log");
+  }
+
+  start(): void {
+    // Create/overwrite log file
+    this.logStream = fs.createWriteStream(this.logFile, { flags: "w" });
+
+    const time = getTime();
+    const header =
+      `\n` +
+      `  ╔══════════════════════════════════════════════╗\n` +
+      `  ║         MANDU MCP Activity Monitor           ║\n` +
+      `  ║                                              ║\n` +
+      `  ║  ${time}                                ║\n` +
+      `  ║  ${this.projectRoot.slice(-40).padEnd(40)}    ║\n` +
+      `  ╚══════════════════════════════════════════════╝\n\n`;
+
+    this.logStream.write(header);
+
+    // Auto-open terminal
+    this.openTerminal();
+  }
+
+  stop(): void {
+    if (this.tailProcess) {
+      this.tailProcess.kill();
+      this.tailProcess = null;
+    }
+    if (this.logStream) {
+      this.logStream.end();
+      this.logStream = null;
+    }
+  }
+
+  /**
+   * Log a tool call (invocation)
+   */
+  logTool(
+    name: string,
+    args?: Record<string, unknown> | null,
+    _result?: unknown,
+    error?: string,
+  ): void {
+    this.callCount++;
+    const time = getTime();
+    const tag = TOOL_ICONS[name] || name.replace("mandu_", "").toUpperCase();
+    const argsStr = summarizeArgs(args);
+
+    let line: string;
+    if (error) {
+      line = `${time} ✗ [${tag}]${argsStr}\n       ERROR: ${error}\n`;
+    } else {
+      line = `${time} → [${tag}]${argsStr}\n`;
+    }
+
+    this.write(line);
+  }
+
+  /**
+   * Log a tool result
+   */
+  logResult(name: string, result: unknown): void {
+    const time = getTime();
+    const tag = TOOL_ICONS[name] || name.replace("mandu_", "").toUpperCase();
+    const summary = summarizeResult(result);
+
+    if (summary) {
+      this.write(`${time} ✓ [${tag}]${summary}\n`);
+    }
+  }
+
+  /**
+   * Log a watch event (called from watcher)
+   */
+  logWatch(level: string, ruleId: string, file: string, message: string): void {
+    const time = getTime();
+    const icon = level === "info" ? "ℹ" : "⚠";
+    this.write(`${time} ${icon} [WATCH:${ruleId}] ${file}\n       ${message}\n`);
+  }
+
+  /**
+   * Log a custom event
+   */
+  logEvent(category: string, message: string): void {
+    const time = getTime();
+    this.write(`${time}   [${category}] ${message}\n`);
+  }
+
+  private write(text: string): void {
+    if (this.logStream) {
+      this.logStream.write(text);
+    }
+  }
+
+  private openTerminal(): void {
+    try {
+      if (process.platform === "win32") {
+        this.tailProcess = spawn("cmd", [
+          "/c", "start",
+          "Mandu Activity Monitor",
+          "powershell", "-NoExit", "-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" });
+      } else if (process.platform === "darwin") {
+        this.tailProcess = spawn("osascript", [
+          "-e", `tell application "Terminal" to do script "tail -f '${this.logFile}'"`,
+        ], { detached: true, stdio: "ignore" });
+      } else {
+        this.tailProcess = spawn("x-terminal-emulator", [
+          "-e", `tail -f '${this.logFile}'`,
+        ], { cwd: this.projectRoot, detached: true, stdio: "ignore" });
+      }
+      this.tailProcess?.unref();
+    } catch {
+      // Terminal auto-open failed silently
+    }
+  }
+}

package/src/server.ts

@@ -18,8 +18,10 @@ import { slotTools, slotToolDefinitions } from "./tools/slot.js";
 import { hydrationTools, hydrationToolDefinitions } from "./tools/hydration.js";
 import { contractTools, contractToolDefinitions } from "./tools/contract.js";
 import { brainTools, brainToolDefinitions } from "./tools/brain.js";
+import { runtimeTools, runtimeToolDefinitions } from "./tools/runtime.js";
 import { resourceHandlers, resourceDefinitions } from "./resources/handlers.js";
 import { findProjectRoot } from "./utils/project.js";
+import { applyWarningInjection } from "./utils/withWarnings.js";
 import { ActivityMonitor } from "./activity-monitor.js";
 import { startWatcher } from "../../core/src/index.js";
 
@@ -60,11 +62,12 @@ export class ManduMcpServer {
       ...hydrationToolDefinitions,
       ...contractToolDefinitions,
       ...brainToolDefinitions,
+      ...runtimeToolDefinitions,
     ];
   }
 
   private getAllToolHandlers(): Record<string, (args: Record<string, unknown>) => Promise<unknown>> {
-    return {
+    const handlers = {
       ...specTools(this.projectRoot),
       ...generateTools(this.projectRoot),
       ...transactionTools(this.projectRoot),
@@ -74,7 +77,10 @@ export class ManduMcpServer {
       ...hydrationTools(this.projectRoot),
       ...contractTools(this.projectRoot),
       ...brainTools(this.projectRoot, this.server, this.monitor),
+      ...runtimeTools(this.projectRoot),
     };
+
+    return applyWarningInjection(handlers);
   }
 
   private registerToolHandlers(): void {

package/src/tools/hydration.ts

@@ -318,8 +318,8 @@ export function hydrationTools(projectRoot: string) {
         };
       }
 
-      // Create client slot file
-      const clientModulePath = `spec/slots/${routeId}.client.ts`;
+      // Create client slot file in apps/web/components/ (not spec/slots/)
+      const clientModulePath = `apps/web/components/${routeId}.client.tsx`;
       const clientFilePath = path.join(projectRoot, clientModulePath);
 
       // Check if file already exists

package/src/tools/index.ts

@@ -7,3 +7,4 @@ export { slotTools, slotToolDefinitions } from "./slot.js";
 export { hydrationTools, hydrationToolDefinitions } from "./hydration.js";
 export { contractTools, contractToolDefinitions } from "./contract.js";
 export { brainTools, brainToolDefinitions } from "./brain.js";
+export { runtimeTools, runtimeToolDefinitions } from "./runtime.js";

package/src/tools/runtime.ts

@@ -0,0 +1,497 @@
+/**
+ * Mandu MCP Runtime Tools
+ * Runtime 설정 조회 및 관리 도구
+ *
+ * - Logger 설정 조회/변경
+ * - Normalize 설정 조회
+ * - Contract 옵션 확인
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { getProjectPaths, readJsonFile } from "../utils/project.js";
+import { loadManifest } from "@mandujs/core";
+import path from "path";
+import fs from "fs/promises";
+
+export const runtimeToolDefinitions: Tool[] = [
+  {
+    name: "mandu_get_runtime_config",
+    description:
+      "Get current runtime configuration including logger and normalize settings. " +
+      "Shows default values and any overrides from contracts.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+    },
+  },
+  {
+    name: "mandu_get_contract_options",
+    description:
+      "Get normalize and coerce options for a specific contract. " +
+      "These options control how request data is sanitized and type-converted.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        routeId: {
+          type: "string",
+          description: "The route ID to get contract options for",
+        },
+      },
+      required: ["routeId"],
+    },
+  },
+  {
+    name: "mandu_set_contract_normalize",
+    description:
+      "Set normalize mode for a contract. " +
+      "Modes: 'strip' (remove undefined fields, default), 'strict' (error on undefined), 'passthrough' (allow all).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        routeId: {
+          type: "string",
+          description: "The route ID to update",
+        },
+        normalize: {
+          type: "string",
+          enum: ["strip", "strict", "passthrough"],
+          description:
+            "Normalize mode: strip (Mass Assignment 방지), strict (에러 발생), passthrough (모두 허용)",
+        },
+        coerceQueryParams: {
+          type: "boolean",
+          description: "Whether to auto-convert query string types (default: true)",
+        },
+      },
+      required: ["routeId"],
+    },
+  },
+  {
+    name: "mandu_list_logger_options",
+    description:
+      "List available logger configuration options and their descriptions. " +
+      "Useful for understanding how to configure logging in Mandu.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+    },
+  },
+  {
+    name: "mandu_generate_logger_config",
+    description:
+      "Generate logger configuration code based on requirements. " +
+      "Returns TypeScript code that can be added to the project.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        environment: {
+          type: "string",
+          enum: ["development", "production", "testing"],
+          description: "Target environment (default: development)",
+        },
+        includeHeaders: {
+          type: "boolean",
+          description: "Whether to log request headers (default: false for security)",
+        },
+        includeBody: {
+          type: "boolean",
+          description: "Whether to log request body (default: false for security)",
+        },
+        format: {
+          type: "string",
+          enum: ["pretty", "json"],
+          description: "Log output format (pretty for dev, json for prod)",
+        },
+        customRedact: {
+          type: "array",
+          items: { type: "string" },
+          description: "Additional fields to redact from logs",
+        },
+      },
+      required: [],
+    },
+  },
+];
+
+async function readFileContent(filePath: string): Promise<string | null> {
+  try {
+    return await Bun.file(filePath).text();
+  } catch {
+    return null;
+  }
+}
+
+export function runtimeTools(projectRoot: string) {
+  const paths = getProjectPaths(projectRoot);
+
+  return {
+    mandu_get_runtime_config: async () => {
+      return {
+        defaults: {
+          logger: {
+            format: "pretty",
+            level: "info",
+            includeHeaders: false,
+            includeBody: false,
+            maxBodyBytes: 1024,
+            sampleRate: 1,
+            slowThresholdMs: 1000,
+            redact: [
+              "authorization",
+              "cookie",
+              "set-cookie",
+              "x-api-key",
+              "password",
+              "token",
+              "secret",
+              "bearer",
+              "credential",
+            ],
+          },
+          normalize: {
+            mode: "strip",
+            coerceQueryParams: true,
+            deep: true,
+          },
+        },
+        description: {
+          logger: {
+            format: "Log output format: 'pretty' (colored, dev) or 'json' (structured, prod)",
+            level: "Minimum log level: 'debug' | 'info' | 'warn' | 'error'",
+            includeHeaders: "⚠️ Security risk if true - logs request headers",
+            includeBody: "⚠️ Security risk if true - logs request body",
+            maxBodyBytes: "Maximum body size to log (truncates larger bodies)",
+            sampleRate: "Sampling rate 0-1 (1 = 100% logging)",
+            slowThresholdMs: "Requests slower than this get detailed logging",
+            redact: "Header/field names to mask in logs",
+          },
+          normalize: {
+            mode: "strip: remove undefined fields (Mass Assignment 방지), strict: error on undefined, passthrough: allow all",
+            coerceQueryParams: "Auto-convert query string '123' → number 123",
+            deep: "Apply normalization to nested objects",
+          },
+        },
+        usage: {
+          logger: `import { logger, devLogger, prodLogger } from "@mandujs/core";
+
+// Development
+app.use(devLogger());
+
+// Production
+app.use(prodLogger({ sampleRate: 0.1 }));`,
+          normalize: `// In contract definition
+export default Mandu.contract({
+  normalize: "strip",  // or "strict" | "passthrough"
+  coerceQueryParams: true,
+  request: { ... },
+  response: { ... },
+});`,
+        },
+      };
+    },
+
+    mandu_get_contract_options: async (args: Record<string, unknown>) => {
+      const { routeId } = args as { routeId: string };
+
+      const result = await loadManifest(paths.manifestPath);
+      if (!result.success || !result.data) {
+        return { error: result.errors };
+      }
+
+      const route = result.data.routes.find((r) => r.id === routeId);
+      if (!route) {
+        return { error: `Route not found: ${routeId}` };
+      }
+
+      if (!route.contractModule) {
+        return {
+          routeId,
+          hasContract: false,
+          defaults: {
+            normalize: "strip",
+            coerceQueryParams: true,
+          },
+          suggestion: `Create a contract with: mandu_create_contract({ routeId: "${routeId}" })`,
+        };
+      }
+
+      // Read contract file and extract options
+      const contractPath = path.join(projectRoot, route.contractModule);
+      const contractContent = await readFileContent(contractPath);
+
+      if (!contractContent) {
+        return {
+          routeId,
+          contractModule: route.contractModule,
+          error: "Contract file not found",
+        };
+      }
+
+      // Parse normalize and coerceQueryParams from content
+      const normalizeMatch = contractContent.match(/normalize\s*:\s*["'](\w+)["']/);
+      const coerceMatch = contractContent.match(/coerceQueryParams\s*:\s*(true|false)/);
+
+      return {
+        routeId,
+        contractModule: route.contractModule,
+        options: {
+          normalize: normalizeMatch?.[1] || "strip (default)",
+          coerceQueryParams: coerceMatch ? coerceMatch[1] === "true" : "true (default)",
+        },
+        explanation: {
+          normalize: {
+            strip: "정의되지 않은 필드 제거 (Mass Assignment 공격 방지)",
+            strict: "정의되지 않은 필드 있으면 400 에러",
+            passthrough: "모든 필드 허용 (검증만, 필터링 안 함)",
+          },
+          coerceQueryParams: "URL query string은 항상 문자열이므로, 스키마 타입으로 자동 변환",
+        },
+      };
+    },
+
+    mandu_set_contract_normalize: async (args: Record<string, unknown>) => {
+      const { routeId, normalize, coerceQueryParams } = args as {
+        routeId: string;
+        normalize?: "strip" | "strict" | "passthrough";
+        coerceQueryParams?: boolean;
+      };
+
+      const result = await loadManifest(paths.manifestPath);
+      if (!result.success || !result.data) {
+        return { error: result.errors };
+      }
+
+      const route = result.data.routes.find((r) => r.id === routeId);
+      if (!route) {
+        return { error: `Route not found: ${routeId}` };
+      }
+
+      if (!route.contractModule) {
+        return {
+          error: "Route has no contract module",
+          suggestion: `Create a contract first: mandu_create_contract({ routeId: "${routeId}" })`,
+        };
+      }
+
+      const contractPath = path.join(projectRoot, route.contractModule);
+      let content = await readFileContent(contractPath);
+
+      if (!content) {
+        return { error: `Contract file not found: ${route.contractModule}` };
+      }
+
+      const changes: string[] = [];
+
+      // Update normalize option
+      if (normalize) {
+        if (content.includes("normalize:")) {
+          content = content.replace(
+            /normalize\s*:\s*["']\w+["']/,
+            `normalize: "${normalize}"`
+          );
+          changes.push(`normalize: "${normalize}"`);
+        } else {
+          // Add normalize option after description or tags
+          const insertPoint =
+            content.indexOf("request:") ||
+            content.indexOf("response:");
+          if (insertPoint > 0) {
+            const before = content.slice(0, insertPoint);
+            const after = content.slice(insertPoint);
+            content = before + `normalize: "${normalize}",\n  ` + after;
+            changes.push(`normalize: "${normalize}" (added)`);
+          }
+        }
+      }
+
+      // Update coerceQueryParams option
+      if (coerceQueryParams !== undefined) {
+        if (content.includes("coerceQueryParams:")) {
+          content = content.replace(
+            /coerceQueryParams\s*:\s*(true|false)/,
+            `coerceQueryParams: ${coerceQueryParams}`
+          );
+          changes.push(`coerceQueryParams: ${coerceQueryParams}`);
+        } else if (insertAfter(content, "normalize:")) {
+          content = content.replace(
+            /(normalize\s*:\s*["']\w+["']),?/,
+            `$1,\n  coerceQueryParams: ${coerceQueryParams},`
+          );
+          changes.push(`coerceQueryParams: ${coerceQueryParams} (added)`);
+        }
+      }
+
+      if (changes.length === 0) {
+        return {
+          success: false,
+          message: "No changes to apply",
+          currentContent: content.slice(0, 500) + "...",
+        };
+      }
+
+      // Write updated content
+      await Bun.write(contractPath, content);
+
+      return {
+        success: true,
+        contractModule: route.contractModule,
+        changes,
+        message: `Updated ${route.contractModule}`,
+        securityNote:
+          normalize === "passthrough"
+            ? "⚠️ passthrough 모드는 Mass Assignment 공격에 취약할 수 있습니다. 신뢰할 수 있는 입력에만 사용하세요."
+            : normalize === "strict"
+            ? "strict 모드는 클라이언트가 추가 필드를 보내면 400 에러를 반환합니다."
+            : "strip 모드 (권장): 정의되지 않은 필드는 자동 제거됩니다.",
+      };
+    },
+
+    mandu_list_logger_options: async () => {
+      return {
+        options: [
+          {
+            name: "format",
+            type: '"pretty" | "json"',
+            default: "pretty",
+            description: "로그 출력 형식. pretty는 개발용 컬러 출력, json은 운영용 구조화 로그",
+          },
+          {
+            name: "level",
+            type: '"debug" | "info" | "warn" | "error"',
+            default: "info",
+            description: "최소 로그 레벨. debug는 모든 요청 상세, error는 에러만",
+          },
+          {
+            name: "includeHeaders",
+            type: "boolean",
+            default: false,
+            description: "⚠️ 요청 헤더 로깅. 민감 정보 노출 위험",
+          },
+          {
+            name: "includeBody",
+            type: "boolean",
+            default: false,
+            description: "⚠️ 요청 바디 로깅. 민감 정보 노출 + 스트림 문제",
+          },
+          {
+            name: "maxBodyBytes",
+            type: "number",
+            default: 1024,
+            description: "바디 로깅 시 최대 크기 (초과분 truncate)",
+          },
+          {
+            name: "redact",
+            type: "string[]",
+            default: '["authorization", "cookie", "password", ...]',
+            description: "로그에서 마스킹할 헤더/필드명",
+          },
+          {
+            name: "requestId",
+            type: '"auto" | ((ctx) => string)',
+            default: "auto",
+            description: "요청 ID 생성 방식. auto는 UUID 또는 타임스탬프 기반",
+          },
+          {
+            name: "sampleRate",
+            type: "number (0-1)",
+            default: 1,
+            description: "샘플링 비율. 운영에서 로그 양 조절 (0.1 = 10%)",
+          },
+          {
+            name: "slowThresholdMs",
+            type: "number",
+            default: 1000,
+            description: "느린 요청 임계값. 초과 시 warn 레벨로 상세 출력",
+          },
+          {
+            name: "includeTraceOnSlow",
+            type: "boolean",
+            default: true,
+            description: "느린 요청에 Trace 리포트 포함",
+          },
+          {
+            name: "sink",
+            type: "(entry: LogEntry) => void",
+            default: "console",
+            description: "커스텀 로그 출력 (Pino, CloudWatch 등 연동)",
+          },
+          {
+            name: "skip",
+            type: "(string | RegExp)[]",
+            default: "[]",
+            description: '로깅 제외 경로 패턴. 예: ["/health", /^\\/static\\//]',
+          },
+        ],
+        presets: {
+          devLogger: "개발용: debug 레벨, pretty 포맷, 헤더 포함",
+          prodLogger: "운영용: info 레벨, json 포맷, 헤더/바디 미포함",
+        },
+      };
+    },
+
+    mandu_generate_logger_config: async (args: Record<string, unknown>) => {
+      const {
+        environment = "development",
+        includeHeaders = false,
+        includeBody = false,
+        format,
+        customRedact = [],
+      } = args as {
+        environment?: "development" | "production" | "testing";
+        includeHeaders?: boolean;
+        includeBody?: boolean;
+        format?: "pretty" | "json";
+        customRedact?: string[];
+      };
+
+      const isDev = environment === "development";
+      const isProd = environment === "production";
+
+      const config = {
+        format: format || (isDev ? "pretty" : "json"),
+        level: isDev ? "debug" : "info",
+        includeHeaders: isDev ? includeHeaders : false,
+        includeBody: isDev ? includeBody : false,
+        maxBodyBytes: 1024,
+        sampleRate: isProd ? 0.1 : 1,
+        slowThresholdMs: isDev ? 500 : 1000,
+        ...(customRedact.length > 0 && { redact: customRedact }),
+      };
+
+      const code = `import { logger } from "@mandujs/core";
+
+// ${environment} environment logger configuration
+export const appLogger = logger(${JSON.stringify(config, null, 2)});
+
+// Usage in your app:
+// app.use(appLogger);
+`;
+
+      const warnings: string[] = [];
+      if (includeHeaders && isProd) {
+        warnings.push("⚠️ includeHeaders: true는 프로덕션에서 민감 정보 노출 위험이 있습니다.");
+      }
+      if (includeBody && isProd) {
+        warnings.push("⚠️ includeBody: true는 프로덕션에서 민감 정보 노출 위험이 있습니다.");
+      }
+
+      return {
+        environment,
+        config,
+        code,
+        warnings: warnings.length > 0 ? warnings : undefined,
+        tips: [
+          "devLogger() 또는 prodLogger() 프리셋을 사용할 수도 있습니다.",
+          "sink 옵션으로 Pino, CloudWatch 등 외부 시스템 연동 가능",
+          "skip 옵션으로 /health, /metrics 등 제외 가능",
+        ],
+      };
+    },
+  };
+}
+
+function insertAfter(content: string, search: string): boolean {
+  return content.includes(search);
+}

package/src/utils/withWarnings.ts

@@ -0,0 +1,83 @@
+/**
+ * Watcher Warning Injection for Mutation Tools
+ *
+ * Mutation 도구(write_slot, add_route, generate 등) 실행 후
+ * watcher 경고를 자동으로 응답에 포함시킨다.
+ *
+ * MCP notification이 Claude Code에 전달되지 않는 문제를 해결.
+ */
+
+import { getWatcher } from "../../../core/src/index.js";
+
+const MUTATION_TOOLS = new Set([
+  "mandu_write_slot",
+  "mandu_add_route",
+  "mandu_update_route",
+  "mandu_delete_route",
+  "mandu_generate",
+  "mandu_build",
+  "mandu_commit",
+  "mandu_add_client_slot",
+  "mandu_set_hydration",
+  "mandu_create_contract",
+  "mandu_update_route_contract",
+  "mandu_sync_contract_slot",
+]);
+
+/** watcher debounce(300ms) + 여유분 */
+const WARNING_WAIT_MS = 400;
+
+type ToolHandler = (args: Record<string, unknown>) => Promise<unknown>;
+
+/**
+ * Mutation 도구 핸들러를 감싸서, 실행 후 발생한 watcher 경고를
+ * 응답 객체의 `_warnings` 필드에 자동 포함시킨다.
+ */
+export function applyWarningInjection(
+  handlers: Record<string, ToolHandler>
+): Record<string, ToolHandler> {
+  const wrapped: Record<string, ToolHandler> = {};
+
+  for (const [name, handler] of Object.entries(handlers)) {
+    if (MUTATION_TOOLS.has(name)) {
+      wrapped[name] = wrapWithWarnings(handler);
+    } else {
+      wrapped[name] = handler;
+    }
+  }
+
+  return wrapped;
+}
+
+function wrapWithWarnings(handler: ToolHandler): ToolHandler {
+  return async (args: Record<string, unknown>) => {
+    const watcher = getWatcher();
+    const beforeCount = watcher?.getRecentWarnings(100).length ?? 0;
+
+    const result = await handler(args);
+
+    // watcher debounce 대기
+    await new Promise((resolve) => setTimeout(resolve, WARNING_WAIT_MS));
+
+    const allWarnings = watcher?.getRecentWarnings(100) ?? [];
+    const newWarnings = allWarnings.slice(beforeCount);
+
+    if (
+      newWarnings.length > 0 &&
+      typeof result === "object" &&
+      result !== null
+    ) {
+      return {
+        ...(result as Record<string, unknown>),
+        _warnings: newWarnings.map((w) => ({
+          ruleId: w.ruleId,
+          file: w.file,
+          message: w.message,
+          level: w.level ?? "warn",
+        })),
+      };
+    }
+
+    return result;
+  };
+}