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

package/dist/server/git-branch-list-tool.js

@@ -1,138 +0,0 @@
-import { z } from "zod";
-import { ERROR_CODES } from "./error-codes.js";
-import { spawnGitAsync } from "./git.js";
-import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
-import { requireSingleRepo } from "./roots.js";
-import { WorkspacePickSchema } from "./schemas.js";
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-async function runBranchList(opts) {
-    const { top, includeRemotes } = opts;
-    // Local branches: name, full SHA, upstream (may be empty), HEAD marker (* or space)
-    const localR = await spawnGitAsync(top, [
-        "for-each-ref",
-        "--format=%(refname:short)%00%(objectname)%00%(upstream:short)%00%(HEAD)",
-        "refs/heads",
-    ]);
-    if (!localR.ok) {
-        return {
-            error: ERROR_CODES.BRANCH_LIST_FAILED,
-            detail: (localR.stderr || localR.stdout).trim(),
-        };
-    }
-    const branches = [];
-    const localLines = (localR.stdout || "").split("\n").filter((l) => l.length > 0);
-    for (const line of localLines) {
-        const parts = line.split("\x00");
-        const name = parts[0] ?? "";
-        const sha = parts[1] ?? "";
-        const upstream = parts[2] ?? "";
-        const headMarker = parts[3] ?? "";
-        if (!name || !sha)
-            continue;
-        branches.push({
-            name,
-            sha,
-            current: headMarker === "*",
-            ...spreadDefined("upstream", upstream || undefined),
-        });
-    }
-    if (!includeRemotes) {
-        return { branches };
-    }
-    // Remote branches: name, full SHA — skip symbolic origin/HEAD refs
-    const remoteR = await spawnGitAsync(top, [
-        "for-each-ref",
-        "--format=%(refname:short)%00%(objectname)",
-        "refs/remotes",
-    ]);
-    if (!remoteR.ok) {
-        return {
-            error: ERROR_CODES.BRANCH_LIST_FAILED,
-            detail: (remoteR.stderr || remoteR.stdout).trim(),
-        };
-    }
-    const remotes = [];
-    const remoteLines = (remoteR.stdout || "").split("\n").filter((l) => l.length > 0);
-    for (const line of remoteLines) {
-        const parts = line.split("\x00");
-        const name = parts[0] ?? "";
-        const sha = parts[1] ?? "";
-        // Skip symbolic origin/HEAD
-        if (!name || !sha || name.endsWith("/HEAD"))
-            continue;
-        remotes.push({ name, sha });
-    }
-    return {
-        branches,
-        ...spreadWhen(remotes.length > 0, { remotes }),
-    };
-}
-// ---------------------------------------------------------------------------
-// Markdown rendering
-// ---------------------------------------------------------------------------
-function renderBranchListMarkdown(result) {
-    const lines = ["## Branches", ""];
-    if (result.branches.length === 0) {
-        lines.push("_(none)_");
-    }
-    else {
-        for (const b of result.branches) {
-            const prefix = b.current ? "* " : "  ";
-            const upstream = b.upstream ? ` → ${b.upstream}` : "";
-            lines.push(`${prefix}**${b.name}**${upstream}  (\`${b.sha}\`)`);
-        }
-    }
-    if (result.remotes && result.remotes.length > 0) {
-        lines.push("");
-        lines.push("## Remote branches");
-        lines.push("");
-        for (const r of result.remotes) {
-            lines.push(`- **${r.name}**  (\`${r.sha}\`)`);
-        }
-    }
-    return lines.join("\n");
-}
-// ---------------------------------------------------------------------------
-// Tool registration
-// ---------------------------------------------------------------------------
-export function registerGitBranchListTool(server) {
-    server.addTool({
-        name: "git_branch_list",
-        description: "List local (and optionally remote-tracking) branches. Current branch marked `current: true`. Set `includeRemotes: true` for remotes.",
-        annotations: {
-            readOnlyHint: true,
-        },
-        parameters: WorkspacePickSchema.omit({ absoluteGitRoots: true, allWorkspaceRoots: true })
-            .pick({
-            workspaceRoot: true,
-            rootIndex: true,
-            format: true,
-        })
-            .extend({
-            includeRemotes: z
-                .boolean()
-                .optional()
-                .default(false)
-                .describe("Include remote-tracking branches from refs/remotes (symbolic origin/HEAD excluded)."),
-        }),
-        execute: async (args) => {
-            const pre = requireSingleRepo(server, args);
-            if (!pre.ok)
-                return jsonRespond(pre.error);
-            const { gitTop } = pre;
-            const result = await runBranchList({
-                top: gitTop,
-                includeRemotes: args.includeRemotes ?? false,
-            });
-            if ("error" in result) {
-                return jsonRespond(result);
-            }
-            if (args.format === "json") {
-                return jsonRespond(result);
-            }
-            return renderBranchListMarkdown(result);
-        },
-    });
-}

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

@@ -1,266 +0,0 @@
-import { z } from "zod";
-import { ERROR_CODES } from "./error-codes.js";
-import { isSafeGitUpstreamToken, spawnGitAsync } from "./git.js";
-import { jsonRespond, spreadWhen } from "./json.js";
-import { requireSingleRepo } from "./roots.js";
-import { WorkspacePickSchema } from "./schemas.js";
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-/**
- * Parse `git fetch` output to extract updated and new refs.
- * Lines containing "[new" indicate new refs (new branch, new tag, new ref).
- * Lines with " -> " but not containing "[new" indicate updated refs.
- */
-function parseGitFetchOutput(output) {
-    const lines = output.split("\n");
-    const updatedRefs = [];
-    const newRefs = [];
-    for (const line of lines) {
-        const trimmed = line.trim();
-        if (!trimmed)
-            continue;
-        // Lines containing "[new" indicate new refs (e.g. "[new branch]", "[new tag]", "[new ref]")
-        if (trimmed.includes("[new")) {
-            newRefs.push(trimmed);
-        }
-        // Lines with " -> " that don't contain "[new" indicate ref updates
-        else if (trimmed.includes(" -> ")) {
-            updatedRefs.push(trimmed);
-        }
-    }
-    return { updatedRefs, newRefs };
-}
-const ZEROS_SHA = "0000000000000000000000000000000000000000";
-/**
- * Parse `git fetch --porcelain` stdout.
- *
- * Machine-readable lines have the form:
- *   <flag><SP><old-sha><SP><new-sha><SP><local-ref>
- *
- * Flags:
- *   ' ' = fast-forward update
- *   '+' = forced update
- *   '*' = new ref
- *   '-' = pruned (deleted)
- *   '!' = rejected
- *   '=' = up-to-date (no change)
- *   't' = tag update
- */
-function parsePorcelainOutput(stdout) {
-    const updated = [];
-    const created = [];
-    const pruned = [];
-    for (const line of stdout.split("\n")) {
-        if (!line)
-            continue;
-        // Porcelain lines: flag(1) + space(1) + old-sha + space + new-sha + space + ref
-        // Minimum viable line: 1 flag + 1 space + at least some content
-        if (line.length < 3)
-            continue;
-        const flag = line[0];
-        const rest = line.slice(2); // skip "flag " prefix
-        const parts = rest.split(" ");
-        // Expected: [old-sha, new-sha, ref...]
-        if (parts.length < 3)
-            continue;
-        const oldSha = parts[0] ?? "";
-        const newSha = parts[1] ?? "";
-        const ref = parts.slice(2).join(" ");
-        if (!ref)
-            continue;
-        if (flag === "-") {
-            pruned.push({ ref });
-        }
-        else if (flag === "*" || oldSha === ZEROS_SHA) {
-            // New ref: flag is '*' OR old-sha is all-zeros
-            created.push({ ref, newSha, flag: flag ?? "*" });
-        }
-        else if (flag === " " || flag === "+" || flag === "t") {
-            // Update: old and new differ
-            if (oldSha !== newSha) {
-                updated.push({ ref, oldSha, newSha, flag: flag ?? " " });
-            }
-        }
-        // '!' (rejected) and '=' (up-to-date) are intentionally ignored
-    }
-    return { updated, created, pruned };
-}
-// ---------------------------------------------------------------------------
-// Tool registration
-// ---------------------------------------------------------------------------
-export function registerGitFetchTool(server) {
-    server.addTool({
-        name: "git_fetch",
-        description: "Fetch updates from a remote repository without modifying the working tree. " +
-            "Returns structured output distinguishing updated refs from new refs.",
-        annotations: {
-            readOnlyHint: false, // Fetch modifies refs but not working tree; not strictly read-only but safe
-        },
-        parameters: WorkspacePickSchema.omit({ absoluteGitRoots: true, allWorkspaceRoots: true })
-            .pick({
-            workspaceRoot: true,
-            rootIndex: true,
-            format: true,
-        })
-            .extend({
-            remote: z
-                .string()
-                .optional()
-                .default("origin")
-                .describe("Remote to fetch from (default: origin)."),
-            branch: z
-                .string()
-                .optional()
-                .describe("If specified: fetch only this branch (e.g. 'main')."),
-            prune: z
-                .boolean()
-                .optional()
-                .default(false)
-                .describe("Pass --prune to remove deleted remote branches (default: false)."),
-            tags: z
-                .boolean()
-                .optional()
-                .default(false)
-                .describe("Pass --tags to also fetch all tags (default: false)."),
-        }),
-        execute: async (args) => {
-            const pre = requireSingleRepo(server, args);
-            if (!pre.ok) {
-                return jsonRespond(pre.error);
-            }
-            const gitTop = pre.gitTop;
-            const remote = (args.remote ?? "origin").trim();
-            const branch = args.branch?.trim();
-            const prune = args.prune === true;
-            const tags = args.tags === true;
-            // Validate remote and branch to prevent argument injection.
-            if (!isSafeGitUpstreamToken(remote)) {
-                return jsonRespond({ error: ERROR_CODES.UNSAFE_REMOTE_TOKEN, remote });
-            }
-            if (branch && !isSafeGitUpstreamToken(branch)) {
-                return jsonRespond({ error: ERROR_CODES.UNSAFE_REF_TOKEN, branch });
-            }
-            // Build base fetch args (without --porcelain for now)
-            const baseArgs = ["fetch"];
-            if (prune) {
-                baseArgs.push("--prune");
-            }
-            if (tags) {
-                baseArgs.push("--tags");
-            }
-            baseArgs.push(remote);
-            if (branch) {
-                baseArgs.push(branch);
-            }
-            // --- Attempt structured fetch with --porcelain (requires git >= 2.41) ---
-            let structured = null;
-            let result;
-            const porcelainArgs = ["fetch", "--porcelain"];
-            if (prune)
-                porcelainArgs.push("--prune");
-            if (tags)
-                porcelainArgs.push("--tags");
-            porcelainArgs.push(remote);
-            if (branch)
-                porcelainArgs.push(branch);
-            const porcelainResult = await spawnGitAsync(gitTop, porcelainArgs);
-            if (!porcelainResult.ok &&
-                (porcelainResult.stderr.includes("unknown option") ||
-                    porcelainResult.stderr.includes("unknown switch") ||
-                    porcelainResult.stderr.includes("invalid option"))) {
-                // --porcelain not supported: fall back to plain fetch
-                result = await spawnGitAsync(gitTop, baseArgs);
-                structured = null;
-            }
-            else {
-                // Use porcelain result (ok or actual fetch error)
-                result = porcelainResult;
-                if (porcelainResult.ok || !porcelainResult.stderr.includes("unknown option")) {
-                    structured = parsePorcelainOutput(porcelainResult.stdout);
-                }
-            }
-            // Legacy string-line parse: use combined output when porcelain is unavailable.
-            // When porcelain succeeded, derive legacy fields from structured data so
-            // that callers who rely on updatedRefs/newRefs still get useful values.
-            let updatedRefs;
-            let newRefs;
-            if (structured !== null) {
-                // Derive legacy string arrays from structured deltas
-                updatedRefs = structured.updated.map((d) => `${d.oldSha.slice(0, 7)}..${d.newSha.slice(0, 7)}  ${d.ref}`);
-                newRefs = structured.created.map((d) => `[new ref] ${d.ref} -> ${d.newSha.slice(0, 7)}`);
-            }
-            else {
-                const parsed = parseGitFetchOutput(result.stdout + result.stderr);
-                updatedRefs = parsed.updatedRefs;
-                newRefs = parsed.newRefs;
-            }
-            const fetchResult = {
-                ok: result.ok,
-                remote,
-                updatedRefs,
-                newRefs,
-                output: (result.stdout + result.stderr).trim(),
-                ...spreadWhen(structured !== null && structured.updated.length > 0, {
-                    updated: structured?.updated ?? [],
-                }),
-                ...spreadWhen(structured !== null && structured.created.length > 0, {
-                    created: structured?.created ?? [],
-                }),
-                ...spreadWhen(structured !== null && structured.pruned.length > 0, {
-                    pruned: structured?.pruned ?? [],
-                }),
-            };
-            if (args.format === "json") {
-                return jsonRespond(fetchResult);
-            }
-            // Markdown output
-            const lines = [`# Git fetch from '${remote}'`];
-            if (!result.ok) {
-                lines.push("", "**Status**: Failed", "");
-                lines.push("```", result.stdout || result.stderr || "(no output)", "```");
-                return lines.join("\n");
-            }
-            lines.push("", "**Status**: Success", "");
-            // Prefer structured deltas in markdown when available
-            if (structured !== null && structured.updated.length > 0) {
-                lines.push("## Updated refs", "");
-                for (const d of structured.updated) {
-                    lines.push(`- \`${d.ref}\` ${d.oldSha.slice(0, 7)}→${d.newSha.slice(0, 7)}`);
-                }
-            }
-            else if (updatedRefs.length > 0) {
-                lines.push("## Updated refs", "");
-                for (const ref of updatedRefs) {
-                    lines.push(`- ${ref}`);
-                }
-            }
-            if (structured !== null && structured.created.length > 0) {
-                lines.push("", "## New refs", "");
-                for (const d of structured.created) {
-                    lines.push(`- \`${d.ref}\` (new, ${d.newSha.slice(0, 7)})`);
-                }
-            }
-            else if (newRefs.length > 0) {
-                lines.push("", "## New refs", "");
-                for (const ref of newRefs) {
-                    lines.push(`- ${ref}`);
-                }
-            }
-            if (structured !== null && structured.pruned.length > 0) {
-                lines.push("", "## Pruned refs", "");
-                for (const d of structured.pruned) {
-                    lines.push(`- \`${d.ref}\` (deleted)`);
-                }
-            }
-            if (updatedRefs.length === 0 &&
-                newRefs.length === 0 &&
-                (structured === null ||
-                    (structured.updated.length === 0 && structured.created.length === 0)) &&
-                result.stdout.trim()) {
-                lines.push("", "## Output", "", "```", result.stdout.trim(), "```");
-            }
-            return lines.join("\n");
-        },
-    });
-}

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

@@ -1,126 +0,0 @@
-import { z } from "zod";
-import { ERROR_CODES } from "./error-codes.js";
-import { spawnGitAsync } from "./git.js";
-import { isSafeGitRefToken } from "./git-refs.js";
-import { jsonRespond } from "./json.js";
-import { requireSingleRepo } from "./roots.js";
-import { WorkspacePickSchema } from "./schemas.js";
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-const MAX_ENTRIES_HARD_CAP = 200;
-const DEFAULT_MAX_ENTRIES = 30;
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-/**
- * Run git reflog for a single ref and return structured data.
- * Uses NUL-delimited fields within each line for robust parsing.
- */
-async function runGitReflog(opts) {
-    const { top, ref, maxEntries } = opts;
-    // %h = short sha, %H = full sha, %gd = selector (HEAD@{0}), %gs = reflog subject
-    const reflogArgs = [
-        "reflog",
-        "show",
-        ref,
-        "--format=%h%x00%H%x00%gd%x00%gs",
-        `-n`,
-        String(maxEntries),
-    ];
-    const r = await spawnGitAsync(top, reflogArgs);
-    if (!r.ok) {
-        return {
-            error: ERROR_CODES.REFLOG_FAILED,
-            detail: (r.stderr || r.stdout || "git reflog failed").trim(),
-        };
-    }
-    const entries = [];
-    const lines = r.stdout.split("\n");
-    for (const line of lines) {
-        if (!line.trim())
-            continue;
-        const parts = line.split("\x00");
-        // Expect 4 fields: shaShort, shaFull, selector, message
-        if (parts.length < 4)
-            continue;
-        const [, shaFull, selector, message] = parts;
-        if (!shaFull)
-            continue;
-        entries.push({
-            sha: shaFull.trim(),
-            selector: (selector ?? "").trim(),
-            message: (message ?? "").trim(),
-        });
-    }
-    return { ref, entries };
-}
-// ---------------------------------------------------------------------------
-// Markdown rendering
-// ---------------------------------------------------------------------------
-function renderReflogMarkdown(result) {
-    const lines = [];
-    lines.push(`## Reflog (${result.ref})`);
-    lines.push("");
-    if (result.entries.length === 0) {
-        lines.push("_(no reflog entries)_");
-    }
-    else {
-        for (const entry of result.entries) {
-            lines.push(`${entry.selector}  ${entry.sha.slice(0, 7)}  ${entry.message}`);
-        }
-    }
-    return lines.join("\n");
-}
-// ---------------------------------------------------------------------------
-// Tool registration
-// ---------------------------------------------------------------------------
-export function registerGitReflogTool(server) {
-    server.addTool({
-        name: "git_reflog",
-        description: "Show the reflog for a ref (default HEAD). Returns a list of recent HEAD movements with selector (e.g. HEAD@{0}), full SHA, and message. Useful for recovering lost commits or inspecting reset/checkout history.",
-        annotations: {
-            readOnlyHint: true,
-        },
-        parameters: WorkspacePickSchema.omit({ absoluteGitRoots: true, allWorkspaceRoots: true })
-            .pick({
-            workspaceRoot: true,
-            rootIndex: true,
-            format: true,
-        })
-            .extend({
-            ref: z
-                .string()
-                .optional()
-                .default("HEAD")
-                .describe("Ref whose reflog to show (branch name, HEAD, etc.). Default: HEAD."),
-            maxEntries: z
-                .number()
-                .int()
-                .min(1)
-                .max(MAX_ENTRIES_HARD_CAP)
-                .optional()
-                .default(DEFAULT_MAX_ENTRIES)
-                .describe(`Maximum reflog entries to return (hard cap ${MAX_ENTRIES_HARD_CAP}). Default ${DEFAULT_MAX_ENTRIES}.`),
-        }),
-        execute: async (args) => {
-            const pre = requireSingleRepo(server, args);
-            if (!pre.ok)
-                return jsonRespond(pre.error);
-            const top = pre.gitTop;
-            const ref = args.ref ?? "HEAD";
-            if (!isSafeGitRefToken(ref)) {
-                return jsonRespond({ error: ERROR_CODES.UNSAFE_REF_TOKEN, ref });
-            }
-            const maxEntries = Math.min(args.maxEntries ?? DEFAULT_MAX_ENTRIES, MAX_ENTRIES_HARD_CAP);
-            const result = await runGitReflog({ top, ref, maxEntries });
-            if ("error" in result) {
-                return jsonRespond(result);
-            }
-            if (args.format === "json") {
-                return jsonRespond(result);
-            }
-            return renderReflogMarkdown(result);
-        },
-    });
-}

package/schemas/git_branch_list.json

@@ -1,36 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "@rethunk/mcp-multi-root-git: git_branch_list",
-  "description": "Parameter schema for the 'git_branch_list' MCP tool.",
-  "type": "object",
-  "properties": {
-    "workspaceRoot": {
-      "description": "Highest-priority root override.",
-      "type": "string"
-    },
-    "rootIndex": {
-      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
-      "type": "integer",
-      "minimum": 0,
-      "maximum": 9007199254740991
-    },
-    "format": {
-      "default": "markdown",
-      "type": "string",
-      "enum": [
-        "markdown",
-        "json"
-      ]
-    },
-    "includeRemotes": {
-      "default": false,
-      "description": "Include remote-tracking branches from refs/remotes (symbolic origin/HEAD excluded).",
-      "type": "boolean"
-    }
-  },
-  "required": [
-    "format",
-    "includeRemotes"
-  ],
-  "additionalProperties": false
-}

package/schemas/git_fetch.json

@@ -1,52 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "@rethunk/mcp-multi-root-git: git_fetch",
-  "description": "Parameter schema for the 'git_fetch' MCP tool.",
-  "type": "object",
-  "properties": {
-    "workspaceRoot": {
-      "description": "Highest-priority root override.",
-      "type": "string"
-    },
-    "rootIndex": {
-      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
-      "type": "integer",
-      "minimum": 0,
-      "maximum": 9007199254740991
-    },
-    "format": {
-      "default": "markdown",
-      "type": "string",
-      "enum": [
-        "markdown",
-        "json"
-      ]
-    },
-    "remote": {
-      "default": "origin",
-      "description": "Remote to fetch from (default: origin).",
-      "type": "string"
-    },
-    "branch": {
-      "description": "If specified: fetch only this branch (e.g. 'main').",
-      "type": "string"
-    },
-    "prune": {
-      "default": false,
-      "description": "Pass --prune to remove deleted remote branches (default: false).",
-      "type": "boolean"
-    },
-    "tags": {
-      "default": false,
-      "description": "Pass --tags to also fetch all tags (default: false).",
-      "type": "boolean"
-    }
-  },
-  "required": [
-    "format",
-    "remote",
-    "prune",
-    "tags"
-  ],
-  "additionalProperties": false
-}

package/schemas/git_reflog.json

@@ -1,44 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "@rethunk/mcp-multi-root-git: git_reflog",
-  "description": "Parameter schema for the 'git_reflog' MCP tool.",
-  "type": "object",
-  "properties": {
-    "workspaceRoot": {
-      "description": "Highest-priority root override.",
-      "type": "string"
-    },
-    "rootIndex": {
-      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
-      "type": "integer",
-      "minimum": 0,
-      "maximum": 9007199254740991
-    },
-    "format": {
-      "default": "markdown",
-      "type": "string",
-      "enum": [
-        "markdown",
-        "json"
-      ]
-    },
-    "ref": {
-      "default": "HEAD",
-      "description": "Ref whose reflog to show (branch name, HEAD, etc.). Default: HEAD.",
-      "type": "string"
-    },
-    "maxEntries": {
-      "default": 30,
-      "description": "Maximum reflog entries to return (hard cap 200). Default 30.",
-      "type": "integer",
-      "minimum": 1,
-      "maximum": 200
-    }
-  },
-  "required": [
-    "format",
-    "ref",
-    "maxEntries"
-  ],
-  "additionalProperties": false
-}