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

package/dist/server/tool-parameter-schemas.js

@@ -0,0 +1,94 @@
+import { z } from "zod";
+import { registerBatchCommitTool } from "./batch-commit-tool.js";
+import { registerGitCherryPickTool } from "./git-cherry-pick-tool.js";
+import { registerGitDiffSummaryTool } from "./git-diff-summary-tool.js";
+import { registerGitDiffTool } from "./git-diff-tool.js";
+import { registerGitFetchTool } from "./git-fetch-tool.js";
+import { registerGitInventoryTool } from "./git-inventory-tool.js";
+import { registerGitLogTool } from "./git-log-tool.js";
+import { registerGitMergeTool } from "./git-merge-tool.js";
+import { registerGitParityTool } from "./git-parity-tool.js";
+import { registerGitPushTool } from "./git-push-tool.js";
+import { registerGitResetSoftTool } from "./git-reset-soft-tool.js";
+import { registerGitShowTool } from "./git-show-tool.js";
+import { registerGitStashApplyTool, registerGitStashListTool } from "./git-stash-tool.js";
+import { registerGitStatusTool } from "./git-status-tool.js";
+import { registerGitTagTool } from "./git-tag-tool.js";
+import { registerGitWorktreeAddTool, registerGitWorktreeListTool, registerGitWorktreeRemoveTool, } from "./git-worktree-tool.js";
+import { registerListPresetsTool } from "./list-presets-tool.js";
+export const READ_ONLY_ABSOLUTE_ROOT_TOOLS = [
+    "git_status",
+    "git_inventory",
+    "git_parity",
+    "list_presets",
+    "git_log",
+    "git_diff_summary",
+];
+export const READ_ONLY_SINGLE_REPO_TOOLS = [
+    "git_diff",
+    "git_show",
+    "git_worktree_list",
+    "git_stash_list",
+];
+export const MUTATING_TOOLS = [
+    "git_fetch",
+    "batch_commit",
+    "git_push",
+    "git_merge",
+    "git_cherry_pick",
+    "git_reset_soft",
+    "git_tag",
+    "git_worktree_add",
+    "git_worktree_remove",
+    "git_stash_apply",
+];
+export const ALL_PARAMETER_SCHEMA_TOOLS = [
+    ...READ_ONLY_ABSOLUTE_ROOT_TOOLS,
+    ...READ_ONLY_SINGLE_REPO_TOOLS,
+    ...MUTATING_TOOLS,
+];
+function captureParameterTools(register) {
+    const tools = [];
+    const server = {
+        sessions: [],
+        addTool(tool) {
+            tools.push({ name: tool.name, parameters: tool.parameters });
+        },
+    };
+    register(server);
+    return tools;
+}
+export function captureToolParameterSchemas() {
+    const tools = captureParameterTools((server) => {
+        registerGitStatusTool(server);
+        registerGitInventoryTool(server);
+        registerGitParityTool(server);
+        registerListPresetsTool(server);
+        registerGitLogTool(server);
+        registerGitDiffSummaryTool(server);
+        registerGitDiffTool(server);
+        registerGitShowTool(server);
+        registerGitWorktreeListTool(server);
+        registerGitStashListTool(server);
+        registerGitFetchTool(server);
+        registerBatchCommitTool(server);
+        registerGitPushTool(server);
+        registerGitMergeTool(server);
+        registerGitCherryPickTool(server);
+        registerGitResetSoftTool(server);
+        registerGitTagTool(server);
+        registerGitWorktreeAddTool(server);
+        registerGitWorktreeRemoveTool(server);
+        registerGitStashApplyTool(server);
+    });
+    return Object.fromEntries(tools.map((tool) => [tool.name, z.toJSONSchema(tool.parameters)]));
+}
+export function buildToolParameterSchemaDocument() {
+    return {
+        $schema: "https://json-schema.org/draft/2020-12/schema",
+        title: "@rethunk/mcp-multi-root-git tool parameter schemas",
+        description: "JSON Schema snapshots generated from registered FastMCP tool parameter schemas.",
+        generatedBy: "scripts/generate-tool-parameters-schema.ts",
+        tools: captureToolParameterSchemas(),
+    };
+}

package/dist/server/tools.js

@@ -1,13 +1,18 @@
 import { registerBatchCommitTool } from "./batch-commit-tool.js";
 import { registerGitCherryPickTool } from "./git-cherry-pick-tool.js";
 import { registerGitDiffSummaryTool } from "./git-diff-summary-tool.js";
+import { registerGitDiffTool } from "./git-diff-tool.js";
+import { registerGitFetchTool } from "./git-fetch-tool.js";
 import { registerGitInventoryTool } from "./git-inventory-tool.js";
 import { registerGitLogTool } from "./git-log-tool.js";
 import { registerGitMergeTool } from "./git-merge-tool.js";
 import { registerGitParityTool } from "./git-parity-tool.js";
 import { registerGitPushTool } from "./git-push-tool.js";
 import { registerGitResetSoftTool } from "./git-reset-soft-tool.js";
+import { registerGitShowTool } from "./git-show-tool.js";
+import { registerGitStashApplyTool, registerGitStashListTool } from "./git-stash-tool.js";
 import { registerGitStatusTool } from "./git-status-tool.js";
+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";
@@ -19,15 +24,21 @@ export function registerRethunkGitTools(server) {
     registerListPresetsTool(server);
     registerGitLogTool(server);
     registerGitDiffSummaryTool(server);
+    registerGitDiffTool(server);
+    registerGitShowTool(server);
     registerGitWorktreeListTool(server);
+    registerGitStashListTool(server);
+    registerGitFetchTool(server);
     // Mutating tools
     registerBatchCommitTool(server);
     registerGitPushTool(server);
     registerGitMergeTool(server);
     registerGitCherryPickTool(server);
     registerGitResetSoftTool(server);
+    registerGitTagTool(server);
     registerGitWorktreeAddTool(server);
     registerGitWorktreeRemoveTool(server);
+    registerGitStashApplyTool(server);
     // Resources
     registerPresetsResource(server);
 }

package/docs/install.md

@@ -10,6 +10,7 @@ This package is an MCP **stdio** server. The client starts the process and passe
 - [GitHub Packages](#github-packages)
 - [Ways to run the binary](#ways-to-run-the-binary)
 - [Configuration shape (stdio)](#configuration-shape-stdio)
+- [Environment variables](#environment-variables)
 - [Cursor](#cursor)
 - [Visual Studio Code (GitHub Copilot)](#visual-studio-code-github-copilot)
 - [Claude Desktop](#claude-desktop)
@@ -86,11 +87,27 @@ Register the server under a stable name (this documentation uses **`rethunk-git`
 
 Omit any `cwd` / `workingDirectory` field unless your client requires it for unrelated reasons. This server resolves repos from MCP **roots**, not from the process cwd.
 
+## Environment variables
+
+| 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. |
+
+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).
+
+Example: Running the server with 8 parallel git processes on a 4-core machine:
+
+```bash
+GIT_SUBPROCESS_PARALLELISM=8 npx -y @rethunk/mcp-multi-root-git
+```
+
+On a 4-core machine (CPU count = 4), the max parallelism is clamped to 8 (2×4). The value requested is used if valid.
+
 ## Cursor
 
 **User scope (all workspaces):** `~/.cursor/mcp.json` on macOS/Linux, or `%USERPROFILE%\.cursor\mcp.json` on Windows.
 
-**Project scope:** `.cursor/mcp.json` in the workspace (often committed for team dogfooding).
+**Project scope:** `.cursor/mcp.json` in the workspace (use when a team wants repo-local MCP wiring).
 
 Cursor uses a top-level **`mcpServers`** object:
 
@@ -185,7 +202,7 @@ For contributors working inside a clone of [mcp-multi-root-git](https://github.c
 1. **Dependencies, build, and CI parity:** **[HUMANS.md](../HUMANS.md)** — *Development* (`bun install`, `bun run build`, `bun run check`). Do not duplicate that workflow here.
 2. **Run the dev server** (no `dist/` required): from the repo root, **`bun src/server.ts`** (stdio MCP).
 
-**MCP registration for a local checkout:** point your client at that command (or at **`dist/server.js`** via `node` after `bun run build` — see HUMANS). **Cursor:** this repo may ship an example **`.cursor/mcp.json`** using `bun` + `["src/server.ts"]`; open the workspace at the repository root so relative args resolve.
+**MCP registration for a local checkout:** point your client at that command (or at **`dist/server.js`** via `node` after `bun run build` — see HUMANS). **Cursor:** add the command to either your user-scope or project-scope `mcp.json`, and open the workspace at the repository root so relative args resolve.
 
 **Reload** the MCP connection after changing server code.
 

package/docs/mcp-tools.md

@@ -13,18 +13,24 @@ MCP clients expose tools as `{serverName}_{toolName}`. With the server registere
 |----------|-----------------------------------|---------|
 | `git_status` | `rethunk-git_git_status` | `git status --short -b` per MCP root and optional submodules (`includeSubmodules`); parallel submodule status. Args include `absoluteGitRoots`, `allWorkspaceRoots`, `rootIndex`, `workspaceRoot`, `format`. **Read-only.** |
 | `git_inventory` | `rethunk-git_git_inventory` | Status + ahead/behind per path; default upstream each repo’s `@{u}`; pass **both** `remote` and `branch` for fixed tracking. `nestedRoots`, `preset`, `presetMerge`, `maxRoots`, `format`, plus workspace pick args (`absoluteGitRoots` cannot combine with `preset`/`nestedRoots`). **Read-only.** |
-| `git_parity` | `rethunk-git_git_parity` | Compare `git rev-parse HEAD` for path pairs. `pairs`, `preset`, `presetMerge`, `format`, plus workspace pick args. **Read-only.** |
+| `git_parity` | `rethunk-git_git_parity` | Compare `git rev-parse HEAD` for path pairs. `pairs`, `preset`, `presetMerge`, `format`, plus workspace pick args (`absoluteGitRoots` for sibling clone batches). **Read-only.** |
 | `list_presets` | `rethunk-git_list_presets` | List preset names/counts from `.rethunk/git-mcp-presets.json`; invalid JSON/schema surface as errors. Workspace pick + `format` only (includes `absoluteGitRoots`). **Read-only.** |
 | `git_log` | `rethunk-git_git_log` | Path-filtered, time-windowed `git log` across one or more workspace roots. Returns commit history with author, date, subject, and shortstat. Args: `since`, `paths`, `grep`, `author`, `maxCommits`, `branch`, plus workspace pick args (`absoluteGitRoots` for sibling clones) + `format`. **Read-only.** |
 | `git_diff_summary` | `rethunk-git_git_diff_summary` | Structured, token-efficient diff viewer. Returns per-file diffs with additions/deletions counts, truncated to configurable line limits, with lock files/dist/vendor excluded by default. Args: `range`, `fileFilter`, `maxLinesPerFile`, `maxFiles`, `excludePatterns`, plus workspace pick args (optional single-entry `absoluteGitRoots`) + `format`. **Read-only.** |
+| `git_diff` | `rethunk-git_git_diff` | Raw diff text for a single repo. Supports unstaged, staged, or `base..head` ranges, optionally scoped to one path. Args: `base?`, `head?`, `path?`, `staged?`, plus single-repo workspace pick + `format`. **Read-only.** |
+| `git_show` | `rethunk-git_git_show` | Inspect one commit or ref. Returns commit message plus diff, or file content at `path` for that ref. Args: `ref`, `path?`, plus single-repo workspace pick + `format`. **Read-only.** |
 | `git_worktree_list` | `rethunk-git_git_worktree_list` | List all worktrees (`git worktree list --porcelain`). Workspace pick + `format`. **Read-only.** |
+| `git_stash_list` | `rethunk-git_git_stash_list` | List `git stash` entries for one repo. Args: single-repo workspace pick + `format`. **Read-only.** |
+| `git_fetch` | `rethunk-git_git_fetch` | Fetch from a remote without modifying the working tree. Updates refs only and reports updated/new refs. Args: `remote?`, `branch?`, `prune?`, `tags?`, plus single-repo workspace pick + `format`. **Mutating — refs only.** |
 | `git_push` | `rethunk-git_git_push` | Push the current branch to its upstream. Optional `remote`, `branch`, `setUpstream` (passes `-u`). Refuses on detached HEAD; never force-pushes. Workspace pick + `format`. **Mutating.** |
+| `git_tag` | `rethunk-git_git_tag` | Create/delete annotated or lightweight tags for one repo. Args: `tag`, `message?`, `ref?`, `delete?`, plus single-repo workspace pick + `format`. **Mutating.** |
 | `git_worktree_add` | `rethunk-git_git_worktree_add` | Create a new linked worktree, creating the branch from `baseRef` if it does not yet exist. Refuses on protected branch names. Args: `path`, `branch`, `baseRef?`, plus workspace pick + `format`. **Mutating.** |
 | `git_worktree_remove` | `rethunk-git_git_worktree_remove` | Remove a registered worktree; refuses to remove the main worktree. Optional `force: true` for dirty trees. Args: `path`, `force?`, plus workspace pick + `format`. **Mutating.** |
 | `git_reset_soft` | `rethunk-git_git_reset_soft` | Soft-reset the current branch to a ref (`HEAD~N`, SHA, branch). Rewound changes land in the staging index; requires a clean working tree. Args: `ref`, plus workspace pick + `format`. **Mutating — not idempotent.** |
-| `batch_commit` | `rethunk-git_batch_commit` | Create multiple sequential git commits in a single call. Each entry stages the listed files then commits with the given message. Stops on first failure. Optional `push: "after"` pushes the current branch to its upstream once every commit lands. Args: `commits` (array of `{message, files}`), `push?`, plus workspace pick args + `format`. **Mutating — not idempotent.** |
+| `batch_commit` | `rethunk-git_batch_commit` | Create multiple sequential git commits in a single call. Each entry stages the listed files or line-ranged file hunks, then commits with the given message. Stops on first failure. Optional `push: "after"` pushes once every commit lands; optional `dryRun: true` previews staged content without writing commits. Args: `commits` (array of `{message, files}`), `push?`, `dryRun?`, plus workspace pick args + `format`. **Mutating — not idempotent.** |
 | `git_merge` | `rethunk-git_git_merge` | 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\*). Args: `sources`, `into?`, `strategy?`, `message?`, cleanup flags + workspace pick + `format`. **Mutating.** |
 | `git_cherry_pick` | `rethunk-git_git_cherry_pick` | 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 cleanup flags as `git_merge` (branch-kind sources only, protected names skipped). Args: `sources`, `onto?`, cleanup flags + workspace pick + `format`. **Mutating.** |
+| `git_stash_apply` | `rethunk-git_git_stash_apply` | Apply or pop a stash entry for one repo. Args: `index?`, `pop?`, plus single-repo workspace pick + `format`. **Mutating.** |
 
 Pass **`format: "json"`** on any tool for structured JSON instead of markdown (default).
 
@@ -32,6 +38,8 @@ Pass **`format: "json"`** on any tool for structured JSON instead of markdown (d
 
 Tool JSON bodies are minified and contain only the payload — no `rethunkGitMcp` envelope. Current `MCP_JSON_FORMAT_VERSION` is **`"3"`**; server + format version are discoverable via MCP `initialize`. Payload keys (`groups`, `inventories`, `parity`, `roots`) are stable within a given format version. Preset-related responses may include **`presetSchemaVersion`**.
 
+The package also ships **`tool-parameters.schema.json`**, generated from the registered Zod parameter schemas via `bun run schema:tools`, plus the published **`schemas/`** directory (`schemas/index.json` + one JSON Schema per tool) via `bun run schema:individual`. Connected MCP clients should still prefer live schema discovery from `initialize` / tool listing; the shipped artifacts are for offline inspection, drift checks, and code generation.
+
 ### v2/v3 field omission (consumer contract)
 
 To keep responses compact, **optional fields are omitted when they would be empty, `null`, or `false`** — they are not emitted as `null`. Consumers must test for *presence*, not compare to `null`.
@@ -113,6 +121,23 @@ v2 field-omission rules still apply: `filesChanged`, `insertions`, `deletions` o
 | `absolute_git_roots_empty` | `absoluteGitRoots` produced zero git toplevels after resolution. |
 | `absolute_git_roots_single_repo_only` | A single-repo tool received `absoluteGitRoots` resolving to more than one distinct git toplevel. |
 
+### `git_parity` — `absoluteGitRoots` example
+
+Use **`absoluteGitRoots`** when the same parity pair should be checked across sibling clones that are not all MCP workspace roots:
+
+```json
+{
+  "format": "json",
+  "absoluteGitRoots": [
+    "/usr/local/src/com.github/Rethunk-AI/mcp-multi-root-git",
+    "/usr/local/src/com.github/Rethunk-AI/rethunk-github-mcp"
+  ],
+  "pairs": [{ "left": "packages/shared", "right": "apps/web/shared", "label": "shared" }]
+}
+```
+
+The response contains one **`parity[]`** entry per resolved git toplevel. `absoluteGitRoots` cannot be combined with `preset`; pass inline `pairs` for sibling-clone batches.
+
 ### `git_diff_summary` — parameters
 
 | Parameter | Type | Default | Notes |
@@ -160,12 +185,151 @@ v2 field-omission rules still apply: `filesChanged`, `insertions`, `deletions` o
 
 ---
 
+### `git_diff` — parameters
+
+| Parameter | Type | Default | Notes |
+|-----------|------|---------|-------|
+| `base` | string | — | Base ref for a revision diff. When omitted with no `staged`, the tool shows unstaged changes. |
+| `head` | string | `HEAD` | Head ref for a revision diff. Used only when `base` is provided. |
+| `path` | string | — | Optional single file path to scope the diff. |
+| `staged` | boolean | `false` | When `true`, runs `git diff --staged`. Ignored when `base` is provided. |
+| `workspaceRoot`, `rootIndex`, `format` | — | Standard single-repo workspace pick + output format. |
+
+### `git_diff` — JSON shape (`format: "json"`)
+
+```json
+{
+  "range": "HEAD~1..HEAD (src/server.ts)",
+  "diff": "diff --git a/src/server.ts b/src/server.ts\n..."
+}
+```
+
+### `git_diff` — error codes
+
+| Code | Meaning |
+|------|---------|
+| `unsafe_range_token` | `base` or `head` contains characters outside the argv-safe subset. |
+| `git_diff_failed` | `git diff` exited non-zero. |
+| `not_a_git_repository` | The resolved workspace root is not inside a git repository. |
+
+---
+
+### `git_show` — parameters
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| `ref` | string | Commit, branch, tag, or other git rev-spec to inspect. |
+| `path` | string | Optional single path. When provided, the response shows that path's content at `ref` instead of the full commit diff. |
+| `workspaceRoot`, `rootIndex`, `format` | — | Standard single-repo workspace pick + output format. |
+
+### `git_show` — JSON shape (`format: "json"`)
+
+```json
+{
+  "ref": "HEAD",
+  "message": "feat: add tool",
+  "path": "src/server.ts",
+  "diff": "diff --git a/src/server.ts b/src/server.ts\n..."
+}
+```
+
+`path` is omitted when not requested. `diff` is omitted when `git show` returns only a commit message.
+
+### `git_show` — error codes
+
+| Code | Meaning |
+|------|---------|
+| `git_show_failed` | `git show` exited non-zero (e.g. unknown ref). |
+| `not_a_git_repository` | The resolved workspace root is not inside a git repository. |
+
+---
+
+### `git_stash_list` — parameters
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| `workspaceRoot`, `rootIndex`, `format` | — | Standard single-repo workspace pick + output format. |
+
+### `git_stash_list` — JSON shape (`format: "json"`)
+
+```json
+{
+  "stashes": [
+    { "index": 0, "message": "WIP on main: abc1234 feat: add tool", "sha": "abc1234" }
+  ]
+}
+```
+
+### `git_stash_list` — error codes
+
+| Code | Meaning |
+|------|---------|
+| `stash_list_failed` | `git stash list` failed unexpectedly. |
+| `not_a_git_repository` | The resolved workspace root is not inside a git repository. |
+
+---
+
+### `git_fetch` — parameters
+
+| Parameter | Type | Default | Notes |
+|-----------|------|---------|-------|
+| `remote` | string | `"origin"` | Remote to fetch from. |
+| `branch` | string | — | Optional branch/ref to fetch from that remote. |
+| `prune` | boolean | `false` | Pass `--prune` to remove deleted remote-tracking refs. |
+| `tags` | boolean | `false` | Pass `--tags` to also fetch all tags. |
+| `workspaceRoot`, `rootIndex`, `format` | — | Standard single-repo workspace pick + output format. |
+
+### `git_fetch` — JSON shape (`format: "json"`)
+
+```json
+{
+  "ok": true,
+  "remote": "origin",
+  "updatedRefs": ["abc1234..def5678  main       -> origin/main"],
+  "newRefs": ["[new tag]        v2.0.0     -> v2.0.0"],
+  "output": "From origin\n..."
+}
+```
+
+Fetch failures are reported as `ok: false` with the captured git output in `output`.
+
+### `git_fetch` — error codes
+
+| Code | Meaning |
+|------|---------|
+| `not_a_git_repository` | The resolved workspace root is not inside a git repository. |
+
+---
+
+### `batch_commit` — atomic staging semantics
+
+**Critical for AI agents:** Each call to `batch_commit` is **self-contained and atomic per-commit entry**.
+
+- **All files in a single entry are staged together.** When you list `files: ["src/foo.ts", "src/bar.ts"]` in one commit entry, both are staged atomically as a unit with a single `git add` before the commit is created.
+- **Each commit entry is processed sequentially within the call.** The tool stages files, commits, then moves to the next entry. All entries within a single `batch_commit` call happen in one atomic MCP transaction.
+- **A single `batch_commit` call cannot be split across multiple MCP calls.** Do NOT attempt incremental staging like "call 1 with file A, then call 2 with file B hoping they stage together." Each call is independent — call 1's commit lands immediately; call 2's changes are a separate transaction.
+- **Failed entry stops the batch.** If staging or commit fails on entry N, the tool aborts and skips remaining entries. However, **entries that succeeded before the failure remain committed** — they are not rolled back.
+- **Include all files for a logical change in a single `batch_commit` call.** Group related files in each commit entry, list them all in the `files` array, and include all necessary entries in the `commits` array.
+
+Example: to commit two related changes atomically, pass both entries in one call:
+```json
+{
+  "commits": [
+    { "message": "feat: add foo module", "files": ["src/foo.ts", "tests/foo.test.ts"] },
+    { "message": "feat: integrate foo into bar", "files": ["src/bar.ts", "docs/foo.md"] }
+  ]
+}
+```
+
+Do NOT do this: make two separate calls hoping to stage files incrementally. That breaks the contract.
+
 ### `batch_commit` — parameters
 
 | Parameter | Type | Notes |
 |-----------|------|-------|
-| `commits` | `{message: string, files: string[]}[]` | Commits to create in order. 1–50 entries. Each `files` entry is a path relative to the git root; all must stay within the git toplevel. |
+| `commits` | `{message: string, files: (string \| {path: string, lines: {from: number, to: number}})[]}[]` | Commits to create in order. 1–50 entries. Each `files` entry is either a path relative to the git root or a `{path, lines}` object for hunk-level staging. All paths must stay within the git toplevel. |
 | `push` | `"never"` \| `"after"` | Default `"never"`. `"after"` pushes the current branch to its upstream **once all commits succeed**. Never auto-sets upstream — branches without an upstream fail with `push_no_upstream`. Commits are **not** rolled back on push failure. Enum reserved for future modes such as `"force-with-lease"`. |
+| `dryRun` | boolean | Default `false`. When `true`, stages each entry, reports what would be committed (`staged`, `diffStat`), then unstages everything without writing commits. |
 | `workspaceRoot` | string | Explicit root; highest priority. |
 | `rootIndex` | int | Pick one of several MCP roots (0-based). |
 | `format` | `"markdown"` \| `"json"` | Output format. Default: `"markdown"`. |
@@ -200,6 +364,8 @@ v2 field-omission rules still apply: `filesChanged`, `insertions`, `deletions` o
 
 On first failure `ok` is `false`, `committed` reflects only the entries that succeeded before the error, and the failing entry includes `error` and `detail` fields. Remaining entries are skipped and not included in `results`.
 
+When `dryRun: true`, the top-level response includes `dryRun: true`; successful `results[*]` entries omit `sha` and instead include `staged` and `diffStat`.
+
 The `push` object is present only when `push: "after"` was requested **and** every commit landed. On push failure the top-level `ok` stays `true` (the commits themselves succeeded) while `push.ok` is `false` and `push.error` carries the code.
 
 ### `batch_commit` — error codes (per-result `error` field)
@@ -352,6 +518,8 @@ Repo state is cleaned (`git cherry-pick --abort`) before returning — no partia
 
 ### `git_push` — parameters
 
+For already-committed work, call **`git_push`** directly instead of creating an empty commit or falling back to shell. Continue to prefer **`batch_commit`** with **`push: "after"`** when commits and push happen in the same MCP call.
+
 | Parameter | Type | Notes |
 |-----------|------|-------|
 | `remote` | string | Remote to push to. Defaults to the remote inferred from the upstream tracking ref, or `origin` when `setUpstream` is true. |
@@ -378,6 +546,39 @@ Repo state is cleaned (`git cherry-pick --abort`) before returning — no partia
 
 ---
 
+### `git_tag` — parameters
+
+| Parameter | Type | Default | Notes |
+|-----------|------|---------|-------|
+| `tag` | string | — | Tag name to create or delete. |
+| `message` | string | — | When provided, creates an annotated tag; otherwise creates a lightweight tag. |
+| `ref` | string | `HEAD` | Commit/ref to tag. Ignored when `delete: true`. |
+| `delete` | boolean | `false` | Delete the named tag instead of creating it. |
+| `workspaceRoot`, `rootIndex`, `format` | — | Standard single-repo workspace pick + output format. |
+
+### `git_tag` — JSON shape (`format: "json"`)
+
+```json
+{ "tag": "v2.3.5", "type": "annotated", "sha": "a1b2c3d4e5f6..." }
+```
+
+For deletions, `type` is `"deleted"` and `sha` is an empty string.
+
+### `git_tag` — error codes
+
+| Code | Meaning |
+|------|---------|
+| `tag_empty` | `tag` trimmed to an empty string. |
+| `tag_unsafe` | `tag` contains disallowed characters. |
+| `ref_unsafe` | `ref` contains disallowed characters. |
+| `ref_not_found` | `ref` did not resolve to a commit. |
+| `tag_create_failed` | `git tag` failed while creating the tag. |
+| `tag_delete_failed` | `git tag -d` failed. |
+| `tag_verification_failed` | The tag could not be read back after creation. |
+| `not_a_git_repository` | The resolved workspace root is not inside a git repository. |
+
+---
+
 ### `git_reset_soft` — parameters
 
 | Parameter | Type | Notes |
@@ -403,6 +604,35 @@ Repo state is cleaned (`git cherry-pick --abort`) before returning — no partia
 
 ---
 
+### `git_stash_apply` — parameters
+
+| Parameter | Type | Default | Notes |
+|-----------|------|---------|-------|
+| `index` | int | `0` | Stash index to apply/pop (`stash@{index}`). |
+| `pop` | boolean | `false` | When `true`, runs `git stash pop` instead of `git stash apply`. |
+| `workspaceRoot`, `rootIndex`, `format` | — | Standard single-repo workspace pick + output format. |
+
+### `git_stash_apply` — JSON shape (`format: "json"`)
+
+```json
+{
+  "applied": true,
+  "stashIndex": 0,
+  "popped": false,
+  "output": "On branch main\nChanges not staged for commit:\n..."
+}
+```
+
+`output` is omitted when git produced no stdout/stderr text.
+
+### `git_stash_apply` — error codes
+
+| Code | Meaning |
+|------|---------|
+| `not_a_git_repository` | The resolved workspace root is not inside a git repository. |
+
+---
+
 ### `git_worktree_list` — JSON shape (`format: "json"`)
 
 ```json
@@ -494,7 +724,7 @@ Order applied when resolving which directory(ies) tools run against:
 2. **`rootIndex`** (0-based) — one `file://` MCP root when several exist.
 3. **`allWorkspaceRoots`: true** — every `file://` root; markdown output emits one `# {tool}` header with per-root subsections (`git_inventory` uses `### {gitTop}`; `git_status` uses `### MCP root: ...`), or combined JSON.
 4. **`preset`** set and multiple roots — first root whose git toplevel defines that preset (respecting **`workspaceRootHint`** on the preset entry when present).
-5. Otherwise the first `file://` root from MCP **`initialize`** / **`roots/list_changed`**.
+5. Otherwise the first `file://` root reported by the MCP client through **`roots/list`**.
 6. **`process.cwd()`** if no file roots (e.g. CI with explicit `workspaceRoot`).
 
-Roots come from the MCP session (**`FastMCP` with `roots: { enabled: true }`** in code); there is no fixed `cwd` in server config.
+Roots come from active MCP sessions (**`FastMCP` with `roots: { enabled: true }`** in code); there is no fixed `cwd` in server config. This is what allows one globally installed server to follow the workspace opened in VS Code, Claude Code, Cursor, or any other roots-capable MCP client.

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "@rethunk/mcp-multi-root-git",
-  "version": "2.3.3",
+  "version": "2.4.0",
   "description": "MCP stdio server: multi-root git status, inventory, and HEAD parity checks. Generic tools usable by any workspace.",
   "type": "module",
   "private": false,
-  "packageManager": "bun@1.3.11",
+  "packageManager": "bun@1.3.13",
   "engines": {
     "node": ">=22.0.0"
   },
   "files": [
     "dist",
     "git-mcp-presets.schema.json",
+    "tool-parameters.schema.json",
+    "schemas",
     "docs/install.md",
     "docs/mcp-tools.md",
     "AGENTS.md",
@@ -31,9 +33,14 @@
     "build": "rimraf dist && tsc",
     "check": "biome check .",
     "check:fix": "biome check --write .",
+    "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",
+    "schema:individual": "bun scripts/generate-individual-schemas.ts",
+    "publish:preflight": "bun scripts/publish-preflight.ts",
     "test": "bun test src/",
     "test:coverage": "bun test src/ --coverage",
-    "prepublishOnly": "bun run build && bun run check && bun run test",
+    "prepublishOnly": "bun run schema:tools:check && bun run schema:individual && bun run build && bun run check && bun run test",
     "setup-hooks": "git config core.hooksPath .githooks"
   },
   "keywords": [
@@ -57,13 +64,13 @@
     "access": "public"
   },
   "dependencies": {
-    "fastmcp": "^3.35.0",
-    "zod": "^4.3.6"
+    "fastmcp": "^4.0.1",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.11",
-    "@types/node": "^22.19.17",
+    "@biomejs/biome": "^2.4.14",
+    "@types/node": "^25.6.0",
     "rimraf": "^6.1.3",
-    "typescript": "^6.0.2"
+    "typescript": "^6.0.3"
   }
 }