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

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 |

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 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.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/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/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/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_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.** |
-| `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.** |
+| `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.** |
@@ -106,6 +106,12 @@ 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_diff_summary` — parameters
 
@@ -456,6 +462,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.3",
   "description": "MCP stdio server: multi-root git status, inventory, and HEAD parity checks. Generic tools usable by any workspace.",
   "type": "module",
   "private": false,