@mandujs/mcp 0.10.0 → 0.12.0

package/src/hooks/config-watcher.ts

@@ -0,0 +1,174 @@
+/**
+ * MCP Config Watcher
+ *
+ * DNA-006 설정 핫 리로드와 MCP 서버 통합
+ */
+
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { watchConfig, hasConfigChanged, type ManduConfig } from "@mandujs/core";
+import { mcpToolRegistry } from "../registry/mcp-tool-registry.js";
+
+/**
+ * MCP Config Watcher 옵션
+ */
+export interface McpConfigWatcherOptions {
+  /** MCP Server 인스턴스 */
+  server?: Server;
+  /** 설정 변경 콜백 */
+  onReload?: (config: ManduConfig) => void | Promise<void>;
+  /** MCP 설정 변경 시 콜백 */
+  onMcpConfigChange?: (config: ManduConfig) => void | Promise<void>;
+  /** 에러 콜백 */
+  onError?: (error: unknown) => void;
+  /** 디바운스 딜레이 (ms) */
+  debounceMs?: number;
+}
+
+/**
+ * Config Watcher 결과
+ */
+export interface McpConfigWatcher {
+  /** 감시 중지 */
+  stop: () => void;
+  /** 수동 리로드 */
+  reload: () => Promise<ManduConfig | undefined>;
+  /** 현재 설정 */
+  getConfig: () => ManduConfig | undefined;
+}
+
+/**
+ * MCP 서버 설정 감시 시작
+ *
+ * @example
+ * ```ts
+ * const watcher = await startMcpConfigWatcher(projectRoot, {
+ *   server,
+ *   onReload: (config) => {
+ *     console.log("Config reloaded:", config);
+ *   },
+ * });
+ *
+ * // 나중에 중지
+ * watcher.stop();
+ * ```
+ */
+export async function startMcpConfigWatcher(
+  projectRoot: string,
+  options: McpConfigWatcherOptions = {}
+): Promise<McpConfigWatcher> {
+  const {
+    server,
+    onReload,
+    onMcpConfigChange,
+    onError,
+    debounceMs = 200,
+  } = options;
+
+  const watcher = await watchConfig(
+    projectRoot,
+    async (newConfig, event) => {
+      // MCP 서버에 알림
+      if (server) {
+        try {
+          await server.sendLoggingMessage({
+            level: "info",
+            logger: "mandu-config",
+            data: {
+              type: "config_reload",
+              changedSections: event.changedSections,
+              path: event.path,
+            },
+          });
+        } catch {
+          // 알림 실패 무시
+        }
+      }
+
+      // MCP 관련 설정 변경 확인
+      if (event.previous && event.current) {
+        if (hasConfigChanged(event.previous, event.current, "mcp")) {
+          // MCP 설정 변경 시 도구 재초기화 등 필요한 작업
+          if (server) {
+            try {
+              await server.sendLoggingMessage({
+                level: "warning",
+                logger: "mandu-config",
+                data: {
+                  type: "mcp_config_changed",
+                  message: "MCP configuration changed. Some tools may need reinitialization.",
+                },
+              });
+            } catch {
+              // 알림 실패 무시
+            }
+          }
+
+          await onMcpConfigChange?.(newConfig);
+        }
+
+        // Guard 설정 변경 확인
+        if (hasConfigChanged(event.previous, event.current, "guard")) {
+          if (server) {
+            try {
+              await server.sendLoggingMessage({
+                level: "info",
+                logger: "mandu-config",
+                data: {
+                  type: "guard_config_changed",
+                  message: "Guard configuration changed. Architecture rules updated.",
+                },
+              });
+            } catch {
+              // 알림 실패 무시
+            }
+          }
+        }
+      }
+
+      // 일반 콜백
+      await onReload?.(newConfig);
+    },
+    {
+      debounceMs,
+      immediate: false,
+      onError: (err) => {
+        console.error("[MCP:ConfigWatcher] Error:", err);
+
+        if (server) {
+          server.sendLoggingMessage({
+            level: "error",
+            logger: "mandu-config",
+            data: {
+              type: "config_error",
+              error: err instanceof Error ? err.message : String(err),
+            },
+          }).catch(() => {});
+        }
+
+        onError?.(err);
+      },
+    }
+  );
+
+  return watcher;
+}
+
+/**
+ * 설정 변경 시 도구 재등록이 필요한지 확인
+ */
+export function needsToolReregistration(
+  previous: ManduConfig | undefined,
+  current: ManduConfig | undefined
+): boolean {
+  if (!previous || !current) return false;
+
+  // MCP 플러그인 설정 변경
+  const prevPlugins = (previous as Record<string, unknown>).mcpPlugins;
+  const currPlugins = (current as Record<string, unknown>).mcpPlugins;
+
+  if (JSON.stringify(prevPlugins) !== JSON.stringify(currPlugins)) {
+    return true;
+  }
+
+  return false;
+}

package/src/hooks/index.ts

@@ -0,0 +1,23 @@
+/**
+ * MCP Hooks
+ *
+ * DNA-016 기반 도구 실행 훅
+ */
+
+export {
+  mcpHookRegistry,
+  registerDefaultMcpHooks,
+  slowToolLoggingHook,
+  statsCollectorHook,
+  getToolStats,
+  resetToolStats,
+  createArgValidationHook,
+  type McpToolContext,
+  type McpPreToolHook,
+  type McpPostToolHook,
+} from "./mcp-hooks.js";
+
+export {
+  startMcpConfigWatcher,
+  type McpConfigWatcherOptions,
+} from "./config-watcher.js";

package/src/hooks/mcp-hooks.ts

@@ -0,0 +1,227 @@
+/**
+ * MCP Pre/Post Tool Hooks
+ *
+ * DNA-016 Pre-Action 훅 시스템 기반 MCP 도구 훅
+ */
+
+import type { ManduConfig } from "@mandujs/core";
+
+/**
+ * MCP 도구 실행 컨텍스트
+ */
+export interface McpToolContext {
+  /** 도구 이름 */
+  toolName: string;
+  /** 도구 인자 */
+  args: Record<string, unknown>;
+  /** 프로젝트 루트 */
+  projectRoot: string;
+  /** Mandu 설정 */
+  config?: ManduConfig;
+  /** 실행 시작 시간 */
+  startTime: number;
+  /** 커스텀 데이터 (훅 간 공유용) */
+  custom?: Record<string, unknown>;
+}
+
+/**
+ * Pre-Tool 훅 타입
+ *
+ * 도구 실행 전에 호출됨
+ * - 권한 검사
+ * - 인자 검증
+ * - 로깅
+ */
+export type McpPreToolHook = (ctx: McpToolContext) => void | Promise<void>;
+
+/**
+ * Post-Tool 훅 타입
+ *
+ * 도구 실행 후에 호출됨
+ * - 결과 로깅
+ * - 통계 수집
+ * - 정리 작업
+ */
+export type McpPostToolHook = (
+  ctx: McpToolContext,
+  result: unknown,
+  error?: unknown
+) => void | Promise<void>;
+
+/**
+ * MCP 훅 레지스트리
+ */
+class McpHookRegistry {
+  private preHooks: Array<{ hook: McpPreToolHook; priority: number }> = [];
+  private postHooks: Array<{ hook: McpPostToolHook; priority: number }> = [];
+
+  /**
+   * Pre-Tool 훅 등록
+   *
+   * @param hook - 훅 함수
+   * @param priority - 우선순위 (낮을수록 먼저 실행, 기본값 100)
+   * @returns 등록 해제 함수
+   */
+  registerPreHook(hook: McpPreToolHook, priority = 100): () => void {
+    const entry = { hook, priority };
+    this.preHooks.push(entry);
+    this.preHooks.sort((a, b) => a.priority - b.priority);
+
+    return () => {
+      const idx = this.preHooks.indexOf(entry);
+      if (idx >= 0) this.preHooks.splice(idx, 1);
+    };
+  }
+
+  /**
+   * Post-Tool 훅 등록
+   *
+   * @param hook - 훅 함수
+   * @param priority - 우선순위 (낮을수록 먼저 실행, 기본값 100)
+   * @returns 등록 해제 함수
+   */
+  registerPostHook(hook: McpPostToolHook, priority = 100): () => void {
+    const entry = { hook, priority };
+    this.postHooks.push(entry);
+    this.postHooks.sort((a, b) => a.priority - b.priority);
+
+    return () => {
+      const idx = this.postHooks.indexOf(entry);
+      if (idx >= 0) this.postHooks.splice(idx, 1);
+    };
+  }
+
+  /**
+   * 모든 Pre-Tool 훅 실행
+   */
+  async runPreHooks(ctx: McpToolContext): Promise<void> {
+    for (const { hook } of this.preHooks) {
+      try {
+        await hook(ctx);
+      } catch (err) {
+        console.error(`[MCP:PreHook] Error in hook for ${ctx.toolName}:`, err);
+        throw err; // Pre 훅 에러는 도구 실행을 중단
+      }
+    }
+  }
+
+  /**
+   * 모든 Post-Tool 훅 실행
+   */
+  async runPostHooks(ctx: McpToolContext, result: unknown, error?: unknown): Promise<void> {
+    for (const { hook } of this.postHooks) {
+      try {
+        await hook(ctx, result, error);
+      } catch (err) {
+        // Post 훅 에러는 로깅만 하고 계속 진행
+        console.error(`[MCP:PostHook] Error in hook for ${ctx.toolName}:`, err);
+      }
+    }
+  }
+
+  /**
+   * 모든 훅 제거
+   */
+  clear(): void {
+    this.preHooks = [];
+    this.postHooks = [];
+  }
+
+  /**
+   * 등록된 훅 수
+   */
+  get counts(): { pre: number; post: number } {
+    return {
+      pre: this.preHooks.length,
+      post: this.postHooks.length,
+    };
+  }
+}
+
+/**
+ * 전역 MCP 훅 레지스트리
+ */
+export const mcpHookRegistry = new McpHookRegistry();
+
+// ============================================
+// 기본 훅 구현
+// ============================================
+
+/**
+ * 실행 시간 로깅 훅
+ */
+export const slowToolLoggingHook: McpPostToolHook = (ctx, _result, _error) => {
+  const duration = Date.now() - ctx.startTime;
+  if (duration > 5000) {
+    console.warn(`[MCP] Slow tool execution: ${ctx.toolName} (${duration}ms)`);
+  }
+};
+
+/**
+ * 도구별 통계 수집 훅
+ */
+const toolStats = new Map<string, { calls: number; errors: number; totalDuration: number }>();
+
+export const statsCollectorHook: McpPostToolHook = (ctx, _result, error) => {
+  const duration = Date.now() - ctx.startTime;
+  const stats = toolStats.get(ctx.toolName) ?? { calls: 0, errors: 0, totalDuration: 0 };
+
+  stats.calls += 1;
+  stats.totalDuration += duration;
+  if (error) stats.errors += 1;
+
+  toolStats.set(ctx.toolName, stats);
+};
+
+/**
+ * 도구 통계 조회
+ */
+export function getToolStats(): Record<string, { calls: number; errors: number; avgDuration: number }> {
+  const result: Record<string, { calls: number; errors: number; avgDuration: number }> = {};
+
+  for (const [name, stats] of toolStats) {
+    result[name] = {
+      calls: stats.calls,
+      errors: stats.errors,
+      avgDuration: stats.calls > 0 ? Math.round(stats.totalDuration / stats.calls) : 0,
+    };
+  }
+
+  return result;
+}
+
+/**
+ * 도구 통계 초기화
+ */
+export function resetToolStats(): void {
+  toolStats.clear();
+}
+
+/**
+ * 인자 검증 훅 생성기
+ */
+export function createArgValidationHook(
+  validations: Record<string, (args: Record<string, unknown>) => boolean | string>
+): McpPreToolHook {
+  return (ctx) => {
+    const validator = validations[ctx.toolName];
+    if (!validator) return;
+
+    const result = validator(ctx.args);
+    if (result === true) return;
+
+    const message = typeof result === "string" ? result : `Invalid arguments for ${ctx.toolName}`;
+    throw new Error(message);
+  };
+}
+
+/**
+ * 기본 훅 등록
+ */
+export function registerDefaultMcpHooks(): void {
+  // 느린 도구 경고 (우선순위 낮음 - 마지막에 실행)
+  mcpHookRegistry.registerPostHook(slowToolLoggingHook, 900);
+
+  // 통계 수집 (우선순위 높음 - 먼저 실행)
+  mcpHookRegistry.registerPostHook(statsCollectorHook, 10);
+}

package/src/index.ts

@@ -1,20 +1,106 @@
-#!/usr/bin/env bun
-
+#!/usr/bin/env bun
+
+/**
+ * @mandujs/mcp - MCP Server for Mandu Framework
+ *
+ * DNA 기능 통합:
+ * - DNA-001: 플러그인 기반 도구 등록
+ * - DNA-006: 설정 핫 리로드
+ * - DNA-007: 에러 추출 및 분류
+ * - DNA-008: 구조화된 로깅
+ * - DNA-016: Pre/Post 도구 훅
+ */
+
+// Main exports
+export { ManduMcpServer, startServer } from "./server.js";
+
+// Registry exports (DNA-001)
+export {
+  McpToolRegistry,
+  mcpToolRegistry,
+  type ToolRegistration,
+  type RegistryEvent,
+  type RegistryDump,
+} from "./registry/index.js";
+
+// Adapter exports
+export {
+  toolToPlugin,
+  pluginToTool,
+  moduleToPlugins,
+  pluginsToTools,
+  pluginsToHandlers,
+  monitorEventToRecord,
+  recordToMonitorEvent,
+} from "./adapters/index.js";
+
+// Executor exports (DNA-007)
+export {
+  formatMcpError,
+  createToolResponse,
+  isErrorResponse,
+  extractErrorFromResponse,
+  logToolError,
+  ToolExecutor,
+  createToolExecutor,
+  type McpErrorResponse,
+  type McpToolResponse,
+  type ToolExecutorOptions,
+  type ExecutionResult,
+} from "./executor/index.js";
+
+// Hook exports (DNA-016)
+export {
+  mcpHookRegistry,
+  registerDefaultMcpHooks,
+  slowToolLoggingHook,
+  statsCollectorHook,
+  getToolStats,
+  resetToolStats,
+  createArgValidationHook,
+  startMcpConfigWatcher,
+  type McpToolContext,
+  type McpPreToolHook,
+  type McpPostToolHook,
+  type McpConfigWatcherOptions,
+} from "./hooks/index.js";
+
+// Logging exports (DNA-008)
+export {
+  createMcpActivityTransport,
+  setupMcpLogging,
+  teardownMcpLogging,
+  dispatchMonitorEvent,
+  createMcpLogRecord,
+  MCP_TRANSPORT_ID,
+  type McpTransportOptions,
+} from "./logging/index.js";
+
+// Tools exports
+export {
+  registerBuiltinTools,
+  getToolCounts,
+  getToolsSummary,
+} from "./tools/index.js";
+
+// CLI entry point
 import { startServer } from "./server.js";
 import path from "path";
 
-// Start the MCP server
-const args = process.argv.slice(2);
-const globalMode = args.includes("--global");
-const rootIndex = args.indexOf("--root");
-const rootArg = rootIndex >= 0 ? args[rootIndex + 1] : undefined;
-const projectRoot = rootArg
-  ? path.resolve(rootArg)
-  : globalMode
-  ? process.cwd()
-  : undefined;
-
-startServer(projectRoot).catch((error) => {
-  console.error("Failed to start Mandu MCP server:", error);
-  process.exit(1);
-});
+// Start server if run directly
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+  const globalMode = args.includes("--global");
+  const rootIndex = args.indexOf("--root");
+  const rootArg = rootIndex >= 0 ? args[rootIndex + 1] : undefined;
+  const projectRoot = rootArg
+    ? path.resolve(rootArg)
+    : globalMode
+      ? process.cwd()
+      : undefined;
+
+  startServer(projectRoot).catch((error) => {
+    console.error("Failed to start Mandu MCP server:", error);
+    process.exit(1);
+  });
+}

package/src/logging/index.ts

@@ -0,0 +1,15 @@
+/**
+ * MCP Logging
+ *
+ * DNA-008 로깅 통합
+ */
+
+export {
+  createMcpActivityTransport,
+  setupMcpLogging,
+  teardownMcpLogging,
+  dispatchMonitorEvent,
+  createMcpLogRecord,
+  MCP_TRANSPORT_ID,
+  type McpTransportOptions,
+} from "./mcp-transport.js";

package/src/logging/mcp-transport.ts

@@ -0,0 +1,134 @@
+/**
+ * MCP LogTransport Integration
+ *
+ * DNA-008 로깅 시스템과 MCP ActivityMonitor 통합
+ */
+
+import {
+  attachLogTransport,
+  detachLogTransport,
+  type LogTransport,
+  type LogTransportRecord,
+} from "@mandujs/core";
+import { monitorEventToRecord, type MonitorEvent } from "../adapters/monitor-adapter.js";
+
+/**
+ * MCP 로깅 Transport ID
+ */
+export const MCP_TRANSPORT_ID = "mcp-activity";
+
+/**
+ * MCP Activity Transport 옵션
+ */
+export interface McpTransportOptions {
+  /** 로그 파일 경로 (선택) */
+  logFile?: string;
+  /** 콘솔 출력 여부 */
+  consoleOutput?: boolean;
+  /** 커스텀 핸들러 */
+  onRecord?: (record: LogTransportRecord) => void;
+}
+
+/**
+ * MCP Activity Transport 생성
+ *
+ * ActivityMonitor의 이벤트를 DNA-008 TransportRegistry로 전달
+ */
+export function createMcpActivityTransport(
+  options: McpTransportOptions = {}
+): LogTransport {
+  const { consoleOutput = false, onRecord } = options;
+
+  return (record: LogTransportRecord) => {
+    // MCP 관련 로그만 처리
+    const source = record.meta?.source;
+    if (source !== "mcp" && source !== "tool" && source !== "watch") {
+      return;
+    }
+
+    // 커스텀 핸들러
+    if (onRecord) {
+      onRecord(record);
+    }
+
+    // 콘솔 출력
+    if (consoleOutput) {
+      const prefix = `[MCP:${source}]`;
+      const msg = record.error?.message || (record.meta?.message as string) || "";
+
+      switch (record.level) {
+        case "error":
+          console.error(prefix, msg, record.meta);
+          break;
+        case "warn":
+          console.warn(prefix, msg, record.meta);
+          break;
+        default:
+          console.log(prefix, msg, record.meta);
+      }
+    }
+  };
+}
+
+/**
+ * MCP 로깅 설정
+ *
+ * @example
+ * ```ts
+ * setupMcpLogging({
+ *   consoleOutput: true,
+ *   onRecord: (record) => {
+ *     // 커스텀 처리
+ *   },
+ * });
+ * ```
+ */
+export function setupMcpLogging(options: McpTransportOptions = {}): void {
+  const transport = createMcpActivityTransport(options);
+  attachLogTransport(MCP_TRANSPORT_ID, transport, { minLevel: "info" });
+}
+
+/**
+ * MCP 로깅 해제
+ */
+export function teardownMcpLogging(): void {
+  detachLogTransport(MCP_TRANSPORT_ID);
+}
+
+/**
+ * MonitorEvent를 DNA-008 시스템으로 전송
+ *
+ * ActivityMonitor에서 이 함수를 호출하여 로그 통합
+ */
+export function dispatchMonitorEvent(event: MonitorEvent): void {
+  const record = monitorEventToRecord(event);
+
+  // 직접 transport로 전달하지 않고,
+  // 다른 transport들도 받을 수 있도록 registry를 통해 dispatch
+  // (transportRegistry.dispatch는 core에서 export 필요)
+
+  // 임시: 콘솔 출력
+  if (event.severity === "error") {
+    console.error(`[MCP:${event.source}] ${event.message || event.type}`, event.data);
+  }
+}
+
+/**
+ * MCP 로그 레코드 생성 헬퍼
+ */
+export function createMcpLogRecord(
+  level: "debug" | "info" | "warn" | "error",
+  source: "mcp" | "tool" | "watch",
+  message: string,
+  data?: Record<string, unknown>
+): LogTransportRecord {
+  return {
+    timestamp: new Date().toISOString(),
+    level,
+    meta: {
+      source,
+      message,
+      ...data,
+    },
+  };
+}

package/src/registry/index.ts

@@ -0,0 +1,13 @@
+/**
+ * MCP Registry
+ *
+ * 도구 레지스트리 및 관련 유틸리티
+ */
+
+export {
+  McpToolRegistry,
+  mcpToolRegistry,
+  type ToolRegistration,
+  type RegistryEvent,
+  type RegistryDump,
+} from "./mcp-tool-registry.js";