@rethunk/mcp-multi-root-git 2.3.4 → 2.4.0

package/AGENTS.md

@@ -9,6 +9,7 @@ IDEs injecting this as context: do not re-link from rules.
 - Tools, JSON shape, resources, root resolution → [docs/mcp-tools.md](docs/mcp-tools.md)
 - Dev setup, CI, commit conventions → [CONTRIBUTING.md](CONTRIBUTING.md)
 - Presets, auth, publish → [HUMANS.md](HUMANS.md)
+- Spec layout for repo planning → [specs/README.md](specs/README.md)
 
 ## Implementation map
 
@@ -29,6 +30,11 @@ IDEs injecting this as context: do not re-link from rules.
 | [`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` — v3 JSON shape: `sha` (full), `workspaceRoot`, no `sha7`/`ageRelative`, optional `email` |
 | [`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/git-diff-tool.ts`](src/server/git-diff-tool.ts) | `git_diff` — raw scoped diff text; read-only |
+| [`src/server/git-show-tool.ts`](src/server/git-show-tool.ts) | `git_show` — inspect commit message + diff or file content at a ref; read-only |
+| [`src/server/git-stash-tool.ts`](src/server/git-stash-tool.ts) | `git_stash_list`, `git_stash_apply` |
+| [`src/server/git-fetch-tool.ts`](src/server/git-fetch-tool.ts) | `git_fetch` — fetch remote refs without touching the working tree |
+| [`src/server/git-tag-tool.ts`](src/server/git-tag-tool.ts) | `git_tag` — create/delete annotated or lightweight tags |
 | [`src/server/git-worktree-tool.ts`](src/server/git-worktree-tool.ts) | `git_worktree_list`, `git_worktree_add`, `git_worktree_remove` |
 | [`src/server/batch-commit-tool.ts`](src/server/batch-commit-tool.ts) | `batch_commit` — sequential multi-commit; mutating; exports `PushReport`, `runPushAfter` |
 | [`src/server/git-push-tool.ts`](src/server/git-push-tool.ts) | `git_push` — standalone push with optional upstream tracking |
@@ -36,7 +42,7 @@ IDEs injecting this as context: do not re-link from rules.
 | [`src/server/git-cherry-pick-tool.ts`](src/server/git-cherry-pick-tool.ts) | `git_cherry_pick` — mutating |
 | [`src/server/git-reset-soft-tool.ts`](src/server/git-reset-soft-tool.ts) | `git_reset_soft` — soft-reset; mutating |
 | [`src/server/presets-resource.ts`](src/server/presets-resource.ts) | `rethunk-git://presets` resource |
-| [`src/server/tool-parameter-schemas.ts`](src/server/tool-parameter-schemas.ts) | `buildToolParameterSchemaDocument`, `captureToolParameterSchemas`; backs `tool-parameters.schema.json` |
+| [`src/server/tool-parameter-schemas.ts`](src/server/tool-parameter-schemas.ts) | `buildToolParameterSchemaDocument`, `captureToolParameterSchemas`; backs `tool-parameters.schema.json` and published `schemas/*.json` snapshots |
 | [`src/repo-paths.ts`](src/repo-paths.ts) | `resolvePathForRepo`, `assertRelativePathUnderTop`, `isStrictlyUnderGitTop` |
 
 ## Changing contracts
@@ -44,7 +50,7 @@ IDEs injecting this as context: do not re-link from rules.
 - **No banner paragraphs** in shipped docs. Use normal titles + cross-links.
 - **JSON format version** (currently `"3"`, 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. v3 changes in `git_log`: `sha7` → `sha` (full SHA), `workspace_root` → `workspaceRoot`, `ageRelative` removed, `email` omitted when empty.
 - **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.
+- **Public tool surface:** rename/add → update [docs/mcp-tools.md](docs/mcp-tools.md) + [README.md](README.md) (if mentioned), then regenerate the shipped schema artifacts (`tool-parameters.schema.json`, `schemas/index.json`, `schemas/*.json`). Install/client wiring → [docs/install.md](docs/install.md) only.
 
 ## Validate + CI
 
@@ -54,10 +60,30 @@ Optional [`.githooks/`](.githooks): `bun run setup-hooks` once per clone. pre-co
 
 Path confinement: [`src/repo-paths.ts`](src/repo-paths.ts) — extend tests when changing.
 
+## AI constraints
+
+Rules for LLMs operating in or against this repository.
+
+**End-user Git/MCP preference** (status/log/diff/commits): **`~/.claude/CLAUDE.md`** § **Git & GitHub** — same policy when dogfooding this server from a harness.
+
+**Mutating tools require workspace-root confirmation** — `git_fetch`, `batch_commit`, `git_push`, `git_merge`, `git_cherry_pick`, `git_reset_soft`, `git_tag`, and `git_stash_apply` operate only on roots confirmed by `requireGitAndRoots` / `requireSingleRepo`. Never pass caller-supplied absolute paths to mutating tools; use `workspaceRoot` or MCP roots.
+
+**`batch_commit` atomic staging — single call per logical change** — Do NOT attempt incremental staging across multiple `batch_commit` calls. Each call is self-contained: it stages all files in all entries, commits them sequentially, and the moment the call completes, all commits have landed. Include all related files (for all related commit entries) in a single `batch_commit` call. A call cannot be resumed or extended by a later call — each is an independent transaction. If entry N fails, entries before N remain committed; entries after N are skipped (not rolled back).
+
+**`absoluteGitRoots` is read-only** — pass it only on read tools (`git_status`, `git_inventory`, `git_parity`, `git_log`, `git_diff_summary`, `list_presets`). Mutating tools reject this parameter.
+
+**Protected branches are enforced by the server** — do not attempt `git_worktree_add` with a branch name matching `main`, `master`, `dev`, `develop`, `stable`, `trunk`, `prod`, `production`, `release*`, or `hotfix*`. The server rejects such calls.
+
+**Never force-push** — `git_push` has no force-push mode by design. `git_merge` with `strategy: "ff-only"` will fail cleanly rather than force.
+
+**Contract bumps need documentation** — if a JSON output shape changes incompatibly, bump `MCP_JSON_FORMAT_VERSION` in `src/server.ts` and document the migration in both this file and [docs/mcp-tools.md](docs/mcp-tools.md).
+
+**Path confinement** — any tool accepting file paths must use `resolvePathForRepo` / `assertRelativePathUnderTop` from [`src/repo-paths.ts`](src/repo-paths.ts) and include escaping-attempt tests.
+
 ## Repo MCP entry (contributors)
 
 Dogfood from clone: [docs/install.md](docs/install.md) — *From source*.
 
-Repo ships `.cursor/` with alwaysApply rule [`.cursor/rules/rethunk-git-mcp.mdc`](.cursor/rules/rethunk-git-mcp.mdc) covering MCP-vs-shell usage. Rule does not re-link this file (already injected).
+Client Git policy is still **`~/.claude/CLAUDE.md`** § Git & GitHub (see **End-user Git/MCP preference** above).
 
 User-level skills may mention README for discovery. Canonical refs: tools/JSON → [docs/mcp-tools.md](docs/mcp-tools.md); install → [docs/install.md](docs/install.md); presets → [HUMANS.md](HUMANS.md).

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 All notable changes to `@rethunk/mcp-multi-root-git` are documented here. Format loosely follows [Keep a Changelog](https://keepachangelog.com); the project uses [Semantic Versioning](https://semver.org).
 
+## [Unreleased]
+
+## [2.4.0] — 2026-05-07
+
+New git MCP tools, better `batch_commit` ergonomics, published schema coverage for the full tool surface, and a broad docs/test refresh since `v2.3.4`.
+
+### Added
+
+- **New tools:** `git_fetch`, `git_diff`, `git_show`, `git_tag`, `git_stash_list`, and `git_stash_apply`.
+- **`batch_commit` enhancements:** `dryRun: true` preview mode plus hunk-level staging via `{ path, lines: { from, to } }`.
+- **Published per-tool schema artifacts:** `schemas/index.json` plus one JSON Schema file per tool alongside `tool-parameters.schema.json`.
+
+### Changed
+
+- **`GIT_SUBPROCESS_PARALLELISM`** is now configurable via environment and clamps to a safe `2×CPU` maximum.
+- **`git_show`**, **`git_fetch`**, and **`git_tag`** now use the standard single-repo workspace pick (`workspaceRoot` / `rootIndex`) and omit multi-root-only parameters.
+- **Build / release tooling** now aligns on Bun `1.3.13`, updated dev dependencies, and the current prerelease tarball flow.
+
+### Fixed
+
+- **MCP roots** — workspace root collection now scans active MCP sessions and dedupes `file://` roots instead of relying on a fixed server `cwd`.
+- **`git_push`** and **`batch_commit`** now surface raw git stdout/stderr on failure for easier recovery.
+- **Published schema snapshots** are now complete and in sync with the registered tool surface, including `schema:tools:check`.
+- **`publish:preflight`** now writes temporary coverage output under the platform temp directory instead of a hard-coded `/tmp` path.
+
+### Documentation
+
+- **README / HUMANS / AGENTS / CONTRIBUTING / install docs** refreshed for the current tool surface, shipped schema artifacts, and contributor workflow.
+- **`SECURITY.md`** added with repository access, git-operation risk, and disclosure guidance.
+- **`docs/mcp-tools.md`** now documents the full tool surface, `batch_commit` atomic staging semantics, and the shipped schema artifacts.
+- **`TODO.md`** backlog entries now reflect genuine remaining gaps instead of listing already-implemented tools as missing.
+- **`specs/` scaffold** added with standard `active`, `done`, and `parked` layout for repo planning.
+- **CHANGELOG references** for `v2.3.2`–`v2.3.4` were restored.
+
+### Tests
+
+- Coverage expanded across `list_presets`, `git_parity`, `git_cherry_pick`, `git_merge`, `git_show`, schema generation, and roots handling.
+- The shared git test harness now reuses repo-init / commit helpers and speeds up fixture setup.
+
 ## [2.3.4] — 2026-04-26
 
 Publication-prep patch for the `absoluteGitRoots` line.
@@ -138,6 +177,10 @@ Mutating git operations: merge, cherry-pick, and optional push-after for `batch_
 
 - Initial release: `git_status`, `git_inventory`, `git_parity`, `list_presets`.
 
+[2.4.0]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.4.0
+[2.3.4]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.3.4
+[2.3.3]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.3.3
+[2.3.2]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.3.2
 [2.3.1]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.3.1
 [2.3.0]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.3.0
 [2.2.0]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.2.0

package/HUMANS.md

@@ -55,19 +55,21 @@ If you installed from **GitHub Packages**, use **`./node_modules/@rethunk-ai/mcp
 
 ## Tool parameter schema artifact
 
-The package ships **`tool-parameters.schema.json`**, a generated JSON Schema snapshot of every registered tool's parameter schema. Maintainers regenerate it with:
+The package ships **`tool-parameters.schema.json`**, a generated JSON Schema snapshot of every registered tool's parameter schema, plus the published **`schemas/`** directory with **`schemas/index.json`** and one per-tool JSON Schema file. Maintainers regenerate them with:
 
 ```bash
 bun run schema:tools
+bun run schema:individual
 ```
 
 CI and `prepublishOnly` use:
 
 ```bash
 bun run schema:tools:check
+bun run schema:individual
 ```
 
-This artifact is for inspection, drift checks, and clients that want an offline schema snapshot. Runtime MCP schema discovery remains the source of truth for connected clients.
+These artifacts are for inspection, drift checks, code generation, and clients that want offline schema snapshots. Runtime MCP schema discovery remains the source of truth for connected clients.
 
 **Layouts:**
 
@@ -121,13 +123,60 @@ Example `git_parity` batch using the same pair in each sibling clone:
 
 `absoluteGitRoots` is read-only by design. Mutating tools such as **`batch_commit`**, **`git_push`**, **`git_merge`**, and **`git_cherry_pick`** omit it from their schema; use `workspaceRoot` or MCP roots for writes. Full parameter rules and error codes live in **[docs/mcp-tools.md](docs/mcp-tools.md#absoluteGitRoots-sibling-clones)**.
 
+## Prerequisites
+
+- **Git** on `PATH` (`git --version`). Missing git → all tools return `git_not_found`.
+- **Node.js ≥ 22** (for `npx`) or **Bun** (for `bunx`). See `engines` in `package.json`.
+- No other runtime dependencies; the server is a self-contained MCP stdio process.
+
+## Running the server
+
+The server is a **stdio** MCP process — your MCP client starts it. You do not run it directly. Quick start:
+
+```bash
+# npmjs (public, may lag tags)
+npx -y @rethunk/mcp-multi-root-git
+
+# GitHub Packages (CI-aligned, every tag)
+npx -y @rethunk-ai/mcp-multi-root-git   # requires ~/.npmrc with @rethunk-ai registry token
+```
+
+Add the server to your MCP client config under a stable name (e.g. `rethunk-git`). Full per-client config (Cursor, VS Code, Claude Desktop, Zed): **[docs/install.md](docs/install.md)**.
+
+## Common operations
+
+Call tools by their registered id (prefix depends on client config name):
+
+| Operation | Tool |
+|-----------|------|
+| Check status across workspace roots | `git_status` |
+| Status + ahead/behind for submodules | `git_inventory` |
+| Compare HEAD between path pairs | `git_parity` |
+| List preset names | `list_presets` |
+| View commit log | `git_log` |
+| View structured diff | `git_diff_summary` |
+| View raw diff text | `git_diff` |
+| Inspect commit content | `git_show` |
+| List stashes | `git_stash_list` |
+| Apply or pop a stash | `git_stash_apply` |
+| Fetch remote refs | `git_fetch` |
+| Create commits | `batch_commit` |
+| Push a branch | `git_push` |
+| Create or delete tags | `git_tag` |
+| Merge branches | `git_merge` |
+| Cherry-pick commits | `git_cherry_pick` |
+| Soft-reset HEAD | `git_reset_soft` |
+| Manage worktrees | `git_worktree_list` / `git_worktree_add` / `git_worktree_remove` |
+
+Full parameter tables and JSON shapes: **[docs/mcp-tools.md](docs/mcp-tools.md)**.
+
 ## `git_not_found`
 
-If **`git`** is missing or not runnable, tools and the presets resource respond with **`git_not_found`**. Prerequisites and `PATH`: **[docs/install.md](docs/install.md)**.
+If **`git`** is missing or not runnable, tools and the presets resource respond with **`git_not_found`**. Ensure `git` is on `PATH` in the environment that launches the MCP server.
 
 ## Installation
 
-**Package install and MCP clients:** **[docs/install.md](docs/install.md)**.
+**Full install instructions and MCP client wiring:** **[docs/install.md](docs/install.md)**.
 
 ## Development
 
@@ -150,7 +199,7 @@ Before tagging, run the clean-tree preflight from the release commit:
 bun run publish:preflight
 ```
 
-It verifies the `package.json` version has a matching `CHANGELOG.md` section, generated tool schemas are current, build/check/coverage pass, and `npm pack --dry-run` includes the expected package files.
+It verifies the `package.json` version has a matching `CHANGELOG.md` section, both schema artifacts are current, build/check/coverage pass, and `npm pack --dry-run` includes the expected package files.
 
 ### npmjs (manual) — maintainers only
 

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)
 
-**git** tools over MCP: read-only status, multi-root inventory, `HEAD` parity, presets, structured diff viewer, log, push, worktrees, soft-reset, batch commit, merge, and cherry-pick. **Install and MCP client wiring:** **[docs/install.md](docs/install.md)** only — do not duplicate those steps elsewhere.
+**git** tools over MCP: status, multi-root inventory, `HEAD` parity, presets, logs, structured and raw diff views, commit inspection, fetch, stash, tag, batch commit, push, merge, cherry-pick, worktrees, and soft-reset. **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.
 
@@ -14,7 +14,21 @@
 |-----|----------|
 | **[docs/install.md](docs/install.md)** | Single source for prerequisites, running the package, and every supported MCP client (plus from-source and troubleshooting) |
 | **[docs/mcp-tools.md](docs/mcp-tools.md)** | Tool ids, client naming, `format` / JSON, resource URI, workspace root resolution (canonical reference) |
+| **[schemas/index.json](schemas/index.json)** | Published JSON schemas for all MCP tool parameters (JSON Schema draft 2020-12 format) |
 | **[HUMANS.md](HUMANS.md)** | Preset file, dev commands, CI, publishing |
 | **[AGENTS.md](AGENTS.md)** | Contributors: implementation map ([`src/server/`](src/server/) + entry [`src/server.ts`](src/server.ts)), contract bumps, CI |
+| **[CONTRIBUTING.md](CONTRIBUTING.md)** | Dev setup, hooks, commit conventions, release checks, and how to add tools |
+| **[SECURITY.md](SECURITY.md)** | Disclosure policy, threat model, and repository safety guidance |
+| **[specs/README.md](specs/README.md)** | Active / done / parked specification layout used for repo planning |
 
 **Tools at a glance:** see the table in **[docs/mcp-tools.md](docs/mcp-tools.md)**.
+
+## JSON Schemas
+
+All MCP tool parameters are published as JSON Schema (draft 2020-12) documents in the **[`schemas/`](schemas/)** directory. Tools and validators can use these schemas to validate tool input arguments without reading source code.
+
+**Schema files:**
+- `schemas/index.json` — Index of all 20 tool schemas with file paths
+- `schemas/{tool_name}.json` — Individual schema for each tool (e.g., `schemas/batch_commit.json`, `schemas/git_status.json`)
+
+For programmatic use, read `schemas/index.json` to discover available tools and their schema files.

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

@@ -5,9 +5,24 @@ import { getCurrentBranch, inferRemoteFromUpstream } from "./git-refs.js";
 import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
 import { requireSingleRepo } from "./roots.js";
 import { WorkspacePickSchema } from "./schemas.js";
+const FileEntrySchema = z.union([
+    z.string().min(1),
+    z.object({
+        path: z.string().min(1).describe("File path relative to git root."),
+        lines: z
+            .object({
+            from: z.number().int().min(1).describe("Start line number (1-indexed)."),
+            to: z.number().int().min(1).describe("End line number (1-indexed, inclusive)."),
+        })
+            .describe("Line range to stage. Only hunks overlapping [from, to] are staged."),
+    }),
+]);
 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."),
+    files: z
+        .array(FileEntrySchema)
+        .min(1)
+        .describe("Paths to stage, relative to the git root. Each can be a string path or { path, lines } for hunk-level staging."),
 });
 const PushModeSchema = z
     .enum(["never", "after"])
@@ -16,6 +31,132 @@ const PushModeSchema = z
     .describe("`never` (default): no push. `after`: push the current branch to its upstream once all commits succeed; " +
     "fails with `push_no_upstream` if the branch has no upstream (commits are NOT rolled back). " +
     "Enum reserved for future modes such as `force-with-lease`.");
+const DryRunSchema = z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe("When true, stage files, collect preview (files staged, commit messages), return preview response without writing commits. " +
+    "Unstages any files that were staged for the preview. Response indicates DRY RUN mode.");
+/**
+ * Parses a unified diff to extract hunks that overlap with a given line range.
+ * Returns a partial patch containing only the overlapping hunks, including header lines.
+ * Uses new file line numbers (after @@) to determine overlap.
+ */
+function extractOverlappingHunks(diffContent, fromLine, toLine) {
+    const lines = diffContent.split("\n");
+    // Find file header lines (index, ---, +++)
+    const fileHeaderLines = [];
+    let firstHunkIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line === undefined)
+            continue;
+        if (line.startsWith("@@")) {
+            firstHunkIdx = i;
+            break;
+        }
+        fileHeaderLines.push(line);
+    }
+    if (firstHunkIdx === -1) {
+        // No hunks found
+        return null;
+    }
+    const result = [...fileHeaderLines];
+    let i = firstHunkIdx;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line === undefined) {
+            i++;
+            continue;
+        }
+        // Match hunk header: @@ -oldStart,oldCount +newStart,newCount @@
+        const hunkMatch = /^@@\s+-\d+(?:,\d+)?\s+\+(\d+)(?:,(\d+))?\s+@@/.exec(line);
+        if (hunkMatch) {
+            const newStart = Number.parseInt(hunkMatch[1] || "0", 10);
+            const newCount = Number.parseInt(hunkMatch[2] || "1", 10);
+            const hunkEnd = newStart + newCount - 1;
+            // Check if hunk overlaps with requested line range
+            const hasOverlap = !(hunkEnd < fromLine || newStart > toLine);
+            if (hasOverlap) {
+                // Add hunk header
+                result.push(line);
+                i++;
+                // Add hunk content until next hunk or EOF
+                while (i < lines.length) {
+                    const contentLine = lines[i];
+                    if (contentLine === undefined) {
+                        i++;
+                        continue;
+                    }
+                    // Stop at next hunk header
+                    if (contentLine.startsWith("@@")) {
+                        break;
+                    }
+                    result.push(contentLine);
+                    i++;
+                }
+            }
+            else {
+                // Skip hunk
+                i++;
+                while (i < lines.length) {
+                    const contentLine = lines[i];
+                    if (contentLine === undefined) {
+                        i++;
+                        continue;
+                    }
+                    if (contentLine.startsWith("@@")) {
+                        break;
+                    }
+                    i++;
+                }
+            }
+        }
+        else {
+            i++;
+        }
+    }
+    return result.length > fileHeaderLines.length ? result.join("\n") : null;
+}
+/**
+ * Stages a file with optional line range. If lines are provided, only hunks
+ * overlapping the range are staged via a partial patch. Otherwise, stages the whole file.
+ */
+async function stageFile(gitTop, filePath, lines) {
+    if (!lines) {
+        // Simple case: stage the whole file
+        const addResult = await spawnGitAsync(gitTop, ["add", "--", filePath]);
+        return {
+            ok: addResult.ok,
+            error: addResult.ok ? undefined : (addResult.stderr || addResult.stdout).trim(),
+        };
+    }
+    // Line range case: extract overlapping hunks and apply patch
+    const diffResult = await spawnGitAsync(gitTop, ["diff", filePath]);
+    if (!diffResult.ok) {
+        return { ok: false, error: (diffResult.stderr || diffResult.stdout).trim() };
+    }
+    const partialPatch = extractOverlappingHunks(diffResult.stdout, lines.from, lines.to);
+    if (!partialPatch) {
+        return { ok: false, error: "No hunks found in line range" };
+    }
+    // Write partial patch to temp file in the git repo and apply it to the index
+    const tempPatchFile = `${gitTop}/.git/.mcp-patch-${Date.now()}-${Math.random().toString(36).slice(2)}.patch`;
+    const { writeFileSync, unlinkSync } = await import("node:fs");
+    writeFileSync(tempPatchFile, partialPatch, "utf8");
+    const applyResult = await spawnGitAsync(gitTop, ["apply", "--cached", tempPatchFile]);
+    // Clean up temp file
+    try {
+        unlinkSync(tempPatchFile);
+    }
+    catch {
+        // Ignore cleanup errors
+    }
+    return {
+        ok: applyResult.ok,
+        error: applyResult.ok ? undefined : (applyResult.stderr || applyResult.stdout).trim(),
+    };
+}
 /**
  * After all commits succeed, push the current branch to its upstream.
  * Commits are already applied at this point — do NOT attempt rollback on push failure.
@@ -39,7 +180,13 @@ export async function runPushAfter(gitTop) {
             detail: (pushResult.stderr || pushResult.stdout).trim(),
         };
     }
-    return { ok: true, branch, upstream: t.upstream };
+    const gitOutput = (pushResult.stdout || pushResult.stderr).trim();
+    return {
+        ok: true,
+        branch,
+        upstream: t.upstream,
+        ...spreadDefined("output", gitOutput || undefined),
+    };
 }
 export function registerBatchCommitTool(server) {
     server.addTool({
@@ -47,7 +194,8 @@ export function registerBatchCommitTool(server) {
         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. Optional `push: "after"` pushes the current branch ' +
-            "to its upstream once all commits succeed.",
+            "to its upstream once all commits succeed. " +
+            "Optional `dryRun: true` previews what would be staged/committed without writing commits.",
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -60,6 +208,7 @@ export function registerBatchCommitTool(server) {
                 .max(50)
                 .describe("Commits to create, applied in order."),
             push: PushModeSchema,
+            dryRun: DryRunSchema,
         }),
         execute: async (args) => {
             const pre = requireSingleRepo(server, args);
@@ -67,16 +216,30 @@ export function registerBatchCommitTool(server) {
                 return jsonRespond(pre.error);
             const gitTop = pre.gitTop;
             const results = [];
+            const stagedFilesForCleanup = new Set();
             for (let i = 0; i < args.commits.length; i++) {
                 const entry = args.commits[i];
                 if (!entry)
                     break;
+                // Normalize file entries to { path, lines? } format
+                const fileEntries = [];
+                const filePaths = [];
+                for (const fileEntry of entry.files) {
+                    if (typeof fileEntry === "string") {
+                        fileEntries.push({ path: fileEntry });
+                        filePaths.push(fileEntry);
+                    }
+                    else {
+                        fileEntries.push(fileEntry);
+                        filePaths.push(fileEntry.path);
+                    }
+                }
                 // --- Validate all paths are under the git toplevel ---
                 const escapedPaths = [];
-                for (const rel of entry.files) {
-                    const abs = resolvePathForRepo(rel, gitTop);
+                for (const path of filePaths) {
+                    const abs = resolvePathForRepo(path, gitTop);
                     if (!isStrictlyUnderGitTop(abs, gitTop)) {
-                        escapedPaths.push(rel);
+                        escapedPaths.push(path);
                     }
                 }
                 if (escapedPaths.length > 0) {
@@ -84,53 +247,94 @@ export function registerBatchCommitTool(server) {
                         index: i,
                         ok: false,
                         message: entry.message,
-                        files: entry.files,
+                        files: filePaths,
                         error: "path_escapes_repository",
                         detail: escapedPaths.join(", "),
                     });
                     break;
                 }
-                // --- Stage files ---
-                const addResult = await spawnGitAsync(gitTop, ["add", "--", ...entry.files]);
-                if (!addResult.ok) {
+                // --- Stage files (with optional line ranges) ---
+                let stagingFailed = false;
+                let stagingError = "";
+                for (const fileEntry of fileEntries) {
+                    const stageResult = await stageFile(gitTop, fileEntry.path, fileEntry.lines);
+                    if (!stageResult.ok) {
+                        stagingFailed = true;
+                        stagingError = stageResult.error || "Unknown error";
+                        break;
+                    }
+                }
+                if (stagingFailed) {
                     results.push({
                         index: i,
                         ok: false,
                         message: entry.message,
-                        files: entry.files,
+                        files: filePaths,
                         error: "stage_failed",
-                        detail: (addResult.stderr || addResult.stdout).trim(),
+                        detail: stagingError,
+                        ...spreadDefined("output", stagingError || undefined),
                     });
                     break;
                 }
+                // Track staged files for cleanup in dry-run
+                if (args.dryRun) {
+                    for (const path of filePaths) {
+                        stagedFilesForCleanup.add(path);
+                    }
+                }
+                // --- Dry-run mode: collect preview and unstage ---
+                if (args.dryRun) {
+                    // Get diff stat for this staged entry
+                    const diffStatResult = await spawnGitAsync(gitTop, ["diff", "--staged", "--stat"]);
+                    const diffStat = diffStatResult.ok ? (diffStatResult.stdout || "").trim() : undefined;
+                    results.push({
+                        index: i,
+                        ok: true,
+                        message: entry.message,
+                        files: filePaths,
+                        staged: filePaths,
+                        ...spreadDefined("diffStat", diffStat || undefined),
+                    });
+                    continue; // Skip actual commit in dry-run mode
+                }
                 // --- Commit ---
                 const commitResult = await spawnGitAsync(gitTop, ["commit", "-m", entry.message]);
                 if (!commitResult.ok) {
+                    const gitOutput = (commitResult.stderr || commitResult.stdout).trim();
                     results.push({
                         index: i,
                         ok: false,
                         message: entry.message,
-                        files: entry.files,
+                        files: filePaths,
                         error: "commit_failed",
-                        detail: (commitResult.stderr || commitResult.stdout).trim(),
+                        detail: gitOutput,
+                        ...spreadDefined("output", gitOutput || undefined),
                     });
                     break;
                 }
                 // --- Extract SHA from commit output ---
                 const shaMatch = /\[[\w/.-]+\s+([0-9a-f]+)\]/.exec(commitResult.stdout);
+                const gitOutput = (commitResult.stdout || commitResult.stderr).trim();
                 results.push({
                     index: i,
                     ok: true,
                     sha: shaMatch?.[1],
                     message: entry.message,
-                    files: entry.files,
+                    files: filePaths,
+                    ...spreadDefined("output", gitOutput || undefined),
                 });
             }
+            // --- In dry-run mode, unstage all files ---
+            if (args.dryRun && stagedFilesForCleanup.size > 0) {
+                const filesToReset = Array.from(stagedFilesForCleanup);
+                await spawnGitAsync(gitTop, ["reset", "HEAD", "--", ...filesToReset]);
+            }
             const allOk = results.length === args.commits.length && results.every((r) => r.ok);
-            // --- Optional push after all commits succeed ---
-            const push = allOk && args.push === "after" ? await runPushAfter(gitTop) : undefined;
+            // --- Optional push after all commits succeed (not in dry-run mode) ---
+            const push = !args.dryRun && allOk && args.push === "after" ? await runPushAfter(gitTop) : undefined;
             if (args.format === "json") {
                 return jsonRespond({
+                    ...spreadWhen(args.dryRun, { dryRun: true }),
                     ok: allOk,
                     committed: results.filter((r) => r.ok).length,
                     total: args.commits.length,
@@ -140,8 +344,11 @@ export function registerBatchCommitTool(server) {
                         ...spreadDefined("sha", r.sha),
                         message: r.message,
                         files: r.files,
+                        ...spreadDefined("staged", r.staged),
+                        ...spreadDefined("diffStat", r.diffStat),
                         ...spreadDefined("error", r.error),
                         ...spreadDefined("detail", r.detail),
+                        ...spreadDefined("output", r.output),
                     })),
                     ...spreadWhen(push !== undefined, {
                         push: {
@@ -150,15 +357,17 @@ export function registerBatchCommitTool(server) {
                             ...spreadDefined("upstream", push?.upstream),
                             ...spreadDefined("error", push?.error),
                             ...spreadDefined("detail", push?.detail),
+                            ...spreadDefined("output", push?.output),
                         },
                     }),
                 });
             }
             // --- Markdown ---
             const lines = [];
+            const dryRunPrefix = args.dryRun ? "DRY RUN — " : "";
             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)`;
+                ? `# Batch commit: ${dryRunPrefix}${results.length}/${args.commits.length} committed`
+                : `# Batch commit: ${dryRunPrefix}${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 ? "✓" : "✗";
@@ -167,11 +376,24 @@ export function registerBatchCommitTool(server) {
                 if (!r.ok && r.detail) {
                     lines.push(`  Error: ${r.error} — ${r.detail}`);
                 }
+                if (args.dryRun && r.staged) {
+                    lines.push(`  Staged: ${r.staged.join(", ")}`);
+                }
+                if (args.dryRun && r.diffStat) {
+                    lines.push(`  Diff stat:`);
+                    lines.push(`  ${r.diffStat.replace(/\n/g, "\n  ")}`);
+                }
+                if (r.output) {
+                    lines.push(`  Output: ${r.output.replace(/\n/g, "\n  ")}`);
+                }
             }
             if (!allOk && results.length < args.commits.length) {
                 const skipped = args.commits.length - results.length;
                 lines.push("", `${skipped} remaining commit(s) skipped.`);
             }
+            if (args.dryRun) {
+                lines.push("", "**DRY RUN — no commits written. All staged files have been unstaged.**");
+            }
             if (push) {
                 lines.push("");
                 if (push.ok) {
@@ -180,6 +402,9 @@ export function registerBatchCommitTool(server) {
                 else {
                     lines.push(`Push: ✗ ${push.error}${push.detail ? ` — ${push.detail}` : ""}`);
                 }
+                if (push.output) {
+                    lines.push(`  Output: ${push.output.replace(/\n/g, "\n  ")}`);
+                }
             }
             return lines.join("\n");
         },