@rethunk/mcp-multi-root-git 3.1.0 → 4.0.0

package/dist/server/test-harness.js

@@ -16,6 +16,7 @@
  *   const result = await tool({ workspaceRoot: dir, commits: [...] });
  *   // result is string (markdown) or JSON-parseable string
  */
+import { afterEach } from "bun:test";
 import { execFileSync } from "node:child_process";
 import { appendFileSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -33,12 +34,18 @@ const STUB_CONTEXT = {
 };
 // ---------------------------------------------------------------------------
 // Tmp-dir lifecycle — prevents accumulating thousands of leaked test dirs.
-// Each test file must register the hook itself:
-//   afterEach(cleanupTmpPaths);
-// Module-scope afterEach(...) would only register once (first-importer wins)
-// because the module is cached across test files in the same bun test run.
+// Each test file that calls mkTmpDir / makeRepo / trackTmpPath must register
+// cleanup once at module scope:
+//   registerTmpCleanup();
+// (equivalent to afterEach(cleanupTmpPaths) but documents the contract.)
+// Module-scope afterEach(...) in this file would only register once
+// (first-importer wins) because the module is cached across test files.
 // ---------------------------------------------------------------------------
 const tmpPaths = [];
+/** Register afterEach cleanup for dirs created via mkTmpDir / makeRepo. Call once per test file. */
+export function registerTmpCleanup() {
+    afterEach(cleanupTmpPaths);
+}
 export function mkTmpDir(prefix) {
     const dir = mkdtempSync(join(tmpdir(), prefix));
     tmpPaths.push(dir);

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

@@ -1,95 +1,84 @@
 import { z } from "zod";
-import { registerBatchCommitTool } from "./batch-commit-tool.js";
-import { registerGitBlameTool } from "./git-blame-tool.js";
-import { registerGitBranchListTool } from "./git-branch-list-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 { registerGitReflogTool } from "./git-reflog-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 { registerRethunkGitTools } from "./tools.js";
+/**
+ * Fan-out read tools: polymorphic `root` routing (string | string[] | "*").
+ * Must stay in sync with the tools that use RootPickSchema — asserted against
+ * live `registerRethunkGitTools` capture in tests.
+ */
 export const FAN_OUT_ROOT_TOOLS = [
     "git_status",
     "git_inventory",
     "git_parity",
     "list_presets",
     "git_log",
+    "git_grep",
 ];
+/**
+ * Read-only single-repo tools: `workspaceRoot` routing only.
+ */
 export const READ_ONLY_SINGLE_REPO_TOOLS = [
     "git_diff_summary",
     "git_diff",
     "git_show",
-    "git_worktree_list",
-    "git_stash_list",
+    "git_conflicts",
     "git_blame",
-    "git_branch_list",
-    "git_reflog",
 ];
+/**
+ * Mutating tools: `workspaceRoot` routing only.
+ */
 export const MUTATING_TOOLS = [
-    "git_fetch",
     "batch_commit",
     "git_push",
     "git_merge",
     "git_cherry_pick",
+    "git_cherry_pick_continue",
     "git_reset_soft",
+    "git_revert",
     "git_tag",
+    "git_branch",
     "git_worktree_add",
     "git_worktree_remove",
     "git_stash_apply",
+    "git_stash_push",
 ];
+/** Category union used for routing assertions; must equal live registrar names. */
 export const ALL_PARAMETER_SCHEMA_TOOLS = [
     ...FAN_OUT_ROOT_TOOLS,
     ...READ_ONLY_SINGLE_REPO_TOOLS,
     ...MUTATING_TOOLS,
 ];
-function captureParameterTools(register) {
+/**
+ * Capture parameter Zod schemas by driving the same registrar path as the live
+ * server (`registerRethunkGitTools`), so adding a tool only in `tools.ts` is
+ * enough for schema capture — no parallel register* list here.
+ *
+ * Clears `RETHUNK_GIT_TOOLS` for the duration so allowlist filtering cannot
+ * silently omit tools from published artifacts.
+ */
+export function captureToolParameterSchemas() {
     const tools = [];
     const server = {
         sessions: [],
         addTool(tool) {
             tools.push({ name: tool.name, parameters: tool.parameters });
         },
+        addResource() {
+            // Presets resource is always registered; capture only needs tools.
+        },
     };
-    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);
-        registerGitBlameTool(server);
-        registerGitBranchListTool(server);
-        registerGitReflogTool(server);
-        registerBatchCommitTool(server);
-        registerGitPushTool(server);
-        registerGitMergeTool(server);
-        registerGitCherryPickTool(server);
-        registerGitResetSoftTool(server);
-        registerGitTagTool(server);
-        registerGitWorktreeAddTool(server);
-        registerGitWorktreeRemoveTool(server);
-        registerGitStashApplyTool(server);
-    });
+    const prev = process.env.RETHUNK_GIT_TOOLS;
+    delete process.env.RETHUNK_GIT_TOOLS;
+    try {
+        registerRethunkGitTools(server);
+    }
+    finally {
+        if (prev === undefined) {
+            delete process.env.RETHUNK_GIT_TOOLS;
+        }
+        else {
+            process.env.RETHUNK_GIT_TOOLS = prev;
+        }
+    }
     return Object.fromEntries(tools.map((tool) => [tool.name, z.toJSONSchema(tool.parameters)]));
 }
 export function buildToolParameterSchemaDocument() {

package/dist/server/tools.js

@@ -1,26 +1,27 @@
 import { registerBatchCommitTool } from "./batch-commit-tool.js";
 import { registerGitBlameTool } from "./git-blame-tool.js";
-import { registerGitBranchListTool } from "./git-branch-list-tool.js";
-import { registerGitCherryPickTool } from "./git-cherry-pick-tool.js";
+import { registerGitBranchTool } from "./git-branch-tool.js";
+import { registerGitCherryPickContinueTool, registerGitCherryPickTool, } from "./git-cherry-pick-tool.js";
+import { registerGitConflictsTool } from "./git-conflicts-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 { registerGitGrepTool } from "./git-grep-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 { registerGitReflogTool } from "./git-reflog-tool.js";
 import { registerGitResetSoftTool } from "./git-reset-soft-tool.js";
+import { registerGitRevertTool } from "./git-revert-tool.js";
 import { registerGitShowTool } from "./git-show-tool.js";
-import { registerGitStashApplyTool, registerGitStashListTool } from "./git-stash-tool.js";
+import { registerGitStashApplyTool, registerGitStashPushTool } 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 { registerGitWorktreeAddTool, registerGitWorktreeRemoveTool } from "./git-worktree-tool.js";
 import { registerListPresetsTool } from "./list-presets-tool.js";
 import { registerPresetsResource } from "./presets-resource.js";
 /**
- * Ordered registry of all 23 MCP tools. Registration order is preserved for
+ * Ordered registry of all 24 MCP tools. Registration order is preserved for
  * both full and filtered (RETHUNK_GIT_TOOLS) subsets.
  */
 const TOOL_REGISTRARS = [
@@ -30,30 +31,36 @@ const TOOL_REGISTRARS = [
     { name: "git_parity", register: registerGitParityTool },
     { name: "list_presets", register: registerListPresetsTool },
     { name: "git_log", register: registerGitLogTool },
+    { name: "git_grep", register: registerGitGrepTool },
     { 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_conflicts", register: registerGitConflictsTool },
     { name: "git_blame", register: registerGitBlameTool },
-    { name: "git_branch_list", register: registerGitBranchListTool },
-    { name: "git_reflog", register: registerGitReflogTool },
     // Mutating tools
     { name: "batch_commit", register: registerBatchCommitTool },
     { name: "git_push", register: registerGitPushTool },
     { name: "git_merge", register: registerGitMergeTool },
     { name: "git_cherry_pick", register: registerGitCherryPickTool },
+    { name: "git_cherry_pick_continue", register: registerGitCherryPickContinueTool },
     { name: "git_reset_soft", register: registerGitResetSoftTool },
+    { name: "git_revert", register: registerGitRevertTool },
     { name: "git_tag", register: registerGitTagTool },
+    { name: "git_branch", register: registerGitBranchTool },
     { name: "git_worktree_add", register: registerGitWorktreeAddTool },
     { name: "git_worktree_remove", register: registerGitWorktreeRemoveTool },
     { name: "git_stash_apply", register: registerGitStashApplyTool },
+    { name: "git_stash_push", register: registerGitStashPushTool },
 ];
 /**
  * Parse the RETHUNK_GIT_TOOLS env var and return the matching subset of
  * registrars plus any unrecognized token names.
  *
+ * Semantics:
+ * - unset / empty / whitespace-only → all tools
+ * - bare `*` (sole non-empty token) → all tools (all-tools sentinel; not an empty selection)
+ * - otherwise → exact name match (case-sensitive), canonical order, duplicates ignored
+ *
  * @param envValue  Raw value of process.env.RETHUNK_GIT_TOOLS (may be undefined).
  * @param registrars  Full ordered registrar list (injectable for tests).
  */
@@ -62,13 +69,25 @@ export function selectToolRegistrars(envValue, registrars) {
         .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: [] };
+    // Unset, empty, whitespace-only, or bare "*" → register all tools.
+    // Bare "*" is an intentional all-tools sentinel (operators used to root="*"
+    // fan-out may set RETHUNK_GIT_TOOLS=* expecting the full surface — treating
+    // it as an unrecognized name that empties the allowlist is a footgun).
+    if (tokens.length === 0 || (tokens.length === 1 && tokens[0] === "*")) {
+        // Shallow copy so callers cannot mutate the shared TOOL_REGISTRARS array.
+        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));
+    // Deduplicate unknown tokens while preserving first-seen order.
+    const unknownSeen = new Set();
+    const unknown = [];
+    for (const t of tokens) {
+        if (!knownNames.has(t) && !unknownSeen.has(t)) {
+            unknownSeen.add(t);
+            unknown.push(t);
+        }
+    }
     // Preserve canonical order; deduplicate duplicate tokens automatically.
     const selected = registrars.filter((r) => requested.has(r.name));
     return { selected, unknown };
@@ -81,7 +100,7 @@ export function registerRethunkGitTools(server) {
     }
     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`);
+            `Set RETHUNK_GIT_TOOLS to a comma-separated list of valid tool names, bare "*" for all tools, or unset it to register all tools.\n`);
     }
     for (const { register } of selected) {
         register(server);

package/dist/server.js

@@ -7,7 +7,7 @@ import { registerRethunkGitTools } from "./server/tools.js";
  * (renamed/nested/omitted fields). Surfaced via the FastMCP `instructions`
  * field below, so it is discoverable in the MCP `initialize` response.
  */
-export const MCP_JSON_FORMAT_VERSION = "5";
+export const MCP_JSON_FORMAT_VERSION = "6";
 const server = new FastMCP({
     name: "rethunk-git",
     version: readMcpServerVersion(),

package/docs/install.md

@@ -91,11 +91,30 @@ 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`. |
+| `GIT_SUBPROCESS_PARALLELISM` | `4` | Max concurrent git subprocesses for `git_inventory` rows, `git_status` submodule rows, and multi-root fan-out in `git_log` and `git_grep`. Valid range: 1 to 2×CPU count (auto-clamped). Increase on high-core machines to accelerate large fleet scans; decrease if system resources are constrained. |
+| `GIT_SUBPROCESS_TIMEOUT_MS` | `120000` | Per-subprocess timeout in milliseconds for async git calls. On expiry the child receives SIGTERM and the call fails. Set `0` (or negative) to disable timeout for intentionally unbounded operations. |
+| `RETHUNK_GIT_TOOLS` | _(unset)_ | Comma-separated list of tool names to register. When unset or empty, all 24 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_grep`, `git_diff_summary`, `git_diff`, `git_show`, `git_conflicts`, `git_blame`, `batch_commit`, `git_push`, `git_merge`, `git_cherry_pick`, `git_cherry_pick_continue`, `git_reset_soft`, `git_revert`, `git_tag`, `git_branch`, `git_worktree_add`, `git_worktree_remove`, `git_stash_apply`, `git_stash_push`. |
 
 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).
 
+**MCP client `env` block** (Cursor / Claude Desktop `mcpServers`; VS Code adds `"env"` beside `"command"` / `"args"`):
+
+```json
+{
+  "mcpServers": {
+    "rethunk-git": {
+      "command": "npx",
+      "args": ["-y", "@rethunk/mcp-multi-root-git"],
+      "env": {
+        "GIT_SUBPROCESS_PARALLELISM": "8",
+        "GIT_SUBPROCESS_TIMEOUT_MS": "120000",
+        "RETHUNK_GIT_TOOLS": "git_status,git_log,batch_commit,git_push"
+      }
+    }
+  }
+}
+```
+
 Example: Running the server with 8 parallel git processes on a 4-core machine:
 
 ```bash
@@ -200,12 +219,40 @@ Official protocol overview: [modelcontextprotocol.io](https://modelcontextprotoc
 
 For contributors working inside a clone of [mcp-multi-root-git](https://github.com/Rethunk-AI/mcp-multi-root-git):
 
-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.
+1. **Dependencies, build, and CI parity:** [CONTRIBUTING.md](../CONTRIBUTING.md) — *Development setup* (`bun install`, `bun run build`, `bun run ci`).
 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:** 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.
+**MCP registration for a local checkout** — set `cwd` to the repository root (exception to the no-`cwd` rule for published packages) so relative `args` resolve, or pass absolute paths in `args`. Open the workspace at the clone root in your client.
+
+**Bun dev server** (no `dist/` build):
+
+```json
+{
+  "mcpServers": {
+    "rethunk-git": {
+      "command": "bun",
+      "args": ["src/server.ts"],
+      "cwd": "/path/to/mcp-multi-root-git"
+    }
+  }
+}
+```
+
+**Built entrypoint** (after `bun run build`):
+
+```json
+{
+  "mcpServers": {
+    "rethunk-git": {
+      "command": "node",
+      "args": ["dist/server.js"],
+      "cwd": "/path/to/mcp-multi-root-git"
+    }
+  }
+}
+```
 
-**Reload** the MCP connection after changing server code.
+**Cursor:** add either block to user-scope (`~/.cursor/mcp.json`) or project-scope (`.cursor/mcp.json`). **Reload** the MCP connection after changing server code.
 
 ## Troubleshooting