@rethunk/mcp-multi-root-git 1.0.0

package/dist/server/git-status-tool.js

@@ -0,0 +1,84 @@
+import { join, resolve } from "node:path";
+import { z } from "zod";
+import { isStrictlyUnderGitTop } from "../repo-paths.js";
+import { asyncPool, GIT_SUBPROCESS_PARALLELISM, gitStatusShortBranchAsync, gitTopLevel, hasGitMetadata, parseGitSubmodulePaths, } from "./git.js";
+import { jsonRespond } from "./json.js";
+import { requireGitAndRoots } from "./roots.js";
+import { WorkspacePickSchema } from "./schemas.js";
+export function registerGitStatusTool(server) {
+    server.addTool({
+        name: "git_status",
+        description: "Run `git status --short -b` in the workspace root and (optionally) each path from `.gitmodules`. " +
+            "Read-only. Supports multi-root MCP workspaces via `allWorkspaceRoots` or `rootIndex`.",
+        parameters: WorkspacePickSchema.extend({
+            includeSubmodules: z
+                .boolean()
+                .optional()
+                .default(true)
+                .describe("When true (default), include submodule paths listed in .gitmodules."),
+        }),
+        execute: async (args) => {
+            const pre = requireGitAndRoots(server, args, undefined);
+            if (!pre.ok) {
+                return jsonRespond(pre.error);
+            }
+            const groups = [];
+            for (const rootInput of pre.roots) {
+                const repos = [];
+                const top = gitTopLevel(rootInput);
+                if (!top) {
+                    repos.push({
+                        label: rootInput,
+                        path: rootInput,
+                        statusText: "not a git repository",
+                        ok: false,
+                    });
+                    groups.push({ mcpRoot: rootInput, repos });
+                    continue;
+                }
+                const includeSubmodules = args.includeSubmodules !== false;
+                const meta = await gitStatusShortBranchAsync(top);
+                repos.push({ label: ".", path: top, statusText: meta.text, ok: meta.ok });
+                if (includeSubmodules) {
+                    const rels = parseGitSubmodulePaths(top);
+                    const subRows = await asyncPool(rels, GIT_SUBPROCESS_PARALLELISM, async (rel) => {
+                        const subPath = resolve(join(top, rel));
+                        if (!isStrictlyUnderGitTop(subPath, top)) {
+                            return {
+                                label: rel,
+                                path: subPath,
+                                statusText: "(submodule path escapes repository — rejected)",
+                                ok: false,
+                            };
+                        }
+                        if (!hasGitMetadata(subPath)) {
+                            return {
+                                label: rel,
+                                path: subPath,
+                                statusText: "(no .git — submodule not checked out?)",
+                                ok: false,
+                            };
+                        }
+                        const st = await gitStatusShortBranchAsync(subPath);
+                        return { label: rel, path: subPath, statusText: st.text, ok: st.ok };
+                    });
+                    repos.push(...subRows);
+                }
+                groups.push({ mcpRoot: rootInput, repos });
+            }
+            if (args.format === "json") {
+                return jsonRespond({ groups });
+            }
+            const sections = ["# Multi-root git status", ""];
+            for (const g of groups) {
+                if (groups.length > 1) {
+                    sections.push(`### MCP root: ${g.mcpRoot}`, "");
+                }
+                for (const row of g.repos) {
+                    sections.push(`## ${row.label}`, `path: ${row.path}`, "```text", row.statusText || "(empty)", "```", ``);
+                }
+            }
+            return sections.join("\n");
+        },
+    });
+}

package/dist/server/git.js

@@ -0,0 +1,165 @@
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/** Parallel git subprocesses for inventory rows and git_status submodule rows. */
+export const GIT_SUBPROCESS_PARALLELISM = 4;
+let gitPathState = "unknown";
+const GIT_NOT_FOUND_BODY = {
+    error: "git_not_found",
+    message: "The `git` binary was not found on PATH or failed `git --version`. Install Git and ensure it is available to the MCP server process.",
+};
+export function gateGit() {
+    if (gitPathState === "ok") {
+        return { ok: true };
+    }
+    if (gitPathState === "missing") {
+        return {
+            ok: false,
+            body: GIT_NOT_FOUND_BODY,
+        };
+    }
+    const r = spawnSync("git", ["--version"], { encoding: "utf8" });
+    if (r.status !== 0) {
+        gitPathState = "missing";
+        return {
+            ok: false,
+            body: GIT_NOT_FOUND_BODY,
+        };
+    }
+    gitPathState = "ok";
+    return { ok: true };
+}
+// ---------------------------------------------------------------------------
+// Git helpers (sync — used where async batching not needed)
+// ---------------------------------------------------------------------------
+export function gitTopLevel(cwd) {
+    const r = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+        cwd,
+        encoding: "utf8",
+    });
+    if (r.status !== 0)
+        return null;
+    return r.stdout.trim();
+}
+export function gitRevParseGitDir(cwd) {
+    const r = spawnSync("git", ["rev-parse", "--git-dir"], {
+        cwd,
+        encoding: "utf8",
+    });
+    return r.status === 0;
+}
+export function gitRevParseHead(cwd) {
+    const r = spawnSync("git", ["rev-parse", "HEAD"], {
+        cwd,
+        encoding: "utf8",
+    });
+    if (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() };
+}
+export function parseGitSubmodulePaths(gitRoot) {
+    const f = join(gitRoot, ".gitmodules");
+    if (!existsSync(f))
+        return [];
+    const text = readFileSync(f, "utf8");
+    const paths = [];
+    for (const line of text.split("\n")) {
+        const m = /^\s*path\s*=\s*(.+)\s*$/.exec(line);
+        if (m?.[1])
+            paths.push(m[1].trim());
+    }
+    return paths;
+}
+export function hasGitMetadata(dir) {
+    return existsSync(join(dir, ".git"));
+}
+/** Conservative checks for remote/branch strings passed into git rev-parse / rev-list argv. */
+export function isSafeGitUpstreamToken(s) {
+    const t = s.trim();
+    if (t.length === 0 || t.length > 256)
+        return false;
+    if (t.includes(".."))
+        return false;
+    if (t.startsWith("-"))
+        return false;
+    if (t.includes("@"))
+        return false;
+    const forbidden = new Set("{}[]~^:?*\\".split(""));
+    for (let i = 0; i < t.length; i++) {
+        const ch = t.charAt(i);
+        const c = ch.charCodeAt(0);
+        if (c < 32 || c === 127)
+            return false;
+        if (/\s/.test(ch))
+            return false;
+        if (forbidden.has(ch))
+            return false;
+    }
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Async pool for parallel git (inventory)
+// ---------------------------------------------------------------------------
+export async function asyncPool(items, concurrency, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    async function worker() {
+        for (;;) {
+            const i = next++;
+            if (i >= items.length)
+                break;
+            const item = items[i];
+            if (item === undefined)
+                break;
+            results[i] = await fn(item);
+        }
+    }
+    const n = Math.min(Math.max(1, concurrency), Math.max(1, items.length));
+    await Promise.all(Array.from({ length: n }, () => worker()));
+    return results;
+}
+export function spawnGitAsync(cwd, args) {
+    return new Promise((resolveP) => {
+        const child = spawn("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.setEncoding("utf8");
+        child.stderr?.setEncoding("utf8");
+        child.stdout?.on("data", (c) => {
+            stdout += c;
+        });
+        child.stderr?.on("data", (c) => {
+            stderr += c;
+        });
+        child.on("error", () => resolveP({ ok: false, stdout, stderr }));
+        child.on("close", (code) => resolveP({ ok: code === 0, stdout, stderr }));
+    });
+}
+function gitStatusFailText(r) {
+    return (r.stderr || r.stdout || "git status failed").trim();
+}
+export async function gitStatusSnapshotAsync(cwd) {
+    const [br, sh] = await Promise.all([
+        spawnGitAsync(cwd, ["status", "--short", "-b"]),
+        spawnGitAsync(cwd, ["status", "--short"]),
+    ]);
+    return {
+        branchOk: br.ok,
+        shortOk: sh.ok,
+        branchLine: br.ok ? br.stdout.trimEnd() : gitStatusFailText(br),
+        shortLine: sh.ok ? sh.stdout.trimEnd() : gitStatusFailText(sh),
+    };
+}
+export async function gitStatusShortBranchAsync(cwd) {
+    const s = await gitStatusSnapshotAsync(cwd);
+    return { ok: s.branchOk, text: s.branchLine };
+}
+export async function fetchAheadBehind(absPath, upstreamSpec) {
+    const aheadR = await spawnGitAsync(absPath, ["rev-list", "--count", `${upstreamSpec}..HEAD`]);
+    const behindR = await spawnGitAsync(absPath, ["rev-list", "--count", `HEAD..${upstreamSpec}`]);
+    return {
+        ahead: aheadR.ok ? aheadR.stdout.trim() : null,
+        behind: behindR.ok ? behindR.stdout.trim() : null,
+    };
+}

package/dist/server/inventory.js

@@ -0,0 +1,133 @@
+import { assertRelativePathUnderTop, resolvePathForRepo } from "../repo-paths.js";
+import { fetchAheadBehind, gitStatusSnapshotAsync, spawnGitAsync } from "./git.js";
+export const MAX_INVENTORY_ROOTS_DEFAULT = 64;
+export function validateRepoPath(rel, gitTop) {
+    const abs = resolvePathForRepo(rel, gitTop);
+    return { abs, underTop: assertRelativePathUnderTop(rel, abs, gitTop) };
+}
+export function makeSkipEntry(label, abs, upstreamMode, skipReason) {
+    return {
+        label,
+        path: abs,
+        branchStatus: "",
+        shortStatus: "",
+        detached: false,
+        headAbbrev: "",
+        upstreamMode,
+        upstreamRef: null,
+        ahead: null,
+        behind: null,
+        upstreamNote: "",
+        skipReason,
+    };
+}
+export function buildInventorySectionMarkdown(e) {
+    if (e.skipReason) {
+        return [`## ${e.label}`, `path: ${e.path}`, "```text", e.skipReason, "```", ``];
+    }
+    const lines = [];
+    lines.push(e.branchStatus);
+    lines.push("");
+    lines.push("short:");
+    lines.push(e.shortStatus || "(clean)");
+    lines.push("");
+    if (e.detached) {
+        lines.push("branch: (detached HEAD)");
+        lines.push("");
+    }
+    if (e.ahead != null && e.behind != null && e.upstreamRef) {
+        lines.push(`ahead_of_${e.upstreamRef.replace(/\//g, "_")}: ${e.ahead}`);
+        lines.push(`behind_${e.upstreamRef.replace(/\//g, "_")}: ${e.behind}`);
+    }
+    else {
+        lines.push(`upstream: ${e.upstreamNote}`);
+    }
+    return [`## ${e.label}`, `path: ${e.path}`, "```text", lines.join("\n"), "```", ``];
+}
+function upstreamNoteFor(ref, ahead, behind) {
+    return ahead != null && behind != null
+        ? `tracking ${ref}`
+        : `upstream ${ref} (counts unreadable)`;
+}
+export async function collectInventoryEntry(label, absPath, fixedRemote, fixedBranch) {
+    const [snap, headR] = await Promise.all([
+        gitStatusSnapshotAsync(absPath),
+        spawnGitAsync(absPath, ["rev-parse", "--abbrev-ref", "HEAD"]),
+    ]);
+    const branchStatus = snap.branchLine;
+    const shortStatus = snap.shortLine;
+    const headAbbrev = headR.ok ? headR.stdout.trim() : "";
+    const detached = !headR.ok || headAbbrev === "HEAD" || headAbbrev.endsWith("/HEAD");
+    const useFixed = fixedRemote !== undefined && fixedBranch !== undefined;
+    if (useFixed) {
+        const remote = fixedRemote;
+        const branch = fixedBranch;
+        const verify = await spawnGitAsync(absPath, ["rev-parse", "--verify", `${remote}/${branch}`]);
+        if (!verify.ok) {
+            return {
+                label,
+                path: absPath,
+                branchStatus,
+                shortStatus,
+                detached,
+                headAbbrev: headAbbrev || "(unknown)",
+                upstreamMode: "fixed",
+                upstreamRef: `${remote}/${branch}`,
+                ahead: null,
+                behind: null,
+                upstreamNote: `(no local ref ${remote}/${branch} or unreadable)`,
+            };
+        }
+        const ref = `${remote}/${branch}`;
+        const { ahead, behind } = await fetchAheadBehind(absPath, ref);
+        return {
+            label,
+            path: absPath,
+            branchStatus,
+            shortStatus,
+            detached,
+            headAbbrev: headAbbrev || "(unknown)",
+            upstreamMode: "fixed",
+            upstreamRef: ref,
+            ahead,
+            behind,
+            upstreamNote: upstreamNoteFor(ref, ahead, behind),
+        };
+    }
+    const upVerify = await spawnGitAsync(absPath, ["rev-parse", "--verify", "@{u}"]);
+    if (!upVerify.ok) {
+        let note = "no upstream configured";
+        if (detached) {
+            note = "detached HEAD — no upstream";
+        }
+        return {
+            label,
+            path: absPath,
+            branchStatus,
+            shortStatus,
+            detached,
+            headAbbrev: headAbbrev || "(unknown)",
+            upstreamMode: "auto",
+            upstreamRef: null,
+            ahead: null,
+            behind: null,
+            upstreamNote: note,
+        };
+    }
+    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 {
+        label,
+        path: absPath,
+        branchStatus,
+        shortStatus,
+        detached,
+        headAbbrev: headAbbrev || "(unknown)",
+        upstreamMode: "auto",
+        upstreamRef,
+        ahead,
+        behind,
+        upstreamNote: upstreamNoteFor(upstreamRef, ahead, behind),
+    };
+}

package/dist/server/json.js

@@ -0,0 +1,41 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+export const MCP_JSON_FORMAT_VERSION = "1";
+export function readPackageVersion() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkgPath = join(here, "..", "..", "package.json");
+    try {
+        const j = JSON.parse(readFileSync(pkgPath, "utf8"));
+        return j.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+/** FastMCP types require major.minor.patch; strip prerelease suffixes from package.json. */
+export function readMcpServerVersion() {
+    const raw = readPackageVersion().trim();
+    const m = /^(\d+)\.(\d+)\.(\d+)/.exec(raw);
+    if (m?.[1] !== undefined && m[2] !== undefined && m[3] !== undefined) {
+        return `${m[1]}.${m[2]}.${m[3]}`;
+    }
+    return "0.0.0";
+}
+export function jsonRespond(body) {
+    return JSON.stringify({
+        ...body,
+        rethunkGitMcp: {
+            jsonFormatVersion: MCP_JSON_FORMAT_VERSION,
+            packageVersion: readPackageVersion(),
+        },
+    }, null, 2);
+}
+/** Spread into an object literal only when `cond` is true; otherwise `{}`. */
+export function spreadWhen(cond, fields) {
+    return cond ? fields : {};
+}
+/** Spread `{ [key]: value }` only when `value` is not `undefined`. */
+export function spreadDefined(key, value) {
+    return spreadWhen(value !== undefined, { [key]: value });
+}

package/dist/server/list-presets-tool.js

@@ -0,0 +1,105 @@
+import { join } from "node:path";
+import { gitTopLevel } from "./git.js";
+import { jsonRespond, spreadDefined } from "./json.js";
+import { loadPresetsFromGitTop, PRESET_FILE_PATH, presetLoadErrorPayload } from "./presets.js";
+import { requireGitAndRoots } from "./roots.js";
+import { WorkspacePickSchema } from "./schemas.js";
+export function registerListPresetsTool(server) {
+    server.addTool({
+        name: "list_presets",
+        description: "List named entries from `.rethunk/git-mcp-presets.json` at the git toplevel for the resolved workspace root.",
+        parameters: WorkspacePickSchema.pick({
+            workspaceRoot: true,
+            rootIndex: true,
+            allWorkspaceRoots: true,
+            format: true,
+        }),
+        execute: async (args) => {
+            const pre = requireGitAndRoots(server, args, undefined);
+            if (!pre.ok) {
+                return jsonRespond(pre.error);
+            }
+            const out = [];
+            for (const ws of pre.roots) {
+                const top = gitTopLevel(ws);
+                const presetFile = top ? join(top, PRESET_FILE_PATH) : join(ws, PRESET_FILE_PATH);
+                if (!top) {
+                    out.push({
+                        workspaceRoot: ws,
+                        gitTop: null,
+                        presetFile,
+                        fileExists: false,
+                        presets: [],
+                        error: { error: "not_a_git_repository", path: ws },
+                    });
+                    continue;
+                }
+                const loaded = loadPresetsFromGitTop(top);
+                if (!loaded.ok) {
+                    if (loaded.reason === "missing") {
+                        out.push({
+                            workspaceRoot: ws,
+                            gitTop: top,
+                            presetFile,
+                            fileExists: false,
+                            presets: [],
+                        });
+                    }
+                    else {
+                        out.push({
+                            workspaceRoot: ws,
+                            gitTop: top,
+                            presetFile,
+                            fileExists: true,
+                            presets: [],
+                            error: presetLoadErrorPayload(top, loaded),
+                        });
+                    }
+                    continue;
+                }
+                const presets = Object.entries(loaded.data).map(([name, e]) => ({
+                    name,
+                    nestedRootsCount: e.nestedRoots?.length ?? 0,
+                    parityPairsCount: e.parityPairs?.length ?? 0,
+                    ...spreadDefined("workspaceRootHint", e.workspaceRootHint ? e.workspaceRootHint : undefined),
+                }));
+                out.push({
+                    workspaceRoot: ws,
+                    gitTop: top,
+                    presetFile,
+                    fileExists: true,
+                    ...spreadDefined("presetSchemaVersion", loaded.schemaVersion),
+                    presets,
+                });
+            }
+            if (args.format === "json") {
+                return jsonRespond({ roots: out });
+            }
+            const lines = ["# Git MCP presets", ""];
+            for (const row of out) {
+                lines.push(`## ${row.workspaceRoot}`, `git_top: ${row.gitTop ?? "(none)"}`, `preset_file: ${row.presetFile}`, "");
+                if (row.error) {
+                    lines.push("```json", JSON.stringify(row.error, null, 2), "```", "");
+                    continue;
+                }
+                if (!row.fileExists) {
+                    lines.push("(no preset file)", "");
+                    continue;
+                }
+                if (row.presets.length === 0) {
+                    lines.push("(empty preset file)", "");
+                    continue;
+                }
+                if (row.presetSchemaVersion !== undefined) {
+                    lines.push(`preset_schema_version: ${row.presetSchemaVersion}`, "");
+                }
+                for (const p of row.presets) {
+                    lines.push(`- **${p.name}**: nestedRoots=${p.nestedRootsCount}, parityPairs=${p.parityPairsCount}` +
+                        (p.workspaceRootHint ? `, hint=${p.workspaceRootHint}` : ""));
+                }
+                lines.push("");
+            }
+            return lines.join("\n");
+        },
+    });
+}

package/dist/server/presets-resource.js

@@ -0,0 +1,47 @@
+import { join } from "node:path";
+import { gitTopLevel } from "./git.js";
+import { jsonRespond, spreadDefined } from "./json.js";
+import { loadPresetsFromGitTop, PRESET_FILE_PATH, presetLoadErrorPayload } from "./presets.js";
+import { requireGitAndRoots } from "./roots.js";
+export function registerPresetsResource(server) {
+    server.addResource({
+        uri: "rethunk-git://presets",
+        name: "git-mcp-presets",
+        mimeType: "application/json",
+        async load() {
+            const pre = requireGitAndRoots(server, {}, undefined);
+            if (!pre.ok) {
+                return { text: jsonRespond(pre.error) };
+            }
+            const ws = pre.roots[0];
+            if (!ws) {
+                return { text: jsonRespond({ error: "no_workspace_root" }) };
+            }
+            const top = gitTopLevel(ws);
+            if (!top) {
+                return { text: jsonRespond({ error: "not_a_git_repository", path: ws }) };
+            }
+            const loaded = loadPresetsFromGitTop(top);
+            if (!loaded.ok) {
+                if (loaded.reason === "missing") {
+                    return {
+                        text: jsonRespond({
+                            presetFile: join(top, PRESET_FILE_PATH),
+                            fileExists: false,
+                            presets: {},
+                        }),
+                    };
+                }
+                return { text: jsonRespond(presetLoadErrorPayload(top, loaded)) };
+            }
+            return {
+                text: jsonRespond({
+                    presetFile: join(top, PRESET_FILE_PATH),
+                    fileExists: true,
+                    ...spreadDefined("presetSchemaVersion", loaded.schemaVersion),
+                    presets: loaded.data,
+                }),
+            };
+        },
+    });
+}