@rethunk/mcp-multi-root-git 3.1.0 → 4.0.0

package/dist/server/git.js

@@ -7,13 +7,11 @@ import { ERROR_CODES } from "./error-codes.js";
  * Parallel git subprocesses for inventory rows and git_status submodule rows.
  * Reads from GIT_SUBPROCESS_PARALLELISM env var (default 4), clamped to [1, 2×CPU_COUNT].
  */
-function resolveGitSubprocessParallelism() {
-    const env = process.env.GIT_SUBPROCESS_PARALLELISM;
-    if (env) {
-        const n = Number.parseInt(env, 10);
+export function resolveGitSubprocessParallelism(envValue = process.env.GIT_SUBPROCESS_PARALLELISM, cpuCount = cpus().length) {
+    if (envValue) {
+        const n = Number.parseInt(envValue, 10);
         if (!Number.isNaN(n) && n >= 1) {
-            const cpuCount = cpus().length;
-            const maxParallel = cpuCount * 2;
+            const maxParallel = Math.max(1, cpuCount * 2);
             return Math.min(n, maxParallel);
         }
     }
@@ -26,10 +24,9 @@ export const GIT_SUBPROCESS_PARALLELISM = resolveGitSubprocessParallelism();
  * A value of 0 (or negative/NaN) disables the timeout — use for operations
  * like large clones where unbounded wait is intentional.
  */
-function resolveGitSubprocessTimeoutMs() {
-    const env = process.env.GIT_SUBPROCESS_TIMEOUT_MS;
-    if (env) {
-        const n = Number.parseInt(env, 10);
+export function resolveGitSubprocessTimeoutMs(envValue = process.env.GIT_SUBPROCESS_TIMEOUT_MS) {
+    if (envValue) {
+        const n = Number.parseInt(envValue, 10);
         if (!Number.isNaN(n) && n > 0)
             return n;
         // 0 or negative → disabled
@@ -39,10 +36,31 @@ function resolveGitSubprocessTimeoutMs() {
     return 120_000;
 }
 export const GIT_SUBPROCESS_TIMEOUT_MS = resolveGitSubprocessTimeoutMs();
+/**
+ * Max combined stdout+stderr bytes retained from spawnGitAsync.
+ * Env: GIT_SUBPROCESS_MAX_BUFFER_BYTES (default 16 MiB). Exceeding kills the child.
+ */
+export function resolveGitSubprocessMaxBufferBytes(envValue = process.env.GIT_SUBPROCESS_MAX_BUFFER_BYTES) {
+    if (envValue) {
+        const n = Number.parseInt(envValue, 10);
+        if (!Number.isNaN(n) && n >= 1024)
+            return n;
+    }
+    return 16 * 1024 * 1024;
+}
+export const GIT_SUBPROCESS_MAX_BUFFER_BYTES = resolveGitSubprocessMaxBufferBytes();
+/** Delay after SIGTERM before escalating to SIGKILL (spawnGitAsync timeout/abort/overflow). */
+export const GIT_SUBPROCESS_SIGKILL_ESCALATION_MS = 2_000;
+/** Timeout for sync spawnSync helpers (gateGit, rev-parse). */
+export const GIT_SYNC_TIMEOUT_MS = 30_000;
 let gitPathState = "unknown";
 const GIT_NOT_FOUND_BODY = {
     error: ERROR_CODES.GIT_NOT_FOUND,
 };
+/** Test-only: reset the cached git-on-PATH probe. */
+export function resetGitPathStateForTests() {
+    gitPathState = "unknown";
+}
 export function gateGit() {
     if (gitPathState === "ok") {
         return { ok: true };
@@ -53,9 +71,16 @@ export function gateGit() {
             body: GIT_NOT_FOUND_BODY,
         };
     }
-    const r = spawnSync("git", ["--version"], { encoding: "utf8" });
-    if (r.status !== 0) {
-        gitPathState = "missing";
+    const r = spawnSync("git", ["--version"], {
+        encoding: "utf8",
+        timeout: GIT_SYNC_TIMEOUT_MS,
+    });
+    if (r.error || r.status !== 0) {
+        // Do not cache "missing" on timeout — a wedged git may recover.
+        const timedOut = r.error !== undefined && r.error.code === "ETIMEDOUT";
+        if (!timedOut) {
+            gitPathState = "missing";
+        }
         return {
             ok: false,
             body: GIT_NOT_FOUND_BODY,
@@ -71,8 +96,9 @@ export function gitTopLevel(cwd) {
     const r = spawnSync("git", ["rev-parse", "--show-toplevel"], {
         cwd,
         encoding: "utf8",
+        timeout: GIT_SYNC_TIMEOUT_MS,
     });
-    if (r.status !== 0)
+    if (r.error || r.status !== 0)
         return null;
     return r.stdout.trim();
 }
@@ -80,15 +106,17 @@ export function gitRevParseGitDir(cwd) {
     const r = spawnSync("git", ["rev-parse", "--git-dir"], {
         cwd,
         encoding: "utf8",
+        timeout: GIT_SYNC_TIMEOUT_MS,
     });
-    return r.status === 0;
+    return !r.error && r.status === 0;
 }
 export function gitRevParseHead(cwd) {
     const r = spawnSync("git", ["rev-parse", "HEAD"], {
         cwd,
         encoding: "utf8",
+        timeout: GIT_SYNC_TIMEOUT_MS,
     });
-    if (r.status !== 0) {
+    if (r.error || r.status !== 0) {
         return { ok: false, text: (r.stderr || r.stdout || "git rev-parse HEAD failed").trim() };
     }
     return { ok: true, sha: r.stdout.trim(), text: r.stdout.trim() };
@@ -163,17 +191,70 @@ export async function asyncPool(items, concurrency, fn) {
 }
 export function spawnGitAsync(cwd, args, opts) {
     return new Promise((resolveP) => {
-        const child = spawn("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+        const child = spawn("git", args, { cwd, stdio: ["pipe", "pipe", "pipe"] });
         let stdout = "";
         let stderr = "";
         let settled = false;
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let sigkillTimer;
+        const maxBuffer = opts?.maxBufferBytes ?? GIT_SUBPROCESS_MAX_BUFFER_BYTES;
+        const sigkillAfter = opts?.sigkillAfterMs ?? GIT_SUBPROCESS_SIGKILL_ESCALATION_MS;
+        if (!opts?.holdStdin) {
+            child.stdin?.end();
+        }
         child.stdout?.setEncoding("utf8");
         child.stderr?.setEncoding("utf8");
+        function escalateKill() {
+            try {
+                child.kill("SIGTERM");
+            }
+            catch {
+                /* already dead */
+            }
+            if (sigkillTimer !== undefined)
+                return;
+            sigkillTimer = setTimeout(() => {
+                sigkillTimer = undefined;
+                try {
+                    if (!settled && child.exitCode === null && child.signalCode === null) {
+                        child.kill("SIGKILL");
+                    }
+                }
+                catch {
+                    /* already dead */
+                }
+            }, sigkillAfter);
+            // Do not keep the process alive solely for SIGKILL escalation.
+            if (typeof sigkillTimer === "object" && "unref" in sigkillTimer) {
+                sigkillTimer.unref();
+            }
+        }
+        function onChunk(stream, chunk) {
+            const byteLen = Buffer.byteLength(chunk, "utf8");
+            if (stream === "stdout") {
+                stdoutBytes += byteLen;
+                stdout += chunk;
+            }
+            else {
+                stderrBytes += byteLen;
+                stderr += chunk;
+            }
+            if (stdoutBytes + stderrBytes > maxBuffer) {
+                escalateKill();
+                settle({
+                    ok: false,
+                    stdout,
+                    stderr: `${stderr}\n<git output exceeded ${maxBuffer} bytes>`,
+                    truncated: true,
+                });
+            }
+        }
         child.stdout?.on("data", (c) => {
-            stdout += c;
+            onChunk("stdout", c);
         });
         child.stderr?.on("data", (c) => {
-            stderr += c;
+            onChunk("stderr", c);
         });
         const effectiveTimeout = opts?.timeoutMs ?? GIT_SUBPROCESS_TIMEOUT_MS;
         let timer;
@@ -183,10 +264,20 @@ export function spawnGitAsync(cwd, args, opts) {
                 clearTimeout(timer);
                 timer = undefined;
             }
+            if (sigkillTimer !== undefined) {
+                clearTimeout(sigkillTimer);
+                sigkillTimer = undefined;
+            }
             if (abortListener !== undefined && opts?.signal) {
                 opts.signal.removeEventListener("abort", abortListener);
                 abortListener = undefined;
             }
+            try {
+                child.stdin?.destroy();
+            }
+            catch {
+                /* ignore */
+            }
         }
         function settle(result) {
             if (settled)
@@ -195,15 +286,18 @@ export function spawnGitAsync(cwd, args, opts) {
             cleanup();
             resolveP(result);
         }
+        // Register lifecycle handlers before any early kill so close/error are observed.
+        child.on("error", () => settle({ ok: false, stdout, stderr }));
+        child.on("close", (code) => settle({ ok: code === 0, stdout, stderr }));
         // AbortSignal: kill immediately if already aborted, else listen
         if (opts?.signal) {
             if (opts.signal.aborted) {
-                child.kill("SIGTERM");
+                escalateKill();
                 settle({ ok: false, stdout, stderr, aborted: true });
                 return;
             }
             abortListener = () => {
-                child.kill("SIGTERM");
+                escalateKill();
                 settle({ ok: false, stdout, stderr, aborted: true });
             };
             opts.signal.addEventListener("abort", abortListener, { once: true });
@@ -211,7 +305,7 @@ export function spawnGitAsync(cwd, args, opts) {
         // Timeout: set timer if effectiveTimeout > 0
         if (effectiveTimeout > 0) {
             timer = setTimeout(() => {
-                child.kill("SIGTERM");
+                escalateKill();
                 settle({
                     ok: false,
                     stdout,
@@ -220,8 +314,6 @@ export function spawnGitAsync(cwd, args, opts) {
                 });
             }, effectiveTimeout);
         }
-        child.on("error", () => settle({ ok: false, stdout, stderr }));
-        child.on("close", (code) => settle({ ok: code === 0, stdout, stderr }));
     });
 }
 function gitStatusFailText(r) {

package/dist/server/inventory.js

@@ -22,6 +22,15 @@ export function buildInventorySectionMarkdown(e) {
     else if (e.upstreamNote) {
         lines.push(`upstream: ${e.upstreamNote}`);
     }
+    if (e.compareRefs) {
+        const cr = e.compareRefs;
+        if (cr.ahead !== undefined && cr.behind !== undefined) {
+            lines.push(`${cr.left}...${cr.right}: ahead ${cr.ahead}, behind ${cr.behind}`);
+        }
+        else if (cr.note) {
+            lines.push(`compareRefs ${cr.left}...${cr.right}: ${cr.note}`);
+        }
+    }
     const single = lines.length === 1 ? lines[0] : undefined;
     if (single !== undefined && !single.includes("\n")) {
         return ["", header, single];
@@ -53,7 +62,48 @@ function buildEntry(params) {
         out.upstreamNote = params.upstreamNote;
     return out;
 }
-export async function collectInventoryEntry(label, absPath, fixedRemote, fixedBranch) {
+/**
+ * Ahead = commits reachable from `right` but not `left` (`left..right`).
+ * Behind = commits reachable from `left` but not `right` (`right..left`).
+ */
+async function fetchCompareAheadBehind(absPath, left, right) {
+    const [aheadR, behindR] = await Promise.all([
+        spawnGitAsync(absPath, ["rev-list", "--count", `${left}..${right}`]),
+        spawnGitAsync(absPath, ["rev-list", "--count", `${right}..${left}`]),
+    ]);
+    return {
+        ahead: aheadR.ok ? aheadR.stdout.trim() : null,
+        behind: behindR.ok ? behindR.stdout.trim() : null,
+    };
+}
+async function attachCompareRefs(entry, absPath, compareRefs) {
+    if (!compareRefs)
+        return entry;
+    const left = compareRefs.left;
+    const right = compareRefs.right;
+    const [leftOk, rightOk] = await Promise.all([
+        spawnGitAsync(absPath, ["rev-parse", "--verify", left]),
+        spawnGitAsync(absPath, ["rev-parse", "--verify", right]),
+    ]);
+    if (!leftOk.ok || !rightOk.ok) {
+        entry.compareRefs = {
+            left,
+            right,
+            note: `(ref unreadable: ${[!leftOk.ok ? left : "", !rightOk.ok ? right : ""].filter(Boolean).join(", ")})`,
+        };
+        return entry;
+    }
+    const { ahead, behind } = await fetchCompareAheadBehind(absPath, left, right);
+    entry.compareRefs = {
+        left,
+        right,
+        ...(ahead != null ? { ahead } : {}),
+        ...(behind != null ? { behind } : {}),
+        ...(ahead == null || behind == null ? { note: "(counts unreadable)" } : {}),
+    };
+    return entry;
+}
+export async function collectInventoryEntry(label, absPath, fixedRemote, fixedBranch, compareRefs) {
     const [snap, headR] = await Promise.all([
         gitStatusSnapshotAsync(absPath),
         spawnGitAsync(absPath, ["rev-parse", "--abbrev-ref", "HEAD"]),
@@ -62,11 +112,12 @@ export async function collectInventoryEntry(label, absPath, fixedRemote, fixedBr
     const headAbbrev = headR.ok ? headR.stdout.trim() : "";
     const detached = !headR.ok || headAbbrev === "HEAD" || headAbbrev.endsWith("/HEAD");
     const base = { label, absPath, branchStatus, detached, headAbbrev };
+    let entry;
     if (fixedRemote !== undefined && fixedBranch !== undefined) {
         const ref = `${fixedRemote}/${fixedBranch}`;
         const verify = await spawnGitAsync(absPath, ["rev-parse", "--verify", ref]);
         if (!verify.ok) {
-            return buildEntry({
+            entry = buildEntry({
                 ...base,
                 upstreamMode: "fixed",
                 upstreamRef: ref,
@@ -75,36 +126,43 @@ export async function collectInventoryEntry(label, absPath, fixedRemote, fixedBr
                 upstreamNote: `(no local ref ${ref} or unreadable)`,
             });
         }
-        const { ahead, behind } = await fetchAheadBehind(absPath, ref);
-        return buildEntry({
-            ...base,
-            upstreamMode: "fixed",
-            upstreamRef: ref,
-            ahead,
-            behind,
-            upstreamNote: upstreamNoteFor(ref, ahead != null && behind != null),
-        });
+        else {
+            const { ahead, behind } = await fetchAheadBehind(absPath, ref);
+            entry = buildEntry({
+                ...base,
+                upstreamMode: "fixed",
+                upstreamRef: ref,
+                ahead,
+                behind,
+                upstreamNote: upstreamNoteFor(ref, ahead != null && behind != null),
+            });
+        }
     }
-    const upVerify = await spawnGitAsync(absPath, ["rev-parse", "--verify", "@{u}"]);
-    if (!upVerify.ok) {
-        return buildEntry({
-            ...base,
-            upstreamMode: "auto",
-            upstreamRef: null,
-            ahead: null,
-            behind: null,
-            upstreamNote: detached ? "detached HEAD — no upstream" : "no upstream configured",
-        });
+    else {
+        const upVerify = await spawnGitAsync(absPath, ["rev-parse", "--verify", "@{u}"]);
+        if (!upVerify.ok) {
+            entry = buildEntry({
+                ...base,
+                upstreamMode: "auto",
+                upstreamRef: null,
+                ahead: null,
+                behind: null,
+                upstreamNote: detached ? "detached HEAD — no upstream" : "no upstream configured",
+            });
+        }
+        else {
+            const abbrevR = await spawnGitAsync(absPath, ["rev-parse", "--abbrev-ref", "@{u}"]);
+            const upstreamRef = abbrevR.ok ? abbrevR.stdout.trim() : "@{u}";
+            const { ahead, behind } = await fetchAheadBehind(absPath, "@{u}");
+            entry = buildEntry({
+                ...base,
+                upstreamMode: "auto",
+                upstreamRef,
+                ahead,
+                behind,
+                upstreamNote: upstreamNoteFor(upstreamRef, ahead != null && behind != null),
+            });
+        }
     }
-    const abbrevR = await spawnGitAsync(absPath, ["rev-parse", "--abbrev-ref", "@{u}"]);
-    const upstreamRef = abbrevR.ok ? abbrevR.stdout.trim() : "@{u}";
-    const { ahead, behind } = await fetchAheadBehind(absPath, "@{u}");
-    return buildEntry({
-        ...base,
-        upstreamMode: "auto",
-        upstreamRef,
-        ahead,
-        behind,
-        upstreamNote: upstreamNoteFor(upstreamRef, ahead != null && behind != null),
-    });
+    return attachCompareRefs(entry, absPath, compareRefs);
 }

package/dist/server/presets-resource.js

@@ -10,39 +10,56 @@ export function registerPresetsResource(server) {
         name: "git-mcp-presets",
         mimeType: "application/json",
         async load() {
-            const pre = requireGitAndRoots(server, {}, undefined);
+            const pre = requireGitAndRoots(server, { root: "*" }, undefined);
             if (!pre.ok) {
                 return { text: jsonRespond(pre.error) };
             }
-            const ws = pre.roots[0];
-            if (!ws) {
+            if (pre.roots.length === 0) {
                 return { text: jsonRespond({ error: ERROR_CODES.NO_WORKSPACE_ROOT }) };
             }
-            const top = gitTopLevel(ws);
-            if (!top) {
-                return { text: jsonRespond({ error: ERROR_CODES.NOT_A_GIT_REPOSITORY, path: ws }) };
-            }
-            const loaded = loadPresetsFromGitTop(top);
-            if (!loaded.ok) {
-                if (loaded.reason === "missing") {
+            const roots = pre.roots.map((ws) => {
+                const top = gitTopLevel(ws);
+                const presetFile = top ? join(top, PRESET_FILE_PATH) : join(ws, PRESET_FILE_PATH);
+                if (!top) {
                     return {
-                        text: jsonRespond({
-                            presetFile: join(top, PRESET_FILE_PATH),
+                        workspaceRoot: ws,
+                        gitTop: null,
+                        presetFile,
+                        fileExists: false,
+                        presets: {},
+                        error: { error: ERROR_CODES.NOT_A_GIT_REPOSITORY, path: ws },
+                    };
+                }
+                const loaded = loadPresetsFromGitTop(top);
+                if (!loaded.ok) {
+                    if (loaded.reason === "missing") {
+                        return {
+                            workspaceRoot: ws,
+                            gitTop: top,
+                            presetFile,
                             fileExists: false,
                             presets: {},
-                        }),
+                        };
+                    }
+                    return {
+                        workspaceRoot: ws,
+                        gitTop: top,
+                        presetFile,
+                        fileExists: true,
+                        presets: {},
+                        error: presetLoadErrorPayload(top, loaded),
                     };
                 }
-                return { text: jsonRespond(presetLoadErrorPayload(top, loaded)) };
-            }
-            return {
-                text: jsonRespond({
-                    presetFile: join(top, PRESET_FILE_PATH),
+                return {
+                    workspaceRoot: ws,
+                    gitTop: top,
+                    presetFile,
                     fileExists: true,
                     ...spreadDefined("presetSchemaVersion", loaded.schemaVersion),
                     presets: loaded.data,
-                }),
-            };
+                };
+            });
+            return { text: jsonRespond({ roots }) };
         },
     });
 }

package/dist/server/presets.js

@@ -5,21 +5,56 @@ import { ERROR_CODES } from "./error-codes.js";
 /**
  * Schema for `.rethunk/git-mcp-presets.json` at the workspace root.
  * Each named entry defines roots for `git_inventory` and/or pairs for `git_parity`.
+ * Must stay aligned with `git-mcp-presets.schema.json`.
  */
-const PresetEntrySchema = z.object({
+const ParityPairSchema = z
+    .object({
+    left: z.string(),
+    right: z.string(),
+    label: z.string().optional(),
+})
+    .strict();
+const PresetEntrySchema = z
+    .object({
     nestedRoots: z.array(z.string()).optional(),
-    parityPairs: z
-        .array(z.object({
-        left: z.string(),
-        right: z.string(),
-        label: z.string().optional(),
-    }))
-        .optional(),
+    parityPairs: z.array(ParityPairSchema).optional(),
     /** When multiple MCP file roots exist, prefer one whose path basename or suffix matches this hint. */
     workspaceRootHint: z.string().optional(),
-});
+})
+    .strict();
 const PresetFileSchema = z.record(z.string(), PresetEntrySchema);
 export const PRESET_FILE_PATH = ".rethunk/git-mcp-presets.json";
+const PRESET_ENTRY_FIELD_NAMES = new Set(["nestedRoots", "parityPairs", "workspaceRootHint"]);
+const WRAPPED_META_KEYS = new Set(["$schema", "schemaVersion", "presets"]);
+const PRESET_SCHEMA_VERSION = "1";
+function looksLikePresetEntryObject(obj) {
+    const keys = Object.keys(obj);
+    if (keys.length === 0)
+        return true;
+    return keys.every((k) => PRESET_ENTRY_FIELD_NAMES.has(k));
+}
+function isWrappedLayout(o) {
+    if (!("presets" in o))
+        return false;
+    const inner = o.presets;
+    if (inner === null || typeof inner !== "object" || Array.isArray(inner)) {
+        return false;
+    }
+    const innerObj = inner;
+    // Non-empty inner with only PresetEntry field names → legacy preset named "presets".
+    if (looksLikePresetEntryObject(innerObj) && Object.keys(innerObj).length > 0) {
+        return false;
+    }
+    // Empty inner: wrapped when top level has only metadata + presets.
+    if (Object.keys(innerObj).length === 0) {
+        const topKeys = Object.keys(o);
+        return topKeys.every((k) => WRAPPED_META_KEYS.has(k));
+    }
+    return true;
+}
+function schemaIssue(message, path = []) {
+    return { code: "custom", path, message };
+}
 /**
  * Supports:
  * - Wrapped: `{ "schemaVersion": "1", "presets": { "name": { ... } } }`
@@ -30,10 +65,12 @@ function splitPresetFileRaw(raw) {
         throw new Error("invalid_root");
     }
     const o = raw;
-    if ("presets" in o &&
-        o.presets !== null &&
-        typeof o.presets === "object" &&
-        !Array.isArray(o.presets)) {
+    if (isWrappedLayout(o)) {
+        for (const key of Object.keys(o)) {
+            if (!WRAPPED_META_KEYS.has(key)) {
+                throw new Error("wrapped_extra_keys");
+            }
+        }
         const sv = o.schemaVersion;
         return {
             mapRaw: o.presets,
@@ -69,13 +106,39 @@ export function loadPresetsFromGitTop(gitTop) {
         mapRaw = s.mapRaw;
         schemaVersion = s.schemaVersion;
     }
-    catch {
+    catch (e) {
+        if (e instanceof Error && e.message === "wrapped_extra_keys") {
+            return {
+                ok: false,
+                reason: "schema",
+                issues: [
+                    schemaIssue("Wrapped preset files allow only $schema, schemaVersion, and presets"),
+                ],
+            };
+        }
         return {
             ok: false,
             reason: "invalid_json",
             message: "Preset file root must be a JSON object",
         };
     }
+    if (schemaVersion !== undefined && schemaVersion !== PRESET_SCHEMA_VERSION) {
+        return {
+            ok: false,
+            reason: "schema",
+            issues: [schemaIssue(`schemaVersion must be "${PRESET_SCHEMA_VERSION}"`, ["schemaVersion"])],
+        };
+    }
+    if (mapRaw === null ||
+        typeof mapRaw !== "object" ||
+        Array.isArray(mapRaw) ||
+        Object.keys(mapRaw).length === 0) {
+        return {
+            ok: false,
+            reason: "schema",
+            issues: [schemaIssue("Preset file must contain at least one preset")],
+        };
+    }
     const parsed = PresetFileSchema.safeParse(mapRaw);
     if (!parsed.success) {
         return { ok: false, reason: "schema", issues: parsed.error.issues };
@@ -150,7 +213,16 @@ function mergePairs(preset, inline) {
     const b = inline ?? [];
     if (a.length === 0 && b.length === 0)
         return undefined;
-    return [...a, ...b];
+    const seen = new Set();
+    const out = [];
+    for (const pair of [...a, ...b]) {
+        const key = `${pair.left}\0${pair.right}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            out.push(pair);
+        }
+    }
+    return out;
 }
 export function applyPresetNestedRoots(gitTop, presetName, presetMerge, inlineNestedRoots) {
     const got = getPresetEntry(gitTop, presetName);

package/dist/server/roots.js

@@ -139,7 +139,19 @@ export function requireGitAndRoots(server, args, presetName) {
     const trimmed = root?.trim();
     if (trimmed === "*") {
         const fileRoots = listFileRoots(server);
-        return fileRoots.length === 0 ? defaultRoots(fileRoots) : { ok: true, roots: fileRoots };
+        if (fileRoots.length === 0)
+            return defaultRoots(fileRoots);
+        if (fileRoots.length > MAX_ROOT_PATHS) {
+            return {
+                ok: false,
+                error: {
+                    error: ERROR_CODES.ROOT_LIST_TOO_MANY,
+                    max: MAX_ROOT_PATHS,
+                    count: fileRoots.length,
+                },
+            };
+        }
+        return { ok: true, roots: fileRoots };
     }
     if (trimmed) {
         return { ok: true, roots: [resolve(trimmed)] };

package/dist/server/schemas.js

@@ -8,10 +8,17 @@ export const WorkspacePickSchema = z.object({
     workspaceRoot: z.string().optional().describe("Repo path. Default: first MCP root / cwd."),
     format: FormatSchema,
 });
-/** Fan-out tools: one polymorphic routing param plus output format. */
+/**
+ * Fan-out tools: one polymorphic routing param plus output format.
+ *
+ * Array length is intentionally uncapped here so `resolveRootPathList` can
+ * return the structured `{ error: root_list_too_many, max, count }` JSON
+ * payload. Zod `.max(MAX_ROOT_PATHS)` would reject with `too_big` before execute.
+ * The `"*"` sentinel is a plain string (no redundant `z.literal("*")`).
+ */
 export const RootPickSchema = z.object({
     root: z
-        .union([z.string(), z.array(z.string()).max(MAX_ROOT_PATHS), z.literal("*")])
+        .union([z.string(), z.array(z.string())])
         .optional()
         .describe('Repo path, array of paths, or "*" for all MCP roots.'),
     format: FormatSchema,