@rethunk/mcp-multi-root-git 2.0.1 → 2.1.0

package/AGENTS.md

@@ -14,10 +14,10 @@ IDEs injecting this as context: do not re-link from rules.
 | File | Symbols |
 |------|---------|
 | [`src/server.ts`](src/server.ts) | `FastMCP` + `roots: { enabled: true }`; `readMcpServerVersion()`; `registerRethunkGitTools` |
-| [`src/server/json.ts`](src/server/json.ts) | `MCP_JSON_FORMAT_VERSION="2"`, `jsonRespond()` (minified, no envelope), `spreadWhen`, `spreadDefined` |
+| [`src/server/json.ts`](src/server/json.ts) | `jsonRespond()` (minified, no envelope), `spreadWhen`, `spreadDefined` |
 | [`src/server/git.ts`](src/server/git.ts) | `gateGit`, `spawnGitAsync`, `asyncPool`, `GIT_SUBPROCESS_PARALLELISM`, `gitTopLevel`, `gitRevParseGitDir`, `gitRevParseHead`, `parseGitSubmodulePaths`, `hasGitMetadata`, `gitStatusSnapshotAsync`, `gitStatusShortBranchAsync`, `fetchAheadBehind`, `isSafeGitUpstreamToken` |
-| [`src/server/roots.ts`](src/server/roots.ts) | `uriToPath`, `listFileRoots`, `pathMatchesWorkspaceRootHint`, `resolveWorkspaceRoots`, `resolveRootsForPreset`, `requireGitAndRoots` — session roots only |
-| [`src/server/presets.ts`](src/server/presets.ts) | `PRESET_FILE_PATH`, `splitPresetFileRaw`, `loadPresetsFromGitTop`, `getPresetEntry`, `presetLoadErrorPayload`, `applyPresetNestedRoots`, `applyPresetParityPairs`; Zod schemas must match [`git-mcp-presets.schema.json`](git-mcp-presets.schema.json) |
+| [`src/server/roots.ts`](src/server/roots.ts) | `requireGitAndRoots` — sole public export; session root resolution |
+| [`src/server/presets.ts`](src/server/presets.ts) | `PRESET_FILE_PATH`, `loadPresetsFromGitTop`, `presetLoadErrorPayload`, `applyPresetNestedRoots`, `applyPresetParityPairs`; Zod schemas must match [`git-mcp-presets.schema.json`](git-mcp-presets.schema.json) |
 | [`src/server/schemas.ts`](src/server/schemas.ts) | `WorkspacePickSchema`, `MAX_INVENTORY_ROOTS_DEFAULT` |
 | [`src/server/inventory.ts`](src/server/inventory.ts) | `InventoryEntryJson`, `validateRepoPath`, `makeSkipEntry`, `buildInventorySectionMarkdown`, `collectInventoryEntry` |
 | [`src/server/tools.ts`](src/server/tools.ts) | `registerRethunkGitTools` — dispatches to `register*` below |
@@ -25,14 +25,17 @@ IDEs injecting this as context: do not re-link from rules.
 | [`src/server/git-inventory-tool.ts`](src/server/git-inventory-tool.ts) | `git_inventory` |
 | [`src/server/git-parity-tool.ts`](src/server/git-parity-tool.ts) | `git_parity` |
 | [`src/server/list-presets-tool.ts`](src/server/list-presets-tool.ts) | `list_presets` |
+| [`src/server/git-log-tool.ts`](src/server/git-log-tool.ts) | `git_log` |
+| [`src/server/git-diff-summary-tool.ts`](src/server/git-diff-summary-tool.ts) | `git_diff_summary` — structured token-efficient diff viewer; read-only |
+| [`src/server/batch-commit-tool.ts`](src/server/batch-commit-tool.ts) | `batch_commit` — sequential multi-commit; mutating |
 | [`src/server/presets-resource.ts`](src/server/presets-resource.ts) | `rethunk-git://presets` resource |
-| [`src/repo-paths.ts`](src/repo-paths.ts) | `resolvePathForRepo`, `assertRelativePathUnderTop`, `isStrictlyUnderGitTop`, `realPathOrSelf` |
+| [`src/repo-paths.ts`](src/repo-paths.ts) | `resolvePathForRepo`, `assertRelativePathUnderTop`, `isStrictlyUnderGitTop` |
 
 ## Changing contracts
 
 - **No banner paragraphs** in shipped docs. Use normal titles + cross-links.
-- **`MCP_JSON_FORMAT_VERSION`** (currently `"2"`): bump on incompatible JSON changes (renamed/nested/omitted fields). Document migration here + [docs/mcp-tools.md](docs/mcp-tools.md). v2 removed the `rethunkGitMcp` envelope; payloads are minified; optional fields omitted when empty/null/false.
-- **Preset file:** keep `splitPresetFileRaw` + Zod aligned with [`git-mcp-presets.schema.json`](git-mcp-presets.schema.json).
+- **JSON format version** (currently `"2"`, discoverable via MCP `initialize`): bump on incompatible JSON changes (renamed/nested/omitted fields). Document migration here + [docs/mcp-tools.md](docs/mcp-tools.md). v2 removed the `rethunkGitMcp` envelope; payloads are minified; optional fields omitted when empty/null/false.
+- **Preset file:** keep `presets.ts` Zod schemas aligned with [`git-mcp-presets.schema.json`](git-mcp-presets.schema.json).
 - **Public tool surface:** rename/add → update [docs/mcp-tools.md](docs/mcp-tools.md) + [README.md](README.md) (if mentioned). Install/client wiring → [docs/install.md](docs/install.md) only. `.cursor/rules/rethunk-git-mcp.mdc` → only when *MCP-vs-shell* guidance changes.
 
 ## Validate + CI

package/README.md

@@ -4,7 +4,7 @@
 [![npm version](https://img.shields.io/npm/v/%40rethunk%2Fmcp-multi-root-git.svg)](https://www.npmjs.com/package/@rethunk/mcp-multi-root-git)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Read-only **git** tools over MCP (status, multi-root inventory, `HEAD` parity, presets). **Install and MCP client wiring:** **[docs/install.md](docs/install.md)** only — do not duplicate those steps elsewhere.
+**git** tools over MCP: read-only status, multi-root inventory, `HEAD` parity, presets, structured diff viewer, and batch commit. **Install and MCP client wiring:** **[docs/install.md](docs/install.md)** only — do not duplicate those steps elsewhere.
 
 **Repository:** [github.com/Rethunk-AI/mcp-multi-root-git](https://github.com/Rethunk-AI/mcp-multi-root-git) · **npmjs (manual releases):** [`@rethunk/mcp-multi-root-git`](https://www.npmjs.com/package/@rethunk/mcp-multi-root-git) · **GitHub Packages (CI on each tag):** [`@rethunk-ai/mcp-multi-root-git`](https://github.com/Rethunk-AI/mcp-multi-root-git/packages) — see [docs/install.md](docs/install.md) and [HUMANS.md](HUMANS.md) Publishing.
 

package/dist/repo-paths.js

@@ -1,6 +1,6 @@
 import { realpathSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
-export function realPathOrSelf(p) {
+function realPathOrSelf(p) {
     try {
         return realpathSync(p);
     }

package/dist/server/batch-commit-tool.js

@@ -0,0 +1,139 @@
+import { z } from "zod";
+import { isStrictlyUnderGitTop, resolvePathForRepo } from "../repo-paths.js";
+import { gitTopLevel, spawnGitAsync } from "./git.js";
+import { jsonRespond, spreadDefined } from "./json.js";
+import { requireGitAndRoots } from "./roots.js";
+import { WorkspacePickSchema } from "./schemas.js";
+const CommitEntrySchema = z.object({
+    message: z.string().min(1).describe("Commit message."),
+    files: z.array(z.string().min(1)).min(1).describe("Paths to stage, relative to the git root."),
+});
+export function registerBatchCommitTool(server) {
+    server.addTool({
+        name: "batch_commit",
+        description: "Create multiple sequential git commits in a single call. " +
+            "Each entry stages the listed files then commits with the given message. " +
+            "Stops on first failure. See docs/mcp-tools.md.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+        },
+        parameters: WorkspacePickSchema.extend({
+            commits: z
+                .array(CommitEntrySchema)
+                .min(1)
+                .max(50)
+                .describe("Commits to create, applied in order."),
+        }),
+        execute: async (args) => {
+            const pre = requireGitAndRoots(server, args, undefined);
+            if (!pre.ok)
+                return jsonRespond(pre.error);
+            const rootInput = pre.roots[0];
+            if (!rootInput) {
+                return jsonRespond({ error: "no_workspace_root" });
+            }
+            const gitTop = gitTopLevel(rootInput);
+            if (!gitTop) {
+                return jsonRespond({ error: "not_a_git_repository", path: rootInput });
+            }
+            const results = [];
+            for (let i = 0; i < args.commits.length; i++) {
+                const entry = args.commits[i];
+                if (!entry)
+                    break;
+                // --- Validate all paths are under the git toplevel ---
+                const escapedPaths = [];
+                for (const rel of entry.files) {
+                    const abs = resolvePathForRepo(rel, gitTop);
+                    if (!isStrictlyUnderGitTop(abs, gitTop)) {
+                        escapedPaths.push(rel);
+                    }
+                }
+                if (escapedPaths.length > 0) {
+                    results.push({
+                        index: i,
+                        ok: false,
+                        message: entry.message,
+                        files: entry.files,
+                        error: "path_escapes_repository",
+                        detail: escapedPaths.join(", "),
+                    });
+                    break;
+                }
+                // --- Stage files ---
+                const addResult = await spawnGitAsync(gitTop, ["add", "--", ...entry.files]);
+                if (!addResult.ok) {
+                    results.push({
+                        index: i,
+                        ok: false,
+                        message: entry.message,
+                        files: entry.files,
+                        error: "stage_failed",
+                        detail: (addResult.stderr || addResult.stdout).trim(),
+                    });
+                    break;
+                }
+                // --- Commit ---
+                const commitResult = await spawnGitAsync(gitTop, ["commit", "-m", entry.message]);
+                if (!commitResult.ok) {
+                    results.push({
+                        index: i,
+                        ok: false,
+                        message: entry.message,
+                        files: entry.files,
+                        error: "commit_failed",
+                        detail: (commitResult.stderr || commitResult.stdout).trim(),
+                    });
+                    break;
+                }
+                // --- Extract SHA from commit output ---
+                const shaMatch = /\[[\w/.-]+\s+([0-9a-f]+)\]/.exec(commitResult.stdout);
+                results.push({
+                    index: i,
+                    ok: true,
+                    sha: shaMatch?.[1],
+                    message: entry.message,
+                    files: entry.files,
+                });
+            }
+            const allOk = results.length === args.commits.length && results.every((r) => r.ok);
+            if (args.format === "json") {
+                return jsonRespond({
+                    ok: allOk,
+                    committed: results.filter((r) => r.ok).length,
+                    total: args.commits.length,
+                    results: results.map((r) => ({
+                        index: r.index,
+                        ok: r.ok,
+                        ...spreadDefined("sha", r.sha),
+                        message: r.message,
+                        files: r.files,
+                        ...spreadDefined("error", r.error),
+                        ...spreadDefined("detail", r.detail),
+                    })),
+                });
+            }
+            // --- Markdown ---
+            const lines = [];
+            const header = allOk
+                ? `# Batch commit: ${results.length}/${args.commits.length} committed`
+                : `# Batch commit: ${results.filter((r) => r.ok).length}/${args.commits.length} committed (stopped on error)`;
+            lines.push(header, "");
+            for (const r of results) {
+                const icon = r.ok ? "✓" : "✗";
+                const sha = r.sha ? ` \`${r.sha}\`` : "";
+                lines.push(`${icon}${sha} ${r.message}`);
+                if (!r.ok && r.detail) {
+                    lines.push(`  Error: ${r.error} — ${r.detail}`);
+                }
+            }
+            if (!allOk && results.length < args.commits.length) {
+                const skipped = args.commits.length - results.length;
+                lines.push("", `${skipped} remaining commit(s) skipped.`);
+            }
+            return lines.join("\n");
+        },
+    });
+}

package/dist/server/git-diff-summary-tool.js

@@ -0,0 +1,319 @@
+import { matchesGlob } from "node:path";
+import { z } from "zod";
+import { gitTopLevel, isSafeGitUpstreamToken, spawnGitAsync } from "./git.js";
+import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
+import { requireGitAndRoots } from "./roots.js";
+import { WorkspacePickSchema } from "./schemas.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DEFAULT_EXCLUDE_PATTERNS = [
+    "*.lock",
+    "*.lockb",
+    "bun.lock",
+    "package-lock.json",
+    "yarn.lock",
+    "pnpm-lock.yaml",
+    "*.min.js",
+    "*.min.css",
+    "vendor/**",
+    "node_modules/**",
+    "dist/**",
+];
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Parse `git diff --stat` output into per-file stats.
+ * Format: " path/to/file | N ++++---"
+ * Final line: " N files changed, N insertions(+), N deletions(-)"
+ */
+function parseStatOutput(stat) {
+    const result = new Map();
+    for (const line of stat.split("\n")) {
+        // Skip the summary line and blank lines
+        if (!line.includes("|"))
+            continue;
+        const pipeIdx = line.indexOf("|");
+        const filePart = line.slice(0, pipeIdx).trim();
+        const statPart = line.slice(pipeIdx + 1).trim();
+        // statPart looks like "5 ++---" or "3 +++", count + and -
+        const additions = (statPart.match(/\+/g) ?? []).length;
+        const deletions = (statPart.match(/-/g) ?? []).length;
+        result.set(filePart, { additions, deletions });
+    }
+    return result;
+}
+/**
+ * Parse `git diff` output into per-file chunks.
+ * Splits on "diff --git a/..." lines.
+ */
+function parseDiffOutput(diff) {
+    const chunks = [];
+    // Each file section starts with "diff --git"
+    const parts = diff.split(/(?=^diff --git )/m);
+    for (const part of parts) {
+        if (!part.startsWith("diff --git "))
+            continue;
+        const firstNewline = part.indexOf("\n");
+        const header = firstNewline >= 0 ? part.slice(0, firstNewline) : part;
+        const body = firstNewline >= 0 ? part.slice(firstNewline + 1) : "";
+        chunks.push({ header, body });
+    }
+    return chunks;
+}
+/**
+ * Extract file paths and status from a diff chunk header + body.
+ * Header: "diff --git a/old b/new"
+ * Body may contain "rename from", "rename to", "new file mode", "deleted file mode".
+ */
+function extractFileInfo(header, body) {
+    // Parse "diff --git a/X b/Y"
+    const headerMatch = /^diff --git a\/(.+) b\/(.+)$/.exec(header);
+    const aPath = headerMatch?.[1] ?? "";
+    const bPath = headerMatch?.[2] ?? aPath;
+    let status = "modified";
+    let oldPath;
+    if (/^new file mode/m.test(body)) {
+        status = "added";
+    }
+    else if (/^deleted file mode/m.test(body)) {
+        status = "deleted";
+    }
+    else if (/^rename from /m.test(body)) {
+        status = "renamed";
+        const fromMatch = /^rename from (.+)$/m.exec(body);
+        oldPath = fromMatch?.[1];
+    }
+    const path = status === "deleted" ? aPath : bPath;
+    return { path, oldPath, status };
+}
+/**
+ * Truncate diff body to at most `maxLines` lines (counting only hunk content lines).
+ * Returns { text, truncated }.
+ */
+function truncateDiffBody(body, maxLines) {
+    const lines = body.split("\n");
+    if (lines.length <= maxLines) {
+        return { text: body, truncated: false };
+    }
+    return { text: lines.slice(0, maxLines).join("\n"), truncated: true };
+}
+/** Check whether a file path matches any of the given glob patterns. */
+function matchesAnyPattern(filePath, patterns) {
+    const normalized = filePath.replace(/\\/g, "/");
+    for (const pattern of patterns) {
+        if (matchesGlob(normalized, pattern))
+            return true;
+        // Also match just the basename against simple patterns (e.g. "*.lock")
+        const basename = normalized.split("/").at(-1) ?? normalized;
+        if (matchesGlob(basename, pattern))
+            return true;
+    }
+    return false;
+}
+/** Build the diff args array from the `range` parameter. */
+function buildDiffArgs(range) {
+    if (range === undefined || range === "") {
+        return { ok: true, args: [] };
+    }
+    const normalized = range.trim().toLowerCase();
+    if (normalized === "staged" || normalized === "cached") {
+        return { ok: true, args: ["--cached"] };
+    }
+    if (normalized === "head") {
+        return { ok: true, args: ["HEAD"] };
+    }
+    // Range like "A..B", "A...B", or a single ref
+    // Split on ".." or "..." separators to validate each token
+    const separatorMatch = /^(.+?)(\.{2,3})(.+)$/.exec(range.trim());
+    if (separatorMatch) {
+        const [, left, sep, right] = separatorMatch;
+        if (!isSafeGitUpstreamToken(left ?? "") || !isSafeGitUpstreamToken(right ?? "")) {
+            return { ok: false, error: `unsafe_range_token: ${range}` };
+        }
+        return { ok: true, args: [`${left}${sep}${right}`] };
+    }
+    // Single ref
+    if (!isSafeGitUpstreamToken(range.trim())) {
+        return { ok: false, error: `unsafe_range_token: ${range}` };
+    }
+    return { ok: true, args: [range.trim()] };
+}
+/** Human-readable label for the range. */
+function rangeLabel(range, diffArgs) {
+    if (!range || range === "")
+        return "unstaged changes";
+    if (diffArgs[0] === "--cached")
+        return "staged changes";
+    return range;
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+export function registerGitDiffSummaryTool(server) {
+    server.addTool({
+        name: "git_diff_summary",
+        description: "Structured, token-efficient diff viewer. Returns per-file diffs with additions/deletions, " +
+            "truncated to configurable line limits, with noise files (lock files, dist, etc.) excluded by default. " +
+            "Use `range` to target staged, HEAD, or any revision range. See docs/mcp-tools.md.",
+        annotations: {
+            readOnlyHint: true,
+        },
+        parameters: WorkspacePickSchema.extend({
+            range: z
+                .string()
+                .optional()
+                .describe('Diff range. Examples: "staged", "HEAD~3..HEAD", "main...feature". ' +
+                "Default: unstaged changes."),
+            fileFilter: z
+                .string()
+                .optional()
+                .describe('Glob pattern to restrict output to matching files, e.g. "*.ts", "src/**".'),
+            maxLinesPerFile: z
+                .number()
+                .int()
+                .min(1)
+                .max(2000)
+                .optional()
+                .default(50)
+                .describe("Max diff lines to include per file. Default: 50."),
+            maxFiles: z
+                .number()
+                .int()
+                .min(1)
+                .max(500)
+                .optional()
+                .default(30)
+                .describe("Max files to include in output. Default: 30."),
+            excludePatterns: z
+                .array(z.string())
+                .optional()
+                .describe("Glob patterns to exclude. Defaults to common noise: lock files, dist, vendor, etc."),
+        }),
+        execute: async (args) => {
+            // --- Standard prelude ---
+            const pre = requireGitAndRoots(server, args, undefined);
+            if (!pre.ok)
+                return jsonRespond(pre.error);
+            const rootInput = pre.roots[0];
+            if (!rootInput)
+                return jsonRespond({ error: "no_workspace_root" });
+            const gitTop = gitTopLevel(rootInput);
+            if (!gitTop) {
+                return jsonRespond({ error: "not_a_git_repository", path: rootInput });
+            }
+            // --- Build git diff args ---
+            const diffArgsResult = buildDiffArgs(args.range);
+            if (!diffArgsResult.ok) {
+                return jsonRespond({ error: diffArgsResult.error });
+            }
+            const diffArgs = diffArgsResult.args;
+            // --- Run git diff --stat ---
+            const statResult = await spawnGitAsync(gitTop, ["diff", "--stat", ...diffArgs]);
+            if (!statResult.ok) {
+                return jsonRespond({
+                    error: "git_diff_failed",
+                    detail: (statResult.stderr || statResult.stdout).trim(),
+                });
+            }
+            const statMap = parseStatOutput(statResult.stdout);
+            // --- Run git diff ---
+            const diffResult = await spawnGitAsync(gitTop, ["diff", ...diffArgs]);
+            if (!diffResult.ok) {
+                return jsonRespond({
+                    error: "git_diff_failed",
+                    detail: (diffResult.stderr || diffResult.stdout).trim(),
+                });
+            }
+            // --- Parse diff chunks ---
+            const chunks = parseDiffOutput(diffResult.stdout);
+            const totalFiles = chunks.length;
+            // --- Apply excludePatterns and fileFilter ---
+            const excludePatterns = args.excludePatterns !== undefined ? args.excludePatterns : DEFAULT_EXCLUDE_PATTERNS;
+            const excludedFiles = [];
+            const includedChunks = [];
+            for (const chunk of chunks) {
+                const { path: filePath } = extractFileInfo(chunk.header, chunk.body);
+                if (matchesAnyPattern(filePath, excludePatterns)) {
+                    excludedFiles.push(filePath);
+                    continue;
+                }
+                if (args.fileFilter && !matchesAnyPattern(filePath, [args.fileFilter])) {
+                    continue;
+                }
+                includedChunks.push(chunk);
+            }
+            // --- Truncate to maxFiles ---
+            const maxFiles = args.maxFiles ?? 30;
+            const maxLinesPerFile = args.maxLinesPerFile ?? 50;
+            const truncatedFileCount = includedChunks.length > maxFiles ? includedChunks.length - maxFiles : 0;
+            const processedChunks = includedChunks.slice(0, maxFiles);
+            // --- Build FileDiff entries ---
+            let totalAdditions = 0;
+            let totalDeletions = 0;
+            const files = [];
+            for (const chunk of processedChunks) {
+                const { path: filePath, oldPath, status } = extractFileInfo(chunk.header, chunk.body);
+                const stat = statMap.get(filePath) ?? { additions: 0, deletions: 0 };
+                totalAdditions += stat.additions;
+                totalDeletions += stat.deletions;
+                const { text: diffText, truncated } = truncateDiffBody(chunk.body, maxLinesPerFile);
+                files.push({
+                    path: filePath,
+                    status,
+                    additions: stat.additions,
+                    deletions: stat.deletions,
+                    ...spreadDefined("oldPath", oldPath),
+                    truncated,
+                    diff: diffText,
+                });
+            }
+            const rangeStr = rangeLabel(args.range, diffArgs);
+            const summary = {
+                range: rangeStr,
+                totalFiles,
+                totalAdditions,
+                totalDeletions,
+                files,
+                ...spreadWhen(truncatedFileCount > 0, { truncatedFiles: truncatedFileCount }),
+                ...spreadWhen(excludedFiles.length > 0, { excludedFiles }),
+            };
+            // --- Format output ---
+            if (args.format === "json") {
+                return jsonRespond(summary);
+            }
+            // --- Markdown output ---
+            const lines = [];
+            lines.push(`# Diff: ${rangeStr}`, "");
+            // Summary line
+            const fileWord = totalFiles === 1 ? "file" : "files";
+            let summaryLine = `**${totalFiles} ${fileWord} changed** (+${totalAdditions} \u2212${totalDeletions})`;
+            if (excludedFiles.length > 0) {
+                const excWord = excludedFiles.length === 1 ? "file" : "files";
+                summaryLine += `, ${excludedFiles.length} ${excWord} excluded (${excludedFiles.join(", ")})`;
+            }
+            if (truncatedFileCount > 0) {
+                summaryLine += `, ${truncatedFileCount} more file(s) omitted (maxFiles=${maxFiles})`;
+            }
+            lines.push(summaryLine, "");
+            for (const file of files) {
+                // Section header
+                const statusTag = file.status !== "modified" ? `, ${file.status}` : "";
+                const renameTag = file.oldPath ? ` (from ${file.oldPath})` : "";
+                lines.push(`## ${file.path}${renameTag} (+${file.additions} \u2212${file.deletions}${statusTag})`);
+                if (file.diff) {
+                    lines.push("```diff", file.diff.trimEnd(), "```");
+                }
+                else {
+                    lines.push("_(no diff content)_");
+                }
+                if (file.truncated) {
+                    lines.push(`_(diff truncated at ${maxLinesPerFile} lines)_`);
+                }
+                lines.push("");
+            }
+            return lines.join("\n");
+        },
+    });
+}

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

@@ -0,0 +1,276 @@
+import { basename } from "node:path";
+import { z } from "zod";
+import { asyncPool, GIT_SUBPROCESS_PARALLELISM, gitTopLevel, spawnGitAsync } from "./git.js";
+import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
+import { requireGitAndRoots } from "./roots.js";
+import { WorkspacePickSchema } from "./schemas.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const MAX_COMMITS_HARD_CAP = 500;
+const DEFAULT_MAX_COMMITS = 50;
+const DEFAULT_SINCE = "7.days";
+// Field separator written by git into stdout — we use git's %x01 (SOH) escape.
+// The format string itself is safe ASCII; git emits the byte.
+const FIELD_SEP_OUT = "\x01"; // what git outputs (SOH)
+const RECORD_SEP_OUT = "\x02"; // what git outputs (STX) — used as record-START marker
+// git log --pretty tformat: sha7, shaFull, subject, author, email, ISO date, relative date.
+// %x02 is placed at the START of each record (tformat adds \n as terminator after each).
+// Splitting stdout on \x02 then gives empty-first-chunk + one chunk per commit,
+// each structured as:  <fields>\x01\n\n <shortstat text>\n
+// Fields are separated by %x01; the trailing \x01 before \n leaves one empty last field (ignored).
+const PRETTY_FORMAT = "%x02%h%x01%H%x01%s%x01%aN%x01%aE%x01%aI%x01%ar%x01";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Parse a shortstat line like "3 files changed, 12 insertions(+), 5 deletions(-)"
+ * Returns undefined when the line doesn't match (e.g. empty diff).
+ */
+function parseShortstat(line) {
+    const m = /(\d+) files? changed(?:, (\d+) insertions?\(\+\))?(?:, (\d+) deletions?\(-\))?/.exec(line);
+    if (!m)
+        return undefined;
+    return {
+        filesChanged: parseInt(m[1] ?? "0", 10),
+        insertions: parseInt(m[2] ?? "0", 10),
+        deletions: parseInt(m[3] ?? "0", 10),
+    };
+}
+/**
+ * Fetch the current branch name (or detached HEAD fallback).
+ */
+async function gitCurrentBranch(cwd, branchArg) {
+    if (branchArg?.trim())
+        return branchArg.trim();
+    const r = await spawnGitAsync(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
+    if (r.ok)
+        return r.stdout.trim();
+    return "HEAD";
+}
+/**
+ * Run git log for a single repo root and return structured data.
+ */
+async function runGitLog(opts) {
+    const { top, since, paths, grep, author, maxCommits, branch } = opts;
+    // Resolve branch first (needed for output metadata).
+    const resolvedBranch = await gitCurrentBranch(top, branch);
+    // Fetch one extra commit to detect truncation.
+    const fetchLimit = maxCommits + 1;
+    const logArgs = [
+        "log",
+        `--pretty=tformat:${PRETTY_FORMAT}`,
+        "--shortstat",
+        `-n`,
+        String(fetchLimit),
+        `--since=${since}`,
+    ];
+    if (branch?.trim()) {
+        logArgs.push(branch.trim());
+    }
+    if (grep?.trim()) {
+        logArgs.push(`--grep=${grep.trim()}`, "-i");
+    }
+    if (author?.trim()) {
+        logArgs.push(`--author=${author.trim()}`);
+    }
+    if (paths.length > 0) {
+        logArgs.push("--", ...paths);
+    }
+    const r = await spawnGitAsync(top, logArgs);
+    if (!r.ok) {
+        return {
+            error: "git_log_failed",
+            path: top,
+        };
+    }
+    // Parse output.
+    // git log --pretty=tformat:%x02<fields>%x01 --shortstat emits, per commit:
+    //   \x02<fields separated by SOH>\x01\n\n <shortstat line>\n
+    // The \x02 is a record-START marker. Splitting on \x02 gives an empty first chunk
+    // followed by one chunk per commit. Each chunk is:
+    //   <fields>\x01\n\n <shortstat>\n
+    const raw = r.stdout;
+    const recordChunks = raw.split(RECORD_SEP_OUT).slice(1); // drop leading empty
+    const allCommits = [];
+    for (const chunk of recordChunks) {
+        if (!chunk.trim())
+            continue;
+        // Fields before the first newline; shortstat (if any) follows blank line.
+        const newlineIdx = chunk.indexOf("\n");
+        const fieldsPart = newlineIdx >= 0 ? chunk.slice(0, newlineIdx) : chunk;
+        const statPart = newlineIdx >= 0 ? chunk.slice(newlineIdx + 1) : "";
+        const fields = fieldsPart.split(FIELD_SEP_OUT);
+        const [sha7, shaFull, subject, authorName, email, date, ageRelative] = fields;
+        if (!sha7 || !shaFull)
+            continue;
+        const stat = parseShortstat(statPart);
+        const commit = {
+            sha7: sha7.trim(),
+            shaFull: shaFull.trim(),
+            subject: subject?.trim() ?? "",
+            author: authorName?.trim() ?? "",
+            email: email?.trim() ?? "",
+            date: date?.trim() ?? "",
+            ageRelative: ageRelative?.trim() ?? "",
+            ...spreadDefined("filesChanged", stat?.filesChanged),
+            ...spreadDefined("insertions", stat?.insertions),
+            ...spreadDefined("deletions", stat?.deletions),
+        };
+        allCommits.push(commit);
+    }
+    const truncated = allCommits.length > maxCommits;
+    const commits = truncated ? allCommits.slice(0, maxCommits) : allCommits;
+    const omittedCount = truncated ? allCommits.length - maxCommits : 0;
+    return {
+        workspace_root: top,
+        repo: basename(top),
+        branch: resolvedBranch,
+        commits,
+        truncated,
+        omittedCount,
+    };
+}
+// ---------------------------------------------------------------------------
+// Markdown rendering
+// ---------------------------------------------------------------------------
+function renderLogMarkdown(group, filterSummary) {
+    const lines = [];
+    lines.push(`### ${group.repo} (${group.branch})${filterSummary ? `  —  ${filterSummary}` : ""}`);
+    lines.push(`_root: ${group.workspace_root}_`);
+    lines.push("");
+    if (group.commits.length === 0) {
+        lines.push("_(no commits match)_");
+    }
+    else {
+        for (const c of group.commits) {
+            lines.push(`- \`${c.sha7}\`  ${c.ageRelative}  ${c.subject}  —  ${c.author}`);
+        }
+    }
+    if (group.truncated) {
+        lines.push("");
+        lines.push(`_(truncated — ${group.omittedCount} more commit(s) not shown; lower \`since\` or \`maxCommits\`)_`);
+    }
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+export function registerGitLogTool(server) {
+    server.addTool({
+        name: "git_log",
+        description: "Path-filtered, time-windowed read-only `git log` across one or more workspace roots. " +
+            "Returns structured commit history with author, date, subject, and optional diff stats. " +
+            "See docs/mcp-tools.md.",
+        annotations: {
+            readOnlyHint: true,
+        },
+        parameters: WorkspacePickSchema.extend({
+            since: z
+                .string()
+                .optional()
+                .describe("Passed to `git log --since=`. Accepts ISO timestamps or git relative forms like " +
+                "`48.hours` or `2.weeks.ago`. Default: `7.days`."),
+            paths: z
+                .array(z.string())
+                .optional()
+                .describe("Limit to commits touching these paths (passed as `-- <paths>`)."),
+            grep: z
+                .string()
+                .optional()
+                .describe("Filter commits whose message matches this regex (git `--grep`, case-insensitive)."),
+            author: z
+                .string()
+                .optional()
+                .describe("Filter by author name or email (passed as `--author=`)."),
+            maxCommits: z
+                .number()
+                .int()
+                .min(1)
+                .max(MAX_COMMITS_HARD_CAP)
+                .optional()
+                .default(DEFAULT_MAX_COMMITS)
+                .describe(`Maximum commits to return per root (hard cap ${MAX_COMMITS_HARD_CAP}). Default ${DEFAULT_MAX_COMMITS}.`),
+            branch: z.string().optional().describe("Ref/branch to log from. Default: HEAD."),
+        }),
+        execute: async (args) => {
+            const pre = requireGitAndRoots(server, args, undefined);
+            if (!pre.ok)
+                return jsonRespond(pre.error);
+            // Validate `since` — reject obvious injection attempts (newlines, semicolons, shell chars).
+            const rawSince = (args.since?.trim() ?? DEFAULT_SINCE) || DEFAULT_SINCE;
+            if (/[\n\r;|&`$<>]/.test(rawSince)) {
+                return jsonRespond({ error: "invalid_since", since: rawSince });
+            }
+            // Validate paths — reject anything with null bytes or shell meta.
+            // Use charCodeAt(0) === 0 for the null byte to avoid a biome lint on control chars in regex.
+            const rawPaths = args.paths ?? [];
+            for (const p of rawPaths) {
+                if (p.split("").some((c) => c.charCodeAt(0) === 0) || /[\n\r;|&`$<>]/.test(p)) {
+                    return jsonRespond({ error: "invalid_paths", path: p });
+                }
+            }
+            const maxCommits = Math.min(args.maxCommits ?? DEFAULT_MAX_COMMITS, MAX_COMMITS_HARD_CAP);
+            // Fan out across roots.
+            const jobs = pre.roots.map((rootInput) => ({ rootInput }));
+            const results = await asyncPool(jobs, GIT_SUBPROCESS_PARALLELISM, async ({ rootInput }) => {
+                const top = gitTopLevel(rootInput);
+                if (!top) {
+                    return { _error: true, workspace_root: rootInput, error: "not_a_git_repo" };
+                }
+                const r = await runGitLog({
+                    top,
+                    since: rawSince,
+                    paths: rawPaths,
+                    grep: args.grep,
+                    author: args.author,
+                    maxCommits,
+                    branch: args.branch,
+                });
+                if ("error" in r) {
+                    return { _error: true, workspace_root: rootInput, error: r.error };
+                }
+                return { _error: false, ...r };
+            });
+            // Build filter summary string for markdown.
+            const filterParts = [`since: ${rawSince}`];
+            if (rawPaths.length > 0)
+                filterParts.push(`paths: ${rawPaths.join(", ")}`);
+            if (args.grep)
+                filterParts.push(`grep: ${args.grep}`);
+            if (args.author)
+                filterParts.push(`author: ${args.author}`);
+            const filterSummary = filterParts.join(" | ");
+            if (args.format === "json") {
+                const groups = results.map((r) => {
+                    if (r._error) {
+                        return {
+                            workspace_root: r.workspace_root,
+                            repo: basename(r.workspace_root),
+                            branch: "",
+                            commits: [],
+                            ...spreadWhen(true, { error: r.error }),
+                        };
+                    }
+                    const { _error: _e, ...rest } = r;
+                    return {
+                        ...rest,
+                        ...spreadWhen(r.truncated, { truncated: true, omittedCount: r.omittedCount }),
+                    };
+                });
+                return jsonRespond({ groups });
+            }
+            // Markdown
+            const mdChunks = ["# Git log"];
+            for (const r of results) {
+                if (r._error) {
+                    mdChunks.push(`### ${r.workspace_root}\n_error: ${r.error}_`);
+                    continue;
+                }
+                const { _error: _e, ...group } = r;
+                mdChunks.push(renderLogMarkdown(group, filterSummary));
+            }
+            return mdChunks.join("\n\n");
+        },
+    });
+}

package/dist/server/json.js

@@ -1,8 +1,7 @@
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-export const MCP_JSON_FORMAT_VERSION = "2";
-export function readPackageVersion() {
+function readPackageVersion() {
     const here = dirname(fileURLToPath(import.meta.url));
     const pkgPath = join(here, "..", "..", "package.json");
     try {

package/dist/server/presets.js

@@ -24,7 +24,7 @@ export const PRESET_FILE_PATH = ".rethunk/git-mcp-presets.json";
  * - Wrapped: `{ "schemaVersion": "1", "presets": { "name": { ... } } }`
  * - Legacy: `{ "name": { ... }, ... }` with optional top-level `schemaVersion` / `$schema` (editor hints).
  */
-export function splitPresetFileRaw(raw) {
+function splitPresetFileRaw(raw) {
     if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
         throw new Error("invalid_root");
     }
@@ -96,7 +96,7 @@ export function presetLoadErrorPayload(gitTop, fail) {
     }
     return { error: "preset_file_invalid", presetFile };
 }
-export function getPresetEntry(gitTop, presetName) {
+function getPresetEntry(gitTop, presetName) {
     const loaded = loadPresetsFromGitTop(gitTop);
     if (!loaded.ok) {
         if (loaded.reason === "missing") {
@@ -124,7 +124,7 @@ export function getPresetEntry(gitTop, presetName) {
     }
     return { ok: true, entry, presetSchemaVersion: loaded.schemaVersion };
 }
-export function mergeNestedRoots(preset, inline) {
+function mergeNestedRoots(preset, inline) {
     const a = preset ?? [];
     const b = inline ?? [];
     if (a.length === 0 && b.length === 0)
@@ -139,7 +139,7 @@ export function mergeNestedRoots(preset, inline) {
     }
     return out;
 }
-export function mergePairs(preset, inline) {
+function mergePairs(preset, inline) {
     const a = preset ?? [];
     const b = inline ?? [];
     if (a.length === 0 && b.length === 0)

package/dist/server/roots.js

@@ -2,7 +2,7 @@ import { basename, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { gateGit, gitTopLevel } from "./git.js";
 import { loadPresetsFromGitTop, presetLoadErrorPayload } from "./presets.js";
-export function uriToPath(uri) {
+function uriToPath(uri) {
     if (!uri.startsWith("file://"))
         return null;
     try {
@@ -12,7 +12,7 @@ export function uriToPath(uri) {
         return null;
     }
 }
-export function listFileRoots(server) {
+function listFileRoots(server) {
     const sessions = server.sessions;
     const roots = sessions[0]?.roots ?? [];
     const paths = [];
@@ -24,7 +24,7 @@ export function listFileRoots(server) {
     return paths;
 }
 /** Basename or trailing path segment; compares using normalized slashes so Windows backslashes match. */
-export function pathMatchesWorkspaceRootHint(rootPath, hint) {
+function pathMatchesWorkspaceRootHint(rootPath, hint) {
     const h = hint.trim();
     if (!h)
         return true;
@@ -39,7 +39,7 @@ export function pathMatchesWorkspaceRootHint(rootPath, hint) {
         return true;
     return basename(rootPath) === h;
 }
-export function resolveWorkspaceRoots(server, args) {
+function resolveWorkspaceRoots(server, args) {
     if (args.workspaceRoot?.trim()) {
         return { ok: true, roots: [resolve(args.workspaceRoot.trim())] };
     }
@@ -69,7 +69,7 @@ export function resolveWorkspaceRoots(server, args) {
  * When a preset name is requested and multiple MCP roots exist, pick the first root
  * whose git toplevel loads a preset file containing that name.
  */
-export function resolveRootsForPreset(server, args, presetName) {
+function resolveRootsForPreset(server, args, presetName) {
     if (args.workspaceRoot?.trim() || args.allWorkspaceRoots || args.rootIndex != null) {
         return resolveWorkspaceRoots(server, args);
     }

package/dist/server/test-harness.js

@@ -0,0 +1,64 @@
+/**
+ * Lightweight test harness for MCP tool execute handlers.
+ *
+ * FastMCP does not expose a way to inject a custom transport, so the full
+ * MCP client/server stack cannot be wired up in tests without stdio or HTTP.
+ * Instead, we use a duck-typed fake server that satisfies the FastMCP interface
+ * just enough for tool registration: it has `sessions` (empty — tools use
+ * `workspaceRoot` arg which bypasses session root detection) and `addTool`
+ * which captures the tool definition so we can call `execute` directly.
+ *
+ * Context passed to execute is a no-op stub — none of the current tools
+ * use the context object (logging, progress, etc.).
+ *
+ * Usage:
+ *   const tool = captureTool(registerBatchCommitTool);
+ *   const result = await tool({ workspaceRoot: dir, commits: [...] });
+ *   // result is string (markdown) or JSON-parseable string
+ */
+// Stub context — no tool currently uses context
+const STUB_CONTEXT = {
+    log: {
+        debug: () => undefined,
+        error: () => undefined,
+        info: () => undefined,
+        warn: () => undefined,
+    },
+    reportProgress: async () => undefined,
+    session: undefined,
+};
+// ---------------------------------------------------------------------------
+// Fake server
+// ---------------------------------------------------------------------------
+function makeFakeServer() {
+    const tools = [];
+    const server = {
+        sessions: [],
+        addTool(tool) {
+            tools.push({ name: tool.name, execute: tool.execute });
+        },
+    };
+    return { server, tools };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Register one tool and return a caller that invokes its execute handler.
+ * The returned function accepts tool args (always include `workspaceRoot`)
+ * and returns the raw result as a string.
+ */
+export function captureTool(register, toolName) {
+    const { server, tools } = makeFakeServer();
+    register(server);
+    const pick = toolName ? tools.find((t) => t.name === toolName) : tools[0];
+    if (!pick) {
+        throw new Error(`captureTool: no tool captured${toolName ? ` named "${toolName}"` : ""}. Did you forget to call register?`);
+    }
+    return async (args) => {
+        const result = await pick.execute(args, STUB_CONTEXT);
+        if (typeof result === "string")
+            return result;
+        return JSON.stringify(result);
+    };
+}

package/dist/server/tools.js

@@ -1,4 +1,7 @@
+import { registerBatchCommitTool } from "./batch-commit-tool.js";
+import { registerGitDiffSummaryTool } from "./git-diff-summary-tool.js";
 import { registerGitInventoryTool } from "./git-inventory-tool.js";
+import { registerGitLogTool } from "./git-log-tool.js";
 import { registerGitParityTool } from "./git-parity-tool.js";
 import { registerGitStatusTool } from "./git-status-tool.js";
 import { registerListPresetsTool } from "./list-presets-tool.js";
@@ -8,5 +11,8 @@ export function registerRethunkGitTools(server) {
     registerGitInventoryTool(server);
     registerGitParityTool(server);
     registerListPresetsTool(server);
+    registerBatchCommitTool(server);
+    registerGitDiffSummaryTool(server);
+    registerGitLogTool(server);
     registerPresetsResource(server);
 }

package/docs/mcp-tools.md

@@ -15,6 +15,9 @@ MCP clients expose tools as `{serverName}_{toolName}`. With the server registere
 | `git_inventory` | `rethunk-git_git_inventory` | Status + ahead/behind per path; default upstream each repo’s `@{u}`; pass **both** `remote` and `branch` for fixed tracking. `nestedRoots`, `preset`, `presetMerge`, `maxRoots`, `format`, plus workspace pick args. |
 | `git_parity` | `rethunk-git_git_parity` | Compare `git rev-parse HEAD` for path pairs. `pairs`, `preset`, `presetMerge`, `format`, plus workspace pick args. |
 | `list_presets` | `rethunk-git_list_presets` | List preset names/counts from `.rethunk/git-mcp-presets.json`; invalid JSON/schema surface as errors. Workspace pick + `format` only. |
+| `git_log` | `rethunk-git_git_log` | Path-filtered, time-windowed `git log` across one or more workspace roots. Returns commit history with author, date, subject, and shortstat. Args: `since`, `paths`, `grep`, `author`, `maxCommits`, `branch`, plus workspace pick args + `format`. |
+| `git_diff_summary` | `rethunk-git_git_diff_summary` | Structured, token-efficient diff viewer. Returns per-file diffs with additions/deletions counts, truncated to configurable line limits, with lock files/dist/vendor excluded by default. Args: `range`, `fileFilter`, `maxLinesPerFile`, `maxFiles`, `excludePatterns`, plus workspace pick args + `format`. **Read-only.** |
+| `batch_commit` | `rethunk-git_batch_commit` | Create multiple sequential git commits in a single call. Each entry stages the listed files then commits with the given message. Stops on first failure. Args: `commits` (array of `{message, files}`), plus workspace pick args + `format`. **Mutating — not idempotent.** |
 
 Pass **`format: "json"`** on any tool for structured JSON instead of markdown (default).
 
@@ -43,6 +46,152 @@ To keep responses compact, **optional fields are omitted when they would be empt
 
 **When to bump `MCP_JSON_FORMAT_VERSION` or change payload shape:** [AGENTS.md](../AGENTS.md) — *Changing contracts*.
 
+### `git_log` — parameters
+
+| Parameter | Type | Default | Notes |
+|-----------|------|---------|-------|
+| `since` | string | `"7.days"` | Passed to `git log --since=`. Accepts ISO timestamps (`2026-04-01T00:00:00Z`) or git relative forms (`48.hours`, `2.weeks.ago`). |
+| `paths` | string[] | (all) | Restrict to commits touching these paths (appended after `--`). |
+| `grep` | string | — | Filter by commit message regex (git `--grep`, always case-insensitive). |
+| `author` | string | — | Filter by author name or email (`--author=`). |
+| `maxCommits` | int | `50` | Max commits per root. Hard cap: `500`. |
+| `branch` | string | `HEAD` | Ref/branch to log from. |
+| `workspaceRoot` | string | — | Explicit root; highest priority. |
+| `rootIndex` | int | — | Pick one of several MCP roots (0-based). |
+| `allWorkspaceRoots` | boolean | `false` | Fan out across all MCP roots. |
+| `format` | `"markdown"` \| `"json"` | `"markdown"` | Output format. |
+
+### `git_log` — JSON shape (`format: "json"`)
+
+```json
+{
+  "groups": [{
+    "workspace_root": "/abs/path",
+    "repo": "my-repo",
+    "branch": "main",
+    "commits": [{
+      "sha7": "a1bf184",
+      "shaFull": "a1bf184c3d...",
+      "subject": "feat(satcom): upgrade to PROTOCOL_VERSION 4",
+      "author": "Damon Blais",
+      "email": "damon@example.com",
+      "date": "2026-04-12T18:32:01-07:00",
+      "ageRelative": "42m ago",
+      "filesChanged": 4,
+      "insertions": 16,
+      "deletions": 5
+    }],
+    "truncated": true,
+    "omittedCount": 12
+  }]
+}
+```
+
+v2 field-omission rules: `filesChanged`, `insertions`, `deletions` are omitted when zero/absent (new file with no shortstat). `truncated` and `omittedCount` are omitted when `false`/`0`. A group emits `error` instead of `commits` when git fails for that root.
+
+### `git_log` — error codes
+
+| Code | Meaning |
+|------|---------|
+| `git_not_found` | `git` binary not on `PATH`. |
+| `not_a_git_repo` | The resolved workspace root is not inside a git repository. |
+| `invalid_since` | The `since` string contains shell metacharacters and was rejected. |
+| `invalid_paths` | One of the `paths` entries contains shell metacharacters and was rejected. |
+| `git_log_failed` | `git log` exited non-zero (e.g. unknown branch ref). |
+| `root_index_out_of_range` | `rootIndex` exceeds the number of MCP file roots. |
+
+### `git_diff_summary` — parameters
+
+| Parameter | Type | Default | Notes |
+|-----------|------|---------|-------|
+| `range` | string | unstaged | Diff range. `"staged"` / `"cached"` for index; `"HEAD"` for last commit; `"A..B"` or `"A...B"` for revision ranges; single ref. Default: unstaged working-tree changes. |
+| `fileFilter` | string | — | Glob pattern to restrict output to matching files (e.g. `"*.ts"`, `"src/**"`). |
+| `maxLinesPerFile` | int | `50` | Max diff lines to include per file (1–2000). |
+| `maxFiles` | int | `30` | Max files to include in output (1–500). |
+| `excludePatterns` | string[] | lock files, dist, vendor | Glob patterns to exclude. Defaults to `*.lock`, `*.lockb`, `bun.lock`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `*.min.js`, `*.min.css`, `vendor/**`, `node_modules/**`, `dist/**`. Pass an empty array to disable. |
+| `workspaceRoot` | string | — | Explicit root; highest priority. |
+| `rootIndex` | int | — | Pick one of several MCP roots (0-based). |
+| `format` | `"markdown"` \| `"json"` | `"markdown"` | Output format. |
+
+### `git_diff_summary` — JSON shape (`format: "json"`)
+
+```json
+{
+  "range": "unstaged changes",
+  "totalFiles": 2,
+  "totalAdditions": 10,
+  "totalDeletions": 5,
+  "files": [{
+    "path": "src/foo.ts",
+    "status": "modified",
+    "additions": 8,
+    "deletions": 3,
+    "truncated": false,
+    "diff": "@@ -1,3 +1,8 @@\n-const x = 1;\n+const x = 2;"
+  }],
+  "truncatedFiles": 1,
+  "excludedFiles": ["yarn.lock"]
+}
+```
+
+`status` is one of `"modified"`, `"added"`, `"deleted"`, `"renamed"`. `oldPath` is present only for renamed files. `truncatedFiles` and `excludedFiles` are omitted when zero/empty (v2 field-omission contract).
+
+### `git_diff_summary` — error codes
+
+| Code | Meaning |
+|------|---------|
+| `git_not_found` | `git` binary not on `PATH`. |
+| `not_a_git_repository` | The resolved workspace root is not inside a git repository. |
+| `unsafe_range_token` | The `range` string contains characters outside the safe token set. |
+| `git_diff_failed` | `git diff` exited non-zero. |
+
+---
+
+### `batch_commit` — parameters
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| `commits` | `{message: string, files: string[]}[]` | Commits to create in order. 1–50 entries. Each `files` entry is a path relative to the git root; all must stay within the git toplevel. |
+| `workspaceRoot` | string | Explicit root; highest priority. |
+| `rootIndex` | int | Pick one of several MCP roots (0-based). |
+| `format` | `"markdown"` \| `"json"` | Output format. Default: `"markdown"`. |
+
+### `batch_commit` — JSON shape (`format: "json"`)
+
+```json
+{
+  "ok": true,
+  "committed": 2,
+  "total": 2,
+  "results": [{
+    "index": 0,
+    "ok": true,
+    "sha": "a1b2c3d",
+    "message": "feat: add foo",
+    "files": ["src/foo.ts"]
+  }, {
+    "index": 1,
+    "ok": true,
+    "sha": "b2c3d4e",
+    "message": "chore: update config",
+    "files": ["config.json"]
+  }]
+}
+```
+
+On first failure `ok` is `false`, `committed` reflects only the entries that succeeded before the error, and the failing entry includes `error` and `detail` fields. Remaining entries are skipped and not included in `results`.
+
+### `batch_commit` — error codes (per-result `error` field)
+
+| Code | Meaning |
+|------|---------|
+| `path_escapes_repository` | One of the listed file paths resolves outside the git toplevel. |
+| `stage_failed` | `git add` failed (e.g. untracked path or permission error). |
+| `commit_failed` | `git commit` failed (e.g. nothing staged, hooks rejected). |
+| `not_a_git_repository` | The resolved workspace root is not inside a git repository. |
+
+---
+
 ## Resource
 
 | URI | Purpose |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rethunk/mcp-multi-root-git",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "MCP stdio server: multi-root git status, inventory, and HEAD parity checks. Generic tools usable by any workspace.",
   "type": "module",
   "private": false,