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

package/AGENTS.md

@@ -17,9 +17,9 @@ IDEs injecting this as context: do not re-link from rules.
 | [`src/server.ts`](src/server.ts) | `FastMCP` + `roots: { enabled: true }`; `readMcpServerVersion()`; `registerRethunkGitTools` |
 | [`src/server/json.ts`](src/server/json.ts) | `jsonRespond()` (minified, no envelope), `spreadWhen`, `spreadDefined` |
 | [`src/server/git.ts`](src/server/git.ts) | `gateGit`, `spawnGitAsync`, `asyncPool`, `GIT_SUBPROCESS_PARALLELISM`, `gitTopLevel`, `gitRevParseGitDir`, `gitRevParseHead`, `parseGitSubmodulePaths`, `hasGitMetadata`, `gitStatusSnapshotAsync`, `gitStatusShortBranchAsync`, `fetchAheadBehind`, `isSafeGitUpstreamToken` |
-| [`src/server/roots.ts`](src/server/roots.ts) | `requireGitAndRoots`, `requireSingleRepo` — shared tool preludes; session root resolution |
+| [`src/server/roots.ts`](src/server/roots.ts) | `requireGitAndRoots`, `requireSingleRepo`, `resolveAbsoluteGitRootsList`, `GitRootPickArgs` — shared tool preludes; session root resolution; optional `absoluteGitRoots` bulk pick |
 | [`src/server/presets.ts`](src/server/presets.ts) | `PRESET_FILE_PATH`, `loadPresetsFromGitTop`, `presetLoadErrorPayload`, `applyPresetNestedRoots`, `applyPresetParityPairs`; Zod schemas must match [`git-mcp-presets.schema.json`](git-mcp-presets.schema.json) |
-| [`src/server/schemas.ts`](src/server/schemas.ts) | `WorkspacePickSchema`, `MAX_INVENTORY_ROOTS_DEFAULT` |
+| [`src/server/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`, `commitListBetween`; `listWorktrees`, `worktreeForBranch`; `conflictPaths` |
 | [`src/server/tools.ts`](src/server/tools.ts) | `registerRethunkGitTools` — dispatches to `register*` below |
@@ -36,6 +36,7 @@ IDEs injecting this as context: do not re-link from rules.
 | [`src/server/git-cherry-pick-tool.ts`](src/server/git-cherry-pick-tool.ts) | `git_cherry_pick` — mutating |
 | [`src/server/git-reset-soft-tool.ts`](src/server/git-reset-soft-tool.ts) | `git_reset_soft` — soft-reset; mutating |
 | [`src/server/presets-resource.ts`](src/server/presets-resource.ts) | `rethunk-git://presets` resource |
+| [`src/server/tool-parameter-schemas.ts`](src/server/tool-parameter-schemas.ts) | `buildToolParameterSchemaDocument`, `captureToolParameterSchemas`; backs `tool-parameters.schema.json` |
 | [`src/repo-paths.ts`](src/repo-paths.ts) | `resolvePathForRepo`, `assertRelativePathUnderTop`, `isStrictlyUnderGitTop` |
 
 ## Changing contracts
@@ -47,7 +48,7 @@ IDEs injecting this as context: do not re-link from rules.
 
 ## Validate + CI
 
-Local: `bun run build` | `bun run check` | `bun run test`. CI ([`ci.yml`](.github/workflows/ci.yml)) runs same on PRs + `main` after `bun install --frozen-lockfile`, 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 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)).
 
 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,34 @@
 
 All notable changes to `@rethunk/mcp-multi-root-git` are documented here. Format loosely follows [Keep a Changelog](https://keepachangelog.com); the project uses [Semantic Versioning](https://semver.org).
 
+## [2.3.4] — 2026-04-26
+
+Publication-prep patch for the `absoluteGitRoots` line.
+
+### Added
+
+- **`tool-parameters.schema.json`** — generated JSON Schema snapshot for every registered tool parameter surface, plus `bun run schema:tools` / `bun run schema:tools:check`.
+- **`git_parity` absolute-root regression coverage** — sibling clone batches are now covered directly.
+
+### Fixed
+
+- **CI coverage gate** now checks `% Lines` from Bun's coverage table instead of accidentally reading `% Funcs`.
+
+### Documentation
+
+- **`HUMANS.md`** — added sibling-clone `absoluteGitRoots` examples for `git_status` and `git_parity`.
+- **`docs/mcp-tools.md`** — clarified direct `git_push` use for already-committed work and `git_parity` sibling-clone batches.
+
+## [2.3.3] — 2026-04-21
+
+### Added
+
+- **`absoluteGitRoots`** on the workspace pick schema: pass absolute paths to many independent git clones in one MCP call for **`git_status`**, **`git_inventory`**, **`git_log`**, **`git_parity`**, **`git_diff_summary`** (single distinct toplevel only), and **`list_presets`**. Mutating tools omit this parameter from their Zod surface. See **`docs/mcp-tools.md`** (*Workspace root resolution*).
+
+### Changed
+
+- **`requireGitAndRoots`** / **`requireSingleRepo`**: new prelude **`resolveAbsoluteGitRootsList`** with dedupe, fail-fast on invalid paths, and mutual exclusion with `workspaceRoot` / `rootIndex` / `allWorkspaceRoots` / `preset` (and `nestedRoots`+`preset` guarded in **`git_inventory`**).
+
 ## [2.3.2] — 2026-04-21
 
 ### CI

package/HUMANS.md

@@ -53,6 +53,22 @@ With **multiple MCP file roots**, the server picks a root whose git toplevel def
 
 If you installed from **GitHub Packages**, use **`./node_modules/@rethunk-ai/mcp-multi-root-git/git-mcp-presets.schema.json`** in **`$schema`** instead (see [docs/install.md](docs/install.md#github-packages)).
 
+## Tool parameter schema artifact
+
+The package ships **`tool-parameters.schema.json`**, a generated JSON Schema snapshot of every registered tool's parameter schema. Maintainers regenerate it with:
+
+```bash
+bun run schema:tools
+```
+
+CI and `prepublishOnly` use:
+
+```bash
+bun run schema:tools:check
+```
+
+This artifact is for inspection, drift checks, and clients that want an offline schema snapshot. Runtime MCP schema discovery remains the source of truth for connected clients.
+
 **Layouts:**
 
 1. **Wrapped (recommended):** `{ "schemaVersion": "1", "presets": { "<name>": { ... } } }`.
@@ -74,6 +90,37 @@ Invalid JSON or schema errors return **`preset_file_invalid`** (not a silent emp
 
 Relative preset paths must stay inside the git toplevel; escapes are rejected.
 
+## Sibling clone batches
+
+Use **`absoluteGitRoots`** when you want one read-only call to inspect independent sibling clones that are not all exposed as MCP workspace roots. This is most useful from agent workflows rooted at a parent directory or when an MCP client exposes only one repo root.
+
+Example `git_status` batch:
+
+```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"
+  ]
+}
+```
+
+Example `git_parity` batch using the same pair in each sibling clone:
+
+```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" }]
+}
+```
+
+`absoluteGitRoots` is read-only by design. Mutating tools such as **`batch_commit`**, **`git_push`**, **`git_merge`**, and **`git_cherry_pick`** omit it from their schema; use `workspaceRoot` or MCP roots for writes. Full parameter rules and error codes live in **[docs/mcp-tools.md](docs/mcp-tools.md#absoluteGitRoots-sibling-clones)**.
+
 ## `git_not_found`
 
 If **`git`** is missing or not runnable, tools and the presets resource respond with **`git_not_found`**. Prerequisites and `PATH`: **[docs/install.md](docs/install.md)**.
@@ -97,6 +144,14 @@ Tag pushes run [`.github/workflows/release.yml`](.github/workflows/release.yml):
 
 Prerequisite: push a **semver git tag** `vX.Y.Z` that **exactly matches** `version` in `package.json` (e.g. `v1.2.3` and `"version": "1.2.3"`).
 
+Before tagging, run the clean-tree preflight from the release commit:
+
+```bash
+bun run publish:preflight
+```
+
+It verifies the `package.json` version has a matching `CHANGELOG.md` section, generated tool schemas are current, build/check/coverage pass, and `npm pack --dry-run` includes the expected package files.
+
 ### npmjs (manual) — maintainers only
 
 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`**):

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

@@ -53,7 +53,7 @@ export function registerBatchCommitTool(server) {
             destructiveHint: false,
             idempotentHint: false,
         },
-        parameters: WorkspacePickSchema.extend({
+        parameters: WorkspacePickSchema.omit({ absoluteGitRoots: true }).extend({
             commits: z
                 .array(CommitEntrySchema)
                 .min(1)

package/dist/server/coverage.js

@@ -0,0 +1,22 @@
+export function parseAllFilesLineCoverage(output) {
+    const rows = output
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.includes("|"));
+    const header = rows.find((line) => /^File\s*\|/i.test(line));
+    if (!header)
+        return null;
+    const columns = header.split("|").map((column) => column.trim().toLowerCase());
+    const lineIndex = columns.indexOf("% lines");
+    if (lineIndex === -1)
+        return null;
+    const allFiles = rows.find((line) => /^All files\s*\|/i.test(line));
+    if (!allFiles)
+        return null;
+    const cells = allFiles.split("|").map((cell) => cell.trim());
+    const raw = cells[lineIndex];
+    if (!raw)
+        return null;
+    const value = Number.parseFloat(raw);
+    return Number.isFinite(value) ? value : null;
+}

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

@@ -103,7 +103,7 @@ export function registerGitCherryPickTool(server) {
             destructiveHint: false,
             idempotentHint: false,
         },
-        parameters: WorkspacePickSchema.extend({
+        parameters: WorkspacePickSchema.omit({ absoluteGitRoots: true }).extend({
             sources: z
                 .array(z.string().min(1))
                 .min(1)

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

@@ -25,6 +25,11 @@ export function registerGitInventoryTool(server) {
             maxRoots: z.number().int().min(1).max(256).optional().default(MAX_INVENTORY_ROOTS_DEFAULT),
         }),
         execute: async (args) => {
+            if (args.absoluteGitRoots != null && args.absoluteGitRoots.length > 0) {
+                if (args.preset || (args.nestedRoots?.length ?? 0) > 0) {
+                    return jsonRespond({ error: "absolute_git_roots_nested_or_preset_conflict" });
+                }
+            }
             const pre = requireGitAndRoots(server, args, args.preset);
             if (!pre.ok) {
                 return jsonRespond(pre.error);

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

@@ -217,7 +217,7 @@ export function registerGitMergeTool(server) {
             destructiveHint: false,
             idempotentHint: false,
         },
-        parameters: WorkspacePickSchema.extend({
+        parameters: WorkspacePickSchema.omit({ absoluteGitRoots: true }).extend({
             sources: z
                 .array(z.string().min(1))
                 .min(1)

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

@@ -15,7 +15,7 @@ export function registerGitPushTool(server) {
             destructiveHint: false,
             idempotentHint: false,
         },
-        parameters: WorkspacePickSchema.extend({
+        parameters: WorkspacePickSchema.omit({ absoluteGitRoots: true }).extend({
             remote: z
                 .string()
                 .optional()

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

@@ -16,7 +16,7 @@ export function registerGitResetSoftTool(server) {
             destructiveHint: false,
             idempotentHint: false,
         },
-        parameters: WorkspacePickSchema.extend({
+        parameters: WorkspacePickSchema.omit({ absoluteGitRoots: true }).extend({
             ref: z
                 .string()
                 .min(1)

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

@@ -55,7 +55,7 @@ export function registerGitWorktreeAddTool(server) {
             destructiveHint: false,
             idempotentHint: false,
         },
-        parameters: WorkspacePickSchema.extend({
+        parameters: WorkspacePickSchema.omit({ absoluteGitRoots: true }).extend({
             path: z
                 .string()
                 .min(1)
@@ -139,7 +139,7 @@ export function registerGitWorktreeRemoveTool(server) {
             destructiveHint: true,
             idempotentHint: false,
         },
-        parameters: WorkspacePickSchema.extend({
+        parameters: WorkspacePickSchema.omit({ absoluteGitRoots: true }).extend({
             path: z
                 .string()
                 .min(1)

package/dist/server/list-presets-tool.js

@@ -15,6 +15,7 @@ export function registerListPresetsTool(server) {
             workspaceRoot: true,
             rootIndex: true,
             allWorkspaceRoots: true,
+            absoluteGitRoots: true,
             format: true,
         }),
         execute: async (args) => {

package/dist/server/roots.js

@@ -2,6 +2,7 @@ import { basename, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { gateGit, gitTopLevel } from "./git.js";
 import { loadPresetsFromGitTop, presetLoadErrorPayload } from "./presets.js";
+import { MAX_ABSOLUTE_GIT_ROOTS } from "./schemas.js";
 function uriToPath(uri) {
     if (!uri.startsWith("file://"))
         return null;
@@ -39,6 +40,51 @@ function pathMatchesWorkspaceRootHint(rootPath, hint) {
         return true;
     return basename(rootPath) === h;
 }
+function hasExclusiveWorkspacePick(args) {
+    if (args.workspaceRoot?.trim())
+        return true;
+    if (args.rootIndex != null)
+        return true;
+    if (args.allWorkspaceRoots === true)
+        return true;
+    return false;
+}
+/**
+ * Resolve `absoluteGitRoots` to unique git toplevels (stable order, first occurrence wins).
+ */
+export function resolveAbsoluteGitRootsList(raw) {
+    if (raw.length > MAX_ABSOLUTE_GIT_ROOTS) {
+        return {
+            ok: false,
+            error: {
+                error: "absolute_git_roots_too_many",
+                max: MAX_ABSOLUTE_GIT_ROOTS,
+                count: raw.length,
+            },
+        };
+    }
+    const seen = new Set();
+    const tops = [];
+    for (const item of raw) {
+        const trimmed = item.trim();
+        if (trimmed.length === 0) {
+            return { ok: false, error: { error: "invalid_absolute_git_root", path: item } };
+        }
+        const abs = resolve(trimmed);
+        const top = gitTopLevel(abs);
+        if (!top) {
+            return { ok: false, error: { error: "invalid_absolute_git_root", path: abs } };
+        }
+        if (seen.has(top))
+            continue;
+        seen.add(top);
+        tops.push(top);
+    }
+    if (tops.length === 0) {
+        return { ok: false, error: { error: "absolute_git_roots_empty" } };
+    }
+    return { ok: true, roots: tops };
+}
 function resolveWorkspaceRoots(server, args) {
     if (args.workspaceRoot?.trim()) {
         return { ok: true, roots: [resolve(args.workspaceRoot.trim())] };
@@ -110,6 +156,16 @@ export function requireGitAndRoots(server, args, presetName) {
     if (!gg.ok) {
         return { ok: false, error: gg.body };
     }
+    const abs = args.absoluteGitRoots;
+    if (abs != null && abs.length > 0) {
+        if (presetName) {
+            return { ok: false, error: { error: "absolute_git_roots_preset_conflict" } };
+        }
+        if (hasExclusiveWorkspacePick(args)) {
+            return { ok: false, error: { error: "absolute_git_roots_exclusive" } };
+        }
+        return resolveAbsoluteGitRootsList(abs);
+    }
     const rootsRes = presetName
         ? resolveRootsForPreset(server, args, presetName)
         : resolveWorkspaceRoots(server, args);
@@ -127,6 +183,15 @@ export function requireSingleRepo(server, args, presetName = undefined) {
     const pre = requireGitAndRoots(server, args, presetName);
     if (!pre.ok)
         return pre;
+    if (args.absoluteGitRoots != null && args.absoluteGitRoots.length > 0 && pre.roots.length !== 1) {
+        return {
+            ok: false,
+            error: {
+                error: "absolute_git_roots_single_repo_only",
+                rootCount: pre.roots.length,
+            },
+        };
+    }
     const rootInput = pre.roots[0];
     if (!rootInput)
         return { ok: false, error: { error: "no_workspace_root" } };

package/dist/server/schemas.js

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { MAX_INVENTORY_ROOTS_DEFAULT } from "./inventory.js";
 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."),
     rootIndex: z
@@ -14,6 +16,12 @@ export const WorkspacePickSchema = z.object({
         .optional()
         .default(false)
         .describe("Fan out across all MCP file 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."),
     format: FormatSchema,
 });
 export { MAX_INVENTORY_ROOTS_DEFAULT };

package/dist/server/test-harness.js

@@ -62,7 +62,10 @@ function makeFakeServer() {
     const server = {
         sessions: [],
         addTool(tool) {
-            tools.push({ name: tool.name, execute: tool.execute });
+            tools.push({ name: tool.name, parameters: tool.parameters, execute: tool.execute });
+        },
+        addResource() {
+            // Resource tests do not need transport behavior; tool-surface tests only need registration to complete.
         },
     };
     return { server, tools };
@@ -89,3 +92,8 @@ export function captureTool(register, toolName) {
         return JSON.stringify(result);
     };
 }
+export function captureToolDefinitions(register) {
+    const { server, tools } = makeFakeServer();
+    register(server);
+    return tools;
+}

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

@@ -0,0 +1,74 @@
+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 { 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 { registerGitStatusTool } from "./git-status-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 MUTATING_TOOLS = [
+    "batch_commit",
+    "git_push",
+    "git_merge",
+    "git_cherry_pick",
+    "git_reset_soft",
+    "git_worktree_add",
+    "git_worktree_remove",
+];
+export const ALL_PARAMETER_SCHEMA_TOOLS = [
+    ...READ_ONLY_ABSOLUTE_ROOT_TOOLS,
+    "git_worktree_list",
+    ...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);
+        registerGitWorktreeListTool(server);
+        registerBatchCommitTool(server);
+        registerGitPushTool(server);
+        registerGitMergeTool(server);
+        registerGitCherryPickTool(server);
+        registerGitResetSoftTool(server);
+        registerGitWorktreeAddTool(server);
+        registerGitWorktreeRemoveTool(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/docs/mcp-tools.md

@@ -11,12 +11,12 @@ MCP clients expose tools as `{serverName}_{toolName}`. With the server registere
 
 | Short id | Client id (server `rethunk-git`) | Purpose |
 |----------|-----------------------------------|---------|
-| `git_status` | `rethunk-git_git_status` | `git status --short -b` per MCP root and optional submodules (`includeSubmodules`); parallel submodule status. Args include `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. **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.** |
-| `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. **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 + `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 + `format`. **Read-only.** |
+| `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 (`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_worktree_list` | `rethunk-git_git_worktree_list` | List all worktrees (`git worktree list --porcelain`). Workspace pick + `format`. **Read-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_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.** |
@@ -32,6 +32,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`. Connected MCP clients should still prefer live schema discovery from `initialize` / tool listing; the artifact is for offline inspection and drift checks.
+
 ### 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`.
@@ -106,6 +108,29 @@ v2 field-omission rules still apply: `filesChanged`, `insertions`, `deletions` o
 | `invalid_paths` | One of the `paths` entries contains shell metacharacters and was rejected. |
 | `git_log_failed` | `git log` exited non-zero (e.g. unknown branch ref). |
 | `root_index_out_of_range` | `rootIndex` exceeds the number of MCP file roots. |
+| `absolute_git_roots_exclusive` | `absoluteGitRoots` was combined with `workspaceRoot`, `rootIndex`, or `allWorkspaceRoots: true`. |
+| `absolute_git_roots_preset_conflict` | `absoluteGitRoots` was combined with a `preset` argument (root resolution). |
+| `invalid_absolute_git_root` | An `absoluteGitRoots` entry is empty, not inside a git worktree, or not a directory git recognizes. |
+| `absolute_git_roots_too_many` | More than 256 entries in `absoluteGitRoots`. |
+| `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
 
@@ -346,6 +371,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. |
@@ -456,6 +483,32 @@ Repo state is cleaned (`git cherry-pick --abort`) before returning — no partia
 
 ## Workspace root resolution
 
+### `absoluteGitRoots` (sibling clones)
+
+When **`absoluteGitRoots`** is a **non-empty** string array, it **replaces** the normal workspace pick for that tool call:
+
+- Each entry is passed through `path.resolve`, then resolved to a **git toplevel** via the same logic as `workspaceRoot`. Duplicate toplevels are dropped (stable order, first wins).
+- **Maximum** **256** paths (same cap as `git_inventory` `maxRoots` upper bound).
+- **Mutually exclusive** with **`workspaceRoot`**, **`rootIndex`**, and **`allWorkspaceRoots: true`**. Combining them returns `{ "error": "absolute_git_roots_exclusive" }`.
+- **Mutually exclusive** with a **`preset`** argument on root resolution (`absolute_git_roots_preset_conflict`).
+- **`git_inventory` only:** also mutually exclusive with **`nestedRoots`** or **`preset`** on the same call (`absolute_git_roots_nested_or_preset_conflict`).
+- **Mutating** tools (`batch_commit`, `git_push`, `git_merge`, …) **omit** this parameter from their schema; callers must use `workspaceRoot` / MCP roots for writes.
+- **Read tools** that use **`requireSingleRepo`** (`git_diff_summary`, …) accept at most **one** distinct toplevel from `absoluteGitRoots`; more than one returns `absolute_git_roots_single_repo_only`.
+
+Example — two sibling repos in one `git_status` call:
+
+```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"
+  ]
+}
+```
+
+### Default order (when `absoluteGitRoots` is absent or empty)
+
 Order applied when resolving which directory(ies) tools run against:
 
 1. Explicit **`workspaceRoot`** on the tool call (highest priority).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rethunk/mcp-multi-root-git",
-  "version": "2.3.2",
+  "version": "2.3.4",
   "description": "MCP stdio server: multi-root git status, inventory, and HEAD parity checks. Generic tools usable by any workspace.",
   "type": "module",
   "private": false,
@@ -11,6 +11,7 @@
   "files": [
     "dist",
     "git-mcp-presets.schema.json",
+    "tool-parameters.schema.json",
     "docs/install.md",
     "docs/mcp-tools.md",
     "AGENTS.md",
@@ -31,9 +32,13 @@
     "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",
+    "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 build && bun run check && bun run test",
     "setup-hooks": "git config core.hooksPath .githooks"
   },
   "keywords": [
@@ -57,13 +62,13 @@
     "access": "public"
   },
   "dependencies": {
-    "fastmcp": "^3.35.0",
+    "fastmcp": "^4.0.1",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.11",
-    "@types/node": "^22.19.17",
+    "@biomejs/biome": "^2.4.13",
+    "@types/node": "^25.6.0",
     "rimraf": "^6.1.3",
-    "typescript": "^6.0.2"
+    "typescript": "^6.0.3"
   }
 }