@mandujs/mcp 0.18.9 → 0.18.10

package/README.md

@@ -185,7 +185,6 @@ bunx @mandujs/mcp --root /path/to/project
 | URI | Description |
 |-----|-------------|
 | `mandu://spec/manifest` | Current routes.manifest.json |
-| `mandu://spec/lock` | Current spec.lock.json with hash |
 | `mandu://generated/map` | Generated files mapping |
 | `mandu://transaction/active` | Active transaction state |
 | `mandu://slots/{routeId}` | Slot file content by route ID |

package/package.json

@@ -1,42 +1,42 @@
-{
-  "name": "@mandujs/mcp",
-  "version": "0.18.9",
-  "description": "Mandu MCP Server - Agent-native interface for Mandu framework operations",
-  "type": "module",
-  "main": "./src/index.ts",
-  "bin": {
-    "mandu-mcp": "./src/index.ts"
-  },
-  "exports": {
-    ".": "./src/index.ts"
-  },
-  "files": [
-    "src/**/*"
-  ],
-  "keywords": [
-    "mandu",
-    "mcp",
-    "model-context-protocol",
-    "ai",
-    "agent",
-    "code-generation"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/konamgil/mandu.git",
-    "directory": "packages/mcp"
-  },
-  "author": "konamgil",
-  "license": "MPL-2.0",
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "@mandujs/core": "^0.19.0",
-    "@mandujs/ate": "^0.17.2",
-    "@modelcontextprotocol/sdk": "^1.25.3"
-  },
-  "engines": {
-    "bun": ">=1.0.0"
-  }
-}
+{
+  "name": "@mandujs/mcp",
+  "version": "0.18.10",
+  "description": "Mandu MCP Server - Agent-native interface for Mandu framework operations",
+  "type": "module",
+  "main": "./src/index.ts",
+  "bin": {
+    "mandu-mcp": "./src/index.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src/**/*"
+  ],
+  "keywords": [
+    "mandu",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "agent",
+    "code-generation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/konamgil/mandu.git",
+    "directory": "packages/mcp"
+  },
+  "author": "konamgil",
+  "license": "MPL-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@mandujs/core": "^0.19.1",
+    "@mandujs/ate": "^0.17.2",
+    "@modelcontextprotocol/sdk": "^1.25.3"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}

package/src/activity-monitor.ts

@@ -18,14 +18,14 @@ const TOOL_ICONS: Record<string, string> = {
   mandu_delete_route: "SPEC-",
   mandu_validate_manifest: "SPEC?",
   // Generate
-  mandu_generate: "GEN",
-  mandu_generate_status: "GEN?",
+  "mandu.generate": "GEN",
+  "mandu.generate.status": "GEN?",
   // Guard
   mandu_guard_check: "GUARD",
   // Slot
-  mandu_read_slot: "SLOT",
+  "mandu.slot.read": "SLOT",
   mandu_write_slot: "SLOT~",
-  mandu_validate_slot: "SLOT?",
+  "mandu.slot.validate": "SLOT?",
   // Contract
   mandu_list_contracts: "CONTRACT",
   mandu_get_contract: "CONTRACT",
@@ -281,7 +281,10 @@ export class ActivityMonitor {
     this.projectRoot = projectRoot;
     const userConfig = loadMonitorConfig(projectRoot);
     this.config = mergeConfig(DEFAULT_CONFIG, userConfig);
-    this.outputFormat = resolveOutputFormat(this.config.output);
+    // When openTerminal is enabled, force pretty format for human-readable terminal output
+    this.outputFormat = this.config.openTerminal
+      ? "pretty"
+      : resolveOutputFormat(this.config.output);
   }
 
   start(): void {
@@ -327,9 +330,7 @@ export class ActivityMonitor {
       );
     }
 
-    const openTerminal =
-      this.config.openTerminal && this.outputFormat === "pretty";
-    if (openTerminal) {
+    if (this.config.openTerminal) {
       this.openTerminal();
     }
   }

package/src/adapters/tool-adapter.ts

@@ -26,6 +26,7 @@ export function toolToPlugin(
     name: definition.name,
     description: definition.description ?? "",
     inputSchema: definition.inputSchema as unknown as Record<string, unknown>,
+    ...(definition.annotations && { annotations: definition.annotations as unknown as Record<string, unknown> }),
     execute: handler as (input: unknown) => Promise<unknown>,
   };
 }
@@ -38,6 +39,7 @@ export function pluginToTool(plugin: McpToolPlugin): Tool {
     name: plugin.name,
     description: plugin.description,
     inputSchema: plugin.inputSchema as Tool["inputSchema"],
+    ...(plugin.annotations && { annotations: plugin.annotations as Tool["annotations"] }),
   };
 }
 

package/src/executor/error-handler.ts

@@ -1,250 +1,268 @@
-/**
- * MCP Error Handler
- *
- * DNA-007 에러 추출 시스템 기반 MCP 에러 처리
- */
-
-import {
-  extractErrorInfo,
-  classifyError,
-  serializeError,
-  isRetryableError,
-  type ErrorCategory,
-  type ExtractedErrorInfo,
-} from "@mandujs/core";
-
-/**
- * MCP 에러 응답 타입
- */
-export interface McpErrorResponse {
-  /** 에러 메시지 */
-  error: string;
-  /** 에러 코드 (있는 경우) */
-  code?: string;
-  /** 에러 카테고리 (DNA-007) */
-  category: ErrorCategory;
-  /** 재시도 가능 여부 */
-  retryable: boolean;
-  /** 추가 컨텍스트 */
-  context?: Record<string, unknown>;
-  /** 복구 제안 */
-  suggestion?: string;
-}
-
-/**
- * MCP 도구 응답 타입
- */
-export interface McpToolResponse {
-  content: Array<{ type: string; text: string }>;
-  isError?: boolean;
-}
-
-/**
- * 에러를 MCP 응답 형식으로 변환
- *
- * @example
- * ```ts
- * try {
- *   await tool.execute(args);
- * } catch (err) {
- *   const response = formatMcpError(err, "mandu_guard_check");
- *   // { error: "...", code: "...", category: "validation", ... }
- * }
- * ```
- */
-export function formatMcpError(err: unknown, toolName?: string): McpErrorResponse {
-  const info = extractErrorInfo(err);
-
-  return {
-    error: info.message,
-    code: info.code,
-    category: info.category,
-    retryable: isRetryableError(err),
-    context: {
-      ...info.context,
-      toolName,
-      errorName: info.name,
-    },
-    suggestion: generateSuggestion(info, toolName),
-  };
-}
-
-/**
- * 에러 카테고리 및 도구별 복구 제안 생성
- */
-function generateSuggestion(info: ExtractedErrorInfo, toolName?: string): string | undefined {
-  // 도구별 특화 제안
-  if (toolName) {
-    const toolSuggestion = getToolSpecificSuggestion(toolName, info);
-    if (toolSuggestion) return toolSuggestion;
-  }
-
-  // 카테고리별 일반 제안
-  switch (info.category) {
-    case "network":
-      return "네트워크 연결을 확인하고 다시 시도해주세요.";
-
-    case "timeout":
-      return "요청 시간이 초과되었습니다. 잠시 후 다시 시도해주세요.";
-
-    case "auth":
-      return "인증 정보를 확인해주세요.";
-
-    case "validation":
-      return "입력 값을 확인해주세요. 필수 파라미터가 누락되었거나 형식이 올바르지 않을 수 있습니다.";
-
-    case "config":
-      return "설정 파일(mandu.config.ts)을 확인해주세요.";
-
-    case "system":
-      if (info.code === "ENOENT") {
-        const path = info.context?.path ?? "unknown";
-        return `파일 또는 디렉토리를 찾을 수 없습니다: ${path}`;
-      }
-      if (info.code === "EACCES" || info.code === "EPERM") {
-        return "파일 접근 권한을 확인해주세요.";
-      }
-      return "시스템 리소스를 확인해주세요.";
-
-    case "external":
-      return "외부 서비스에 문제가 있습니다. 잠시 후 다시 시도해주세요.";
-
-    case "internal":
-      return "내부 오류가 발생했습니다. 문제가 지속되면 이슈를 보고해주세요.";
-
-    default:
-      return undefined;
-  }
-}
-
-/**
- * 도구별 특화된 에러 제안
- */
-function getToolSpecificSuggestion(toolName: string, info: ExtractedErrorInfo): string | undefined {
-  // spec 관련 도구
-  if (toolName.startsWith("mandu_") && toolName.includes("route")) {
-    if (info.code === "ENOENT") {
-      return "routes.manifest.json 파일이 없습니다. `mandu init`을 먼저 실행해주세요.";
-    }
-    if (info.message.includes("not found")) {
-      return "해당 라우트를 찾을 수 없습니다. `mandu_list_routes`로 존재하는 라우트를 확인해주세요.";
-    }
-  }
-
-  // guard 관련 도구
-  if (toolName === "mandu_guard_check") {
-    if (info.category === "config") {
-      return "Guard 설정을 확인해주세요. mandu.config.ts의 guard 섹션을 검토해주세요.";
-    }
-  }
-
-  // contract 관련 도구
-  if (toolName.includes("contract")) {
-    if (info.category === "validation") {
-      return "Contract 스키마가 올바른지 확인해주세요. Zod 스키마 문법을 확인해주세요.";
-    }
-  }
-
-  // generate 관련 도구
-  if (toolName === "mandu_generate") {
-    if (info.code === "EEXIST") {
-      return "파일이 이미 존재합니다. 덮어쓰려면 force 옵션을 사용해주세요.";
-    }
-  }
-
-  // transaction 관련 도구
-  if (toolName.includes("tx") || toolName.includes("transaction")) {
-    if (info.message.includes("no active")) {
-      return "활성화된 트랜잭션이 없습니다. `mandu_begin`으로 트랜잭션을 시작해주세요.";
-    }
-  }
-
-  return undefined;
-}
-
-/**
- * 도구 실행 결과를 MCP 응답으로 변환
- *
- * @example
- * ```ts
- * // 성공 응답
- * const response = createToolResponse("mandu_list_routes", { routes: [...] });
- *
- * // 에러 응답
- * const response = createToolResponse("mandu_list_routes", null, new Error("..."));
- * ```
- */
-export function createToolResponse(
-  toolName: string,
-  result: unknown,
-  error?: unknown
-): McpToolResponse {
-  if (error) {
-    const errorResponse = formatMcpError(error, toolName);
-    return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify(errorResponse, null, 2),
-        },
-      ],
-      isError: true,
-    };
-  }
-
-  return {
-    content: [
-      {
-        type: "text",
-        text: JSON.stringify(result, null, 2),
-      },
-    ],
-  };
-}
-
-/**
- * 에러 응답인지 확인
- */
-export function isErrorResponse(response: McpToolResponse): boolean {
-  return response.isError === true;
-}
-
-/**
- * 에러 응답에서 McpErrorResponse 추출
- */
-export function extractErrorFromResponse(response: McpToolResponse): McpErrorResponse | null {
-  if (!response.isError) return null;
-
-  try {
-    const text = response.content[0]?.text;
-    if (!text) return null;
-    return JSON.parse(text) as McpErrorResponse;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * 에러 로깅 헬퍼
- */
-export function logToolError(
-  toolName: string,
-  error: unknown,
-  args?: Record<string, unknown>
-): void {
-  const info = extractErrorInfo(error);
-
-  console.error(`[MCP:${toolName}] ${info.category.toUpperCase()}: ${info.message}`);
-
-  if (info.code) {
-    console.error(`  Code: ${info.code}`);
-  }
-
-  if (args && Object.keys(args).length > 0) {
-    console.error(`  Args:`, JSON.stringify(args, null, 2));
-  }
-
-  if (info.context && Object.keys(info.context).length > 0) {
-    console.error(`  Context:`, info.context);
-  }
-}
+/**
+ * MCP Error Handler
+ *
+ * DNA-007 에러 추출 시스템 기반 MCP 에러 처리
+ */
+
+import {
+  extractErrorInfo,
+  classifyError,
+  serializeError,
+  isRetryableError,
+  type ErrorCategory,
+  type ExtractedErrorInfo,
+} from "@mandujs/core";
+
+/**
+ * MCP 에러 응답 타입
+ */
+export interface McpErrorResponse {
+  /** 에러 메시지 */
+  error: string;
+  /** 에러 코드 (있는 경우) */
+  code?: string;
+  /** 에러 카테고리 (DNA-007) */
+  category: ErrorCategory;
+  /** 재시도 가능 여부 */
+  retryable: boolean;
+  /** 추가 컨텍스트 */
+  context?: Record<string, unknown>;
+  /** 복구 제안 */
+  suggestion?: string;
+}
+
+/**
+ * MCP 도구 응답 타입
+ */
+export interface McpToolResponse {
+  content: Array<{ type: string; text: string }>;
+  isError?: boolean;
+}
+
+/**
+ * 에러를 MCP 응답 형식으로 변환
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await tool.execute(args);
+ * } catch (err) {
+ *   const response = formatMcpError(err, "mandu_guard_check");
+ *   // { error: "...", code: "...", category: "validation", ... }
+ * }
+ * ```
+ */
+export function formatMcpError(err: unknown, toolName?: string): McpErrorResponse {
+  const info = extractErrorInfo(err);
+
+  return {
+    error: info.message,
+    code: info.code,
+    category: info.category,
+    retryable: isRetryableError(err),
+    context: {
+      ...info.context,
+      toolName,
+      errorName: info.name,
+    },
+    suggestion: generateSuggestion(info, toolName),
+  };
+}
+
+/**
+ * 에러 카테고리 및 도구별 복구 제안 생성
+ */
+function generateSuggestion(info: ExtractedErrorInfo, toolName?: string): string | undefined {
+  // 도구별 특화 제안
+  if (toolName) {
+    const toolSuggestion = getToolSpecificSuggestion(toolName, info);
+    if (toolSuggestion) return toolSuggestion;
+  }
+
+  // 카테고리별 일반 제안
+  switch (info.category) {
+    case "network":
+      return "네트워크 연결을 확인하고 다시 시도해주세요.";
+
+    case "timeout":
+      return "요청 시간이 초과되었습니다. 잠시 후 다시 시도해주세요.";
+
+    case "auth":
+      return "인증 정보를 확인해주세요.";
+
+    case "validation":
+      return "입력 값을 확인해주세요. 필수 파라미터가 누락되었거나 형식이 올바르지 않을 수 있습니다.";
+
+    case "config":
+      return "설정 파일(mandu.config.ts)을 확인해주세요.";
+
+    case "system":
+      if (info.code === "ENOENT") {
+        const path = info.context?.path ?? "unknown";
+        return `파일 또는 디렉토리를 찾을 수 없습니다: ${path}`;
+      }
+      if (info.code === "EACCES" || info.code === "EPERM") {
+        return "파일 접근 권한을 확인해주세요.";
+      }
+      return "시스템 리소스를 확인해주세요.";
+
+    case "external":
+      return "외부 서비스에 문제가 있습니다. 잠시 후 다시 시도해주세요.";
+
+    case "internal":
+      return "내부 오류가 발생했습니다. 문제가 지속되면 이슈를 보고해주세요.";
+
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * 도구별 특화된 에러 제안
+ */
+function getToolSpecificSuggestion(toolName: string, info: ExtractedErrorInfo): string | undefined {
+  // spec 관련 도구
+  if (toolName.startsWith("mandu_") && toolName.includes("route")) {
+    if (info.code === "ENOENT") {
+      return "routes.manifest.json 파일이 없습니다. `mandu init`을 먼저 실행해주세요.";
+    }
+    if (info.message.includes("not found")) {
+      return "해당 라우트를 찾을 수 없습니다. `mandu_list_routes`로 존재하는 라우트를 확인해주세요.";
+    }
+  }
+
+  // guard 관련 도구
+  if (toolName === "mandu_guard_check") {
+    if (info.category === "config") {
+      return "Guard 설정을 확인해주세요. mandu.config.ts의 guard 섹션을 검토해주세요.";
+    }
+  }
+
+  // contract 관련 도구
+  if (toolName.includes("contract")) {
+    if (info.category === "validation") {
+      return "Contract 스키마가 올바른지 확인해주세요. Zod 스키마 문법을 확인해주세요.";
+    }
+  }
+
+  // generate 관련 도구
+  if (toolName === "mandu.generate" || toolName === "mandu_generate") {
+    if (info.code === "EEXIST") {
+      return "파일이 이미 존재합니다. 덮어쓰려면 force 옵션을 사용해주세요.";
+    }
+  }
+
+  // transaction 관련 도구
+  if (toolName.includes("tx") || toolName.includes("transaction")) {
+    if (info.message.includes("no active")) {
+      return "활성화된 트랜잭션이 없습니다. `mandu_begin`으로 트랜잭션을 시작해주세요.";
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * 도구 실행 결과를 MCP 응답으로 변환
+ *
+ * @example
+ * ```ts
+ * // 성공 응답
+ * const response = createToolResponse("mandu_list_routes", { routes: [...] });
+ *
+ * // 에러 응답
+ * const response = createToolResponse("mandu_list_routes", null, new Error("..."));
+ * ```
+ */
+/**
+ * Detect "soft error" results: handler returned { error: "..." } or { success: false, error: "..." }
+ * without throwing. These should still be flagged as isError for the MCP client.
+ */
+function isSoftErrorResult(result: unknown): boolean {
+  if (result == null || typeof result !== "object") return false;
+  const obj = result as Record<string, unknown>;
+  // Has an explicit "error" field (string or array)
+  if ("error" in obj && obj.error != null) return true;
+  // Has success: false with no data payload
+  if (obj.success === false && "error" in obj) return true;
+  return false;
+}
+
+export function createToolResponse(
+  toolName: string,
+  result: unknown,
+  error?: unknown
+): McpToolResponse {
+  if (error) {
+    const errorResponse = formatMcpError(error, toolName);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(errorResponse, null, 2),
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  // Detect soft errors returned by handlers (e.g. { error: "Route not found" })
+  const softError = isSoftErrorResult(result);
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(result, null, 2),
+      },
+    ],
+    ...(softError && { isError: true }),
+  };
+}
+
+/**
+ * 에러 응답인지 확인
+ */
+export function isErrorResponse(response: McpToolResponse): boolean {
+  return response.isError === true;
+}
+
+/**
+ * 에러 응답에서 McpErrorResponse 추출
+ */
+export function extractErrorFromResponse(response: McpToolResponse): McpErrorResponse | null {
+  if (!response.isError) return null;
+
+  try {
+    const text = response.content[0]?.text;
+    if (!text) return null;
+    return JSON.parse(text) as McpErrorResponse;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 에러 로깅 헬퍼
+ */
+export function logToolError(
+  toolName: string,
+  error: unknown,
+  args?: Record<string, unknown>
+): void {
+  const info = extractErrorInfo(error);
+
+  console.error(`[MCP:${toolName}] ${info.category.toUpperCase()}: ${info.message}`);
+
+  if (info.code) {
+    console.error(`  Code: ${info.code}`);
+  }
+
+  if (args && Object.keys(args).length > 0) {
+    console.error(`  Args:`, JSON.stringify(args, null, 2));
+  }
+
+  if (info.context && Object.keys(info.context).length > 0) {
+    console.error(`  Context:`, info.context);
+  }
+}