@rethunk/mcp-multi-root-git 2.5.0 → 2.8.0

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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ERROR_CODES } from "./error-codes.js";
 import { spawnGitAsync } from "./git.js";
 import { jsonRespond, spreadDefined } from "./json.js";
 import { requireSingleRepo } from "./roots.js";
@@ -30,7 +31,7 @@ export function registerGitStashListTool(server) {
                 // If there are no stashes, git still returns ok=true with empty output
                 // Only treat as error if git itself failed
                 return jsonRespond({
-                    error: "stash_list_failed",
+                    error: ERROR_CODES.STASH_LIST_FAILED,
                     detail: (r.stderr || r.stdout).trim(),
                 });
             }
@@ -39,21 +40,22 @@ export function registerGitStashListTool(server) {
                 .split("\n")
                 .map((l) => l.trim())
                 .filter((l) => l.length > 0);
-            for (let i = 0; i < lines.length; i++) {
-                const line = lines[i];
-                if (line) {
-                    const parts = line.split("|");
-                    // parts[0] = stash@{N}, last part = short SHA, middle = message (may contain "|")
-                    const sha = parts[parts.length - 1];
-                    const message = parts.slice(1, -1).join("|");
-                    if (parts.length >= 3 && message && sha) {
-                        stashes.push({
-                            index: i,
-                            message,
-                            sha,
-                        });
-                    }
+            for (const line of lines) {
+                const parts = line.split("|");
+                // parts[0] = stash@{N}, last part = short SHA, middle = message (may contain "|")
+                const sha = parts[parts.length - 1];
+                const message = parts.slice(1, -1).join("|");
+                // Parse the real stash index from the canonical stash@{N} ref in parts[0].
+                const indexMatch = parts[0] ? /stash@\{(\d+)\}/.exec(parts[0]) : null;
+                if (!indexMatch || parts.length < 3 || !message || !sha) {
+                    // Malformed line — skip without affecting index tracking.
+                    continue;
                 }
+                stashes.push({
+                    index: Number(indexMatch[1]),
+                    message,
+                    sha,
+                });
             }
             if (args.format === "json") {
                 return jsonRespond({ stashes });

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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ERROR_CODES } from "./error-codes.js";
 import { isSafeGitUpstreamToken, spawnGitAsync } from "./git.js";
 import { jsonRespond } from "./json.js";
 import { requireSingleRepo } from "./roots.js";
@@ -72,18 +73,18 @@ export function registerGitTagTool(server) {
             const gitTop = pre.gitTop;
             const tag = args.tag.trim();
             if (!tag) {
-                return jsonRespond({ error: "tag_empty" });
+                return jsonRespond({ error: ERROR_CODES.EMPTY_TAG_NAME });
             }
             // Validate tag name: no shell metacharacters
             if (!isSafeGitUpstreamToken(tag)) {
-                return jsonRespond({ error: "tag_unsafe", tag });
+                return jsonRespond({ error: ERROR_CODES.UNSAFE_TAG_TOKEN, tag });
             }
             // Handle deletion
             if (args.delete === true) {
                 const delResult = await spawnGitAsync(gitTop, ["tag", "-d", tag]);
                 if (!delResult.ok) {
                     return jsonRespond({
-                        error: "tag_delete_failed",
+                        error: ERROR_CODES.TAG_DELETE_FAILED,
                         detail: (delResult.stderr || delResult.stdout).trim(),
                     });
                 }
@@ -99,13 +100,13 @@ export function registerGitTagTool(server) {
             // Determine the ref to tag (default HEAD)
             const ref = (args.ref ?? "HEAD").trim();
             if (!isSafeGitUpstreamToken(ref)) {
-                return jsonRespond({ error: "ref_unsafe", ref });
+                return jsonRespond({ error: ERROR_CODES.UNSAFE_REF_TOKEN, ref });
             }
             // Get the SHA of the ref to tag
             const sha = await getRefSha(gitTop, ref);
             if (!sha) {
                 return jsonRespond({
-                    error: "ref_not_found",
+                    error: ERROR_CODES.REF_NOT_FOUND,
                     ref,
                 });
             }
@@ -122,7 +123,7 @@ export function registerGitTagTool(server) {
             const createResult = await spawnGitAsync(gitTop, tagArgs);
             if (!createResult.ok) {
                 return jsonRespond({
-                    error: "tag_create_failed",
+                    error: ERROR_CODES.TAG_CREATE_FAILED,
                     detail: (createResult.stderr || createResult.stdout).trim(),
                 });
             }
@@ -130,7 +131,7 @@ export function registerGitTagTool(server) {
             const tagType = await getTagType(gitTop, tag);
             if (!tagType) {
                 return jsonRespond({
-                    error: "tag_verification_failed",
+                    error: ERROR_CODES.TAG_VERIFICATION_FAILED,
                     tag,
                 });
             }

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

@@ -1,5 +1,6 @@
 import { resolve } from "node:path";
 import { z } from "zod";
+import { ERROR_CODES } from "./error-codes.js";
 import { spawnGitAsync } from "./git.js";
 import { isProtectedBranch, isSafeGitRefToken, listWorktrees, } from "./git-refs.js";
 import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
@@ -76,13 +77,13 @@ export function registerGitWorktreeAddTool(server) {
             const { gitTop } = pre;
             // Validate branch
             if (!isSafeGitRefToken(args.branch)) {
-                return jsonRespond({ error: "unsafe_ref_token", ref: args.branch });
+                return jsonRespond({ error: ERROR_CODES.UNSAFE_REF_TOKEN, ref: args.branch });
             }
             if (isProtectedBranch(args.branch)) {
-                return jsonRespond({ error: "protected_branch", branch: args.branch });
+                return jsonRespond({ error: ERROR_CODES.PROTECTED_BRANCH, branch: args.branch });
             }
             if (args.baseRef !== undefined && !isSafeGitRefToken(args.baseRef)) {
-                return jsonRespond({ error: "unsafe_ref_token", ref: args.baseRef });
+                return jsonRespond({ error: ERROR_CODES.UNSAFE_REF_TOKEN, ref: args.baseRef });
             }
             // Resolve path
             const wtPath = resolve(gitTop, args.path);
@@ -107,7 +108,7 @@ export function registerGitWorktreeAddTool(server) {
             if (!r.ok) {
                 return jsonRespond({
                     ok: false,
-                    error: "worktree_add_failed",
+                    error: ERROR_CODES.WORKTREE_ADD_FAILED,
                     detail: (r.stderr || r.stdout).trim(),
                 });
             }
@@ -158,13 +159,13 @@ export function registerGitWorktreeRemoveTool(server) {
             // Refuse to remove the main worktree
             const wtPath = resolve(gitTop, args.path);
             if (wtPath === gitTop) {
-                return jsonRespond({ error: "cannot_remove_main_worktree", path: wtPath });
+                return jsonRespond({ error: ERROR_CODES.CANNOT_REMOVE_MAIN_WORKTREE, path: wtPath });
             }
             // Verify it exists in the worktree list
             const trees = await listWorktrees(gitTop);
             const isRegistered = trees.some((t) => t.path === wtPath || t.path === args.path);
             if (!isRegistered) {
-                return jsonRespond({ error: "worktree_not_found", path: args.path });
+                return jsonRespond({ error: ERROR_CODES.WORKTREE_NOT_FOUND, path: args.path });
             }
             const removeArgs = ["worktree", "remove", wtPath];
             if (args.force)
@@ -173,7 +174,7 @@ export function registerGitWorktreeRemoveTool(server) {
             if (!r.ok) {
                 return jsonRespond({
                     ok: false,
-                    error: "worktree_remove_failed",
+                    error: ERROR_CODES.WORKTREE_REMOVE_FAILED,
                     detail: (r.stderr || r.stdout).trim(),
                     ...spreadWhen((r.stderr || r.stdout).includes("contains modified") ||
                         (r.stderr || r.stdout).includes("is not empty"), { hint: "Pass force: true to remove a worktree with uncommitted changes." }),

package/dist/server/git.js

@@ -2,6 +2,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { existsSync, lstatSync, readFileSync } from "node:fs";
 import { cpus } from "node:os";
 import { join } from "node:path";
+import { ERROR_CODES } from "./error-codes.js";
 /**
  * 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].
@@ -19,9 +20,28 @@ function resolveGitSubprocessParallelism() {
     return 4;
 }
 export const GIT_SUBPROCESS_PARALLELISM = resolveGitSubprocessParallelism();
+/**
+ * Default timeout for git subprocesses spawned by spawnGitAsync.
+ * Reads from GIT_SUBPROCESS_TIMEOUT_MS env var (default 120000 ms = 2 min).
+ * A value of 0 (or negative/NaN) disables the timeout — use for operations
+ * like large clones where unbounded wait is intentional.
+ */
+function resolveGitSubprocessTimeoutMs() {
+    const env = process.env.GIT_SUBPROCESS_TIMEOUT_MS;
+    if (env) {
+        const n = Number.parseInt(env, 10);
+        if (!Number.isNaN(n) && n > 0)
+            return n;
+        // 0 or negative → disabled
+        if (!Number.isNaN(n))
+            return 0;
+    }
+    return 120_000;
+}
+export const GIT_SUBPROCESS_TIMEOUT_MS = resolveGitSubprocessTimeoutMs();
 let gitPathState = "unknown";
 const GIT_NOT_FOUND_BODY = {
-    error: "git_not_found",
+    error: ERROR_CODES.GIT_NOT_FOUND,
 };
 export function gateGit() {
     if (gitPathState === "ok") {
@@ -94,10 +114,23 @@ export function parseGitSubmodulePaths(gitRoot) {
         return [];
     }
     const paths = [];
-    for (const line of text.split("\n")) {
-        const m = /^\s*path\s*=\s*(.+)\s*$/.exec(line);
+    let inSubmoduleSection = false;
+    for (const rawLine of text.split("\n")) {
+        // Strip inline and whole-line comments (; and #)
+        const commentIdx = rawLine.search(/\s*[;#]/);
+        const line = commentIdx >= 0 ? rawLine.slice(0, commentIdx) : rawLine;
+        // Track INI section header
+        const sectionMatch = /^\s*\[(.+)\]\s*$/.exec(line);
+        if (sectionMatch) {
+            inSubmoduleSection = /^submodule\s+"/.test(sectionMatch[1] ?? "");
+            continue;
+        }
+        // Only collect path = lines inside a [submodule "..."] section
+        if (!inSubmoduleSection)
+            continue;
+        const m = /^\s*path\s*=\s*(.+?)\s*$/.exec(line);
         if (m?.[1])
-            paths.push(m[1].trim());
+            paths.push(m[1]);
     }
     return paths;
 }
@@ -134,11 +167,12 @@ export async function asyncPool(items, concurrency, fn) {
     await Promise.all(Array.from({ length: n }, () => worker()));
     return results;
 }
-export function spawnGitAsync(cwd, args) {
+export function spawnGitAsync(cwd, args, opts) {
     return new Promise((resolveP) => {
         const child = spawn("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
         let stdout = "";
         let stderr = "";
+        let settled = false;
         child.stdout?.setEncoding("utf8");
         child.stderr?.setEncoding("utf8");
         child.stdout?.on("data", (c) => {
@@ -147,8 +181,53 @@ export function spawnGitAsync(cwd, args) {
         child.stderr?.on("data", (c) => {
             stderr += c;
         });
-        child.on("error", () => resolveP({ ok: false, stdout, stderr }));
-        child.on("close", (code) => resolveP({ ok: code === 0, stdout, stderr }));
+        const effectiveTimeout = opts?.timeoutMs ?? GIT_SUBPROCESS_TIMEOUT_MS;
+        let timer;
+        let abortListener;
+        function cleanup() {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            if (abortListener !== undefined && opts?.signal) {
+                opts.signal.removeEventListener("abort", abortListener);
+                abortListener = undefined;
+            }
+        }
+        function settle(result) {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolveP(result);
+        }
+        // AbortSignal: kill immediately if already aborted, else listen
+        if (opts?.signal) {
+            if (opts.signal.aborted) {
+                child.kill("SIGTERM");
+                settle({ ok: false, stdout, stderr, aborted: true });
+                return;
+            }
+            abortListener = () => {
+                child.kill("SIGTERM");
+                settle({ ok: false, stdout, stderr, aborted: true });
+            };
+            opts.signal.addEventListener("abort", abortListener, { once: true });
+        }
+        // Timeout: set timer if effectiveTimeout > 0
+        if (effectiveTimeout > 0) {
+            timer = setTimeout(() => {
+                child.kill("SIGTERM");
+                settle({
+                    ok: false,
+                    stdout,
+                    stderr: `${stderr}\n<git timed out after ${effectiveTimeout}ms>`,
+                    timedOut: true,
+                });
+            }, effectiveTimeout);
+        }
+        child.on("error", () => settle({ ok: false, stdout, stderr }));
+        child.on("close", (code) => settle({ ok: code === 0, stdout, stderr }));
     });
 }
 function gitStatusFailText(r) {

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

@@ -1,4 +1,5 @@
 import { join } from "node:path";
+import { ERROR_CODES } from "./error-codes.js";
 import { gitTopLevel } from "./git.js";
 import { jsonRespond, spreadDefined } from "./json.js";
 import { loadPresetsFromGitTop, PRESET_FILE_PATH, presetLoadErrorPayload } from "./presets.js";
@@ -34,7 +35,7 @@ export function registerListPresetsTool(server) {
                         presetFile,
                         fileExists: false,
                         presets: [],
-                        error: { error: "not_a_git_repository", path: ws },
+                        error: { error: ERROR_CODES.NOT_A_GIT_REPOSITORY, path: ws },
                     });
                     continue;
                 }

package/dist/server/presets-resource.js

@@ -1,4 +1,5 @@
 import { join } from "node:path";
+import { ERROR_CODES } from "./error-codes.js";
 import { gitTopLevel } from "./git.js";
 import { jsonRespond, spreadDefined } from "./json.js";
 import { loadPresetsFromGitTop, PRESET_FILE_PATH, presetLoadErrorPayload } from "./presets.js";
@@ -15,11 +16,11 @@ export function registerPresetsResource(server) {
             }
             const ws = pre.roots[0];
             if (!ws) {
-                return { text: jsonRespond({ error: "no_workspace_root" }) };
+                return { text: jsonRespond({ error: ERROR_CODES.NO_WORKSPACE_ROOT }) };
             }
             const top = gitTopLevel(ws);
             if (!top) {
-                return { text: jsonRespond({ error: "not_a_git_repository", path: ws }) };
+                return { text: jsonRespond({ error: ERROR_CODES.NOT_A_GIT_REPOSITORY, path: ws }) };
             }
             const loaded = loadPresetsFromGitTop(top);
             if (!loaded.ok) {

package/dist/server/presets.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
+import { ERROR_CODES } from "./error-codes.js";
 /**
  * Schema for `.rethunk/git-mcp-presets.json` at the workspace root.
  * Each named entry defines roots for `git_inventory` and/or pairs for `git_parity`.
@@ -85,16 +86,21 @@ export function presetLoadErrorPayload(gitTop, fail) {
     const presetFile = join(gitTop, PRESET_FILE_PATH);
     if (fail.reason === "invalid_json") {
         return {
-            error: "preset_file_invalid",
+            error: ERROR_CODES.PRESET_FILE_INVALID,
             kind: "invalid_json",
             presetFile,
             message: fail.message,
         };
     }
     if (fail.reason === "schema") {
-        return { error: "preset_file_invalid", kind: "schema", presetFile, issues: fail.issues };
+        return {
+            error: ERROR_CODES.PRESET_FILE_INVALID,
+            kind: "schema",
+            presetFile,
+            issues: fail.issues,
+        };
     }
-    return { error: "preset_file_invalid", presetFile };
+    return { error: ERROR_CODES.PRESET_FILE_INVALID, presetFile };
 }
 function getPresetEntry(gitTop, presetName) {
     const loaded = loadPresetsFromGitTop(gitTop);
@@ -103,7 +109,7 @@ function getPresetEntry(gitTop, presetName) {
             return {
                 ok: false,
                 error: {
-                    error: "preset_not_found",
+                    error: ERROR_CODES.PRESET_NOT_FOUND,
                     preset: presetName,
                     presetFile: join(gitTop, PRESET_FILE_PATH),
                 },
@@ -116,7 +122,7 @@ function getPresetEntry(gitTop, presetName) {
         return {
             ok: false,
             error: {
-                error: "preset_not_found",
+                error: ERROR_CODES.PRESET_NOT_FOUND,
                 preset: presetName,
                 presetFile: join(gitTop, PRESET_FILE_PATH),
             },

package/dist/server/roots.js

@@ -1,5 +1,6 @@
 import { basename, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { ERROR_CODES } from "./error-codes.js";
 import { gateGit, gitTopLevel } from "./git.js";
 import { loadPresetsFromGitTop, presetLoadErrorPayload } from "./presets.js";
 import { MAX_ABSOLUTE_GIT_ROOTS } from "./schemas.js";
@@ -61,7 +62,7 @@ export function resolveAbsoluteGitRootsList(raw) {
         return {
             ok: false,
             error: {
-                error: "absolute_git_roots_too_many",
+                error: ERROR_CODES.ABSOLUTE_GIT_ROOTS_TOO_MANY,
                 max: MAX_ABSOLUTE_GIT_ROOTS,
                 count: raw.length,
             },
@@ -72,12 +73,12 @@ export function resolveAbsoluteGitRootsList(raw) {
     for (const item of raw) {
         const trimmed = item.trim();
         if (trimmed.length === 0) {
-            return { ok: false, error: { error: "invalid_absolute_git_root", path: item } };
+            return { ok: false, error: { error: ERROR_CODES.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 } };
+            return { ok: false, error: { error: ERROR_CODES.INVALID_ABSOLUTE_GIT_ROOT, path: abs } };
         }
         if (seen.has(top))
             continue;
@@ -85,7 +86,7 @@ export function resolveAbsoluteGitRootsList(raw) {
         tops.push(top);
     }
     if (tops.length === 0) {
-        return { ok: false, error: { error: "absolute_git_roots_empty" } };
+        return { ok: false, error: { error: ERROR_CODES.ABSOLUTE_GIT_ROOTS_EMPTY } };
     }
     return { ok: true, roots: tops };
 }
@@ -104,7 +105,7 @@ function resolveWorkspaceRoots(server, args) {
             return {
                 ok: false,
                 error: {
-                    error: "root_index_out_of_range",
+                    error: ERROR_CODES.ROOT_INDEX_OUT_OF_RANGE,
                     rootIndex: args.rootIndex,
                     rootCount: fileRoots.length,
                 },
@@ -163,10 +164,10 @@ export function requireGitAndRoots(server, args, presetName) {
     const abs = args.absoluteGitRoots;
     if (abs != null && abs.length > 0) {
         if (presetName) {
-            return { ok: false, error: { error: "absolute_git_roots_preset_conflict" } };
+            return { ok: false, error: { error: ERROR_CODES.ABSOLUTE_GIT_ROOTS_PRESET_CONFLICT } };
         }
         if (hasExclusiveWorkspacePick(args)) {
-            return { ok: false, error: { error: "absolute_git_roots_exclusive" } };
+            return { ok: false, error: { error: ERROR_CODES.ABSOLUTE_GIT_ROOTS_EXCLUSIVE } };
         }
         return resolveAbsoluteGitRootsList(abs);
     }
@@ -191,16 +192,16 @@ export function requireSingleRepo(server, args, presetName = undefined) {
         return {
             ok: false,
             error: {
-                error: "absolute_git_roots_single_repo_only",
+                error: ERROR_CODES.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" } };
+        return { ok: false, error: { error: ERROR_CODES.NO_WORKSPACE_ROOT } };
     const top = gitTopLevel(rootInput);
     if (!top)
-        return { ok: false, error: { error: "not_a_git_repository", path: rootInput } };
+        return { ok: false, error: { error: ERROR_CODES.NOT_A_GIT_REPOSITORY, path: rootInput } };
     return { ok: true, gitTop: top };
 }

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

@@ -1,5 +1,7 @@
 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";
@@ -9,6 +11,7 @@ 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";
@@ -29,6 +32,9 @@ export const READ_ONLY_SINGLE_REPO_TOOLS = [
     "git_show",
     "git_worktree_list",
     "git_stash_list",
+    "git_blame",
+    "git_branch_list",
+    "git_reflog",
 ];
 export const MUTATING_TOOLS = [
     "git_fetch",
@@ -71,6 +77,9 @@ export function captureToolParameterSchemas() {
         registerGitWorktreeListTool(server);
         registerGitStashListTool(server);
         registerGitFetchTool(server);
+        registerGitBlameTool(server);
+        registerGitBranchListTool(server);
+        registerGitReflogTool(server);
         registerBatchCommitTool(server);
         registerGitPushTool(server);
         registerGitMergeTool(server);

package/dist/server/tools.js

@@ -1,4 +1,6 @@
 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";
@@ -8,6 +10,7 @@ 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";
@@ -29,6 +32,9 @@ export function registerRethunkGitTools(server) {
     registerGitWorktreeListTool(server);
     registerGitStashListTool(server);
     registerGitFetchTool(server);
+    registerGitBlameTool(server);
+    registerGitBranchListTool(server);
+    registerGitReflogTool(server);
     // Mutating tools
     registerBatchCommitTool(server);
     registerGitPushTool(server);

package/dist/server.js

@@ -2,9 +2,16 @@
 import { FastMCP } from "fastmcp";
 import { readMcpServerVersion } from "./server/json.js";
 import { registerRethunkGitTools } from "./server/tools.js";
+/**
+ * JSON payload contract version. Bump on incompatible JSON output changes
+ * (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 = "3";
 const server = new FastMCP({
     name: "rethunk-git",
     version: readMcpServerVersion(),
+    instructions: `rethunk-git MCP server. JSON payload contract: format version ${MCP_JSON_FORMAT_VERSION} (minified, no envelope; optional fields omitted when empty/null/false).`,
     roots: { enabled: true },
 });
 registerRethunkGitTools(server);