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

package/AGENTS.md

@@ -16,25 +16,31 @@ IDEs injecting this as context: do not re-link from rules.
 | [`src/server.ts`](src/server.ts) | `FastMCP` + `roots: { enabled: true }`; `readMcpServerVersion()`; `registerRethunkGitTools` |
 | [`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) | `requireGitAndRoots` — sole public export; session root resolution |
+| [`src/server/roots.ts`](src/server/roots.ts) | `requireGitAndRoots`, `requireSingleRepo` — shared tool preludes; 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/git-refs.ts`](src/server/git-refs.ts) | `isProtectedBranch`, `isSafeGitRefToken`, `isSafeGitRangeToken`, `isSafeGitAncestorRef`; `getCurrentBranch`, `resolveRef`, `isWorkingTreeClean`, `isFullyMergedInto`, `commitListBetween`; `listWorktrees`, `worktreeForBranch`; `conflictPaths` |
 | [`src/server/tools.ts`](src/server/tools.ts) | `registerRethunkGitTools` — dispatches to `register*` below |
 | [`src/server/git-status-tool.ts`](src/server/git-status-tool.ts) | `git_status` |
 | [`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-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/batch-commit-tool.ts`](src/server/batch-commit-tool.ts) | `batch_commit` — sequential multi-commit; mutating |
+| [`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 |
+| [`src/server/git-merge-tool.ts`](src/server/git-merge-tool.ts) | `git_merge` — mutating |
+| [`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/repo-paths.ts`](src/repo-paths.ts) | `resolvePathForRepo`, `assertRelativePathUnderTop`, `isStrictlyUnderGitTop` |
 
 ## Changing contracts
 
 - **No banner paragraphs** in shipped docs. Use normal titles + cross-links.
-- **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.
+- **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.
 
@@ -53,7 +59,3 @@ 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).
 
 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).
-
-## Commits
-
-Conventional Commits. Small themed commits. Why-focused messages. Stage + commit in one invocation per batch.

package/CHANGELOG.md

@@ -0,0 +1,95 @@
+# Changelog
+
+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).
+
+## [2.3.0] — 2026-04-21
+
+Five new tools, a token-efficiency sweep, a targeted breaking change to the `git_log` JSON contract, and test coverage raised from 70% to 89%.
+
+### Added
+
+- **`git_push`** — push the current branch to its configured upstream. Accepts explicit `remote` / `branch` overrides and a `setUpstream: true` flag for first-push (`git push -u`). Refuses on detached HEAD; does not force-push.
+- **`git_worktree_list`** — list all git worktrees (`git worktree list --porcelain`); annotated `readOnlyHint: true`.
+- **`git_worktree_add`** — create a new linked worktree, creating the branch from `baseRef` if it does not yet exist. Refuses on protected branch names (`main`, `master`, `dev`, `release*`, `hotfix*`, …).
+- **`git_worktree_remove`** — remove a registered worktree; refuses to remove the main worktree. Optional `force: true` for dirty trees.
+- **`git_reset_soft`** — soft-reset the current branch to a ref (`HEAD~1`, `HEAD~N`, SHA, branch name). Preserves rewound changes in the staging index — the canonical way to re-split an already-committed chunk. Requires a clean working tree.
+
+### Changed — breaking (`git_log` JSON, `MCP_JSON_FORMAT_VERSION` → `"3"`)
+
+Consumers using `format: "json"` with `git_log` must update field names. All other tools are unaffected.
+
+- `sha7` removed — was always derivable as `sha.slice(0, 7)`.
+- `ageRelative` removed — was human-readable noise in machine output.
+- `workspace_root` renamed to `workspaceRoot` — consistent camelCase with all other fields.
+- `email` is now omitted when empty rather than always present.
+- Error code `not_a_git_repo` corrected to `not_a_git_repository` — consistent with all other tools.
+
+### Changed — non-breaking
+
+- **Token efficiency:** `readOnlyHint: true` added to `git_status`, `git_inventory`, `git_parity`, and `list_presets`. "See docs/mcp-tools.md" suffix dropped from all 9 tool descriptions; descriptions are now self-contained.
+- **`WorkspacePickSchema`** — `rootIndex` and `allWorkspaceRoots` parameters carry inline descriptions so LLMs can pick them without consulting external docs.
+- **`git_merge`** — protected-branch list in the description collapsed to a single canonical reference (was duplicated inline).
+
+### Internal
+
+- `requireSingleRepo` helper extracted to `roots.ts`; replaces copy-paste preludes across `batch_commit`, `git_diff_summary`, `git_merge`, `git_cherry_pick`, `git_push`, `git_reset_soft`, and all `git_worktree_*`.
+- `conflictPaths` extracted from `git-merge-tool.ts` to `git-refs.ts`; shared by `git_merge` and `git_cherry_pick`.
+- `inferRemoteFromUpstream` extracted to `git-refs.ts`; shared by `runPushAfter` (`batch_commit`) and `git_push`.
+- `isWorkingTreeClean` used consistently everywhere (was inlined in `git_reset_soft`).
+
+### Tests
+
+- Coverage: **88.6% lines / 92.8% functions** (up from 69.9% / 71.4%).
+- 262 tests across 15 files (up from 134 across 7 files).
+- New test files: `presets.test.ts`, `inventory.test.ts`, `git-utils.test.ts`, `json.test.ts`, `git-reset-soft-tool.test.ts`, `git-push-tool.test.ts`, `git-worktree-tool.test.ts`, `roots.test.ts`. `git-refs.test.ts` extended with `isSafeGitAncestorRef` cases.
+
+### Documentation
+
+- `docs/mcp-tools.md` — all new tools documented with parameter tables, JSON shapes, and error-code tables.
+- `AGENTS.md` — implementation map updated with all new and refactored modules.
+
+## [2.2.0] — 2026-04-17
+
+Mutating git operations: merge, cherry-pick, and optional push-after for `batch_commit`.
+
+### Added
+
+- **`git_merge`** tool — merge one or more source branches into a destination. Default strategy `auto` cascades fast-forward → rebase → merge-commit per source, preferring linear history. Refuses on dirty tree; stops on first conflict with structured path report. Optional `deleteMergedBranches` / `deleteMergedWorktrees` cascade cleanup, always skipping protected names (`main`, `master`, `dev`, `develop`, `stable`, `trunk`, `prod`, `production`, `release*`, `hotfix*`).
+- **`git_cherry_pick`** tool — play commits from one or more sources onto a destination. Sources may be SHAs, `A..B` ranges, or branch names (expanded to `onto..<branch>`, oldest-first). Uses `--empty=drop` so patch-equivalent re-applies add nothing. Refuses on dirty tree; stops on first conflict, aborting cleanly. Same protected-name cleanup flags as `git_merge`.
+- **`batch_commit`** `push: "after"` — push the current branch to its upstream once every commit in the batch lands. Omitted by default; no behavior change for existing callers.
+
+### Changed
+
+- **Internal** — shared ref/branch helpers extracted to a common module; merge/cherry-pick/batch-commit implementations now reuse the same dirty-tree guards, protected-name checks, and upstream detection.
+- **Tooling** — Biome upgraded to 2.4.11; dev dependency refresh.
+
+### Documentation
+
+- `docs/mcp-tools.md` — `git_merge` and `git_cherry_pick` sections with parameters, JSON shape, and error codes; `batch_commit` `push: "after"` option documented.
+
+## [2.1.0] — prior
+
+- Added `git_log` — path-filtered, time-windowed log across workspace roots.
+- Added `git_diff_summary` — structured, token-efficient diff viewer with per-file truncation and default exclusions (lock files, `dist`, vendor).
+- Added `batch_commit` — sequential multi-commit tool. Mutating, not idempotent.
+- Test harness: fake-server duck-type lets unit tests drive the full FastMCP execute path without a live transport.
+
+## [2.0.1] — prior
+
+- Bug fixes and internal cleanup; no public tool-surface change.
+
+## [2.0.0] — prior
+
+- **Breaking:** JSON response envelope removed. `MCP_JSON_FORMAT_VERSION` now `"2"`; payloads are minified, and optional fields are omitted when empty / `null` / `false` (consumers test for presence, not equality to `null`).
+- Initial preset file schema (`.rethunk/git-mcp-presets.json`) with wrapped and legacy-map layouts.
+
+## [1.0.0] — prior
+
+- Initial release: `git_status`, `git_inventory`, `git_parity`, `list_presets`.
+
+[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
+[2.1.0]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.1.0
+[2.0.1]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.0.1
+[2.0.0]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.0.0
+[1.0.0]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v1.0.0

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, and batch commit. **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, batch commit, merge, and cherry-pick. **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/server/batch-commit-tool.js

@@ -1,19 +1,53 @@
 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 { spawnGitAsync } from "./git.js";
+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 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."),
 });
+const PushModeSchema = z
+    .enum(["never", "after"])
+    .optional()
+    .default("never")
+    .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`.");
+/**
+ * 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.
+ */
+export async function runPushAfter(gitTop) {
+    const branch = await getCurrentBranch(gitTop);
+    if (!branch) {
+        return { ok: false, error: "push_detached_head" };
+    }
+    const t = await inferRemoteFromUpstream(gitTop);
+    if (!t.ok) {
+        return { ok: false, branch, error: "push_no_upstream", detail: t.detail };
+    }
+    const pushResult = await spawnGitAsync(gitTop, ["push", t.remote, branch]);
+    if (!pushResult.ok) {
+        return {
+            ok: false,
+            branch,
+            upstream: t.upstream,
+            error: "push_failed",
+            detail: (pushResult.stderr || pushResult.stdout).trim(),
+        };
+    }
+    return { ok: true, branch, upstream: t.upstream };
+}
 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.",
+            'Stops on first failure. Optional `push: "after"` pushes the current branch ' +
+            "to its upstream once all commits succeed.",
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -25,19 +59,13 @@ export function registerBatchCommitTool(server) {
                 .min(1)
                 .max(50)
                 .describe("Commits to create, applied in order."),
+            push: PushModeSchema,
         }),
         execute: async (args) => {
-            const pre = requireGitAndRoots(server, args, undefined);
+            const pre = requireSingleRepo(server, args);
             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 gitTop = pre.gitTop;
             const results = [];
             for (let i = 0; i < args.commits.length; i++) {
                 const entry = args.commits[i];
@@ -99,6 +127,8 @@ export function registerBatchCommitTool(server) {
                 });
             }
             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;
             if (args.format === "json") {
                 return jsonRespond({
                     ok: allOk,
@@ -113,6 +143,15 @@ export function registerBatchCommitTool(server) {
                         ...spreadDefined("error", r.error),
                         ...spreadDefined("detail", r.detail),
                     })),
+                    ...spreadWhen(push !== undefined, {
+                        push: {
+                            ok: push?.ok ?? false,
+                            ...spreadDefined("branch", push?.branch),
+                            ...spreadDefined("upstream", push?.upstream),
+                            ...spreadDefined("error", push?.error),
+                            ...spreadDefined("detail", push?.detail),
+                        },
+                    }),
                 });
             }
             // --- Markdown ---
@@ -133,6 +172,15 @@ export function registerBatchCommitTool(server) {
                 const skipped = args.commits.length - results.length;
                 lines.push("", `${skipped} remaining commit(s) skipped.`);
             }
+            if (push) {
+                lines.push("");
+                if (push.ok) {
+                    lines.push(`Push: ✓ ${push.branch} → ${push.upstream}`);
+                }
+                else {
+                    lines.push(`Push: ✗ ${push.error}${push.detail ? ` — ${push.detail}` : ""}`);
+                }
+            }
             return lines.join("\n");
         },
     });

package/dist/server/git-cherry-pick-tool.js

@@ -0,0 +1,285 @@
+import { z } from "zod";
+import { spawnGitAsync } from "./git.js";
+import { commitListBetween, conflictPaths, getCurrentBranch, isFullyMergedInto, isProtectedBranch, isSafeGitRangeToken, isSafeGitRefToken, isWorkingTreeClean, resolveRef, worktreeForBranch, } from "./git-refs.js";
+import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
+import { requireSingleRepo } from "./roots.js";
+import { WorkspacePickSchema } from "./schemas.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function cherryPickHead(gitTop) {
+    const r = await spawnGitAsync(gitTop, ["rev-parse", "--verify", "--quiet", "CHERRY_PICK_HEAD"]);
+    if (!r.ok)
+        return undefined;
+    const sha = r.stdout.trim();
+    return sha === "" ? undefined : sha;
+}
+async function abortCherryPick(gitTop) {
+    await spawnGitAsync(gitTop, ["cherry-pick", "--abort"]);
+}
+async function branchExists(gitTop, name) {
+    const r = await spawnGitAsync(gitTop, ["show-ref", "--verify", "--quiet", `refs/heads/${name}`]);
+    return r.ok;
+}
+/**
+ * Expand a source spec into a list of SHAs to cherry-pick.
+ * - `A..B` / `A...B` → `git rev-list --reverse` of the range
+ * - branch name (refs/heads/<name> exists) → `onto..<branch>` oldest-first
+ * - SHA or ref → single commit
+ */
+async function resolveSource(gitTop, onto, raw) {
+    if (raw.includes("..")) {
+        if (!isSafeGitRangeToken(raw)) {
+            return { error: "unsafe_ref_token", raw };
+        }
+        const r = await spawnGitAsync(gitTop, ["rev-list", "--reverse", raw]);
+        if (!r.ok) {
+            return {
+                error: "range_resolution_failed",
+                detail: (r.stderr || r.stdout).trim(),
+                raw,
+            };
+        }
+        const commits = r.stdout
+            .split("\n")
+            .map((l) => l.trim())
+            .filter((l) => l.length > 0);
+        return { raw, kind: "range", commits };
+    }
+    if (!isSafeGitRefToken(raw)) {
+        return { error: "unsafe_ref_token", raw };
+    }
+    if (await branchExists(gitTop, raw)) {
+        const commits = await commitListBetween(gitTop, onto, raw);
+        if (commits === null) {
+            return { error: "range_resolution_failed", raw };
+        }
+        return { raw, kind: "branch", commits };
+    }
+    const sha = await resolveRef(gitTop, raw);
+    if (!sha) {
+        return { error: "source_not_found", raw };
+    }
+    return { raw, kind: "sha", commits: [sha] };
+}
+/**
+ * Pre-filter already-in-destination commits (they would cherry-pick to empty).
+ * Also dedupe across sources while preserving first-seen order per-commit.
+ */
+async function filterAndDedupe(gitTop, onto, resolved) {
+    const seen = new Set();
+    const picks = [];
+    const perSourceKept = new Map();
+    for (const src of resolved) {
+        const kept = [];
+        for (const sha of src.commits) {
+            if (seen.has(sha))
+                continue;
+            seen.add(sha);
+            // Skip commits already reachable from destination (would produce empty commits).
+            const contained = await spawnGitAsync(gitTop, ["merge-base", "--is-ancestor", sha, onto]);
+            if (contained.ok)
+                continue; // already in destination
+            picks.push(sha);
+            kept.push(sha);
+        }
+        perSourceKept.set(src.raw, kept);
+    }
+    return { picks, perSourceKept };
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+export function registerGitCherryPickTool(server) {
+    server.addTool({
+        name: "git_cherry_pick",
+        description: "Play commits from one or more sources onto a destination. Sources may be SHAs, " +
+            "`A..B` ranges, or branch names (expanded to `onto..<branch>`, oldest-first). " +
+            "Commits already reachable from the destination are skipped. Refuses on dirty tree; " +
+            "stops on the first conflict and reports paths. Optional flags auto-delete fully " +
+            "merged source branches and their worktrees, skipping protected names.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+        },
+        parameters: WorkspacePickSchema.extend({
+            sources: z
+                .array(z.string().min(1))
+                .min(1)
+                .max(50)
+                .describe("Sources to cherry-pick: SHA, `A..B` range, or branch name. Branch sources " +
+                "resolve to `onto..<branch>` (only commits missing from destination)."),
+            onto: z
+                .string()
+                .optional()
+                .describe("Destination branch. Defaults to the currently checked-out branch."),
+            deleteMergedBranches: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("After all commits apply, delete each branch-kind source locally " +
+                "(`git branch -d`) when it is fully merged into the destination. " +
+                "Protected names always skipped; never touches remote refs."),
+            deleteMergedWorktrees: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("After success, remove any local worktree attached to a branch-kind source " +
+                "(`git worktree remove`). Protected tails always skipped."),
+        }),
+        execute: async (args) => {
+            const pre = requireSingleRepo(server, args);
+            if (!pre.ok)
+                return jsonRespond(pre.error);
+            const gitTop = pre.gitTop;
+            // --- Resolve destination ---
+            const startBranch = await getCurrentBranch(gitTop);
+            const onto = args.onto?.trim() || startBranch;
+            if (!onto)
+                return jsonRespond({ error: "onto_detached_head" });
+            if (args.onto !== undefined && !isSafeGitRefToken(args.onto)) {
+                return jsonRespond({ error: "unsafe_ref_token", ref: args.onto });
+            }
+            // --- Refuse dirty tree ---
+            if (!(await isWorkingTreeClean(gitTop))) {
+                return jsonRespond({ error: "working_tree_dirty" });
+            }
+            // --- Ensure destination is checked out ---
+            if (onto !== startBranch) {
+                const co = await spawnGitAsync(gitTop, ["checkout", onto]);
+                if (!co.ok) {
+                    return jsonRespond({
+                        error: "checkout_failed",
+                        detail: (co.stderr || co.stdout).trim(),
+                    });
+                }
+            }
+            if (!(await resolveRef(gitTop, onto))) {
+                return jsonRespond({ error: "destination_not_found", ref: onto });
+            }
+            // --- Resolve each source ---
+            const resolved = [];
+            for (const raw of args.sources) {
+                const r = await resolveSource(gitTop, onto, raw);
+                if ("error" in r) {
+                    return jsonRespond({
+                        error: r.error,
+                        source: raw,
+                        ...spreadDefined("detail", r.detail),
+                    });
+                }
+                resolved.push(r);
+            }
+            // --- Dedupe + skip already-present ---
+            const { picks, perSourceKept } = await filterAndDedupe(gitTop, onto, resolved);
+            // --- Apply cherry-pick (single atomic call) ---
+            // `--empty=drop` silently drops commits that would produce no change against the
+            // current tip — makes the tool idempotent when the same patch is re-applied.
+            let conflict;
+            let appliedCount = 0;
+            const preHeadProbe = await spawnGitAsync(gitTop, ["rev-parse", "HEAD"]);
+            const preHead = preHeadProbe.ok ? preHeadProbe.stdout.trim() : "";
+            if (picks.length > 0) {
+                const r = await spawnGitAsync(gitTop, ["cherry-pick", "--empty=drop", ...picks]);
+                if (!r.ok) {
+                    const failedSha = await cherryPickHead(gitTop);
+                    const paths = await conflictPaths(gitTop);
+                    await abortCherryPick(gitTop);
+                    conflict = {
+                        stage: "cherry-pick",
+                        ...spreadDefined("commit", failedSha),
+                        paths,
+                        detail: (r.stderr || r.stdout).trim(),
+                    };
+                }
+                else {
+                    // Actual commits written = HEAD advance count (empty-drop may skip some).
+                    const adv = await spawnGitAsync(gitTop, ["rev-list", "--count", `${preHead}..HEAD`]);
+                    appliedCount = adv.ok ? parseInt(adv.stdout.trim(), 10) || 0 : 0;
+                }
+            }
+            const allOk = !conflict;
+            // --- Cleanup (only on full success, only branch-kind sources) ---
+            const perSourceReport = resolved.map((s) => ({ ...s }));
+            if (allOk) {
+                for (let i = 0; i < perSourceReport.length; i++) {
+                    const src = perSourceReport[i];
+                    if (!src || src.kind !== "branch")
+                        continue;
+                    if (isProtectedBranch(src.raw))
+                        continue;
+                    if (args.deleteMergedWorktrees) {
+                        const path = await worktreeForBranch(gitTop, src.raw);
+                        if (path) {
+                            const tail = path.split("/").pop() ?? "";
+                            if (!isProtectedBranch(tail)) {
+                                const r = await spawnGitAsync(gitTop, ["worktree", "remove", path]);
+                                if (r.ok)
+                                    src.worktreeRemoved = path;
+                            }
+                        }
+                    }
+                    if (args.deleteMergedBranches) {
+                        const merged = await isFullyMergedInto(gitTop, src.raw, onto);
+                        if (merged) {
+                            const r = await spawnGitAsync(gitTop, ["branch", "-d", src.raw]);
+                            if (r.ok)
+                                src.branchDeleted = true;
+                        }
+                    }
+                }
+            }
+            const headProbe = await spawnGitAsync(gitTop, ["rev-parse", "HEAD"]);
+            const headSha = headProbe.ok ? headProbe.stdout.trim() : undefined;
+            if (args.format === "json") {
+                return jsonRespond({
+                    ok: allOk,
+                    onto,
+                    ...spreadDefined("headSha", headSha),
+                    applied: appliedCount,
+                    picked: picks.length,
+                    results: perSourceReport.map((s) => ({
+                        source: s.raw,
+                        kind: s.kind,
+                        resolvedCommits: s.commits.length,
+                        keptCommits: perSourceKept.get(s.raw)?.length ?? 0,
+                        ...spreadWhen(s.branchDeleted === true, { branchDeleted: true }),
+                        ...spreadDefined("worktreeRemoved", s.worktreeRemoved),
+                    })),
+                    ...spreadWhen(conflict !== undefined, {
+                        conflict: {
+                            stage: conflict?.stage ?? "cherry-pick",
+                            ...spreadDefined("commit", conflict?.commit),
+                            paths: conflict?.paths ?? [],
+                            ...spreadDefined("detail", conflict?.detail),
+                        },
+                    }),
+                });
+            }
+            // --- Markdown ---
+            const lines = [];
+            const header = allOk
+                ? `# Cherry-pick onto \`${onto}\`: ${appliedCount} commit(s) applied`
+                : `# Cherry-pick onto \`${onto}\`: stopped on conflict after ${appliedCount} commit(s)`;
+            lines.push(header, "");
+            for (const s of perSourceReport) {
+                const kept = perSourceKept.get(s.raw)?.length ?? 0;
+                const tail = [`${s.kind}`, `${kept}/${s.commits.length} picked`];
+                if (s.branchDeleted)
+                    tail.push("branch deleted");
+                if (s.worktreeRemoved)
+                    tail.push(`worktree removed: ${s.worktreeRemoved}`);
+                lines.push(`- ${s.raw}  —  ${tail.join(", ")}`);
+            }
+            if (conflict) {
+                lines.push("", `Conflict at commit \`${conflict.commit ?? "?"}\` (${conflict.stage}):`);
+                for (const p of conflict.paths)
+                    lines.push(`  conflict: ${p}`);
+                if (conflict.detail)
+                    lines.push(`  detail: ${conflict.detail}`);
+            }
+            return lines.join("\n");
+        },
+    });
+}

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

@@ -1,8 +1,8 @@
 import { matchesGlob } from "node:path";
 import { z } from "zod";
-import { gitTopLevel, isSafeGitUpstreamToken, spawnGitAsync } from "./git.js";
+import { isSafeGitUpstreamToken, spawnGitAsync } from "./git.js";
 import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
-import { requireGitAndRoots } from "./roots.js";
+import { requireSingleRepo } from "./roots.js";
 import { WorkspacePickSchema } from "./schemas.js";
 // ---------------------------------------------------------------------------
 // Constants
@@ -156,7 +156,7 @@ export function registerGitDiffSummaryTool(server) {
         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.",
+            "Use `range` to target staged, HEAD, or any revision range.",
         annotations: {
             readOnlyHint: true,
         },
@@ -192,17 +192,10 @@ export function registerGitDiffSummaryTool(server) {
                 .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);
+            const pre = requireSingleRepo(server, args);
             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 gitTop = pre.gitTop;
             // --- Build git diff args ---
             const diffArgsResult = buildDiffArgs(args.range);
             if (!diffArgsResult.ok) {

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

@@ -8,7 +8,10 @@ import { MAX_INVENTORY_ROOTS_DEFAULT, WorkspacePickSchema } from "./schemas.js";
 export function registerGitInventoryTool(server) {
     server.addTool({
         name: "git_inventory",
-        description: "Read-only status + ahead/behind per root. See docs/mcp-tools.md.",
+        description: "Read-only status + ahead/behind per root.",
+        annotations: {
+            readOnlyHint: true,
+        },
         parameters: WorkspacePickSchema.extend({
             nestedRoots: z.array(z.string()).optional(),
             preset: z.string().optional(),