@mandujs/mcp 0.18.1 → 0.18.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/mcp",
-  "version": "0.18.1",
+  "version": "0.18.3",
   "description": "Mandu MCP Server - Agent-native interface for Mandu framework operations",
   "type": "module",
   "main": "./src/index.ts",

package/src/tools/ate.ts

@@ -14,61 +14,110 @@ import {
 export const ateToolDefinitions: Tool[] = [
   {
     name: "mandu.ate.extract",
-    description: "ATE: AST 기반 상호작용 그래프 추출",
+    description:
+      "ATE Step 1 — Extract: Statically analyze the Mandu project's AST to build an interaction graph of routes, slots, contracts, and data flow. " +
+      "Identifies all testable interactions without running the server. " +
+      "Output is stored in .mandu/ate/extract/ and used by mandu.ate.generate.",
     inputSchema: {
       type: "object",
       properties: {
-        repoRoot: { type: "string" },
-        tsconfigPath: { type: "string" },
-        routeGlobs: { type: "array", items: { type: "string" } },
-        buildSalt: { type: "string" },
+        repoRoot: { type: "string", description: "Absolute path to the Mandu project root" },
+        tsconfigPath: { type: "string", description: "Path to tsconfig.json (default: tsconfig.json in repoRoot)" },
+        routeGlobs: {
+          type: "array",
+          items: { type: "string" },
+          description: "Glob patterns to limit which routes are analyzed (e.g. ['app/api/**', 'app/blog/**']). Omit for all routes.",
+        },
+        buildSalt: {
+          type: "string",
+          description: "Cache invalidation salt — change this to force re-extraction even if source hasn't changed",
+        },
       },
       required: ["repoRoot"],
     },
   },
   {
     name: "mandu.ate.generate",
-    description: "ATE: 시나리오 생성 + Playwright spec codegen",
+    description:
+      "ATE Step 2 — Generate: Create Playwright test scenarios from the interaction graph produced by mandu.ate.extract. " +
+      "Oracle level controls assertion depth: " +
+      "L0 = no assertions (smoke test only), " +
+      "L1 = basic HTTP status checks, " +
+      "L2 = contract schema validation (response shape matches Zod contract), " +
+      "L3 = full behavioral contract (side effects, state changes, error paths). " +
+      "Output: .mandu/ate/tests/*.spec.ts ready to run with Playwright.",
     inputSchema: {
       type: "object",
       properties: {
-        repoRoot: { type: "string" },
-        oracleLevel: { type: "string", enum: ["L0", "L1", "L2", "L3"] },
-        onlyRoutes: { type: "array", items: { type: "string" } },
+        repoRoot: { type: "string", description: "Absolute path to the Mandu project root" },
+        oracleLevel: {
+          type: "string",
+          enum: ["L0", "L1", "L2", "L3"],
+          description: "Assertion depth: L0=smoke, L1=HTTP status, L2=contract schema, L3=full behavioral",
+        },
+        onlyRoutes: {
+          type: "array",
+          items: { type: "string" },
+          description: "Limit test generation to specific routeIds (e.g. ['api-users', 'blog-slug']). Omit for all routes.",
+        },
       },
       required: ["repoRoot"],
     },
   },
   {
     name: "mandu.ate.run",
-    description: "ATE: Playwright runner 실행(artifacts 수집)",
+    description:
+      "ATE Step 3 — Run: Execute the generated Playwright specs against a running Mandu dev server. " +
+      "Collects test artifacts (screenshots, traces, results) in .mandu/ate/runs/{runId}/. " +
+      "Requires the Mandu dev server to be running (use mandu_dev_start first). " +
+      "Returns a runId for use with mandu.ate.report and mandu.ate.heal.",
     inputSchema: {
       type: "object",
       properties: {
-        repoRoot: { type: "string" },
-        baseURL: { type: "string" },
-        ci: { type: "boolean" },
-        headless: { type: "boolean" },
-        browsers: { type: "array", items: { type: "string", enum: ["chromium", "firefox", "webkit"] } },
+        repoRoot: { type: "string", description: "Absolute path to the Mandu project root" },
+        baseURL: {
+          type: "string",
+          description: "Dev server URL (default: http://localhost:3333). Must match the running mandu dev server.",
+        },
+        ci: { type: "boolean", description: "CI mode: stricter timeouts, no interactive prompts" },
+        headless: { type: "boolean", description: "Run browsers headlessly (default: true)" },
+        browsers: {
+          type: "array",
+          items: { type: "string", enum: ["chromium", "firefox", "webkit"] },
+          description: "Browsers to test against (default: ['chromium'])",
+        },
       },
       required: ["repoRoot"],
     },
   },
   {
     name: "mandu.ate.report",
-    description: "ATE: 테스트 리포트 생성 (JSON, HTML, 또는 both)",
+    description:
+      "ATE Step 4 — Report: Generate a test report from run artifacts. " +
+      "Produces pass/fail summary, coverage by route, and failure details. " +
+      "Use the runId returned by mandu.ate.run. " +
+      "If tests failed, follow up with mandu.ate.heal to get fix suggestions.",
     inputSchema: {
       type: "object",
       properties: {
-        repoRoot: { type: "string" },
-        runId: { type: "string" },
-        startedAt: { type: "string" },
-        finishedAt: { type: "string" },
-        exitCode: { type: "number" },
-        oracleLevel: { type: "string", enum: ["L0", "L1", "L2", "L3"] },
-        format: { type: "string", enum: ["json", "html", "both"], description: "리포트 포맷 (기본값: both)" },
+        repoRoot: { type: "string", description: "Absolute path to the Mandu project root" },
+        runId: { type: "string", description: "Run ID returned by mandu.ate.run" },
+        startedAt: { type: "string", description: "ISO timestamp when run started" },
+        finishedAt: { type: "string", description: "ISO timestamp when run finished" },
+        exitCode: { type: "number", description: "Playwright process exit code (0=pass, non-zero=fail)" },
+        oracleLevel: {
+          type: "string",
+          enum: ["L0", "L1", "L2", "L3"],
+          description: "Oracle level used during generation (for report context)",
+        },
+        format: {
+          type: "string",
+          enum: ["json", "html", "both"],
+          description: "Report format: json (machine-readable), html (visual), both (default)",
+        },
         impact: {
           type: "object",
+          description: "Impact analysis context — set if tests were run on a subset of routes via mandu.ate.impact",
           properties: {
             mode: { type: "string", enum: ["full", "subset"] },
             changedFiles: { type: "array", items: { type: "string" } },
@@ -82,61 +131,89 @@ export const ateToolDefinitions: Tool[] = [
   },
   {
     name: "mandu.ate.heal",
-    description: "ATE: 실패 원인 분류 + 복구 제안(diff) 생성 (자동 커밋 금지)",
+    description:
+      "ATE Step 5 — Heal: Analyze test failures from a run and generate safe diff suggestions for fixing the code. " +
+      "Classifies failures by root cause (schema mismatch, missing handler, wrong status, selector stale, etc.) " +
+      "and produces reviewable diffs — never auto-commits or overwrites files. " +
+      "Use mandu.ate.apply_heal to apply a specific suggestion after review. " +
+      "Supports rollback via mandu_rollback if applied changes cause regressions.",
     inputSchema: {
       type: "object",
       properties: {
-        repoRoot: { type: "string" },
-        runId: { type: "string" },
+        repoRoot: { type: "string", description: "Absolute path to the Mandu project root" },
+        runId: { type: "string", description: "Run ID from mandu.ate.run with failures to analyze" },
       },
       required: ["repoRoot", "runId"],
     },
   },
   {
     name: "mandu.ate.impact",
-    description: "ATE: git diff 기반 subset 계산",
+    description:
+      "ATE Optimization — Impact Analysis: Calculate the minimal subset of routes affected by changed files using git diff. " +
+      "Avoids running the full test suite when only part of the codebase changed. " +
+      "Returns selectedRoutes to pass to mandu.ate.generate (onlyRoutes) or mandu.ate.run. " +
+      "Typical use: run after `git commit` to test only affected routes in CI.",
     inputSchema: {
       type: "object",
       properties: {
-        repoRoot: { type: "string" },
-        base: { type: "string" },
-        head: { type: "string" },
+        repoRoot: { type: "string", description: "Absolute path to the Mandu project root" },
+        base: { type: "string", description: "Git base ref for diff (default: HEAD~1 or main branch)" },
+        head: { type: "string", description: "Git head ref for diff (default: current working tree)" },
       },
       required: ["repoRoot"],
     },
   },
   {
     name: "mandu.ate.auto_pipeline",
-    description: "ATE: 전체 파이프라인 자동 실행 (Extract → Generate → Run → Report → Heal)",
+    description:
+      "ATE Full Pipeline — Run the complete ATE cycle in one call: " +
+      "Extract AST → Generate Playwright specs → Run tests → Create report → Suggest heals. " +
+      "Recommended for: initial setup, scheduled CI runs, and full regression testing. " +
+      "For incremental development, prefer individual steps (extract → generate → run → report → heal). " +
+      "Set useImpactAnalysis=true to automatically limit tests to changed routes.",
     inputSchema: {
       type: "object",
       properties: {
-        repoRoot: { type: "string" },
-        baseURL: { type: "string" },
-        oracleLevel: { type: "string", enum: ["L0", "L1", "L2", "L3"] },
-        ci: { type: "boolean" },
-        useImpactAnalysis: { type: "boolean" },
-        base: { type: "string" },
-        head: { type: "string" },
-        autoHeal: { type: "boolean" },
-        tsconfigPath: { type: "string" },
-        routeGlobs: { type: "array", items: { type: "string" } },
-        buildSalt: { type: "string" },
+        repoRoot: { type: "string", description: "Absolute path to the Mandu project root" },
+        baseURL: { type: "string", description: "Dev server URL (default: http://localhost:3333)" },
+        oracleLevel: {
+          type: "string",
+          enum: ["L0", "L1", "L2", "L3"],
+          description: "Assertion depth: L0=smoke, L1=HTTP status, L2=contract schema, L3=full behavioral",
+        },
+        ci: { type: "boolean", description: "CI mode: stricter timeouts" },
+        useImpactAnalysis: {
+          type: "boolean",
+          description: "Run impact analysis first and only test changed routes (faster in CI)",
+        },
+        base: { type: "string", description: "Git base ref for impact analysis" },
+        head: { type: "string", description: "Git head ref for impact analysis" },
+        autoHeal: {
+          type: "boolean",
+          description: "Automatically run heal analysis after failures (produces diff suggestions, never auto-applies)",
+        },
+        tsconfigPath: { type: "string", description: "Path to tsconfig.json" },
+        routeGlobs: { type: "array", items: { type: "string" }, description: "Limit extraction to specific route patterns" },
+        buildSalt: { type: "string", description: "Cache invalidation salt for extraction" },
       },
       required: ["repoRoot"],
     },
   },
   {
     name: "mandu.ate.feedback",
-    description: "ATE: 테스트 실패 원인 분석 및 heal 제안 평가",
+    description:
+      "ATE Feedback — Evaluate heal suggestions from a failed run and classify which fixes are safe to auto-apply. " +
+      "Safe-to-auto-apply: selector-map updates (CSS selector changes). " +
+      "Requires human review: contract schema changes, handler logic, route restructuring. " +
+      "Returns priority ranking of suggestions to guide review order.",
     inputSchema: {
       type: "object",
       properties: {
-        repoRoot: { type: "string", description: "프로젝트 루트 디렉토리" },
-        runId: { type: "string", description: "테스트 실행 ID" },
+        repoRoot: { type: "string", description: "Absolute path to the Mandu project root" },
+        runId: { type: "string", description: "Run ID with heal suggestions to evaluate" },
         autoApply: {
           type: "boolean",
-          description: "자동 적용 가능 여부 (selector-map만 안전)",
+          description: "If true, auto-apply only selector-map changes (CSS selectors) — other changes always require review",
         },
       },
       required: ["repoRoot", "runId"],
@@ -144,19 +221,23 @@ export const ateToolDefinitions: Tool[] = [
   },
   {
     name: "mandu.ate.apply_heal",
-    description: "ATE: heal diff를 실제 코드에 적용 (rollback 가능)",
+    description:
+      "ATE Apply — Apply a specific heal suggestion diff to the codebase. " +
+      "Always creates a backup snapshot first (use mandu_rollback to undo). " +
+      "Run mandu.ate.feedback first to get the healIndex and confirm the fix is safe. " +
+      "After applying, re-run mandu.ate.run to verify the fix resolved the failure.",
     inputSchema: {
       type: "object",
       properties: {
-        repoRoot: { type: "string", description: "프로젝트 루트 디렉토리" },
-        runId: { type: "string", description: "테스트 실행 ID" },
+        repoRoot: { type: "string", description: "Absolute path to the Mandu project root" },
+        runId: { type: "string", description: "Run ID containing the heal suggestion to apply" },
         healIndex: {
           type: "number",
-          description: "적용할 heal suggestion의 인덱스 (0부터 시작)",
+          description: "0-based index of the heal suggestion to apply (from mandu.ate.heal or mandu.ate.feedback results)",
         },
         createBackup: {
           type: "boolean",
-          description: "백업 생성 여부 (기본값: true, 필수 권장)",
+          description: "Create a snapshot before applying (default: true, strongly recommended — enables mandu_rollback)",
         },
       },
       required: ["repoRoot", "runId", "healIndex"],

package/src/tools/contract.ts

@@ -16,7 +16,15 @@ import fs from "fs/promises";
 export const contractToolDefinitions: Tool[] = [
   {
     name: "mandu_list_contracts",
-    description: "List all contracts in the current Mandu project",
+    description:
+      "List all routes that have a contract module defined. " +
+      "In Mandu, a 'contract' is a Zod-based schema file (spec/contracts/{routeId}.contract.ts) that defines " +
+      "the request/response shape for an API route. Contracts enable: " +
+      "(1) automatic input validation and sanitization (strip/strict/passthrough normalize modes), " +
+      "(2) TypeScript type inference for slot handlers, " +
+      "(3) OpenAPI 3.0 spec generation via mandu_generate_openapi, " +
+      "(4) ATE L2 (schema validation) and L3 (full behavioral) test generation. " +
+      "Also returns a list of API routes that are missing contracts.",
     inputSchema: {
       type: "object",
       properties: {},
@@ -25,13 +33,17 @@ export const contractToolDefinitions: Tool[] = [
   },
   {
     name: "mandu_get_contract",
-    description: "Get details of a specific contract by route ID",
+    description:
+      "Get the full TypeScript source of a contract file for a specific route. " +
+      "Returns the raw content of spec/contracts/{routeId}.contract.ts, " +
+      "which contains Zod schemas for each HTTP method's request body/query params and response shape. " +
+      "If the route has no contract, returns a suggestion to create one with mandu_create_contract.",
     inputSchema: {
       type: "object",
       properties: {
         routeId: {
           type: "string",
-          description: "The route ID to retrieve contract for",
+          description: "The route ID to retrieve the contract for",
         },
       },
       required: ["routeId"],
@@ -39,22 +51,27 @@ export const contractToolDefinitions: Tool[] = [
   },
   {
     name: "mandu_create_contract",
-    description: "Create a new contract for a route",
+    description:
+      "Create a new contract file for a route and link it in the manifest. " +
+      "Generates spec/contracts/{routeId}.contract.ts with Zod schema stubs for each HTTP method. " +
+      "Template includes: request schema (body for POST/PUT/PATCH, query for GET/DELETE) and response schema. " +
+      "After creation: edit the Zod schemas to match your actual API shape, " +
+      "then run mandu_generate to regenerate typed handlers with validation.",
     inputSchema: {
       type: "object",
       properties: {
         routeId: {
           type: "string",
-          description: "The route ID to create contract for",
+          description: "The route ID to create a contract for",
         },
         description: {
           type: "string",
-          description: "API description (optional)",
+          description: "Human-readable API description added as a comment in the contract file",
         },
         methods: {
           type: "array",
           items: { type: "string" },
-          description: "HTTP methods to include (default: route methods or ['GET', 'POST'])",
+          description: "HTTP methods to generate schemas for (default: route's declared methods or ['GET', 'POST'])",
         },
       },
       required: ["routeId"],
@@ -62,7 +79,11 @@ export const contractToolDefinitions: Tool[] = [
   },
   {
     name: "mandu_update_route_contract",
-    description: "Update a route to add or change its contract module",
+    description:
+      "Update the manifest to link an existing contract file to a route. " +
+      "Use this when the contract file already exists but the manifest's contractModule path needs updating, " +
+      "or when moving a contract file to a new location. " +
+      "Does not modify the contract file itself — only updates the manifest reference and lock file.",
     inputSchema: {
       type: "object",
       properties: {
@@ -72,7 +93,7 @@ export const contractToolDefinitions: Tool[] = [
         },
         contractModule: {
           type: "string",
-          description: "Path to contract file (e.g., spec/contracts/users.contract.ts)",
+          description: "Relative path to the contract file from project root (e.g., spec/contracts/users.contract.ts)",
         },
       },
       required: ["routeId", "contractModule"],
@@ -80,7 +101,12 @@ export const contractToolDefinitions: Tool[] = [
   },
   {
     name: "mandu_validate_contracts",
-    description: "Validate all contracts against their slot implementations",
+    description:
+      "Validate all contracts against their linked slot implementations for consistency. " +
+      "Checks that every HTTP method defined in a contract has a matching handler in the slot, " +
+      "response types are compatible, and no orphaned contracts exist. " +
+      "Run this after modifying contracts or slots, or before running ATE tests to catch mismatches early. " +
+      "Returns a list of violations with file locations, descriptions, and fix suggestions.",
     inputSchema: {
       type: "object",
       properties: {},
@@ -89,18 +115,27 @@ export const contractToolDefinitions: Tool[] = [
   },
   {
     name: "mandu_sync_contract_slot",
-    description: "Sync contract and slot to resolve mismatches",
+    description:
+      "Detect and generate code to resolve HTTP method mismatches between a contract and its slot. " +
+      "'contract-to-slot': finds HTTP methods defined in the contract but missing from the slot — " +
+      "generates handler stub code to add to the slot file. " +
+      "'slot-to-contract': finds slot handlers not documented in the contract — " +
+      "generates Zod schema stubs to add to the contract. " +
+      "Returns generated code snippets to review — does NOT auto-write files. " +
+      "Copy the output and use the Edit tool to apply the changes.",
     inputSchema: {
       type: "object",
       properties: {
         routeId: {
           type: "string",
-          description: "The route ID to sync",
+          description: "The route ID to sync (must have both contractModule and slotModule)",
         },
         direction: {
           type: "string",
           enum: ["contract-to-slot", "slot-to-contract"],
-          description: "Direction of sync: contract-to-slot adds slot stubs, slot-to-contract adds contract schemas",
+          description:
+            "'contract-to-slot': generate slot handler stubs for undocumented contract methods. " +
+            "'slot-to-contract': generate contract schema stubs for undocumented slot handlers.",
         },
       },
       required: ["routeId", "direction"],
@@ -108,21 +143,25 @@ export const contractToolDefinitions: Tool[] = [
   },
   {
     name: "mandu_generate_openapi",
-    description: "Generate OpenAPI 3.0 specification from contracts",
+    description:
+      "Generate an OpenAPI 3.0 specification JSON file from all routes with contract modules. " +
+      "Only routes with a defined contractModule are included — add contracts with mandu_create_contract first. " +
+      "Output is written to openapi.json (or a custom path). " +
+      "The generated spec can be served with Swagger UI, Redoc, or imported into any OpenAPI-compatible tooling.",
     inputSchema: {
       type: "object",
       properties: {
         output: {
           type: "string",
-          description: "Output file path (default: openapi.json)",
+          description: "Output file path relative to project root (default: openapi.json)",
         },
         title: {
           type: "string",
-          description: "API title (default: Mandu API)",
+          description: "API title shown in the spec (default: 'Mandu API')",
         },
         version: {
           type: "string",
-          description: "API version (default: from manifest)",
+          description: "API version string (default: taken from the manifest version)",
         },
       },
       required: [],

package/src/tools/generate.ts

@@ -8,17 +8,27 @@ export const generateToolDefinitions: Tool[] = [
   {
     name: "mandu_generate",
     description:
-      "Generate route handlers, components, and resource artifacts. Creates server handlers, page components, slot files, and resource CRUD operations.",
+      "Generate all Mandu framework artifacts from the current routes manifest and resource schemas. " +
+      "Runs two generation steps: " +
+      "(1) Route generation: for every route in .mandu/routes.manifest.json, creates " +
+      "a server-side handler in .mandu/generated/server/{routeId}.route.ts and " +
+      "a web component in .mandu/generated/web/{routeId}.route.tsx. " +
+      "These generated files wire up slots and contracts automatically — do NOT edit them directly. " +
+      "Instead, edit source files in app/ (route definition) or spec/ (slots, contracts). " +
+      "(2) Resource generation (resources=true, default): scans spec/resources/{name}/schema.ts " +
+      "and generates CRUD boilerplate (repository, service, handlers) for each declared resource. " +
+      "Run this after adding routes, modifying slot/contract files, or changing resource schemas. " +
+      "Use dryRun=true to preview what would be created or overwritten without writing any files.",
     inputSchema: {
       type: "object",
       properties: {
         dryRun: {
           type: "boolean",
-          description: "If true, show what would be generated without writing files",
+          description: "Preview what would be generated without writing files (default: false)",
         },
         resources: {
           type: "boolean",
-          description: "Include resource artifact generation (default: true)",
+          description: "Include resource artifact generation from spec/resources/ (default: true)",
         },
       },
       required: [],
@@ -26,7 +36,11 @@ export const generateToolDefinitions: Tool[] = [
   },
   {
     name: "mandu_generate_status",
-    description: "Get the current generation status and generated file map",
+    description:
+      "Show the current state of all generated artifacts from .mandu/generated.map.json. " +
+      "Returns: generation timestamp, source spec version, total file count, " +
+      "and a list of generated files per route with their kinds (server handler, web component, slot stub). " +
+      "If no generated.map.json exists, prompts to run mandu_generate first.",
     inputSchema: {
       type: "object",
       properties: {},

package/src/tools/guard.ts

@@ -82,8 +82,8 @@ export const guardToolDefinitions: Tool[] = [
       properties: {
         preset: {
           type: "string",
-          enum: ["fsd", "clean", "hexagonal", "atomic", "mandu"],
-          description: "Architecture preset to use (default: from config or 'mandu')",
+          enum: ["fsd", "clean", "hexagonal", "atomic", "cqrs", "mandu"],
+          description: "Architecture preset to use (default: from config or 'mandu'). Use 'cqrs' for Command/Query separation.",
         },
         autoFix: {
           type: "boolean",
@@ -120,7 +120,7 @@ export const guardToolDefinitions: Tool[] = [
         },
         preset: {
           type: "string",
-          enum: ["fsd", "clean", "hexagonal", "atomic", "mandu"],
+          enum: ["fsd", "clean", "hexagonal", "atomic", "cqrs", "mandu"],
           description: "Architecture preset for context",
         },
       },

package/src/tools/hydration.ts

@@ -28,6 +28,12 @@ export const hydrationToolDefinitions: Tool[] = [
           type: "boolean",
           description: "Generate source maps for debugging",
         },
+        targetRouteIds: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Only rebuild specific islands by routeId. Skips Runtime/Router/Vendor rebuild for faster incremental updates. Omit to rebuild everything.",
+        },
       },
       required: [],
     },
@@ -115,9 +121,10 @@ export function hydrationTools(projectRoot: string) {
 
   return {
     mandu_build: async (args: Record<string, unknown>) => {
-      const { minify, sourcemap } = args as {
+      const { minify, sourcemap, targetRouteIds } = args as {
         minify?: boolean;
         sourcemap?: boolean;
+        targetRouteIds?: string[];
       };
 
       // Load manifest
@@ -130,6 +137,7 @@ export function hydrationTools(projectRoot: string) {
       const result = await buildClientBundles(manifestResult.data, projectRoot, {
         minify,
         sourcemap,
+        targetRouteIds,
       });
 
       return {

package/src/tools/runtime.ts

@@ -1,10 +1,6 @@
 /**
  * Mandu MCP Runtime Tools
- * Runtime 설정 조회 및 관리 도구
- *
- * - Logger 설정 조회/변경
- * - Normalize 설정 조회
- * - Contract 옵션 확인
+ * Query and manage runtime configuration: logger settings and contract normalize options.
  */
 
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
@@ -17,8 +13,10 @@ 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.",
+      "Get the Mandu runtime configuration defaults for logger and normalize settings. " +
+      "Shows default values for every configurable option along with usage examples. " +
+      "Use this to understand the runtime before calling mandu_set_contract_normalize " +
+      "or mandu_generate_logger_config.",
     inputSchema: {
       type: "object",
       properties: {},
@@ -28,8 +26,11 @@ export const runtimeToolDefinitions: Tool[] = [
   {
     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.",
+      "Read the normalize and coerceQueryParams options currently set in a specific contract file. " +
+      "These options control how incoming request data is validated and sanitized: " +
+      "'normalize' removes or blocks undefined fields (Mass Assignment protection), " +
+      "'coerceQueryParams' auto-converts URL query string values to their declared schema types (e.g., '123' → number). " +
+      "Returns the parsed values and their effect, or defaults if no explicit options are set.",
     inputSchema: {
       type: "object",
       properties: {
@@ -44,8 +45,12 @@ export const runtimeToolDefinitions: Tool[] = [
   {
     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).",
+      "Set the normalize mode (and optionally coerceQueryParams) in a route's contract file. " +
+      "Normalize modes: " +
+      "'strip' (default, recommended) — removes any request fields not defined in the schema, preventing Mass Assignment attacks. " +
+      "'strict' — returns HTTP 400 if the request contains any field not defined in the schema. " +
+      "'passthrough' — allows all fields through without filtering (validation only, no sanitization). " +
+      "coerceQueryParams: when true (default), auto-converts query string values to their declared schema types.",
     inputSchema: {
       type: "object",
       properties: {
@@ -57,11 +62,12 @@ export const runtimeToolDefinitions: Tool[] = [
           type: "string",
           enum: ["strip", "strict", "passthrough"],
           description:
-            "Normalize mode: strip (Mass Assignment 방지), strict (에러 발생), passthrough (모두 허용)",
+            "Normalize mode: 'strip' (remove undefined fields, prevents Mass Assignment), " +
+            "'strict' (return 400 on undefined fields), 'passthrough' (allow all fields through)",
         },
         coerceQueryParams: {
           type: "boolean",
-          description: "Whether to auto-convert query string types (default: true)",
+          description: "Auto-convert URL query string values to schema-declared types (default: true)",
         },
       },
       required: ["routeId"],
@@ -70,8 +76,10 @@ export const runtimeToolDefinitions: Tool[] = [
   {
     name: "mandu_list_logger_options",
     description:
-      "List available logger configuration options and their descriptions. " +
-      "Useful for understanding how to configure logging in Mandu.",
+      "List all available logger configuration options with types, defaults, and descriptions. " +
+      "Covers: log format, level, header/body logging (security risk warnings), " +
+      "sampling rate, slow request threshold, redaction fields, custom sink, and skip patterns. " +
+      "Use this as a reference before calling mandu_generate_logger_config.",
     inputSchema: {
       type: "object",
       properties: {},
@@ -81,33 +89,36 @@ export const runtimeToolDefinitions: Tool[] = [
   {
     name: "mandu_generate_logger_config",
     description:
-      "Generate logger configuration code based on requirements. " +
-      "Returns TypeScript code that can be added to the project.",
+      "Generate ready-to-use TypeScript logger configuration code for a specific environment. " +
+      "Returns an import statement and logger() call with environment-appropriate defaults: " +
+      "development: debug level, pretty format, higher verbosity; " +
+      "production: info level, JSON format, 10% sampling, no headers/body. " +
+      "Security note: includeHeaders and includeBody are forced to false in production regardless of input.",
     inputSchema: {
       type: "object",
       properties: {
         environment: {
           type: "string",
           enum: ["development", "production", "testing"],
-          description: "Target environment (default: development)",
+          description: "Target environment — determines default log level, format, and sampling rate (default: development)",
         },
         includeHeaders: {
           type: "boolean",
-          description: "Whether to log request headers (default: false for security)",
+          description: "Log request headers — security risk, only recommended in development (default: false)",
         },
         includeBody: {
           type: "boolean",
-          description: "Whether to log request body (default: false for security)",
+          description: "Log request body — security risk, only recommended in development (default: false)",
         },
         format: {
           type: "string",
           enum: ["pretty", "json"],
-          description: "Log output format (pretty for dev, json for prod)",
+          description: "Log output format: 'pretty' (colored, human-readable) or 'json' (structured, for log aggregators)",
         },
         customRedact: {
           type: "array",
           items: { type: "string" },
-          description: "Additional fields to redact from logs",
+          description: "Additional header or field names to redact/mask from logs",
         },
       },
       required: [],
@@ -160,17 +171,17 @@ export function runtimeTools(projectRoot: string) {
           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",
+            includeHeaders: "⚠️ Security risk if true — logs all request headers including Authorization, Cookie",
+            includeBody: "⚠️ Security risk if true — logs raw request body; may expose PII",
+            maxBodyBytes: "Maximum body bytes to log (truncates larger bodies to avoid log bloat)",
+            sampleRate: "Sampling rate 0.0–1.0 (1.0 = 100% of requests logged)",
+            slowThresholdMs: "Requests exceeding this threshold (ms) are logged at warn level with details",
+            redact: "Header/field names to mask in logs (replaces value with '[REDACTED]')",
           },
           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",
+            mode: "strip: remove undefined fields (prevents Mass Assignment attacks), strict: return 400 on undefined fields, passthrough: allow all fields (validation only)",
+            coerceQueryParams: "Auto-convert URL query string '123' → number 123 based on schema type",
+            deep: "Apply normalization recursively to nested objects",
           },
         },
         usage: {
@@ -242,11 +253,11 @@ export default Mandu.contract({
         },
         explanation: {
           normalize: {
-            strip: "정의되지 않은 필드 제거 (Mass Assignment 공격 방지)",
-            strict: "정의되지 않은 필드 있으면 400 에러",
-            passthrough: "모든 필드 허용 (검증만, 필터링 안 함)",
+            strip: "Removes any request fields not defined in the schema — prevents Mass Assignment attacks (recommended default)",
+            strict: "Returns HTTP 400 if the request contains any field not defined in the schema",
+            passthrough: "Allows all fields through without filtering — validation only, no sanitization",
           },
-          coerceQueryParams: "URL query string은 항상 문자열이므로, 스키마 타입으로 자동 변환",
+          coerceQueryParams: "URL query strings are always plain strings; this option auto-converts them to the declared schema types (e.g., '42' → number, 'true' → boolean)",
         },
       };
     },
@@ -341,10 +352,10 @@ export default Mandu.contract({
         message: `Updated ${route.contractModule}`,
         securityNote:
           normalize === "passthrough"
-            ? "⚠️ passthrough 모드는 Mass Assignment 공격에 취약할 수 있습니다. 신뢰할 수 있는 입력에만 사용하세요."
+            ? "⚠️ passthrough mode may be vulnerable to Mass Assignment attacks. Only use with trusted, fully-validated input."
             : normalize === "strict"
-            ? "strict 모드는 클라이언트가 추가 필드를 보내면 400 에러를 반환합니다."
-            : "strip 모드 (권장): 정의되지 않은 필드는 자동 제거됩니다.",
+            ? "strict mode returns HTTP 400 if the client sends any field not defined in the contract schema."
+            : "strip mode (recommended): fields not defined in the schema are automatically removed from the request.",
       };
     },
 
@@ -355,78 +366,78 @@ export default Mandu.contract({
             name: "format",
             type: '"pretty" | "json"',
             default: "pretty",
-            description: "로그 출력 형식. pretty는 개발용 컬러 출력, json은 운영용 구조화 로그",
+            description: "Log output format: 'pretty' (colored, human-readable for dev) or 'json' (structured, for log aggregators in prod)",
           },
           {
             name: "level",
             type: '"debug" | "info" | "warn" | "error"',
             default: "info",
-            description: "최소 로그 레벨. debug는 모든 요청 상세, error는 에러만",
+            description: "Minimum log level: 'debug' (all requests with details), 'info' (standard), 'warn' (slow/suspicious only), 'error' (errors only)",
           },
           {
             name: "includeHeaders",
             type: "boolean",
             default: false,
-            description: "⚠️ 요청 헤더 로깅. 민감 정보 노출 위험",
+            description: "⚠️ Security risk — logs all request headers including Authorization and Cookie. Only enable in development.",
           },
           {
             name: "includeBody",
             type: "boolean",
             default: false,
-            description: "⚠️ 요청 바디 로깅. 민감 정보 노출 + 스트림 문제",
+            description: "⚠️ Security risk — logs raw request body which may contain PII or credentials. Only enable in development.",
           },
           {
             name: "maxBodyBytes",
             type: "number",
             default: 1024,
-            description: "바디 로깅 시 최대 크기 (초과분 truncate)",
+            description: "Maximum bytes of request body to log (larger bodies are truncated to avoid log bloat)",
           },
           {
             name: "redact",
             type: "string[]",
             default: '["authorization", "cookie", "password", ...]',
-            description: "로그에서 마스킹할 헤더/필드명",
+            description: "Header or field names to mask in logs (values are replaced with '[REDACTED]')",
           },
           {
             name: "requestId",
             type: '"auto" | ((ctx) => string)',
             default: "auto",
-            description: "요청 ID 생성 방식. auto는 UUID 또는 타임스탬프 기반",
+            description: "Request ID generation strategy: 'auto' uses UUID or timestamp-based ID, or provide a custom function",
           },
           {
             name: "sampleRate",
-            type: "number (0-1)",
+            type: "number (0.0–1.0)",
             default: 1,
-            description: "샘플링 비율. 운영에서 로그 양 조절 (0.1 = 10%)",
+            description: "Fraction of requests to log (1.0 = 100%, 0.1 = 10%). Reduce in production to control log volume.",
           },
           {
             name: "slowThresholdMs",
             type: "number",
             default: 1000,
-            description: "느린 요청 임계값. 초과 시 warn 레벨로 상세 출력",
+            description: "Requests exceeding this duration (ms) are logged at warn level with full details",
           },
           {
             name: "includeTraceOnSlow",
             type: "boolean",
             default: true,
-            description: "느린 요청에 Trace 리포트 포함",
+            description: "Include a timing trace report in the log entry for slow requests",
           },
           {
             name: "sink",
             type: "(entry: LogEntry) => void",
             default: "console",
-            description: "커스텀 로그 출력 (Pino, CloudWatch 등 연동)",
+            description: "Custom log output handler — use for integrating with Pino, CloudWatch, Datadog, etc.",
           },
           {
             name: "skip",
             type: "(string | RegExp)[]",
             default: "[]",
-            description: '로깅 제외 경로 패턴. 예: ["/health", /^\\/static\\//]',
+            description: 'URL path patterns to exclude from logging. Example: ["/health", /^\\/static\\//]',
           },
         ],
         presets: {
-          devLogger: "개발용: debug 레벨, pretty 포맷, 헤더 포함",
-          prodLogger: "운영용: info 레벨, json 포맷, 헤더/바디 미포함",
+          devLogger: "Development preset: debug level, pretty format, detailed output",
+          prodLogger: "Production preset: info level, JSON format, no headers/body logging",
         },
       };
     },
@@ -471,10 +482,10 @@ export const appLogger = logger(${JSON.stringify(config, null, 2)});
 
       const warnings: string[] = [];
       if (includeHeaders && isProd) {
-        warnings.push("⚠️ includeHeaders: true는 프로덕션에서 민감 정보 노출 위험이 있습니다.");
+        warnings.push("⚠️ includeHeaders: true in production may expose sensitive Authorization, Cookie, and API key headers in logs.");
       }
       if (includeBody && isProd) {
-        warnings.push("⚠️ includeBody: true는 프로덕션에서 민감 정보 노출 위험이 있습니다.");
+        warnings.push("⚠️ includeBody: true in production may expose PII, passwords, or credentials in logs.");
       }
 
       return {
@@ -483,9 +494,9 @@ export const appLogger = logger(${JSON.stringify(config, null, 2)});
         code,
         warnings: warnings.length > 0 ? warnings : undefined,
         tips: [
-          "devLogger() 또는 prodLogger() 프리셋을 사용할 수도 있습니다.",
-          "sink 옵션으로 Pino, CloudWatch 등 외부 시스템 연동 가능",
-          "skip 옵션으로 /health, /metrics 등 제외 가능",
+          "You can also use the devLogger() or prodLogger() preset helpers for quick setup.",
+          "Use the 'sink' option to integrate with external systems like Pino, CloudWatch, or Datadog.",
+          "Use the 'skip' option to exclude health check and static asset paths (e.g., ['/health', '/metrics']).",
         ],
       };
     },

package/src/tools/slot.ts

@@ -11,13 +11,19 @@ import path from "path";
 export const slotToolDefinitions: Tool[] = [
   {
     name: "mandu_read_slot",
-    description: "Read the contents of a slot file for a specific route",
+    description:
+      "Read the TypeScript source of a route's slot file and validate its structure. " +
+      "In Mandu, a 'slot' is the server-side data loader for a route: " +
+      "it runs on every request before rendering and returns a typed object " +
+      "that is injected into the page component as props (for pages) or as handler context (for API routes). " +
+      "Slot files live at spec/slots/{routeId}.slot.ts and are auto-linked by generateManifest(). " +
+      "Returns the raw source, line count, and any structural validation issues.",
     inputSchema: {
       type: "object",
       properties: {
         routeId: {
           type: "string",
-          description: "The route ID whose slot file to read",
+          description: "The route ID whose slot file to read (use mandu_list_routes to find IDs)",
         },
       },
       required: ["routeId"],
@@ -26,13 +32,21 @@ export const slotToolDefinitions: Tool[] = [
   {
     name: "mandu_validate_slot",
     description:
-      "Validate slot content without writing, get issues and suggestions",
+      "Validate TypeScript slot content against Mandu's structural rules — without writing any files. " +
+      "A valid slot must export a default function (or use the slot() builder) that accepts a Request " +
+      "and returns a plain serializable object (becomes the typed props injected into the page). " +
+      "Returns: " +
+      "errors (must fix before use), " +
+      "warnings (best-practice suggestions), " +
+      "autoFixable issues (with corrected code preview), " +
+      "manualFixRequired items (issues needing human review). " +
+      "Use this before writing a slot file with the Edit tool to catch structural problems early.",
     inputSchema: {
       type: "object",
       properties: {
         content: {
           type: "string",
-          description: "The TypeScript content to validate",
+          description: "The TypeScript slot source code to validate",
         },
       },
       required: ["content"],
@@ -84,7 +98,7 @@ export function slotTools(projectRoot: string) {
 
         const content = await file.text();
 
-        // 기존 슬롯 내용도 검증
+        // Validate existing slot content structure
         const validation = validateSlotContent(content);
 
         return {
@@ -110,11 +124,11 @@ export function slotTools(projectRoot: string) {
 
       const validation = validateSlotContent(content);
 
-      // 자동 수정 가능한 항목 분류
+      // Classify issues by whether they can be auto-fixed
       const autoFixable = validation.issues.filter((i) => i.autoFixable);
       const manualFix = validation.issues.filter((i) => !i.autoFixable);
 
-      // 수정 미리보기 제공
+      // Generate correction preview for auto-fixable issues
       let correctionPreview = null;
       if (autoFixable.length > 0) {
         const correction = correctSlotContent(content, validation.issues);

package/src/tools/spec.ts

@@ -15,7 +15,16 @@ import fs from "fs/promises";
 export const specToolDefinitions: Tool[] = [
   {
     name: "mandu_list_routes",
-    description: "List all routes in the current Mandu project (reads from .mandu/routes.manifest.json)",
+    description:
+      "List all routes registered in the Mandu project, read from .mandu/routes.manifest.json. " +
+      "Route kinds: " +
+      "'api' (REST endpoint — app/**/route.ts, exports named GET/POST/PUT/PATCH/DELETE handler functions), " +
+      "'page' (SSR page — app/**/page.tsx, React component supporting client-side hydration islands). " +
+      "Special files auto-detected by the filesystem router (not user-created routes): " +
+      "layout.tsx (shared wrapper rendered around child routes), " +
+      "error.tsx (error boundary for the route subtree), " +
+      "loading.tsx (suspense fallback shown while page data loads). " +
+      "Each route may have an associated slotModule (server data loader) and contractModule (Zod API schema).",
     inputSchema: {
       type: "object",
       properties: {},
@@ -24,13 +33,17 @@ export const specToolDefinitions: Tool[] = [
   },
   {
     name: "mandu_get_route",
-    description: "Get details of a specific route by ID",
+    description:
+      "Get full details of a specific route by its ID. " +
+      "Returns the complete route spec: kind, URL pattern, module paths (app, slot, contract, component), " +
+      "HTTP methods, and hydration configuration (for page routes with client islands). " +
+      "Use this before modifying a route to understand its current configuration.",
     inputSchema: {
       type: "object",
       properties: {
         routeId: {
           type: "string",
-          description: "The route ID to retrieve",
+          description: "The route ID to retrieve (use mandu_list_routes to see all IDs)",
         },
       },
       required: ["routeId"],
@@ -38,7 +51,15 @@ export const specToolDefinitions: Tool[] = [
   },
   {
     name: "mandu_add_route",
-    description: "Add a new route by scaffolding files in app/ and optionally in spec/slots/ and spec/contracts/",
+    description:
+      "Scaffold a new route by creating source files in app/ and registering it in the manifest. " +
+      "For 'api' routes: creates app/{path}/route.ts with a GET handler stub. " +
+      "For 'page' routes: creates app/{path}/page.tsx with a React component stub. " +
+      "withSlot=true (default): also creates spec/slots/{routeId}.slot.ts — " +
+      "the server-side data loader that runs on every request before rendering and injects typed props into the page. " +
+      "withContract=true: also creates spec/contracts/{routeId}.contract.ts — " +
+      "Zod schemas for request/response validation, enabling typed handlers, OpenAPI generation, and ATE L2/L3 testing. " +
+      "Automatically runs generateManifest() after creation to link all files.",
     inputSchema: {
       type: "object",
       properties: {
@@ -49,15 +70,15 @@ export const specToolDefinitions: Tool[] = [
         kind: {
           type: "string",
           enum: ["api", "page"],
-          description: "Route type: api (route.ts) or page (page.tsx)",
+          description: "Route type: 'api' creates route.ts with HTTP handlers, 'page' creates page.tsx with a React component",
         },
         withSlot: {
           type: "boolean",
-          description: "Scaffold a slot file in spec/slots/ (default: true)",
+          description: "Also scaffold a server-side data loader at spec/slots/{routeId}.slot.ts (default: true)",
         },
         withContract: {
           type: "boolean",
-          description: "Scaffold a contract file in spec/contracts/",
+          description: "Also scaffold a Zod contract at spec/contracts/{routeId}.contract.ts (default: false)",
         },
       },
       required: ["path", "kind"],
@@ -65,13 +86,18 @@ export const specToolDefinitions: Tool[] = [
   },
   {
     name: "mandu_delete_route",
-    description: "Delete a route's app/ files and rescan (preserves slot/contract files)",
+    description:
+      "Delete a route's app/ source file and regenerate the manifest. " +
+      "Only removes the app/{path}/route.ts or page.tsx file — " +
+      "slot files (spec/slots/) and contract files (spec/contracts/) are intentionally preserved, " +
+      "as they may be reused when the route is recreated. " +
+      "Use mandu_list_routes before deleting to confirm the correct routeId.",
     inputSchema: {
       type: "object",
       properties: {
         routeId: {
           type: "string",
-          description: "The route ID to delete",
+          description: "The route ID to delete (use mandu_list_routes to find it)",
         },
       },
       required: ["routeId"],
@@ -79,7 +105,10 @@ export const specToolDefinitions: Tool[] = [
   },
   {
     name: "mandu_validate_manifest",
-    description: "Validate the current routes manifest (.mandu/routes.manifest.json)",
+    description:
+      "Validate the routes manifest (.mandu/routes.manifest.json) for structural integrity. " +
+      "Checks required fields, valid route kinds, correct module paths, and manifest schema version. " +
+      "Run this after manual manifest edits, after upgrading Mandu, or when routes behave unexpectedly.",
     inputSchema: {
       type: "object",
       properties: {},