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

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` |

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 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.1] — 2026-06-11
+
+Patch release: security hardening, schema refresh, and developer-tooling correctness. No JSON-format change.
+
+### Security
+
+- **Insecure temp-file creation eliminated.** `scripts/publish-preflight.ts` and `src/server/git-merge-tool.test.ts` now use `fs.mkdtemp` instead of predictable paths (2 high `js/insecure-temporary-file` alerts resolved).
+- **TOCTOU race in `.gitmodules` parsing fixed.** `parseGitSubmodulePaths` in `git.ts` previously called `existsSync` then `lstatSync` separately, creating a file-system race window. The redundant `existsSync` check is removed; `lstatSync` + `readFileSync` is now wrapped in a single `try/catch` (1 high `js/file-system-race` alert resolved).
+- **GitHub Actions workflow permissions hardened.** `ci.yml` and `release.yml` gain `permissions: contents: read` blocks at workflow and job level. All third-party action tags are pinned to full commit SHAs (5 medium workflow-permission alerts resolved).
+
+### Changed
+
+- **Schema artifacts regenerated.** `schemas/*.json` (23 files) were stale relative to tool-description changes in the 2.9.0 token-trim and allowlist commits; regenerated so `bun run schema:individual:check` passes in CI.
+
+### Fixed
+
+- **Test files are now type-checked.** `tsconfig.json` includes `**/*.test.ts` with `@types/bun`, and a new `tsconfig.build.json` keeps tests out of the published `dist`. This surfaced and fixed latent type errors in the `tools`, `git-merge`, `list-presets`, and `tool-parameter-schemas` tests that the prior build never caught.
+- **`coverage:check` is robust to ANSI color.** `parseAllFilesLineCoverage` strips ANSI escape codes before matching the summary rows, so coverage parsing no longer fails when `bun test --coverage` emits color (e.g. under `FORCE_COLOR`).
+
+## [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.1] — 2026-06-05
+
+Patch release: token-cost reduction. No behavior or JSON-format change.
+
+### Changed
+
+- Tightened verbose tool parameter descriptions (shared `WorkspacePickSchema` plus several per-tool schemas) to cut the serialized MCP tool payload (~7% of the real `tools/list` size). Descriptions only — no parameter, type, enum, or default changes.
+
 ## [2.8.0] — 2026-05-29
 
 Feature release: three new read-only inspection tools (tool count 20 → 23). Additive — no JSON format-version bump.
@@ -252,6 +287,13 @@ Mutating git operations: merge, cherry-pick, and optional push-after for `batch_
 
 - Initial release: `git_status`, `git_inventory`, `git_parity`, `list_presets`.
 
+[2.9.1]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.9.1
+[2.9.0]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.9.0
+[2.8.1]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.8.1
+[2.8.0]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.8.0
+[2.7.0]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.7.0
+[2.6.0]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.6.0
+[2.5.0]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.5.0
 [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

package/dist/server/coverage.js

@@ -1,7 +1,11 @@
 export function parseAllFilesLineCoverage(output) {
+    // Strip ANSI color codes (bun emits them when FORCE_COLOR is set, which would
+    // otherwise prefix the "All files"/"File" rows and defeat the matchers).
+    // Built via fromCharCode to keep a literal control character out of the source.
+    const ansi = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
     const rows = output
         .split(/\r?\n/)
-        .map((line) => line.trim())
+        .map((line) => line.replace(ansi, "").trim())
         .filter((line) => line.includes("|"));
     const header = rows.find((line) => /^File\s*\|/i.test(line));
     if (!header)

package/dist/server/git.js

@@ -95,19 +95,13 @@ export function gitRevParseHead(cwd) {
 }
 export function parseGitSubmodulePaths(gitRoot) {
     const f = join(gitRoot, ".gitmodules");
-    if (!existsSync(f))
-        return [];
     // Skip non-regular files (character devices, sockets, etc.) — common in
     // Claude Code sandbox environments where stub device files shadow paths.
+    // Use a single try/catch to avoid TOCTOU between existence check and open.
+    let text;
     try {
         if (!lstatSync(f).isFile())
             return [];
-    }
-    catch {
-        return [];
-    }
-    let text;
-    try {
         text = readFileSync(f, "utf8");
     }
     catch {

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).
 

package/docs/mcp-tools.md

@@ -1029,6 +1029,7 @@ For deletions, `type` is `"deleted"` and `sha` is an empty string.
 |----------|---------|-------|
 | `GIT_SUBPROCESS_PARALLELISM` | CPU-based | Max concurrent git subprocesses for multi-root fan-out (`git_inventory`, `git_parity`, multi-root `git_log`). |
 | `GIT_SUBPROCESS_TIMEOUT_MS` | `120000` | Per-subprocess timeout in ms; on expiry the child is killed (SIGTERM) and the call resolves as failed. Set `0` (or negative) to disable (unbounded). |
+| `RETHUNK_GIT_TOOLS` | _(unset — all)_ | Comma-separated allowlist of exact tool names. Unset or empty → all 23 tools registered. Non-empty → only the listed tools; unknown names warned to stderr. If every listed name is unknown, zero tools are registered (restriction honored literally). The presets resource is always available. Example: `RETHUNK_GIT_TOOLS=git_status,git_diff_summary,git_diff,git_log,batch_commit,git_push`. |
 
 ## Resource
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rethunk/mcp-multi-root-git",
-  "version": "2.8.1",
+  "version": "2.9.1",
   "description": "MCP stdio server: multi-root git status, inventory, and HEAD parity checks. Generic tools usable by any workspace.",
   "type": "module",
   "private": false,
@@ -30,7 +30,7 @@
     }
   },
   "scripts": {
-    "build": "rimraf dist && tsc",
+    "build": "rimraf dist && tsc -p tsconfig.build.json",
     "coverage:check": "bun scripts/check-coverage.ts",
     "schema:tools": "bun scripts/generate-tool-parameters-schema.ts",
     "schema:tools:check": "bun scripts/generate-tool-parameters-schema.ts --check",
@@ -67,12 +67,13 @@
     "access": "public"
   },
   "dependencies": {
-    "fastmcp": "^4.0.1",
+    "fastmcp": "^4.0.2",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.16",
-    "@types/node": "^25.9.1",
+    "@types/bun": "^1.3.14",
+    "@types/node": "^25.9.2",
     "rimraf": "^6.1.3",
     "typescript": "^6.0.3"
   },

package/schemas/batch_commit.json

@@ -5,18 +5,18 @@
   "type": "object",
   "properties": {
     "workspaceRoot": {
-      "description": "Highest-priority override.",
+      "description": "Highest-priority root override.",
       "type": "string"
     },
     "rootIndex": {
-      "description": "0-based index into the MCP file roots list; ignored when workspaceRoot is set.",
+      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991
     },
     "allWorkspaceRoots": {
       "default": false,
-      "description": "Fan out across all MCP file roots.",
+      "description": "Fan out across all MCP roots.",
       "type": "boolean"
     },
     "format": {
@@ -88,7 +88,7 @@
                 }
               ]
             },
-            "description": "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."
+            "description": "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."
           }
         },
         "required": [
@@ -97,11 +97,11 @@
         ],
         "additionalProperties": false
       },
-      "description": "Commits to create, applied in order."
+      "description": "Ordered list of commits to create."
     },
     "push": {
       "default": "never",
-      "description": "`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`.",
+      "description": "`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).",
       "type": "string",
       "enum": [
         "never",
@@ -110,7 +110,7 @@
     },
     "dryRun": {
       "default": false,
-      "description": "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.",
+      "description": "Stage files and return a preview without writing commits; unstages afterwards. Response is marked DRY RUN.",
       "type": "boolean"
     }
   },

package/schemas/git_blame.json

@@ -5,11 +5,11 @@
   "type": "object",
   "properties": {
     "workspaceRoot": {
-      "description": "Highest-priority override.",
+      "description": "Highest-priority root override.",
       "type": "string"
     },
     "rootIndex": {
-      "description": "0-based index into the MCP file roots list; ignored when workspaceRoot is set.",
+      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991

package/schemas/git_branch_list.json

@@ -5,11 +5,11 @@
   "type": "object",
   "properties": {
     "workspaceRoot": {
-      "description": "Highest-priority override.",
+      "description": "Highest-priority root override.",
       "type": "string"
     },
     "rootIndex": {
-      "description": "0-based index into the MCP file roots list; ignored when workspaceRoot is set.",
+      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991
@@ -24,7 +24,7 @@
     },
     "includeRemotes": {
       "default": false,
-      "description": "When true, also return remote-tracking branches from refs/remotes (excluding symbolic origin/HEAD).",
+      "description": "Include remote-tracking branches from refs/remotes (symbolic origin/HEAD excluded).",
       "type": "boolean"
     }
   },

package/schemas/git_cherry_pick.json

@@ -5,18 +5,18 @@
   "type": "object",
   "properties": {
     "workspaceRoot": {
-      "description": "Highest-priority override.",
+      "description": "Highest-priority root override.",
       "type": "string"
     },
     "rootIndex": {
-      "description": "0-based index into the MCP file roots list; ignored when workspaceRoot is set.",
+      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991
     },
     "allWorkspaceRoots": {
       "default": false,
-      "description": "Fan out across all MCP file roots.",
+      "description": "Fan out across all MCP roots.",
       "type": "boolean"
     },
     "format": {
@@ -35,7 +35,7 @@
         "type": "string",
         "minLength": 1
       },
-      "description": "Sources to cherry-pick: SHA, `A..B` range, or branch name. Branch sources resolve to `onto..<branch>` (only commits missing from destination)."
+      "description": "Sources: SHA, `A..B` range, or branch name (resolves to `onto..<branch>`)."
     },
     "onto": {
       "description": "Destination branch. Defaults to the currently checked-out branch.",
@@ -43,17 +43,17 @@
     },
     "deleteMergedBranches": {
       "default": false,
-      "description": "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.",
+      "description": "Delete branch-kind sources locally after success. Protected names and remote refs unaffected.",
       "type": "boolean"
     },
     "deleteMergedWorktrees": {
       "default": false,
-      "description": "After success, remove any local worktree attached to a branch-kind source (`git worktree remove`). Protected tails always skipped.",
+      "description": "Remove local worktrees on branch-kind sources after success. Protected tails skipped.",
       "type": "boolean"
     },
     "strictMergedRefEquality": {
       "default": false,
-      "description": "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.",
+      "description": "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).",
       "type": "boolean"
     }
   },

package/schemas/git_diff.json

@@ -5,11 +5,11 @@
   "type": "object",
   "properties": {
     "workspaceRoot": {
-      "description": "Highest-priority override.",
+      "description": "Highest-priority root override.",
       "type": "string"
     },
     "rootIndex": {
-      "description": "0-based index into the MCP file roots list; ignored when workspaceRoot is set.",
+      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991
@@ -23,19 +23,19 @@
       ]
     },
     "base": {
-      "description": "Base ref (e.g. \"main\", \"HEAD~3\"). Required for range diffs. If omitted and `staged: false`, shows unstaged changes.",
+      "description": "Base ref (e.g. \"main\", \"HEAD~3\"). Omit for unstaged changes.",
       "type": "string"
     },
     "head": {
-      "description": "Head ref (e.g. \"feature-branch\"). If omitted, defaults to HEAD. Only used if `base` is provided.",
+      "description": "Head ref (e.g. \"feature-branch\"). Defaults to HEAD. Used only when `base` is set.",
       "type": "string"
     },
     "path": {
-      "description": "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.",
+      "description": "Scope to a single file. Unioned with `paths` if both given.",
       "type": "string"
     },
     "paths": {
-      "description": "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.",
+      "description": "Scope to multiple files (must be within repo root). Unioned with `path` if both given.",
       "type": "array",
       "items": {
         "type": "string"
@@ -43,11 +43,11 @@
     },
     "staged": {
       "default": false,
-      "description": "If true, show staged changes (git diff --staged). Ignored if `base` is provided.",
+      "description": "Show staged changes (`git diff --staged`). Ignored if `base` is set.",
       "type": "boolean"
     },
     "unified": {
-      "description": "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.",
+      "description": "Context lines around each change (`-U<n>`). Default: 3. Use 0 for no context.",
       "type": "integer",
       "minimum": 0,
       "maximum": 100

package/schemas/git_diff_summary.json

@@ -5,17 +5,17 @@
   "type": "object",
   "properties": {
     "workspaceRoot": {
-      "description": "Highest-priority override.",
+      "description": "Highest-priority root override.",
       "type": "string"
     },
     "rootIndex": {
-      "description": "0-based index into the MCP file roots list; ignored when workspaceRoot is set.",
+      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991
     },
     "absoluteGitRoots": {
-      "description": "Absolute paths to git repo roots. Use for many sibling clones under a non-git parent directory.",
+      "description": "Absolute paths to git repo roots; use for sibling clones under a non-git parent.",
       "maxItems": 256,
       "type": "array",
       "items": {
@@ -53,7 +53,7 @@
       "maximum": 500
     },
     "excludePatterns": {
-      "description": "Glob patterns to exclude. Defaults to common noise: lock files, dist, vendor, etc.",
+      "description": "Glob patterns to exclude. Default: lock files, dist, vendor, etc.",
       "type": "array",
       "items": {
         "type": "string"

package/schemas/git_fetch.json

@@ -5,11 +5,11 @@
   "type": "object",
   "properties": {
     "workspaceRoot": {
-      "description": "Highest-priority override.",
+      "description": "Highest-priority root override.",
       "type": "string"
     },
     "rootIndex": {
-      "description": "0-based index into the MCP file roots list; ignored when workspaceRoot is set.",
+      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991

package/schemas/git_inventory.json

@@ -5,22 +5,22 @@
   "type": "object",
   "properties": {
     "workspaceRoot": {
-      "description": "Highest-priority override.",
+      "description": "Highest-priority root override.",
       "type": "string"
     },
     "rootIndex": {
-      "description": "0-based index into the MCP file roots list; ignored when workspaceRoot is set.",
+      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991
     },
     "allWorkspaceRoots": {
       "default": false,
-      "description": "Fan out across all MCP file roots.",
+      "description": "Fan out across all MCP roots.",
       "type": "boolean"
     },
     "absoluteGitRoots": {
-      "description": "Absolute paths to git repo roots. Use for many sibling clones under a non-git parent directory.",
+      "description": "Absolute paths to git repo roots; use for sibling clones under a non-git parent.",
       "maxItems": 256,
       "type": "array",
       "items": {

package/schemas/git_log.json

@@ -5,22 +5,22 @@
   "type": "object",
   "properties": {
     "workspaceRoot": {
-      "description": "Highest-priority override.",
+      "description": "Highest-priority root override.",
       "type": "string"
     },
     "rootIndex": {
-      "description": "0-based index into the MCP file roots list; ignored when workspaceRoot is set.",
+      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991
     },
     "allWorkspaceRoots": {
       "default": false,
-      "description": "Fan out across all MCP file roots.",
+      "description": "Fan out across all MCP roots.",
       "type": "boolean"
     },
     "absoluteGitRoots": {
-      "description": "Absolute paths to git repo roots. Use for many sibling clones under a non-git parent directory.",
+      "description": "Absolute paths to git repo roots; use for sibling clones under a non-git parent.",
       "maxItems": 256,
       "type": "array",
       "items": {
@@ -29,7 +29,7 @@
     },
     "format": {
       "default": "markdown",
-      "description": "`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.",
+      "description": "`markdown` (default): headed sections per root. `json`: groups array. `oneline`: `<sha7> <subject>` per line; lowest-token option for post-commit verification.",
       "type": "string",
       "enum": [
         "markdown",
@@ -38,27 +38,27 @@
       ]
     },
     "since": {
-      "description": "Passed to `git log --since=`. Accepts ISO timestamps or git relative forms like `48.hours` or `2.weeks.ago`. Default: `7.days`.",
+      "description": "Passed to `--since=`. ISO timestamp or git relative form (`48.hours`, `2.weeks.ago`). Default: `7.days`.",
       "type": "string"
     },
     "paths": {
-      "description": "Limit to commits touching these paths (passed as `-- <paths>`).",
+      "description": "Limit to commits touching these paths (`-- <paths>`).",
       "type": "array",
       "items": {
         "type": "string"
       }
     },
     "grep": {
-      "description": "Filter commits whose message matches this regex (git `--grep`, case-insensitive).",
+      "description": "Filter by commit message regex (git `--grep`, case-insensitive).",
       "type": "string"
     },
     "author": {
-      "description": "Filter by author name or email (passed as `--author=`).",
+      "description": "Filter by author name or email (`--author=`).",
       "type": "string"
     },
     "maxCommits": {
       "default": 50,
-      "description": "Maximum commits to return per root (hard cap 500). Default 50.",
+      "description": "Max commits per root (hard cap 500, default 50).",
       "type": "integer",
       "minimum": 1,
       "maximum": 500

package/schemas/git_merge.json

@@ -5,18 +5,18 @@
   "type": "object",
   "properties": {
     "workspaceRoot": {
-      "description": "Highest-priority override.",
+      "description": "Highest-priority root override.",
       "type": "string"
     },
     "rootIndex": {
-      "description": "0-based index into the MCP file roots list; ignored when workspaceRoot is set.",
+      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991
     },
     "allWorkspaceRoots": {
       "default": false,
-      "description": "Fan out across all MCP file roots.",
+      "description": "Fan out across all MCP roots.",
       "type": "boolean"
     },
     "format": {
@@ -58,12 +58,12 @@
     },
     "deleteMergedBranches": {
       "default": false,
-      "description": "After all sources merge cleanly, delete each source branch locally (`git branch -d`). Protected names always skipped. Never affects remote branches.",
+      "description": "Delete each source branch locally after clean merge (`git branch -d`). Protected names and remote refs unaffected.",
       "type": "boolean"
     },
     "deleteMergedWorktrees": {
       "default": false,
-      "description": "After all sources merge cleanly, remove any local worktree currently checked out on a source branch (`git worktree remove`). Protected tails always skipped.",
+      "description": "Remove local worktrees on source branches after clean merge (`git worktree remove`). Protected tails skipped.",
       "type": "boolean"
     }
   },

package/schemas/git_parity.json

@@ -5,22 +5,22 @@
   "type": "object",
   "properties": {
     "workspaceRoot": {
-      "description": "Highest-priority override.",
+      "description": "Highest-priority root override.",
       "type": "string"
     },
     "rootIndex": {
-      "description": "0-based index into the MCP file roots list; ignored when workspaceRoot is set.",
+      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991
     },
     "allWorkspaceRoots": {
       "default": false,
-      "description": "Fan out across all MCP file roots.",
+      "description": "Fan out across all MCP roots.",
       "type": "boolean"
     },
     "absoluteGitRoots": {
-      "description": "Absolute paths to git repo roots. Use for many sibling clones under a non-git parent directory.",
+      "description": "Absolute paths to git repo roots; use for sibling clones under a non-git parent.",
       "maxItems": 256,
       "type": "array",
       "items": {

package/schemas/git_push.json

@@ -5,18 +5,18 @@
   "type": "object",
   "properties": {
     "workspaceRoot": {
-      "description": "Highest-priority override.",
+      "description": "Highest-priority root override.",
       "type": "string"
     },
     "rootIndex": {
-      "description": "0-based index into the MCP file roots list; ignored when workspaceRoot is set.",
+      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991
     },
     "allWorkspaceRoots": {
       "default": false,
-      "description": "Fan out across all MCP file roots.",
+      "description": "Fan out across all MCP roots.",
       "type": "boolean"
     },
     "format": {

package/schemas/git_reflog.json

@@ -5,11 +5,11 @@
   "type": "object",
   "properties": {
     "workspaceRoot": {
-      "description": "Highest-priority override.",
+      "description": "Highest-priority root override.",
       "type": "string"
     },
     "rootIndex": {
-      "description": "0-based index into the MCP file roots list; ignored when workspaceRoot is set.",
+      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991

package/schemas/git_reset_soft.json

@@ -5,18 +5,18 @@
   "type": "object",
   "properties": {
     "workspaceRoot": {
-      "description": "Highest-priority override.",
+      "description": "Highest-priority root override.",
       "type": "string"
     },
     "rootIndex": {
-      "description": "0-based index into the MCP file roots list; ignored when workspaceRoot is set.",
+      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991
     },
     "allWorkspaceRoots": {
       "default": false,
-      "description": "Fan out across all MCP file roots.",
+      "description": "Fan out across all MCP roots.",
       "type": "boolean"
     },
     "format": {
@@ -30,7 +30,7 @@
     "ref": {
       "type": "string",
       "minLength": 1,
-      "description": "Commit to reset to. Accepts ancestor notation (`HEAD~1`, `HEAD~3`), branch names, or full SHAs."
+      "description": "Commit to reset to: ancestor notation (`HEAD~1`, `HEAD~3`), branch name, or SHA."
     }
   },
   "required": [

package/schemas/git_show.json

@@ -5,11 +5,11 @@
   "type": "object",
   "properties": {
     "workspaceRoot": {
-      "description": "Highest-priority override.",
+      "description": "Highest-priority root override.",
       "type": "string"
     },
     "rootIndex": {
-      "description": "0-based index into the MCP file roots list; ignored when workspaceRoot is set.",
+      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991

package/schemas/git_stash_apply.json

@@ -5,11 +5,11 @@
   "type": "object",
   "properties": {
     "workspaceRoot": {
-      "description": "Highest-priority override.",
+      "description": "Highest-priority root override.",
       "type": "string"
     },
     "rootIndex": {
-      "description": "0-based index into the MCP file roots list; ignored when workspaceRoot is set.",
+      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991
@@ -31,7 +31,7 @@
     },
     "pop": {
       "default": false,
-      "description": "If true, runs `git stash pop` instead of `git stash apply` (removes stash after applying).",
+      "description": "Run `git stash pop` instead of `git stash apply` (removes stash after applying).",
       "type": "boolean"
     }
   },

package/schemas/git_stash_list.json

@@ -5,11 +5,11 @@
   "type": "object",
   "properties": {
     "workspaceRoot": {
-      "description": "Highest-priority override.",
+      "description": "Highest-priority root override.",
       "type": "string"
     },
     "rootIndex": {
-      "description": "0-based index into the MCP file roots list; ignored when workspaceRoot is set.",
+      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991

package/schemas/git_status.json

@@ -5,22 +5,22 @@
   "type": "object",
   "properties": {
     "workspaceRoot": {
-      "description": "Highest-priority override.",
+      "description": "Highest-priority root override.",
       "type": "string"
     },
     "rootIndex": {
-      "description": "0-based index into the MCP file roots list; ignored when workspaceRoot is set.",
+      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991
     },
     "allWorkspaceRoots": {
       "default": false,
-      "description": "Fan out across all MCP file roots.",
+      "description": "Fan out across all MCP roots.",
       "type": "boolean"
     },
     "absoluteGitRoots": {
-      "description": "Absolute paths to git repo roots. Use for many sibling clones under a non-git parent directory.",
+      "description": "Absolute paths to git repo roots; use for sibling clones under a non-git parent.",
       "maxItems": 256,
       "type": "array",
       "items": {

package/schemas/git_tag.json

@@ -5,11 +5,11 @@
   "type": "object",
   "properties": {
     "workspaceRoot": {
-      "description": "Highest-priority override.",
+      "description": "Highest-priority root override.",
       "type": "string"
     },
     "rootIndex": {
-      "description": "0-based index into the MCP file roots list; ignored when workspaceRoot is set.",
+      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991

package/schemas/git_worktree_add.json

@@ -5,18 +5,18 @@
   "type": "object",
   "properties": {
     "workspaceRoot": {
-      "description": "Highest-priority override.",
+      "description": "Highest-priority root override.",
       "type": "string"
     },
     "rootIndex": {
-      "description": "0-based index into the MCP file roots list; ignored when workspaceRoot is set.",
+      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991
     },
     "allWorkspaceRoots": {
       "default": false,
-      "description": "Fan out across all MCP file roots.",
+      "description": "Fan out across all MCP roots.",
       "type": "boolean"
     },
     "format": {
@@ -30,15 +30,15 @@
     "path": {
       "type": "string",
       "minLength": 1,
-      "description": "Filesystem path for the new worktree. Relative paths are resolved from the git toplevel."
+      "description": "Filesystem path for the new worktree (relative paths resolved from git toplevel)."
     },
     "branch": {
       "type": "string",
       "minLength": 1,
-      "description": "Branch to check out in the new worktree. Created from `baseRef` if absent."
+      "description": "Branch to check out; created from `baseRef` if it doesn't exist."
     },
     "baseRef": {
-      "description": "Commit-ish to base the new branch on when it does not yet exist. Default: HEAD.",
+      "description": "Commit-ish to base the new branch on. Default: HEAD.",
       "type": "string"
     }
   },

package/schemas/git_worktree_list.json

@@ -5,11 +5,11 @@
   "type": "object",
   "properties": {
     "workspaceRoot": {
-      "description": "Highest-priority override.",
+      "description": "Highest-priority root override.",
       "type": "string"
     },
     "rootIndex": {
-      "description": "0-based index into the MCP file roots list; ignored when workspaceRoot is set.",
+      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991

package/schemas/git_worktree_remove.json

@@ -5,18 +5,18 @@
   "type": "object",
   "properties": {
     "workspaceRoot": {
-      "description": "Highest-priority override.",
+      "description": "Highest-priority root override.",
       "type": "string"
     },
     "rootIndex": {
-      "description": "0-based index into the MCP file roots list; ignored when workspaceRoot is set.",
+      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991
     },
     "allWorkspaceRoots": {
       "default": false,
-      "description": "Fan out across all MCP file roots.",
+      "description": "Fan out across all MCP roots.",
       "type": "boolean"
     },
     "format": {
@@ -34,7 +34,7 @@
     },
     "force": {
       "default": false,
-      "description": "Pass `--force` to allow removal of worktrees with uncommitted changes.",
+      "description": "Allow removal of worktrees with uncommitted changes (`--force`).",
       "type": "boolean"
     }
   },

package/schemas/list_presets.json

@@ -5,22 +5,22 @@
   "type": "object",
   "properties": {
     "workspaceRoot": {
-      "description": "Highest-priority override.",
+      "description": "Highest-priority root override.",
       "type": "string"
     },
     "rootIndex": {
-      "description": "0-based index into the MCP file roots list; ignored when workspaceRoot is set.",
+      "description": "0-based index into MCP roots; ignored if workspaceRoot set.",
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991
     },
     "allWorkspaceRoots": {
       "default": false,
-      "description": "Fan out across all MCP file roots.",
+      "description": "Fan out across all MCP roots.",
       "type": "boolean"
     },
     "absoluteGitRoots": {
-      "description": "Absolute paths to git repo roots. Use for many sibling clones under a non-git parent directory.",
+      "description": "Absolute paths to git repo roots; use for sibling clones under a non-git parent.",
       "maxItems": 256,
       "type": "array",
       "items": {