@mandujs/mcp 0.9.11 → 0.9.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/mcp",
-  "version": "0.9.11",
+  "version": "0.9.13",
   "description": "Mandu MCP Server - Agent-native interface for Mandu framework operations",
   "type": "module",
   "main": "./src/index.ts",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@mandujs/core": "^0.9.11",
+    "@mandujs/core": "^0.9.13",
     "@modelcontextprotocol/sdk": "^1.25.3"
   },
   "engines": {

package/src/activity-monitor.ts

@@ -0,0 +1,231 @@
+/**
+ * Mandu Activity Monitor
+ *
+ * Real-time terminal dashboard for MCP server activity.
+ * Opens automatically when the MCP server starts.
+ * Shows all tool calls, watch events, errors, and agent behavior.
+ */
+
+import fs from "fs";
+import path from "path";
+import { spawn, type ChildProcess } from "child_process";
+
+const TOOL_ICONS: Record<string, string> = {
+  // Spec
+  mandu_list_routes: "SPEC",
+  mandu_get_route: "SPEC",
+  mandu_add_route: "SPEC+",
+  mandu_update_route: "SPEC~",
+  mandu_delete_route: "SPEC-",
+  mandu_validate_spec: "SPEC?",
+  // Generate
+  mandu_generate: "GEN",
+  mandu_generate_status: "GEN?",
+  // Guard
+  mandu_guard_check: "GUARD",
+  // Slot
+  mandu_read_slot: "SLOT",
+  mandu_write_slot: "SLOT~",
+  mandu_validate_slot: "SLOT?",
+  // Contract
+  mandu_list_contracts: "CONTRACT",
+  mandu_get_contract: "CONTRACT",
+  mandu_create_contract: "CONTRACT+",
+  mandu_validate_contracts: "CONTRACT?",
+  mandu_sync_contract_slot: "SYNC",
+  mandu_generate_openapi: "OPENAPI",
+  mandu_update_route_contract: "CONTRACT~",
+  // Transaction
+  mandu_begin: "TX-BEGIN",
+  mandu_commit: "TX-COMMIT",
+  mandu_rollback: "TX-ROLLBACK",
+  mandu_tx_status: "TX?",
+  // History
+  mandu_list_history: "HISTORY",
+  mandu_get_snapshot: "SNAPSHOT",
+  mandu_prune_history: "PRUNE",
+  // Brain
+  mandu_doctor: "DOCTOR",
+  mandu_watch_start: "WATCH+",
+  mandu_watch_status: "WATCH?",
+  mandu_watch_stop: "WATCH-",
+  mandu_check_location: "ARCH?",
+  mandu_check_import: "IMPORT?",
+  mandu_get_architecture: "ARCH",
+  // Build
+  mandu_build: "BUILD",
+  mandu_build_status: "BUILD?",
+  mandu_list_islands: "ISLAND",
+  mandu_set_hydration: "HYDRA~",
+  mandu_add_client_slot: "CLIENT+",
+  // Error
+  mandu_analyze_error: "ERROR",
+};
+
+function getTime(): string {
+  return new Date().toLocaleTimeString("ko-KR", { hour12: false });
+}
+
+function summarizeArgs(args: Record<string, unknown> | null | undefined): string {
+  if (!args || Object.keys(args).length === 0) return "";
+  const entries = Object.entries(args)
+    .filter(([_, v]) => v !== undefined && v !== null)
+    .map(([k, v]) => {
+      const val = typeof v === "string"
+        ? (v.length > 40 ? v.slice(0, 40) + "..." : v)
+        : JSON.stringify(v);
+      return `${k}=${val}`;
+    });
+  return entries.length > 0 ? ` (${entries.join(", ")})` : "";
+}
+
+function summarizeResult(result: unknown): string {
+  if (!result || typeof result !== "object") return "";
+  const obj = result as Record<string, unknown>;
+
+  // Common patterns
+  if (obj.error) return ` >> ERROR: ${obj.error}`;
+  if (obj.success === true) return obj.message ? ` >> ${obj.message}` : " >> OK";
+  if (obj.success === false) return ` >> FAILED: ${obj.message || "unknown"}`;
+  if (Array.isArray(obj.routes)) return ` >> ${obj.routes.length} routes`;
+  if (obj.passed === true) return obj.message ? ` >> ${obj.message}` : " >> PASSED";
+  if (obj.passed === false) return ` >> FAILED (${(obj.violations as unknown[])?.length || 0} violations)`;
+  if (obj.valid === true) return obj.message ? ` >> ${obj.message}` : " >> VALID";
+  if (obj.valid === false) return ` >> INVALID (${(obj.violations as unknown[])?.length || 0} violations)`;
+  if (obj.generated) return " >> Generated";
+  if (obj.status) return ` >> ${JSON.stringify(obj.status).slice(0, 60)}`;
+
+  return "";
+}
+
+export class ActivityMonitor {
+  private logFile: string;
+  private logStream: fs.WriteStream | null = null;
+  private tailProcess: ChildProcess | null = null;
+  private projectRoot: string;
+  private callCount = 0;
+
+  constructor(projectRoot: string) {
+    this.projectRoot = projectRoot;
+    const manduDir = path.join(projectRoot, ".mandu");
+    if (!fs.existsSync(manduDir)) {
+      fs.mkdirSync(manduDir, { recursive: true });
+    }
+    this.logFile = path.join(manduDir, "activity.log");
+  }
+
+  start(): void {
+    // Create/overwrite log file
+    this.logStream = fs.createWriteStream(this.logFile, { flags: "w" });
+
+    const time = getTime();
+    const header =
+      `\n` +
+      `  ╔══════════════════════════════════════════════╗\n` +
+      `  ║         MANDU MCP Activity Monitor           ║\n` +
+      `  ║                                              ║\n` +
+      `  ║  ${time}                                ║\n` +
+      `  ║  ${this.projectRoot.slice(-40).padEnd(40)}    ║\n` +
+      `  ╚══════════════════════════════════════════════╝\n\n`;
+
+    this.logStream.write(header);
+
+    // Auto-open terminal
+    this.openTerminal();
+  }
+
+  stop(): void {
+    if (this.tailProcess) {
+      this.tailProcess.kill();
+      this.tailProcess = null;
+    }
+    if (this.logStream) {
+      this.logStream.end();
+      this.logStream = null;
+    }
+  }
+
+  /**
+   * Log a tool call (invocation)
+   */
+  logTool(
+    name: string,
+    args?: Record<string, unknown> | null,
+    _result?: unknown,
+    error?: string,
+  ): void {
+    this.callCount++;
+    const time = getTime();
+    const tag = TOOL_ICONS[name] || name.replace("mandu_", "").toUpperCase();
+    const argsStr = summarizeArgs(args);
+
+    let line: string;
+    if (error) {
+      line = `${time} ✗ [${tag}]${argsStr}\n       ERROR: ${error}\n`;
+    } else {
+      line = `${time} → [${tag}]${argsStr}\n`;
+    }
+
+    this.write(line);
+  }
+
+  /**
+   * Log a tool result
+   */
+  logResult(name: string, result: unknown): void {
+    const time = getTime();
+    const tag = TOOL_ICONS[name] || name.replace("mandu_", "").toUpperCase();
+    const summary = summarizeResult(result);
+
+    if (summary) {
+      this.write(`${time} ✓ [${tag}]${summary}\n`);
+    }
+  }
+
+  /**
+   * Log a watch event (called from watcher)
+   */
+  logWatch(level: string, ruleId: string, file: string, message: string): void {
+    const time = getTime();
+    const icon = level === "info" ? "ℹ" : "⚠";
+    this.write(`${time} ${icon} [WATCH:${ruleId}] ${file}\n       ${message}\n`);
+  }
+
+  /**
+   * Log a custom event
+   */
+  logEvent(category: string, message: string): void {
+    const time = getTime();
+    this.write(`${time}   [${category}] ${message}\n`);
+  }
+
+  private write(text: string): void {
+    if (this.logStream) {
+      this.logStream.write(text);
+    }
+  }
+
+  private openTerminal(): void {
+    try {
+      if (process.platform === "win32") {
+        this.tailProcess = spawn("cmd", [
+          "/c", "start",
+          "Mandu Activity Monitor",
+          "powershell", "-NoExit", "-Command",
+          `[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; chcp 65001 | Out-Null; Get-Content '${this.logFile}' -Wait -Encoding UTF8`,
+        ], { cwd: this.projectRoot, detached: true, stdio: "ignore" });
+      } else if (process.platform === "darwin") {
+        this.tailProcess = spawn("osascript", [
+          "-e", `tell application "Terminal" to do script "tail -f '${this.logFile}'"`,
+        ], { detached: true, stdio: "ignore" });
+      } else {
+        this.tailProcess = spawn("x-terminal-emulator", [
+          "-e", `tail -f '${this.logFile}'`,
+        ], { cwd: this.projectRoot, detached: true, stdio: "ignore" });
+      }
+      this.tailProcess?.unref();
+    } catch {
+      // Terminal auto-open failed silently
+    }
+  }
+}

package/src/resources/handlers.ts

@@ -2,6 +2,7 @@ import type { Resource } from "@modelcontextprotocol/sdk/types.js";
 import {
   loadManifest,
   getTransactionStatus,
+  getWatcher,
   type GeneratedMap,
   type SpecLock,
 } from "@mandujs/core";
@@ -39,6 +40,18 @@ export const resourceDefinitions: Resource[] = [
     description: "Slot file content for a specific route",
     mimeType: "text/typescript",
   },
+  {
+    uri: "mandu://watch/warnings",
+    name: "Watch Warnings",
+    description: "Recent file watcher warnings (architecture rule violations)",
+    mimeType: "application/json",
+  },
+  {
+    uri: "mandu://watch/status",
+    name: "Watch Status",
+    description: "File watcher status (active/inactive, uptime, rule count)",
+    mimeType: "application/json",
+  },
 ];
 
 type ResourceHandler = (params: Record<string, string>) => Promise<unknown>;
@@ -172,5 +185,44 @@ export function resourceHandlers(
         content,
       };
     },
+
+    "mandu://watch/warnings": async () => {
+      const watcher = getWatcher();
+      if (!watcher) {
+        return { active: false, warnings: [] };
+      }
+
+      const warnings = watcher.getRecentWarnings(50);
+      return {
+        active: true,
+        count: warnings.length,
+        warnings: warnings.map((w) => ({
+          ruleId: w.ruleId,
+          file: w.file,
+          message: w.message,
+          event: w.event,
+          timestamp: w.timestamp.toISOString(),
+        })),
+      };
+    },
+
+    "mandu://watch/status": async () => {
+      const watcher = getWatcher();
+      if (!watcher) {
+        return { active: false };
+      }
+
+      const status = watcher.getStatus();
+      return {
+        active: status.active,
+        rootDir: status.rootDir,
+        fileCount: status.fileCount,
+        warningCount: status.recentWarnings.length,
+        uptime: status.startedAt
+          ? Math.floor((Date.now() - status.startedAt.getTime()) / 1000)
+          : 0,
+        startedAt: status.startedAt?.toISOString() || null,
+      };
+    },
   };
 }

package/src/server.ts

@@ -20,13 +20,17 @@ import { contractTools, contractToolDefinitions } from "./tools/contract.js";
 import { brainTools, brainToolDefinitions } from "./tools/brain.js";
 import { resourceHandlers, resourceDefinitions } from "./resources/handlers.js";
 import { findProjectRoot } from "./utils/project.js";
+import { ActivityMonitor } from "./activity-monitor.js";
+import { startWatcher } from "../../core/src/index.js";
 
 export class ManduMcpServer {
   private server: Server;
   private projectRoot: string;
+  private monitor: ActivityMonitor;
 
   constructor(projectRoot: string) {
     this.projectRoot = projectRoot;
+    this.monitor = new ActivityMonitor(projectRoot);
     this.server = new Server(
       {
         name: "mandu-mcp",
@@ -36,6 +40,7 @@ export class ManduMcpServer {
         capabilities: {
           tools: {},
           resources: {},
+          logging: {},
         },
       }
     );
@@ -68,7 +73,7 @@ export class ManduMcpServer {
       ...slotTools(this.projectRoot),
       ...hydrationTools(this.projectRoot),
       ...contractTools(this.projectRoot),
-      ...brainTools(this.projectRoot),
+      ...brainTools(this.projectRoot, this.server, this.monitor),
     };
   }
 
@@ -86,6 +91,7 @@ export class ManduMcpServer {
 
       const handler = toolHandlers[name];
       if (!handler) {
+        this.monitor.logTool(name, args, null, "Unknown tool");
         return {
           content: [
             {
@@ -98,7 +104,9 @@ export class ManduMcpServer {
       }
 
       try {
+        this.monitor.logTool(name, args);
         const result = await handler(args || {});
+        this.monitor.logResult(name, result);
         return {
           content: [
             {
@@ -108,13 +116,13 @@ export class ManduMcpServer {
           ],
         };
       } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        this.monitor.logTool(name, args, null, msg);
         return {
           content: [
             {
               type: "text",
-              text: JSON.stringify({
-                error: error instanceof Error ? error.message : String(error),
-              }),
+              text: JSON.stringify({ error: msg }),
             },
           ],
           isError: true,
@@ -195,6 +203,36 @@ export class ManduMcpServer {
   async run(): Promise<void> {
     const transport = new StdioServerTransport();
     await this.server.connect(transport);
+    this.monitor.start();
+
+    // Auto-start watcher with activity monitor integration
+    try {
+      const watcher = await startWatcher({ rootDir: this.projectRoot });
+      watcher.onWarning((warning) => {
+        this.monitor.logWatch(
+          warning.level || "warn",
+          warning.ruleId,
+          warning.file,
+          warning.message,
+        );
+        // Also notify Claude Code via MCP
+        this.server.sendLoggingMessage({
+          level: "warning",
+          logger: "mandu-watch",
+          data: {
+            type: "watch_warning",
+            ruleId: warning.ruleId,
+            file: warning.file,
+            message: warning.message,
+            event: warning.event,
+          },
+        }).catch(() => {});
+      });
+      this.monitor.logEvent("SYSTEM", "Watcher auto-started");
+    } catch {
+      this.monitor.logEvent("SYSTEM", "Watcher auto-start failed (non-critical)");
+    }
+
     console.error(`Mandu MCP Server running for project: ${this.projectRoot}`);
   }
 }

package/src/tools/brain.ts

@@ -11,6 +11,8 @@
  */
 
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { ActivityMonitor } from "../activity-monitor.js";
 import {
   loadManifest,
   runGuardCheck,
@@ -69,6 +71,16 @@ export const brainToolDefinitions: Tool[] = [
       required: [],
     },
   },
+  {
+    name: "mandu_watch_stop",
+    description:
+      "Stop file watching and clean up MCP notification subscriptions.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+    },
+  },
   // Architecture tools (v0.2)
   {
     name: "mandu_check_location",
@@ -126,12 +138,15 @@ export const brainToolDefinitions: Tool[] = [
   },
 ];
 
-export function brainTools(projectRoot: string) {
+/** Module-level unsubscribe handle for MCP warning notifications */
+let mcpWarningUnsubscribe: (() => void) | null = null;
+
+export function brainTools(projectRoot: string, server?: Server, monitor?: ActivityMonitor) {
   const paths = getProjectPaths(projectRoot);
 
   return {
     mandu_doctor: async (args: Record<string, unknown>) => {
-      const { useLLM = true } = args as { useLLM?: boolean };
+      const { useLLM = false } = args as { useLLM?: boolean };
 
       try {
         // Initialize Brain
@@ -221,11 +236,55 @@ export function brainTools(projectRoot: string) {
           debounceMs,
         });
 
+        // Register MCP notification handler
+        let notifications = false;
+        if (server) {
+          // Clean up previous subscription
+          if (mcpWarningUnsubscribe) {
+            mcpWarningUnsubscribe();
+            mcpWarningUnsubscribe = null;
+          }
+
+          mcpWarningUnsubscribe = watcher.onWarning((warning) => {
+            // Log to activity monitor
+            if (monitor) {
+              monitor.logWatch(
+                warning.level || "warn",
+                warning.ruleId,
+                warning.file,
+                warning.message,
+              );
+            }
+
+            // Push logging message (Claude Code receives in real-time)
+            server.sendLoggingMessage({
+              level: "warning",
+              logger: "mandu-watch",
+              data: {
+                type: "watch_warning",
+                ruleId: warning.ruleId,
+                file: warning.file,
+                message: warning.message,
+                event: warning.event,
+                timestamp: warning.timestamp.toISOString(),
+              },
+            }).catch(() => {});
+
+            // Resource update notification
+            server.sendResourceUpdated({
+              uri: "mandu://watch/warnings",
+            }).catch(() => {});
+          });
+
+          notifications = true;
+        }
+
         const status = watcher.getStatus();
 
         return {
           success: true,
           message: "Watch started successfully",
+          notifications: notifications ? "enabled" : "disabled",
           status: {
             active: status.active,
             rootDir: status.rootDir,
@@ -238,8 +297,10 @@ export function brainTools(projectRoot: string) {
             "SLOT_NAMING - Slot 파일 네이밍 규칙",
             "CONTRACT_NAMING - Contract 파일 네이밍 규칙",
             "FORBIDDEN_IMPORT - Generated 파일의 금지된 import 감지",
+            "SLOT_MODIFIED - Slot 파일 수정 감지 (info)",
           ],
-          tip: "Watch emits warnings only - it never blocks operations",
+          logFile: ".mandu/watch.log",
+          tip: "Run `tail -f .mandu/watch.log` in another terminal for real-time warnings.",
         };
       } catch (error) {
         return {
@@ -288,6 +349,28 @@ export function brainTools(projectRoot: string) {
       }
     },
 
+    mandu_watch_stop: async () => {
+      try {
+        // Clean up MCP notification subscription
+        if (mcpWarningUnsubscribe) {
+          mcpWarningUnsubscribe();
+          mcpWarningUnsubscribe = null;
+        }
+
+        stopWatcher();
+
+        return {
+          success: true,
+          message: "Watch stopped and notifications cleaned up",
+        };
+      } catch (error) {
+        return {
+          error: "Failed to stop watch",
+          details: error instanceof Error ? error.message : "Unknown error",
+        };
+      }
+    },
+
     // Architecture tools (v0.2)
     mandu_check_location: async (args: Record<string, unknown>) => {
       const { path: filePath, content } = args as {