@mandujs/mcp 0.10.0 → 0.12.0

package/README.md

@@ -64,7 +64,7 @@ bunx @mandujs/mcp --root /path/to/project
 
 ---
 
-## Tools (28+)
+## Tools (35+)
 
 ### Spec Management
 
@@ -105,10 +105,35 @@ bunx @mandujs/mcp --root /path/to/project
 | Tool | Description |
 |------|-------------|
 | `mandu_guard_check` | Run all guard checks |
+| `mandu_guard_heal` | Self-Healing Guard - detect + auto-fix suggestions |
+| `mandu_explain_rule` | Explain architecture rule with examples |
 | `mandu_check_location` | Validate file location before creating |
 | `mandu_check_import` | Validate imports against architecture rules |
 | `mandu_get_architecture` | Get project architecture rules |
 
+### Decision Memory (RFC-001) 🆕
+
+| Tool | Description |
+|------|-------------|
+| `mandu_search_decisions` | Search ADRs by tags or status |
+| `mandu_save_decision` | Save new architecture decision |
+| `mandu_check_consistency` | Check decision-implementation consistency |
+
+### Semantic Slots (RFC-001) 🆕
+
+| Tool | Description |
+|------|-------------|
+| `mandu_validate_slot` | Validate slot against constraints |
+| `mandu_validate_slots` | Batch validate multiple slots |
+
+### Architecture Negotiation (RFC-001) 🆕
+
+| Tool | Description |
+|------|-------------|
+| `mandu_negotiate` | AI-Framework negotiation dialog |
+| `mandu_generate_scaffold` | Generate structure scaffold |
+| `mandu_analyze_structure` | Analyze existing project structure |
+
 ### Brain & Monitoring
 
 | Tool | Description |

package/package.json

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

package/src/adapters/index.ts

@@ -0,0 +1,20 @@
+/**
+ * MCP Adapters
+ *
+ * DNA 기능과 MCP 간의 변환 어댑터
+ */
+
+export {
+  toolToPlugin,
+  pluginToTool,
+  moduleToPlugins,
+  pluginsToTools,
+  pluginsToHandlers,
+} from "./tool-adapter.js";
+
+export {
+  monitorEventToRecord,
+  recordToMonitorEvent,
+  severityToLevel,
+  levelToSeverity,
+} from "./monitor-adapter.js";

package/src/adapters/monitor-adapter.ts

@@ -0,0 +1,100 @@
+/**
+ * Monitor Event Adapter
+ *
+ * ActivityMonitor 이벤트와 DNA-008 LogTransportRecord 간 변환
+ */
+
+import type { LogTransportRecord } from "@mandujs/core";
+
+/**
+ * Monitor 이벤트 타입 (ActivityMonitor에서 사용)
+ */
+export interface MonitorEvent {
+  ts: string;
+  type: string;
+  severity: MonitorSeverity;
+  source: string;
+  message?: string;
+  data?: Record<string, unknown>;
+  actionRequired?: boolean;
+  fingerprint?: string;
+  count?: number;
+  schemaVersion?: string;
+}
+
+export type MonitorSeverity = "info" | "warn" | "error";
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+/**
+ * MonitorSeverity → LogLevel 변환
+ */
+export function severityToLevel(severity: MonitorSeverity): LogLevel {
+  switch (severity) {
+    case "error":
+      return "error";
+    case "warn":
+      return "warn";
+    case "info":
+    default:
+      return "info";
+  }
+}
+
+/**
+ * LogLevel → MonitorSeverity 변환
+ */
+export function levelToSeverity(level: LogLevel): MonitorSeverity {
+  switch (level) {
+    case "error":
+      return "error";
+    case "warn":
+      return "warn";
+    case "debug":
+    case "info":
+    default:
+      return "info";
+  }
+}
+
+/**
+ * MonitorEvent → LogTransportRecord 변환
+ *
+ * ActivityMonitor 이벤트를 DNA-008 로깅 시스템으로 전송할 때 사용
+ */
+export function monitorEventToRecord(event: MonitorEvent): LogTransportRecord {
+  return {
+    timestamp: event.ts,
+    level: severityToLevel(event.severity),
+    meta: {
+      type: event.type,
+      source: event.source,
+      fingerprint: event.fingerprint,
+      count: event.count,
+      actionRequired: event.actionRequired,
+      schemaVersion: event.schemaVersion,
+      ...event.data,
+    },
+  };
+}
+
+/**
+ * LogTransportRecord → MonitorEvent 변환 (역방향)
+ *
+ * DNA-008 로그를 ActivityMonitor에서 표시할 때 사용
+ */
+export function recordToMonitorEvent(record: LogTransportRecord): MonitorEvent {
+  const meta = record.meta ?? {};
+
+  return {
+    ts: record.timestamp,
+    type: (meta.type as string) ?? "log",
+    severity: levelToSeverity(record.level),
+    source: (meta.source as string) ?? "unknown",
+    message: record.error?.message,
+    data: meta,
+    actionRequired: (meta.actionRequired as boolean) ?? false,
+    fingerprint: meta.fingerprint as string | undefined,
+    count: meta.count as number | undefined,
+    schemaVersion: meta.schemaVersion as string | undefined,
+  };
+}

package/src/adapters/tool-adapter.ts

@@ -0,0 +1,88 @@
+/**
+ * MCP Tool Adapter
+ *
+ * MCP SDK Tool을 DNA-001 McpToolPlugin으로 변환
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { McpToolPlugin } from "@mandujs/core";
+
+/**
+ * MCP SDK Tool을 McpToolPlugin으로 변환
+ *
+ * @example
+ * ```ts
+ * const plugin = toolToPlugin(
+ *   { name: "my_tool", description: "...", inputSchema: {} },
+ *   async (args) => ({ success: true })
+ * );
+ * ```
+ */
+export function toolToPlugin(
+  definition: Tool,
+  handler: (args: Record<string, unknown>) => Promise<unknown>
+): McpToolPlugin {
+  return {
+    name: definition.name,
+    description: definition.description ?? "",
+    inputSchema: definition.inputSchema as Record<string, unknown>,
+    execute: handler,
+  };
+}
+
+/**
+ * McpToolPlugin을 MCP SDK Tool로 변환 (역방향)
+ */
+export function pluginToTool(plugin: McpToolPlugin): Tool {
+  return {
+    name: plugin.name,
+    description: plugin.description,
+    inputSchema: plugin.inputSchema,
+  };
+}
+
+/**
+ * 기존 도구 모듈(definitions + handlers)을 플러그인 배열로 변환
+ *
+ * @example
+ * ```ts
+ * const plugins = moduleToPlugins(
+ *   specToolDefinitions,
+ *   specTools(projectRoot)
+ * );
+ * ```
+ */
+export function moduleToPlugins(
+  definitions: Tool[],
+  handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>>
+): McpToolPlugin[] {
+  return definitions.map((def) => {
+    const handler = handlers[def.name];
+    if (!handler) {
+      throw new Error(`Handler not found for tool: ${def.name}`);
+    }
+    return toolToPlugin(def, handler);
+  });
+}
+
+/**
+ * 플러그인 배열을 MCP SDK Tool 배열로 변환
+ */
+export function pluginsToTools(plugins: McpToolPlugin[]): Tool[] {
+  return plugins.map(pluginToTool);
+}
+
+/**
+ * 플러그인 배열을 핸들러 맵으로 변환
+ */
+export function pluginsToHandlers(
+  plugins: McpToolPlugin[]
+): Record<string, (args: Record<string, unknown>) => Promise<unknown>> {
+  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {};
+
+  for (const plugin of plugins) {
+    handlers[plugin.name] = async (args) => plugin.execute(args);
+  }
+
+  return handlers;
+}

package/src/executor/error-handler.ts

@@ -0,0 +1,250 @@
+/**
+ * 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);
+  }
+}

package/src/executor/index.ts

@@ -0,0 +1,22 @@
+/**
+ * MCP Executor
+ *
+ * 도구 실행 및 에러 처리
+ */
+
+export {
+  formatMcpError,
+  createToolResponse,
+  isErrorResponse,
+  extractErrorFromResponse,
+  logToolError,
+  type McpErrorResponse,
+  type McpToolResponse,
+} from "./error-handler.js";
+
+export {
+  ToolExecutor,
+  createToolExecutor,
+  type ToolExecutorOptions,
+  type ExecutionResult,
+} from "./tool-executor.js";

package/src/executor/tool-executor.ts

@@ -0,0 +1,148 @@
+/**
+ * MCP Tool Executor
+ *
+ * 도구 실행 + 훅 + 에러 처리 통합
+ */
+
+import type { McpToolPlugin, ManduConfig } from "@mandujs/core";
+import { mcpToolRegistry } from "../registry/mcp-tool-registry.js";
+import { mcpHookRegistry, type McpToolContext } from "../hooks/mcp-hooks.js";
+import { createToolResponse, logToolError, type McpToolResponse } from "./error-handler.js";
+
+/**
+ * Tool Executor 옵션
+ */
+export interface ToolExecutorOptions {
+  /** 프로젝트 루트 */
+  projectRoot: string;
+  /** Mandu 설정 */
+  config?: ManduConfig;
+  /** 활동 모니터 로깅 함수 */
+  logTool?: (name: string, args?: Record<string, unknown>, result?: unknown, error?: string) => void;
+  /** 결과 로깅 함수 */
+  logResult?: (name: string, result: unknown) => void;
+}
+
+/**
+ * 도구 실행 결과
+ */
+export interface ExecutionResult {
+  success: boolean;
+  response: McpToolResponse;
+  duration: number;
+  toolName: string;
+}
+
+/**
+ * 도구 실행기
+ *
+ * DNA 기능들(플러그인, 훅, 에러 처리)을 통합한 도구 실행
+ */
+export class ToolExecutor {
+  private options: ToolExecutorOptions;
+
+  constructor(options: ToolExecutorOptions) {
+    this.options = options;
+  }
+
+  /**
+   * 도구 실행
+   *
+   * @param name - 도구 이름
+   * @param args - 도구 인자
+   * @returns 실행 결과
+   */
+  async execute(name: string, args: Record<string, unknown> = {}): Promise<ExecutionResult> {
+    const startTime = Date.now();
+
+    // 도구 조회
+    const tool = mcpToolRegistry.get(name);
+    if (!tool) {
+      const response = createToolResponse(name, null, new Error(`Unknown tool: ${name}`));
+      return {
+        success: false,
+        response,
+        duration: Date.now() - startTime,
+        toolName: name,
+      };
+    }
+
+    // 실행 컨텍스트 생성
+    const ctx: McpToolContext = {
+      toolName: name,
+      args,
+      projectRoot: this.options.projectRoot,
+      config: this.options.config,
+      startTime,
+    };
+
+    try {
+      // Pre-Tool 훅 실행
+      await mcpHookRegistry.runPreHooks(ctx);
+
+      // 활동 로깅 (호출)
+      this.options.logTool?.(name, args);
+
+      // 도구 실행
+      const result = await tool.execute(args);
+
+      // 활동 로깅 (결과)
+      this.options.logResult?.(name, result);
+
+      // Post-Tool 훅 실행
+      await mcpHookRegistry.runPostHooks(ctx, result);
+
+      const response = createToolResponse(name, result);
+      return {
+        success: true,
+        response,
+        duration: Date.now() - startTime,
+        toolName: name,
+      };
+    } catch (error) {
+      // 에러 로깅
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      this.options.logTool?.(name, args, null, errorMsg);
+      logToolError(name, error, args);
+
+      // Post-Tool 훅 실행 (에러와 함께)
+      await mcpHookRegistry.runPostHooks(ctx, null, error);
+
+      const response = createToolResponse(name, null, error);
+      return {
+        success: false,
+        response,
+        duration: Date.now() - startTime,
+        toolName: name,
+      };
+    }
+  }
+
+  /**
+   * 설정 업데이트
+   */
+  updateConfig(config: ManduConfig): void {
+    this.options.config = config;
+  }
+
+  /**
+   * 도구 존재 여부 확인
+   */
+  hasTool(name: string): boolean {
+    return mcpToolRegistry.has(name);
+  }
+
+  /**
+   * 등록된 도구 목록
+   */
+  getToolNames(): string[] {
+    return mcpToolRegistry.names;
+  }
+}
+
+/**
+ * Tool Executor 팩토리 함수
+ */
+export function createToolExecutor(options: ToolExecutorOptions): ToolExecutor {
+  return new ToolExecutor(options);
+}