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

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

@@ -0,0 +1,162 @@
+import { z } from "zod";
+import { isSafeGitUpstreamToken, spawnGitAsync } from "./git.js";
+import { jsonRespond } from "./json.js";
+import { requireSingleRepo } from "./roots.js";
+import { WorkspacePickSchema } from "./schemas.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Get the SHA of a given ref (tag, commit, branch, etc).
+ */
+async function getRefSha(gitTop, ref) {
+    const result = await spawnGitAsync(gitTop, ["rev-parse", ref]);
+    if (!result.ok)
+        return null;
+    return result.stdout.trim();
+}
+/**
+ * Check if a tag is annotated or lightweight.
+ */
+async function getTagType(gitTop, tag) {
+    // For annotated tags, `git cat-file -t <tag>` returns "tag"
+    // For lightweight tags, it returns "commit"
+    const result = await spawnGitAsync(gitTop, ["cat-file", "-t", tag]);
+    if (!result.ok)
+        return null;
+    const type = result.stdout.trim();
+    if (type === "tag")
+        return "annotated";
+    if (type === "commit")
+        return "lightweight";
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+export function registerGitTagTool(server) {
+    server.addTool({
+        name: "git_tag",
+        description: "Create, delete, or inspect git tags. Create annotated tags (with message) or lightweight tags (ref only). " +
+            "Returns tag name, type, and SHA.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+        },
+        parameters: WorkspacePickSchema.omit({ absoluteGitRoots: true, allWorkspaceRoots: true })
+            .pick({
+            workspaceRoot: true,
+            rootIndex: true,
+            format: true,
+        })
+            .extend({
+            tag: z.string().min(1).describe("Tag name (e.g. 'v1.2.3')."),
+            message: z
+                .string()
+                .optional()
+                .describe("If provided, create an annotated tag with this message. If absent, create a lightweight tag."),
+            ref: z
+                .string()
+                .optional()
+                .describe("Commit/ref to tag (default: HEAD). Ignored if `delete` is true."),
+            delete: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("If true, delete the named tag instead of creating it."),
+        }),
+        execute: async (args) => {
+            const pre = requireSingleRepo(server, args);
+            if (!pre.ok)
+                return jsonRespond(pre.error);
+            const gitTop = pre.gitTop;
+            const tag = args.tag.trim();
+            if (!tag) {
+                return jsonRespond({ error: "tag_empty" });
+            }
+            // Validate tag name: no shell metacharacters
+            if (!isSafeGitUpstreamToken(tag)) {
+                return jsonRespond({ error: "tag_unsafe", tag });
+            }
+            // Handle deletion
+            if (args.delete === true) {
+                const delResult = await spawnGitAsync(gitTop, ["tag", "-d", tag]);
+                if (!delResult.ok) {
+                    return jsonRespond({
+                        error: "tag_delete_failed",
+                        detail: (delResult.stderr || delResult.stdout).trim(),
+                    });
+                }
+                if (args.format === "json") {
+                    return jsonRespond({
+                        tag,
+                        type: "deleted",
+                        sha: "", // Deleted tags have no SHA
+                    });
+                }
+                return `Deleted tag: ${tag}`;
+            }
+            // Determine the ref to tag (default HEAD)
+            const ref = (args.ref ?? "HEAD").trim();
+            if (!isSafeGitUpstreamToken(ref)) {
+                return jsonRespond({ error: "ref_unsafe", ref });
+            }
+            // Get the SHA of the ref to tag
+            const sha = await getRefSha(gitTop, ref);
+            if (!sha) {
+                return jsonRespond({
+                    error: "ref_not_found",
+                    ref,
+                });
+            }
+            // Create tag (annotated or lightweight)
+            const tagArgs = ["tag"];
+            if (args.message) {
+                // Annotated tag
+                tagArgs.push("-a", "-m", args.message);
+            }
+            else {
+                // Lightweight tag (just the tag name and ref)
+            }
+            tagArgs.push(tag, ref);
+            const createResult = await spawnGitAsync(gitTop, tagArgs);
+            if (!createResult.ok) {
+                return jsonRespond({
+                    error: "tag_create_failed",
+                    detail: (createResult.stderr || createResult.stdout).trim(),
+                });
+            }
+            // Verify the tag was created and get its type
+            const tagType = await getTagType(gitTop, tag);
+            if (!tagType) {
+                return jsonRespond({
+                    error: "tag_verification_failed",
+                    tag,
+                });
+            }
+            const result = {
+                tag,
+                type: tagType,
+                sha,
+            };
+            if (args.format === "json") {
+                return jsonRespond(result);
+            }
+            // Markdown output
+            const lines = [];
+            lines.push(`# Tag: ${tag}`);
+            lines.push("");
+            lines.push(`**Type:** ${tagType}`);
+            lines.push(`**SHA:** \`${sha}\``);
+            if (args.message) {
+                lines.push("");
+                lines.push("**Message:**");
+                lines.push("");
+                lines.push("```");
+                lines.push(args.message);
+                lines.push("```");
+            }
+            return lines.join("\n");
+        },
+    });
+}

package/dist/server/git.js

@@ -1,8 +1,24 @@
 import { spawn, spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
+import { cpus } from "node:os";
 import { join } from "node:path";
-/** Parallel git subprocesses for inventory rows and git_status submodule rows. */
-export const GIT_SUBPROCESS_PARALLELISM = 4;
+/**
+ * Parallel git subprocesses for inventory rows and git_status submodule rows.
+ * Reads from GIT_SUBPROCESS_PARALLELISM env var (default 4), clamped to [1, 2×CPU_COUNT].
+ */
+function resolveGitSubprocessParallelism() {
+    const env = process.env.GIT_SUBPROCESS_PARALLELISM;
+    if (env) {
+        const n = Number.parseInt(env, 10);
+        if (!Number.isNaN(n) && n >= 1) {
+            const cpuCount = cpus().length;
+            const maxParallel = cpuCount * 2;
+            return Math.min(n, maxParallel);
+        }
+    }
+    return 4;
+}
+export const GIT_SUBPROCESS_PARALLELISM = resolveGitSubprocessParallelism();
 let gitPathState = "unknown";
 const GIT_NOT_FOUND_BODY = {
     error: "git_not_found",

package/dist/server/roots.js

@@ -15,12 +15,16 @@ function uriToPath(uri) {
 }
 function listFileRoots(server) {
     const sessions = server.sessions;
-    const roots = sessions[0]?.roots ?? [];
     const paths = [];
-    for (const root of roots) {
-        const p = uriToPath(root.uri);
-        if (p)
+    const seen = new Set();
+    for (const session of sessions) {
+        for (const root of session.roots ?? []) {
+            const p = uriToPath(root.uri);
+            if (!p || seen.has(p))
+                continue;
+            seen.add(p);
             paths.push(p);
+        }
     }
     return paths;
 }

package/dist/server/test-harness.js

@@ -16,7 +16,8 @@
  *   const result = await tool({ workspaceRoot: dir, commits: [...] });
  *   // result is string (markdown) or JSON-parseable string
  */
-import { mkdtempSync, rmSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { appendFileSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 // Stub context — no tool currently uses context
@@ -54,13 +55,20 @@ export function cleanupTmpPaths() {
             rmSync(p, { recursive: true, force: true });
     }
 }
+export function writeTestGitConfig(repo) {
+    appendFileSync(join(repo, ".git", "config"), "\n[user]\n\temail = test@example.com\n\tname = Test User\n[commit]\n\tgpgsign = false\n");
+}
 // ---------------------------------------------------------------------------
 // Fake server
 // ---------------------------------------------------------------------------
-function makeFakeServer() {
+function makeFakeServer(roots = []) {
     const tools = [];
     const server = {
-        sessions: [],
+        sessions: [
+            {
+                roots: roots.map((uri) => ({ uri })),
+            },
+        ],
         addTool(tool) {
             tools.push({ name: tool.name, parameters: tool.parameters, execute: tool.execute });
         },
@@ -78,8 +86,8 @@ function makeFakeServer() {
  * The returned function accepts tool args (always include `workspaceRoot`)
  * and returns the raw result as a string.
  */
-export function captureTool(register, toolName) {
-    const { server, tools } = makeFakeServer();
+export function captureTool(register, toolName, roots = []) {
+    const { server, tools } = makeFakeServer(roots);
     register(server);
     const pick = toolName ? tools.find((t) => t.name === toolName) : tools[0];
     if (!pick) {
@@ -97,3 +105,58 @@ export function captureToolDefinitions(register) {
     register(server);
     return tools;
 }
+// ---------------------------------------------------------------------------
+// Shared git test helpers (extracted from per-file duplication)
+// ---------------------------------------------------------------------------
+/** Execute git command with standard test environment and encoding. */
+export function gitCmd(cwd, ...args) {
+    const opts = {
+        cwd,
+        encoding: "utf8",
+        env: {
+            ...process.env,
+            GIT_AUTHOR_NAME: "Test User",
+            GIT_AUTHOR_EMAIL: "test@example.com",
+            GIT_COMMITTER_NAME: "Test User",
+            GIT_COMMITTER_EMAIL: "test@example.com",
+            GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z",
+            GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z",
+        },
+    };
+    return execFileSync("git", args, opts);
+}
+/** Initialize a basic git repo with test config. */
+export function makeRepo(prefix = "mcp-test-repo-") {
+    const dir = mkTmpDir(prefix);
+    gitCmd(dir, "init", "-b", "main");
+    writeTestGitConfig(dir);
+    return dir;
+}
+/** Initialize a repo with a seed commit (useful for branch/cherry-pick tests). */
+export function makeRepoWithSeed(prefix = "mcp-test-repo-") {
+    const dir = makeRepo(prefix);
+    writeFileSync(join(dir, "seed.txt"), "seed\n");
+    gitCmd(dir, "add", "seed.txt");
+    gitCmd(dir, "commit", "-m", "chore: seed");
+    return dir;
+}
+/** Initialize work repo + bare remote with tracking set up. */
+export function makeRepoWithUpstream(workPrefix = "mcp-work-", remotePrefix = "mcp-remote-") {
+    const remote = mkTmpDir(remotePrefix);
+    gitCmd(remote, "init", "--bare", "-b", "main");
+    const work = makeRepoWithSeed(workPrefix);
+    gitCmd(work, "remote", "add", "origin", remote);
+    gitCmd(work, "push", "-u", "origin", "main");
+    return { work, remote };
+}
+/** Initialize a git repo with main branch and test config. */
+export function gitInitMain(dir) {
+    gitCmd(dir, "init", "-b", "main");
+    writeTestGitConfig(dir);
+}
+/** Add a commit to a repo with specified file content. */
+export function addCommit(dir, file, content, message) {
+    writeFileSync(join(dir, file), content);
+    gitCmd(dir, "add", file);
+    gitCmd(dir, "commit", "-m", message);
+}

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

@@ -2,13 +2,18 @@ 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 = [
@@ -19,18 +24,27 @@ export const READ_ONLY_ABSOLUTE_ROOT_TOOLS = [
     "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,
-    "git_worktree_list",
+    ...READ_ONLY_SINGLE_REPO_TOOLS,
     ...MUTATING_TOOLS,
 ];
 function captureParameterTools(register) {
@@ -52,14 +66,20 @@ export function captureToolParameterSchemas() {
         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)]));
 }

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.