@mandujs/mcp 0.18.8 → 0.18.10

package/src/index.ts

@@ -83,6 +83,14 @@ export {
   getToolsSummary,
 } from "./tools/index.js";
 
+// Profile exports
+export {
+  type McpProfile,
+  PROFILE_CATEGORIES,
+  getProfileCategories,
+  isValidProfile,
+} from "./profiles.js";
+
 // CLI entry point
 import { startServer } from "./server.js";
 import path from "path";

package/src/new-resources.ts

@@ -0,0 +1,119 @@
+/**
+ * MCP Resources for Mandu Framework
+ *
+ * Project state data exposed via the MCP resource protocol.
+ */
+
+import type { Resource } from "@modelcontextprotocol/sdk/types.js";
+import path from "path";
+import { readConfig, readJsonFile } from "./utils/project.js";
+import { loadManduConfig, loadManifest } from "@mandujs/core";
+import { getDevServerState } from "./tools/project.js";
+
+export const manduResourceDefinitions: Resource[] = [
+  {
+    uri: "mandu://routes",
+    name: "Route Manifest",
+    description: "Current project route manifest (JSON)",
+    mimeType: "application/json",
+  },
+  {
+    uri: "mandu://config",
+    name: "Mandu Config",
+    description: "Parsed mandu.config.ts settings",
+    mimeType: "application/json",
+  },
+  {
+    uri: "mandu://errors",
+    name: "Recent Errors",
+    description: "Recent build and runtime errors",
+    mimeType: "application/json",
+  },
+];
+
+type ResourceReadResult = { uri: string; mimeType: string; text: string };
+type ResourceHandler = () => Promise<ResourceReadResult>;
+
+function jsonResult(uri: string, data: unknown): ResourceReadResult {
+  return { uri, mimeType: "application/json", text: JSON.stringify(data, null, 2) };
+}
+
+export function manduResourceHandlers(projectRoot: string): Record<string, ResourceHandler> {
+  const manifestPath = path.join(projectRoot, ".mandu", "routes.manifest.json");
+
+  return {
+    "mandu://routes": async () => {
+      const result = await loadManifest(manifestPath);
+      if (!result.success || !result.data) {
+        return jsonResult("mandu://routes", {
+          error: "Failed to load route manifest",
+          details: result.errors,
+          hint: "Run 'mandu generate' or 'mandu dev' to create the manifest.",
+        });
+      }
+      return jsonResult("mandu://routes", {
+        version: result.data.version,
+        routeCount: result.data.routes.length,
+        routes: result.data.routes.map((r) => ({
+          id: r.id, pattern: r.pattern, kind: r.kind, module: r.module,
+          slotModule: r.slotModule ?? null, clientModule: r.clientModule ?? null,
+        })),
+      });
+    },
+
+    "mandu://config": async () => {
+      try {
+        const config = await loadManduConfig(projectRoot);
+        return jsonResult("mandu://config", {
+          server: config.server ?? {},
+          guard: config.guard ?? {},
+          build: config.build ?? {},
+          dev: config.dev ?? {},
+          fsRoutes: config.fsRoutes ?? {},
+          seo: config.seo ?? {},
+        });
+      } catch {
+        const raw = await readConfig(projectRoot);
+        return jsonResult("mandu://config", raw ?? {
+          error: "No mandu.config.ts/js/json found",
+          hint: "Create a mandu.config.ts in the project root.",
+        });
+      }
+    },
+
+    "mandu://errors": async () => {
+      const errors: unknown[] = [];
+
+      // Try Kitchen DevTools error log from running dev server
+      let port: number | undefined;
+      const serverState = getDevServerState();
+      if (serverState) {
+        for (const line of serverState.output) {
+          const m = line.match(/https?:\/\/localhost:(\d+)/);
+          if (m) port = parseInt(m[1], 10);
+        }
+      }
+      if (port) {
+        try {
+          const res = await fetch(`http://localhost:${port}/__kitchen/api/errors`);
+          if (res.ok) {
+            const body = (await res.json()) as { errors: unknown[] };
+            if (body.errors?.length) errors.push(...body.errors);
+          }
+        } catch { /* dev server not reachable */ }
+      }
+
+      // Read local error log file
+      const loggedErrors = await readJsonFile<unknown[]>(
+        path.join(projectRoot, ".mandu", "errors.json"),
+      );
+      if (Array.isArray(loggedErrors)) errors.push(...loggedErrors);
+
+      return jsonResult("mandu://errors", {
+        count: errors.length,
+        errors,
+        source: port ? "kitchen+log" : "log",
+      });
+    },
+  };
+}

package/src/profiles.ts

@@ -0,0 +1,34 @@
+/**
+ * MCP Tool Profiles
+ *
+ * Controls how many tool categories are exposed to AI agents.
+ * - minimal: Core scaffolding tools only (~15 tools)
+ * - standard: Common development workflow (~40 tools)
+ * - full: All categories, no filtering (default)
+ */
+
+export type McpProfile = "minimal" | "standard" | "full";
+
+export const PROFILE_CATEGORIES: Record<McpProfile, string[] | null> = {
+  minimal: ["spec", "project", "guard", "generate"],
+  standard: [
+    "spec", "project", "guard", "generate",
+    "contract", "slot", "hydration", "seo",
+    "component", "kitchen", "composite",
+  ],
+  full: null,
+};
+
+/**
+ * Returns allowed category names for a profile, or null if all categories are allowed.
+ */
+export function getProfileCategories(profile: McpProfile): string[] | null {
+  return PROFILE_CATEGORIES[profile] ?? null;
+}
+
+/**
+ * Type guard for valid profile strings.
+ */
+export function isValidProfile(value: string): value is McpProfile {
+  return value === "minimal" || value === "standard" || value === "full";
+}

package/src/prompts.ts

@@ -0,0 +1,104 @@
+/**
+ * MCP Prompts for Mandu Framework
+ *
+ * Conversation templates that guide agents through common Mandu workflows.
+ */
+
+import type { Prompt, GetPromptResult } from "@modelcontextprotocol/sdk/types.js";
+
+export const manduPrompts: Prompt[] = [
+  {
+    name: "new-feature",
+    description: "Guide creating a new feature with routes, contracts, and islands",
+    arguments: [
+      { name: "description", description: "Feature description", required: true },
+    ],
+  },
+  {
+    name: "debug",
+    description: "Diagnose and fix errors in the Mandu project",
+    arguments: [
+      { name: "symptom", description: "Error message or symptom", required: false },
+    ],
+  },
+  {
+    name: "add-crud",
+    description: "Create a complete CRUD API with contracts and tests",
+    arguments: [
+      { name: "resource", description: "Resource name (e.g., 'products')", required: true },
+    ],
+  },
+];
+
+function msg(text: string): GetPromptResult {
+  return { messages: [{ role: "user", content: { type: "text", text } }] };
+}
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+type PromptHandler = (args: Record<string, string>) => GetPromptResult;
+
+const promptHandlers: Record<string, PromptHandler> = {
+  "new-feature": (args) => msg(`Create a new feature: ${args.description}
+
+Follow these steps using Mandu MCP tools:
+
+1. Read current route manifest: Resource mandu://routes
+2. Read project config: Resource mandu://config
+3. Negotiate the feature spec: Tool mandu.negotiate
+4. Generate scaffold: Tool mandu.negotiate.scaffold
+5. If client interactivity needed, create island: Tool mandu_create_island
+   Use the declarative pattern: island('visible', Component)
+6. If data requirements exist, create slot: Tool mandu_create_slot
+   Slots are server-side data loaders that run before render
+7. If API is exposed, define contract: Tool mandu_create_contract
+   Contracts are Zod schemas for validation and OpenAPI generation
+8. Validate architecture: Tool mandu_guard_check
+9. Run brain doctor: Tool mandu_brain_diagnose`),
+
+  "debug": (args) => msg(`${args.symptom ? `Diagnose this error: ${args.symptom}` : "Diagnose errors in the Mandu project"}
+
+Follow these diagnostic steps using Mandu MCP tools:
+
+1. Check client-side errors: Tool mandu.kitchen.errors
+2. Check recent build/runtime errors: Resource mandu://errors
+3. Check architecture rule violations: Resource mandu://watch/warnings
+4. Run brain doctor for structural analysis: Tool mandu_brain_diagnose
+5. Verify route manifest: Resource mandu://routes
+6. Inspect specific route slot: Resource mandu://slots/{routeId}
+7. Run guard check: Tool mandu_guard_check
+
+After identifying root cause, fix and re-run checks to confirm.`),
+
+  "add-crud": (args) => {
+    const r = args.resource;
+    const R = capitalize(r);
+    return msg(`Create a complete CRUD API for the '${r}' resource.
+
+Follow these steps using Mandu MCP tools:
+
+1. Read project config: Resource mandu://config
+2. Create API routes: Tool mandu.negotiate
+   - GET/POST for /api/${r}, GET/PUT/DELETE for /api/${r}/[id]
+3. Define contracts: Tool mandu_create_contract
+   - Create${R}Schema, Update${R}Schema, ${R}ResponseSchema
+4. Generate scaffold: Tool mandu.negotiate.scaffold
+5. Create data slot for list page: Tool mandu_create_slot
+6. Validate: Tool mandu_guard_check + Tool mandu_brain_diagnose
+7. Verify routes: Resource mandu://routes`);
+  },
+};
+
+/**
+ * Get the prompt handler result for a given prompt name and arguments.
+ */
+export function getPromptResult(
+  name: string,
+  args: Record<string, string>,
+): GetPromptResult | null {
+  const handler = promptHandlers[name];
+  if (!handler) return null;
+  return handler(args);
+}

package/src/resources/handlers.ts

@@ -4,7 +4,6 @@ import {
   getTransactionStatus,
   getWatcher,
   type GeneratedMap,
-  type SpecLock,
 } from "@mandujs/core";
 import { getProjectPaths, readJsonFile } from "../utils/project.js";
 import {
@@ -26,12 +25,6 @@ export const resourceDefinitions: Resource[] = [
     description: "Current routes.manifest.json content",
     mimeType: "application/json",
   },
-  {
-    uri: "mandu://spec/lock",
-    name: "Spec Lock",
-    description: "Current spec.lock.json with hash verification",
-    mimeType: "application/json",
-  },
   {
     uri: "mandu://generated/map",
     name: "Generated Map",
@@ -181,22 +174,6 @@ export function resourceHandlers(
       };
     },
 
-    "mandu://spec/lock": async () => {
-      const lock = await readJsonFile<SpecLock>(paths.lockPath);
-      if (!lock) {
-        return {
-          exists: false,
-          message: "spec.lock.json not found",
-        };
-      }
-
-      return {
-        exists: true,
-        routesHash: lock.routesHash,
-        updatedAt: lock.updatedAt,
-      };
-    },
-
     "mandu://generated/map": async () => {
       const generatedMap = await readJsonFile<GeneratedMap>(paths.generatedMapPath);
       if (!generatedMap) {

package/src/server.ts

@@ -16,6 +16,8 @@ import {
   ListToolsRequestSchema,
   ListResourcesRequestSchema,
   ReadResourceRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
   type CallToolResult,
 } from "@modelcontextprotocol/sdk/types.js";
 
@@ -38,11 +40,18 @@ import { mcpHookRegistry, registerDefaultMcpHooks, type McpToolContext } from ".
 // DNA-006: 설정 핫 리로드
 import { startMcpConfigWatcher, type McpConfigWatcher } from "./hooks/config-watcher.js";
 
+// Prompts
+import { manduPrompts, getPromptResult } from "./prompts.js";
+
+// New top-level resources
+import { manduResourceDefinitions, manduResourceHandlers } from "./new-resources.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 { type McpProfile, isValidProfile } from "./profiles.js";
 
 /**
  * MCP 서버 버전
@@ -61,11 +70,16 @@ export class ManduMcpServer {
   private config?: ManduConfig;
   private configWatcher?: McpConfigWatcher;
   private toolExecutor: ToolExecutor;
+  private profile: McpProfile;
 
   constructor(projectRoot: string) {
     this.projectRoot = projectRoot;
     this.monitor = new ActivityMonitor(projectRoot);
 
+    // Resolve profile from environment variable (default: "full")
+    const envProfile = process.env.MANDU_MCP_PROFILE ?? "full";
+    this.profile = isValidProfile(envProfile) ? envProfile : "full";
+
     // MCP Server 초기화
     this.server = new Server(
       {
@@ -76,13 +90,16 @@ export class ManduMcpServer {
         capabilities: {
           tools: {},
           resources: {},
+          prompts: {},
           logging: {},
         },
       }
     );
 
     // DNA-001: 플러그인 기반 도구 등록
-    registerBuiltinTools(projectRoot, this.server, this.monitor);
+    registerBuiltinTools(projectRoot, this.server, this.monitor, {
+      profile: this.profile,
+    });
 
     // DNA-008: 로깅 통합
     setupMcpLogging({ consoleOutput: false });
@@ -100,6 +117,7 @@ export class ManduMcpServer {
     // 핸들러 등록
     this.registerToolHandlers();
     this.registerResourceHandlers();
+    this.registerPromptHandlers();
   }
 
   /**
@@ -124,21 +142,75 @@ export class ManduMcpServer {
     });
   }
 
+  /**
+   * Prompt handler registration
+   */
+  private registerPromptHandlers(): void {
+    this.server.setRequestHandler(ListPromptsRequestSchema, async () => {
+      return { prompts: manduPrompts };
+    });
+
+    this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+      const result = getPromptResult(name, args ?? {});
+
+      if (!result) {
+        return {
+          messages: [
+            {
+              role: "user" as const,
+              content: {
+                type: "text" as const,
+                text: `Unknown prompt: ${name}. Available prompts: ${manduPrompts.map((p) => p.name).join(", ")}`,
+              },
+            },
+          ],
+        };
+      }
+
+      return result;
+    });
+  }
+
   /**
    * 리소스 핸들러 등록 (기존 유지)
    */
   private registerResourceHandlers(): void {
     const handlers = resourceHandlers(this.projectRoot);
+    const newHandlers = manduResourceHandlers(this.projectRoot);
+
+    // Merge resource definitions (new top-level + existing)
+    const allResources = [...manduResourceDefinitions, ...resourceDefinitions];
 
     this.server.setRequestHandler(ListResourcesRequestSchema, async () => {
-      return {
-        resources: resourceDefinitions,
-      };
+      return { resources: allResources };
     });
 
     this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
       const { uri } = request.params;
 
+      // Check new top-level resource handlers first
+      const newHandler = newHandlers[uri];
+      if (newHandler) {
+        try {
+          const result = await newHandler();
+          return { contents: [result] };
+        } catch (error) {
+          return {
+            contents: [
+              {
+                uri,
+                mimeType: "application/json",
+                text: JSON.stringify({
+                  error: error instanceof Error ? error.message : String(error),
+                }),
+              },
+            ],
+          };
+        }
+      }
+
+      // Fall through to existing resource handlers
       const handler = handlers[uri];
       if (!handler) {
         // 동적 리소스 패턴 매칭
@@ -244,7 +316,7 @@ export class ManduMcpServer {
           warning.message
         );
 
-        // Claude Code에 알림
+        // MCP 클라이언트에 알림
         this.server.sendLoggingMessage({
           level: "warning",
           logger: "mandu-watch",
@@ -270,6 +342,7 @@ export class ManduMcpServer {
     const summary = getToolsSummary();
     console.error(`Mandu MCP Server v${MCP_VERSION} running`);
     console.error(`  Project: ${this.projectRoot}`);
+    console.error(`  Profile: ${this.profile}`);
     console.error(`  Tools: ${summary.total} (${summary.categories.join(", ")})`);
   }
 

package/src/tools/ate.ts

@@ -15,6 +15,9 @@ import type { OracleLevel } from "@mandujs/ate";
 export const ateToolDefinitions: Tool[] = [
   {
     name: "mandu.ate.extract",
+    annotations: {
+      readOnlyHint: false,
+    },
     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. " +
@@ -39,6 +42,9 @@ export const ateToolDefinitions: Tool[] = [
   },
   {
     name: "mandu.ate.generate",
+    annotations: {
+      readOnlyHint: false,
+    },
     description:
       "ATE Step 2 — Generate: Create Playwright test scenarios from the interaction graph produced by mandu.ate.extract. " +
       "Oracle level controls assertion depth: " +
@@ -67,6 +73,9 @@ export const ateToolDefinitions: Tool[] = [
   },
   {
     name: "mandu.ate.run",
+    annotations: {
+      readOnlyHint: false,
+    },
     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}/. " +
@@ -93,6 +102,9 @@ export const ateToolDefinitions: Tool[] = [
   },
   {
     name: "mandu.ate.report",
+    annotations: {
+      readOnlyHint: true,
+    },
     description:
       "ATE Step 4 — Report: Generate a test report from run artifacts. " +
       "Produces pass/fail summary, coverage by route, and failure details. " +
@@ -132,6 +144,9 @@ export const ateToolDefinitions: Tool[] = [
   },
   {
     name: "mandu.ate.heal",
+    annotations: {
+      readOnlyHint: true,
+    },
     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.) " +
@@ -149,6 +164,9 @@ export const ateToolDefinitions: Tool[] = [
   },
   {
     name: "mandu.ate.impact",
+    annotations: {
+      readOnlyHint: true,
+    },
     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. " +
@@ -166,6 +184,9 @@ export const ateToolDefinitions: Tool[] = [
   },
   {
     name: "mandu.ate.auto_pipeline",
+    annotations: {
+      readOnlyHint: false,
+    },
     description:
       "ATE Full Pipeline — Run the complete ATE cycle in one call: " +
       "Extract AST → Generate Playwright specs → Run tests → Create report → Suggest heals. " +
@@ -202,6 +223,9 @@ export const ateToolDefinitions: Tool[] = [
   },
   {
     name: "mandu.ate.feedback",
+    annotations: {
+      readOnlyHint: true,
+    },
     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). " +
@@ -222,6 +246,10 @@ export const ateToolDefinitions: Tool[] = [
   },
   {
     name: "mandu.ate.apply_heal",
+    annotations: {
+      destructiveHint: true,
+      readOnlyHint: false,
+    },
     description:
       "ATE Apply — Apply a specific heal suggestion diff to the codebase. " +
       "Always creates a backup snapshot first (use mandu_rollback to undo). " +