@mandujs/mcp 0.18.8 → 0.18.10

package/src/tx-lock.ts

@@ -0,0 +1,73 @@
+/**
+ * Transaction Lock — prevents concurrent project mutations from multiple AI agents.
+ *
+ * In-process singleton. If no lock exists, destructive tools work as before (backward compatible).
+ * When a lock is held, only the holder (matching lockId) may execute destructive operations.
+ */
+
+export interface TxLock {
+  lockId: string;
+  sessionId: string;
+  acquiredAt: number;
+  timeoutMs: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+
+let activeLock: TxLock | null = null;
+
+function isExpired(lock: TxLock): boolean {
+  return Date.now() - lock.acquiredAt > lock.timeoutMs;
+}
+
+export function acquireLock(
+  sessionId: string,
+  timeoutMs: number = DEFAULT_TIMEOUT_MS,
+): { success: boolean; lockId?: string; error?: string } {
+  if (activeLock) {
+    if (isExpired(activeLock)) {
+      activeLock = null; // auto-release stale lock
+    } else {
+      return {
+        success: false,
+        error: `Lock held by session "${activeLock.sessionId}" since ${new Date(activeLock.acquiredAt).toISOString()}`,
+      };
+    }
+  }
+  const lockId = crypto.randomUUID();
+  activeLock = { lockId, sessionId, acquiredAt: Date.now(), timeoutMs };
+  return { success: true, lockId };
+}
+
+export function releaseLock(lockId: string): boolean {
+  if (!activeLock || activeLock.lockId !== lockId) return false;
+  activeLock = null;
+  return true;
+}
+
+export function checkLock(): {
+  locked: boolean;
+  lockId?: string;
+  sessionId?: string;
+  acquiredAt?: number;
+} {
+  if (activeLock && isExpired(activeLock)) {
+    activeLock = null;
+  }
+  if (!activeLock) return { locked: false };
+  return {
+    locked: true,
+    lockId: activeLock.lockId,
+    sessionId: activeLock.sessionId,
+    acquiredAt: activeLock.acquiredAt,
+  };
+}
+
+export function requireLock(lockId?: string): { allowed: boolean; error?: string } {
+  if (!activeLock || isExpired(activeLock)) return { allowed: true };
+  if (lockId === activeLock.lockId) return { allowed: true };
+  return {
+    allowed: false,
+    error: `Project is locked by session "${activeLock.sessionId}". Provide a matching lockId or wait for expiry.`,
+  };
+}

package/src/utils/project.ts

@@ -3,19 +3,44 @@ import fs from "fs/promises";
 import { pathToFileURL } from "url";
 
 /**
- * Find the Mandu project root by looking for app/ directory or mandu.config.*
+ * Find the Mandu project root by looking for mandu.config.* or app/ directory.
+ *
+ * Detection order (first match wins):
+ *  1. mandu.config.ts / .js / .json in the current directory
+ *  2. app/ directory in the current directory
+ *  3. Walk up to parent directories and repeat
+ *
+ * For monorepo sub-projects (e.g. demo/ai-chat inside a larger workspace),
+ * the config file takes priority so that the MCP server binds to the correct
+ * sub-project even when launched from the monorepo root.
+ *
+ * ## Monorepo Sub-Project Setup
+ *
+ * When using MCP in a monorepo sub-project, the recommended `.mcp.json` is:
+ *
+ * ```json
+ * {
+ *   "mcpServers": {
+ *     "mandu": {
+ *       "command": "bun",
+ *       "args": ["run", "node_modules/@mandujs/mcp/src/index.ts"],
+ *       "cwd": "."
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * The sub-project must have `@mandujs/mcp` as a devDependency.
+ * Using a `cwd` that points to a parent monorepo root will NOT work because
+ * the MCP stdio transport resolves paths relative to the spawned process,
+ * and the parent's node_modules layout differs from the sub-project's.
  */
 export async function findProjectRoot(startDir: string = process.cwd()): Promise<string | null> {
   let currentDir = path.resolve(startDir);
 
   while (currentDir !== path.dirname(currentDir)) {
-    // Check for app/ directory (FS Routes source)
-    try {
-      const appStat = await fs.stat(path.join(currentDir, "app"));
-      if (appStat.isDirectory()) return currentDir;
-    } catch {}
-
-    // Check for mandu.config.* files
+    // Prioritize config files — they unambiguously mark a Mandu project root,
+    // which is critical for monorepo sub-projects that each have their own config.
     for (const configFile of ["mandu.config.ts", "mandu.config.js", "mandu.config.json"]) {
       try {
         await fs.access(path.join(currentDir, configFile));
@@ -23,6 +48,21 @@ export async function findProjectRoot(startDir: string = process.cwd()): Promise
       } catch {}
     }
 
+    // Check for app/ directory (FS Routes source)
+    try {
+      const appStat = await fs.stat(path.join(currentDir, "app"));
+      if (appStat.isDirectory()) {
+        // Extra guard: only treat this as a Mandu project if it also has
+        // package.json (avoids false positives from unrelated app/ dirs)
+        try {
+          await fs.access(path.join(currentDir, "package.json"));
+          return currentDir;
+        } catch {
+          // No package.json — likely not a Mandu project, keep searching
+        }
+      }
+    } catch {}
+
     currentDir = path.dirname(currentDir);
   }
 
@@ -38,7 +78,6 @@ export function getProjectPaths(rootDir: string) {
     appDir: path.join(rootDir, "app"),
     specDir: path.join(rootDir, "spec"),
     manifestPath: path.join(rootDir, ".mandu", "routes.manifest.json"),
-    lockPath: path.join(rootDir, ".mandu", "spec.lock.json"),
     slotsDir: path.join(rootDir, "spec", "slots"),
     contractsDir: path.join(rootDir, "spec", "contracts"),
     historyDir: path.join(rootDir, ".mandu", "history"),

package/src/utils/runtime-control.ts

@@ -0,0 +1,52 @@
+import path from "path";
+
+export interface RuntimeControlRecord {
+  mode: "dev" | "start";
+  port: number;
+  token: string;
+  baseUrl: string;
+  startedAt: string;
+}
+
+const RUNTIME_CONTROL_RELATIVE_PATH = path.join(".mandu", "runtime-control.json");
+
+export async function readRuntimeControl(rootDir: string): Promise<RuntimeControlRecord | null> {
+  try {
+    const file = Bun.file(path.join(rootDir, RUNTIME_CONTROL_RELATIVE_PATH));
+    if (!(await file.exists())) {
+      return null;
+    }
+    return await file.json() as RuntimeControlRecord;
+  } catch {
+    return null;
+  }
+}
+
+export async function requestRuntimeCache(
+  rootDir: string,
+  action: "stats" | "clear",
+  payload: Record<string, unknown> = {}
+): Promise<{ control: RuntimeControlRecord; response: Response; body: unknown } | null> {
+  const control = await readRuntimeControl(rootDir);
+  if (!control) {
+    return null;
+  }
+
+  const response = await fetch(`${control.baseUrl}/_mandu/cache`, {
+    method: action === "stats" ? "GET" : "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-mandu-control-token": control.token,
+    },
+    ...(action === "clear" ? { body: JSON.stringify(payload) } : {}),
+  });
+
+  let body: unknown = null;
+  try {
+    body = await response.json();
+  } catch {
+    // ignore invalid JSON
+  }
+
+  return { control, response, body };
+}

package/src/utils/withWarnings.ts

@@ -4,7 +4,7 @@
  * Mutation 도구(write_slot, add_route, generate 등) 실행 후
  * watcher 경고를 자동으로 응답에 포함시킨다.
  *
- * MCP notification이 Claude Code에 전달되지 않는 문제를 해결.
+ * MCP notification이 AI 에이전트에 전달되지 않는 문제를 해결.
  */
 
 import { getWatcher } from "../../../core/src/index.js";
@@ -14,6 +14,7 @@ const MUTATION_TOOLS = new Set([
   "mandu_add_route",
   "mandu_update_route",
   "mandu_delete_route",
+  "mandu.generate",
   "mandu_generate",
   "mandu_build",
   "mandu_commit",