@rethunk/mcp-multi-root-git 2.8.0 → 2.9.0

package/AGENTS.md

@@ -23,7 +23,7 @@ IDEs injecting this as context: do not re-link from rules.
 | [`src/server/schemas.ts`](src/server/schemas.ts) | `WorkspacePickSchema`, `MAX_INVENTORY_ROOTS_DEFAULT`, **`MAX_ABSOLUTE_GIT_ROOTS`** (256), optional **`absoluteGitRoots`** on workspace pick |
 | [`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`, `isContentEquivalentlyMergedInto`, `commitListBetween`; `listWorktrees`, `worktreeForBranch`; `inferRemoteFromUpstream`; `conflictPaths` |
-| [`src/server/tools.ts`](src/server/tools.ts) | `registerRethunkGitTools` — dispatches to `register*` below |
+| [`src/server/tools.ts`](src/server/tools.ts) | `registerRethunkGitTools` — dispatches to `register*` below; `selectToolRegistrars(envValue, registrars)` — pure parse/filter fn for `RETHUNK_GIT_TOOLS` (reads env inside `registerRethunkGitTools`, not at module scope); `TOOL_REGISTRARS` ordered array |
 | [`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` |
@@ -54,7 +54,7 @@ IDEs injecting this as context: do not re-link from rules.
 
 ## Validate + CI
 
-Local: `bun run build` | `bun run check` | `bun run schema:tools:check` | `bun run test`. CI ([`ci.yml`](.github/workflows/ci.yml)) runs same on PRs + `main` after `bun install --frozen-lockfile`, then `bun run test:coverage` + `bun run coverage:check`, and uploads prerelease `npm pack` artifact. Tag `v*.*.*` matching `package.json` version → [`release.yml`](.github/workflows/release.yml) publishes to GitHub Packages as `@rethunk-ai/mcp-multi-root-git` + cuts GitHub Release. npmjs publish is manual (see [HUMANS.md](HUMANS.md)).
+Local: `bun run build` | `bun run lint` | `bun run schema:tools:check` | `bun run test`. CI ([`ci.yml`](.github/workflows/ci.yml)) runs same on PRs + `main` after `bun install --frozen-lockfile`, then `bun run test:coverage` + `bun run coverage:check`, and uploads prerelease `npm pack` artifact. Tag `v*.*.*` matching `package.json` version → [`release.yml`](.github/workflows/release.yml) publishes to GitHub Packages as `@rethunk-ai/mcp-multi-root-git` + cuts GitHub Release. npmjs publish is manual (see [HUMANS.md](HUMANS.md)).
 
 Optional [`.githooks/`](.githooks): `bun run setup-hooks` once per clone. pre-commit=`check`; pre-push=frozen install + build + check + test.
 

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 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.9.0] — 2026-06-05
+
+Feature release: `RETHUNK_GIT_TOOLS` allowlist env var. Additive — no JSON format-version bump.
+
+### Added
+
+- **`RETHUNK_GIT_TOOLS`** — comma-separated allowlist of exact tool names. When set to a non-empty value, only the listed tools are registered; unknown names are warned to stderr and ignored. When unset or empty (default), all 23 tools are registered — zero behavioral change for existing consumers. If every name in the list is unrecognized, zero tools are registered and a loud warning is emitted (the restriction is honored literally rather than falling back to all tools). The presets resource (`rethunk-git://presets`) is always registered regardless of this setting. Cuts MCP token cost for agents that only need a small subset of tools. Example: `RETHUNK_GIT_TOOLS=git_status,git_diff_summary,git_diff,git_log,batch_commit,git_push`.
+
 ## [2.8.0] — 2026-05-29
 
 Feature release: three new read-only inspection tools (tool count 20 → 23). Additive — no JSON format-version bump.

package/HUMANS.md

@@ -205,7 +205,7 @@ It verifies the `package.json` version has a matching `CHANGELOG.md` section, bo
 
 npmjs no longer fits an unattended CI publish flow for this org; **do not** rely on automation to [npmjs](https://www.npmjs.com/package/@rethunk/mcp-multi-root-git). To publish the **same** package name consumers already use (**`@rethunk/mcp-multi-root-git`**):
 
-1. On a clean checkout at the release commit (usually **`main`** after bumping version), run **`bun run prepublishOnly`** (or `bun run build && bun run check && bun run test`).
+1. On a clean checkout at the release commit (usually **`main`** after bumping version), run **`bun run prepublishOnly`** (or `bun run build && bun run lint && bun run test`).
 2. Log in to the public registry once per machine: **`npm login`** (or `npm adduser`) so **`npm whoami`** shows the account that owns **`@rethunk`** on npmjs.
 3. Ensure **`package.json`** still has **`"name": "@rethunk/mcp-multi-root-git"`** and **`publishConfig.access`** is **`"public"`** (no **`publishConfig.registry`** pointing at GitHub — leave default registry for npmjs).
 4. Publish: **`npm publish --access public`** (runs **`prepublishOnly`** again unless you pass **`--ignore-scripts`** after you already verified locally).

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

@@ -24,23 +24,20 @@ const CommitEntrySchema = z.object({
     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. " +
-        "Deleted files (missing on disk but tracked in HEAD) are staged as removals via `git rm --cached`. " +
-        "Combining { path, lines } with a deleted file is an error."),
+        .describe("Paths to stage, relative to git root. String or `{ path, lines }` for hunk-level staging. " +
+        "Deleted tracked files are staged via `git rm --cached`. Cannot combine `lines` with a deleted file."),
 });
 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`.");
+    .describe("`never` (default): no push. `after`: push current branch to upstream after all commits succeed; " +
+    "fails with `push_no_upstream` if no upstream (commits are NOT rolled back).");
 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.");
+    .describe("Stage files and return a preview without writing commits; unstages afterwards. Response is marked DRY RUN.");
 /**
  * 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.
@@ -220,11 +217,9 @@ export async function runPushAfter(gitTop) {
 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. Optional `push: "after"` pushes the current branch ' +
-            "to its upstream once all commits succeed. " +
-            "Optional `dryRun: true` previews what would be staged/committed without writing commits.",
+        description: "Create multiple sequential git commits in one call. " +
+            "Each entry stages its files then commits. Stops on first failure. " +
+            'Optional `push: "after"` pushes after all commits succeed. `dryRun: true` previews without writing.',
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -235,7 +230,7 @@ export function registerBatchCommitTool(server) {
                 .array(CommitEntrySchema)
                 .min(1)
                 .max(50)
-                .describe("Commits to create, applied in order."),
+                .describe("Ordered list of commits to create."),
             push: PushModeSchema,
             dryRun: DryRunSchema,
         }),

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

@@ -100,9 +100,7 @@ function renderBranchListMarkdown(result) {
 export function registerGitBranchListTool(server) {
     server.addTool({
         name: "git_branch_list",
-        description: "List local branches (and optionally remote-tracking branches) for a single git repository. " +
-            "Returns `{ branches: [{ name, sha, current, upstream? }], remotes?: [{ name, sha }] }`. " +
-            "The current branch is marked with `current: true`. Remote branches are included when `includeRemotes: true`.",
+        description: "List local (and optionally remote-tracking) branches. Current branch marked `current: true`. Set `includeRemotes: true` for remotes.",
         annotations: {
             readOnlyHint: true,
         },
@@ -117,7 +115,7 @@ export function registerGitBranchListTool(server) {
                 .boolean()
                 .optional()
                 .default(false)
-                .describe("When true, also return remote-tracking branches from refs/remotes (excluding symbolic origin/HEAD)."),
+                .describe("Include remote-tracking branches from refs/remotes (symbolic origin/HEAD excluded)."),
         }),
         execute: async (args) => {
             const pre = requireSingleRepo(server, args);

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

@@ -94,14 +94,11 @@ async function filterAndDedupe(gitTop, onto, resolved) {
 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 source " +
-            "branches and worktrees after success; deletion uses patch-id equivalence by default " +
-            "(content-identical commits with different SHAs are treated as merged, which is the " +
-            "normal cherry-pick outcome). Pass `strictMergedRefEquality: true` for strict `git branch -d` " +
-            "ancestry semantics. Protected branch names always skipped.",
+        description: "Cherry-pick commits from one or more sources onto a destination. Sources: SHAs, `A..B` ranges, " +
+            "or branch names (expanded to `onto..<branch>`, oldest-first). Already-reachable commits skipped. " +
+            "Refuses on dirty tree; stops on first conflict. Optional flags delete source branches/worktrees " +
+            "after success using patch-id equivalence (set `strictMergedRefEquality: true` for strict ancestry). " +
+            "Protected names always skipped.",
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -112,8 +109,7 @@ export function registerGitCherryPickTool(server) {
                 .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)."),
+                .describe("Sources: SHA, `A..B` range, or branch name (resolves to `onto..<branch>`)."),
             onto: z
                 .string()
                 .optional()
@@ -122,24 +118,18 @@ export function registerGitCherryPickTool(server) {
                 .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."),
+                .describe("Delete branch-kind sources locally after success. Protected names and remote refs unaffected."),
             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."),
+                .describe("Remove local worktrees on branch-kind sources after success. Protected tails skipped."),
             strictMergedRefEquality: z
                 .boolean()
                 .optional()
                 .default(false)
-                .describe("When false (default), branch deletion uses patch-id equivalence: a source branch " +
-                "is deleted when every commit it contains has a content-equivalent commit on the " +
-                "destination (same diff, different SHA — the normal cherry-pick outcome). " +
-                "Set to true to require strict ref ancestry (`git branch -d` semantics), which " +
-                "will refuse deletion after a cherry-pick because the SHA differs."),
+                .describe("false (default): delete branch when every commit is content-equivalent on destination (patch-id, normal cherry-pick outcome). " +
+                "true: require strict ref ancestry (`git branch -d` semantics — will refuse after cherry-pick due to SHA mismatch)."),
         }),
         execute: async (args) => {
             const pre = requireSingleRepo(server, args);
@@ -218,7 +208,7 @@ export function registerGitCherryPickTool(server) {
             if (allOk) {
                 for (let i = 0; i < perSourceReport.length; i++) {
                     const src = perSourceReport[i];
-                    if (!src || src.kind !== "branch")
+                    if (src?.kind !== "branch")
                         continue;
                     if (isProtectedBranch(src.raw))
                         continue;

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

@@ -179,9 +179,8 @@ function rangeLabel(range, diffArgs) {
 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.",
+        description: "Structured diff viewer: per-file diffs with counts, truncated to configurable limits. " +
+            "Noise files (lock files, dist, etc.) excluded by default. Use `range` to target staged, HEAD, or a revision range.",
         annotations: {
             readOnlyHint: true,
         },
@@ -214,7 +213,7 @@ export function registerGitDiffSummaryTool(server) {
             excludePatterns: z
                 .array(z.string())
                 .optional()
-                .describe("Glob patterns to exclude. Defaults to common noise: lock files, dist, vendor, etc."),
+                .describe("Glob patterns to exclude. Default: lock files, dist, vendor, etc."),
         }),
         execute: async (args) => {
             const pre = requireSingleRepo(server, args);

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

@@ -61,10 +61,8 @@ function rangeLabel(opts) {
 export function registerGitDiffTool(server) {
     server.addTool({
         name: "git_diff",
-        description: "Get diff text for scoped file(s) or range. Returns the raw diff output. " +
-            "Use `staged: true` for staged changes, `base`/`head` for revision ranges, " +
-            "`path` to scope to a single file, `paths` to scope to multiple files, " +
-            "and `unified` to control the number of context lines.",
+        description: "Raw diff text for scoped file(s) or range. `staged: true` for staged changes, " +
+            "`base`/`head` for revision ranges, `path`/`paths` to scope, `unified` for context lines.",
         annotations: {
             readOnlyHint: true,
         },
@@ -75,37 +73,31 @@ export function registerGitDiffTool(server) {
             base: z
                 .string()
                 .optional()
-                .describe('Base ref (e.g. "main", "HEAD~3"). Required for range diffs. ' +
-                "If omitted and `staged: false`, shows unstaged changes."),
+                .describe('Base ref (e.g. "main", "HEAD~3"). Omit for unstaged changes.'),
             head: z
                 .string()
                 .optional()
-                .describe('Head ref (e.g. "feature-branch"). If omitted, defaults to HEAD. ' +
-                "Only used if `base` is provided."),
+                .describe('Head ref (e.g. "feature-branch"). Defaults to HEAD. Used only when `base` is set.'),
             path: z
                 .string()
                 .optional()
-                .describe('Scope diff to a single file path (e.g. "src/main.ts"). ' +
-                "For multiple files, prefer `paths`. If both `path` and `paths` are given, they are unioned."),
+                .describe("Scope to a single file. Unioned with `paths` if both given."),
             paths: z
                 .array(z.string())
                 .optional()
-                .describe('Scope diff to multiple file paths (e.g. ["src/a.ts", "src/b.ts"]). ' +
-                "Each path is validated and must lie within the repository root. " +
-                "If both `path` and `paths` are given, they are unioned."),
+                .describe("Scope to multiple files (must be within repo root). Unioned with `path` if both given."),
             staged: z
                 .boolean()
                 .optional()
                 .default(false)
-                .describe("If true, show staged changes (git diff --staged). " + "Ignored if `base` is provided."),
+                .describe("Show staged changes (`git diff --staged`). Ignored if `base` is set."),
             unified: z
                 .number()
                 .int()
                 .min(0)
                 .max(100)
                 .optional()
-                .describe("Number of context lines to show around each change (passed as -U<n> to git diff). " +
-                "Defaults to git's built-in default (3). Use 0 for no context."),
+                .describe("Context lines around each change (`-U<n>`). Default: 3. Use 0 for no context."),
         }),
         execute: async (args) => {
             const pre = requireSingleRepo(server, args);

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

@@ -176,8 +176,7 @@ function renderLogMarkdown(group, filterSummary) {
 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.",
+        description: "Read-only `git log` across one or more roots. Returns author, date, subject, optional diff stats.",
         annotations: {
             readOnlyHint: true,
         },
@@ -186,26 +185,21 @@ export function registerGitLogTool(server) {
                 .enum(["markdown", "json", "oneline"])
                 .optional()
                 .default("markdown")
-                .describe("`markdown` (default): headed sections per root. " +
-                "`json`: structured groups array. " +
-                "`oneline`: `<sha7> <subject>` per line, no headers (single-root) or `### repo (branch)` separator per group (multi-root). Lowest-token option for post-commit verification."),
+                .describe("`markdown` (default): headed sections per root. `json`: groups array. " +
+                "`oneline`: `<sha7> <subject>` per line; lowest-token option for post-commit verification."),
             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`."),
+                .describe("Passed to `--since=`. ISO timestamp or git relative form (`48.hours`, `2.weeks.ago`). Default: `7.days`."),
             paths: z
                 .array(z.string())
                 .optional()
-                .describe("Limit to commits touching these paths (passed as `-- <paths>`)."),
+                .describe("Limit to commits touching these paths (`-- <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=`)."),
+                .describe("Filter by commit message regex (git `--grep`, case-insensitive)."),
+            author: z.string().optional().describe("Filter by author name or email (`--author=`)."),
             maxCommits: z
                 .number()
                 .int()
@@ -213,7 +207,7 @@ export function registerGitLogTool(server) {
                 .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}.`),
+                .describe(`Max commits 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) => {

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

@@ -207,12 +207,10 @@ async function maybeDeleteBranch(gitTop, source, enabled, into) {
 export function registerGitMergeTool(server) {
     server.addTool({
         name: "git_merge",
-        description: "Merge one or more source branches into a destination. Default strategy `auto` " +
-            "cascades fast-forward → rebase → merge-commit per source, preferring linear history. " +
-            "Refuses if the working tree is dirty. Stops on the first conflict and reports " +
-            "the affected paths. Optional flags auto-delete merged branches and worktrees, " +
-            "skipping protected names (main, master, dev, develop, stable, trunk, prod, " +
-            "production, release/*, hotfix/*).",
+        description: "Merge one or more source branches into a destination. `auto` cascades " +
+            "fast-forward → rebase → merge-commit, preferring linear history. " +
+            "Refuses on dirty tree; stops on first conflict. Optional flags delete merged branches/worktrees " +
+            "(protected names skipped: main, master, dev, develop, stable, trunk, prod, production, release/*, hotfix/*).",
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -237,14 +235,12 @@ export function registerGitMergeTool(server) {
                 .boolean()
                 .optional()
                 .default(false)
-                .describe("After all sources merge cleanly, delete each source branch locally (`git branch -d`). " +
-                "Protected names always skipped. Never affects remote branches."),
+                .describe("Delete each source branch locally after clean merge (`git branch -d`). Protected names and remote refs unaffected."),
             deleteMergedWorktrees: z
                 .boolean()
                 .optional()
                 .default(false)
-                .describe("After all sources merge cleanly, remove any local worktree currently checked out " +
-                "on a source branch (`git worktree remove`). Protected tails always skipped."),
+                .describe("Remove local worktrees on source branches after clean merge (`git worktree remove`). Protected tails skipped."),
         }),
         execute: async (args) => {
             const pre = requireSingleRepo(server, args);

package/dist/server/git-reset-soft-tool.js

@@ -8,10 +8,8 @@ import { WorkspacePickSchema } from "./schemas.js";
 export function registerGitResetSoftTool(server) {
     server.addTool({
         name: "git_reset_soft",
-        description: "Soft-reset the current branch to a reference (`git reset --soft <ref>`). " +
-            "Moves the branch pointer back while keeping all changes from the rewound commits " +
-            "in the staging index — use this to re-split an already-committed chunk. " +
-            "Refuses when the working tree has any uncommitted or unstaged changes (run on a clean tree).",
+        description: "`git reset --soft <ref>`: moves HEAD back while keeping rewound changes staged. " +
+            "Use to re-split committed work. Refuses on a dirty tree.",
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -21,8 +19,7 @@ export function registerGitResetSoftTool(server) {
             ref: z
                 .string()
                 .min(1)
-                .describe("Commit to reset to. Accepts ancestor notation (`HEAD~1`, `HEAD~3`), " +
-                "branch names, or full SHAs."),
+                .describe("Commit to reset to: ancestor notation (`HEAD~1`, `HEAD~3`), branch name, or SHA."),
         }),
         execute: async (args) => {
             const pre = requireSingleRepo(server, args);

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

@@ -10,7 +10,7 @@ import { WorkspacePickSchema } from "./schemas.js";
 export function registerGitStashListTool(server) {
     server.addTool({
         name: "git_stash_list",
-        description: "List all git stashes. Returns array of `{ index: number, message: string, sha: string }`.",
+        description: "List all git stashes.",
         annotations: {
             readOnlyHint: true,
         },
@@ -77,9 +77,7 @@ export function registerGitStashListTool(server) {
 export function registerGitStashApplyTool(server) {
     server.addTool({
         name: "git_stash_apply",
-        description: "Apply or pop a git stash. `index` defaults to 0 (stash@{0}). " +
-            "Set `pop: true` to run `git stash pop` instead of `git stash apply` (removes stash after applying). " +
-            "Returns `{ applied: boolean, stashIndex: number, popped: boolean, output: string }`.",
+        description: "Apply or pop a git stash. `index` defaults to 0. `pop: true` removes stash after applying.",
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -103,7 +101,7 @@ export function registerGitStashApplyTool(server) {
                 .boolean()
                 .optional()
                 .default(false)
-                .describe("If true, runs `git stash pop` instead of `git stash apply` (removes stash after applying)."),
+                .describe("Run `git stash pop` instead of `git stash apply` (removes stash after applying)."),
         }),
         execute: async (args) => {
             const pre = requireSingleRepo(server, args);

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

@@ -49,8 +49,7 @@ export function registerGitWorktreeListTool(server) {
 export function registerGitWorktreeAddTool(server) {
     server.addTool({
         name: "git_worktree_add",
-        description: "Add a new git worktree. If `branch` does not exist it is created from `baseRef` " +
-            "(defaults to HEAD). Refuses to create on a protected branch name.",
+        description: "Add a new git worktree. Creates `branch` from `baseRef` (default: HEAD) if it doesn't exist. Refuses protected branch names.",
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -60,15 +59,15 @@ export function registerGitWorktreeAddTool(server) {
             path: z
                 .string()
                 .min(1)
-                .describe("Filesystem path for the new worktree. Relative paths are resolved from the git toplevel."),
+                .describe("Filesystem path for the new worktree (relative paths resolved from git toplevel)."),
             branch: z
                 .string()
                 .min(1)
-                .describe("Branch to check out in the new worktree. Created from `baseRef` if absent."),
+                .describe("Branch to check out; created from `baseRef` if it doesn't exist."),
             baseRef: z
                 .string()
                 .optional()
-                .describe("Commit-ish to base the new branch on when it does not yet exist. Default: HEAD."),
+                .describe("Commit-ish to base the new branch on. Default: HEAD."),
         }),
         execute: async (args) => {
             const pre = requireSingleRepo(server, args);
@@ -132,9 +131,7 @@ export function registerGitWorktreeAddTool(server) {
 export function registerGitWorktreeRemoveTool(server) {
     server.addTool({
         name: "git_worktree_remove",
-        description: "Remove a git worktree (`git worktree remove`). " +
-            "Pass `force: true` to remove a worktree with uncommitted changes. " +
-            "Refuses to remove the main worktree.",
+        description: "Remove a git worktree. Pass `force: true` to remove with uncommitted changes. Refuses to remove the main worktree.",
         annotations: {
             readOnlyHint: false,
             destructiveHint: true,
@@ -149,7 +146,7 @@ export function registerGitWorktreeRemoveTool(server) {
                 .boolean()
                 .optional()
                 .default(false)
-                .describe("Pass `--force` to allow removal of worktrees with uncommitted changes."),
+                .describe("Allow removal of worktrees with uncommitted changes (`--force`)."),
         }),
         execute: async (args) => {
             const pre = requireSingleRepo(server, args);

package/dist/server/schemas.js

@@ -4,24 +4,24 @@ const FormatSchema = z.enum(["markdown", "json"]).optional().default("markdown")
 /** Max paths in `absoluteGitRoots` (matches `git_inventory` `maxRoots` hard cap). */
 export const MAX_ABSOLUTE_GIT_ROOTS = 256;
 export const WorkspacePickSchema = z.object({
-    workspaceRoot: z.string().optional().describe("Highest-priority override."),
+    workspaceRoot: z.string().optional().describe("Highest-priority root override."),
     rootIndex: z
         .number()
         .int()
         .min(0)
         .optional()
-        .describe("0-based index into the MCP file roots list; ignored when workspaceRoot is set."),
+        .describe("0-based index into MCP roots; ignored if workspaceRoot set."),
     allWorkspaceRoots: z
         .boolean()
         .optional()
         .default(false)
-        .describe("Fan out across all MCP file roots."),
+        .describe("Fan out across all MCP roots."),
     /** Independent git worktrees (sibling clones). Mutually exclusive with workspaceRoot, rootIndex, allWorkspaceRoots, and (git_inventory) preset/nestedRoots. */
     absoluteGitRoots: z
         .array(z.string())
         .max(MAX_ABSOLUTE_GIT_ROOTS)
         .optional()
-        .describe("Absolute paths to git repo roots. Use for many sibling clones under a non-git parent directory."),
+        .describe("Absolute paths to git repo roots; use for sibling clones under a non-git parent."),
     format: FormatSchema,
 });
 export { MAX_INVENTORY_ROOTS_DEFAULT };

package/dist/server/tools.js

@@ -19,32 +19,73 @@ import { registerGitTagTool } from "./git-tag-tool.js";
 import { registerGitWorktreeAddTool, registerGitWorktreeListTool, registerGitWorktreeRemoveTool, } from "./git-worktree-tool.js";
 import { registerListPresetsTool } from "./list-presets-tool.js";
 import { registerPresetsResource } from "./presets-resource.js";
-export function registerRethunkGitTools(server) {
+/**
+ * Ordered registry of all 23 MCP tools. Registration order is preserved for
+ * both full and filtered (RETHUNK_GIT_TOOLS) subsets.
+ */
+const TOOL_REGISTRARS = [
     // Read-only tools
-    registerGitStatusTool(server);
-    registerGitInventoryTool(server);
-    registerGitParityTool(server);
-    registerListPresetsTool(server);
-    registerGitLogTool(server);
-    registerGitDiffSummaryTool(server);
-    registerGitDiffTool(server);
-    registerGitShowTool(server);
-    registerGitWorktreeListTool(server);
-    registerGitStashListTool(server);
-    registerGitFetchTool(server);
-    registerGitBlameTool(server);
-    registerGitBranchListTool(server);
-    registerGitReflogTool(server);
+    { name: "git_status", register: registerGitStatusTool },
+    { name: "git_inventory", register: registerGitInventoryTool },
+    { name: "git_parity", register: registerGitParityTool },
+    { name: "list_presets", register: registerListPresetsTool },
+    { name: "git_log", register: registerGitLogTool },
+    { name: "git_diff_summary", register: registerGitDiffSummaryTool },
+    { name: "git_diff", register: registerGitDiffTool },
+    { name: "git_show", register: registerGitShowTool },
+    { name: "git_worktree_list", register: registerGitWorktreeListTool },
+    { name: "git_stash_list", register: registerGitStashListTool },
+    { name: "git_fetch", register: registerGitFetchTool },
+    { name: "git_blame", register: registerGitBlameTool },
+    { name: "git_branch_list", register: registerGitBranchListTool },
+    { name: "git_reflog", register: registerGitReflogTool },
     // Mutating tools
-    registerBatchCommitTool(server);
-    registerGitPushTool(server);
-    registerGitMergeTool(server);
-    registerGitCherryPickTool(server);
-    registerGitResetSoftTool(server);
-    registerGitTagTool(server);
-    registerGitWorktreeAddTool(server);
-    registerGitWorktreeRemoveTool(server);
-    registerGitStashApplyTool(server);
-    // Resources
+    { name: "batch_commit", register: registerBatchCommitTool },
+    { name: "git_push", register: registerGitPushTool },
+    { name: "git_merge", register: registerGitMergeTool },
+    { name: "git_cherry_pick", register: registerGitCherryPickTool },
+    { name: "git_reset_soft", register: registerGitResetSoftTool },
+    { name: "git_tag", register: registerGitTagTool },
+    { name: "git_worktree_add", register: registerGitWorktreeAddTool },
+    { name: "git_worktree_remove", register: registerGitWorktreeRemoveTool },
+    { name: "git_stash_apply", register: registerGitStashApplyTool },
+];
+/**
+ * Parse the RETHUNK_GIT_TOOLS env var and return the matching subset of
+ * registrars plus any unrecognized token names.
+ *
+ * @param envValue  Raw value of process.env.RETHUNK_GIT_TOOLS (may be undefined).
+ * @param registrars  Full ordered registrar list (injectable for tests).
+ */
+export function selectToolRegistrars(envValue, registrars) {
+    const tokens = (envValue ?? "")
+        .split(",")
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0);
+    // Unset, empty, or whitespace-only → register all tools.
+    if (tokens.length === 0) {
+        return { selected: registrars, unknown: [] };
+    }
+    const knownNames = new Set(registrars.map((r) => r.name));
+    const requested = new Set(tokens);
+    const unknown = tokens.filter((t) => !knownNames.has(t));
+    // Preserve canonical order; deduplicate duplicate tokens automatically.
+    const selected = registrars.filter((r) => requested.has(r.name));
+    return { selected, unknown };
+}
+export function registerRethunkGitTools(server) {
+    const env = process.env.RETHUNK_GIT_TOOLS;
+    const { selected, unknown } = selectToolRegistrars(env, TOOL_REGISTRARS);
+    if (unknown.length > 0) {
+        process.stderr.write(`[rethunk-git] RETHUNK_GIT_TOOLS: unknown tool name(s) ignored: ${unknown.map((n) => JSON.stringify(n)).join(", ")}\n`);
+    }
+    if (selected.length === 0 && (env ?? "").trim().length > 0) {
+        process.stderr.write(`[rethunk-git] RETHUNK_GIT_TOOLS: every listed name was unrecognized — registering NO tools. ` +
+            `Set RETHUNK_GIT_TOOLS to a comma-separated list of valid tool names, or unset it to register all tools.\n`);
+    }
+    for (const { register } of selected) {
+        register(server);
+    }
+    // The presets RESOURCE is always registered, regardless of the tool allowlist.
     registerPresetsResource(server);
 }

package/docs/install.md

@@ -92,6 +92,7 @@ Omit any `cwd` / `workingDirectory` field unless your client requires it for unr
 | Variable | Default | Purpose |
 |----------|---------|---------|
 | `GIT_SUBPROCESS_PARALLELISM` | `4` | Number of parallel git subprocesses for inventory operations and `git_status` submodule rows. Valid range: 1 to 2×CPU count (auto-clamped to prevent runaway spawning). Increase on high-core machines to accelerate large fleet scans; decrease if system resources are constrained. |
+| `RETHUNK_GIT_TOOLS` | _(unset)_ | Comma-separated list of tool names to register. When unset or empty, all 23 tools are registered (default). When set, only the listed tools are exposed — unknown names are warned and ignored. If every name is unknown, **zero** tools are registered and a loud warning is emitted (the restriction is honored literally). The presets resource (`rethunk-git://presets`) is always registered regardless of this setting. Example: `RETHUNK_GIT_TOOLS=git_status,git_diff_summary,git_diff,git_log,batch_commit,git_push`. Full tool-name list: `git_status`, `git_inventory`, `git_parity`, `list_presets`, `git_log`, `git_diff_summary`, `git_diff`, `git_show`, `git_worktree_list`, `git_stash_list`, `git_fetch`, `git_blame`, `git_branch_list`, `git_reflog`, `batch_commit`, `git_push`, `git_merge`, `git_cherry_pick`, `git_reset_soft`, `git_tag`, `git_worktree_add`, `git_worktree_remove`, `git_stash_apply`. |
 
 Set these in the environment where the MCP client launches the server (e.g. in your shell, in the MCP client config as `env`, or in a startup script).