@rethunk/mcp-multi-root-git 1.0.0

package/dist/server/presets.js

@@ -0,0 +1,175 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+/**
+ * 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`.
+ */
+const PresetEntrySchema = z.object({
+    nestedRoots: z.array(z.string()).optional(),
+    parityPairs: z
+        .array(z.object({
+        left: z.string(),
+        right: z.string(),
+        label: z.string().optional(),
+    }))
+        .optional(),
+    /** When multiple MCP file roots exist, prefer one whose path basename or suffix matches this hint. */
+    workspaceRootHint: z.string().optional(),
+});
+const PresetFileSchema = z.record(z.string(), PresetEntrySchema);
+export const PRESET_FILE_PATH = ".rethunk/git-mcp-presets.json";
+/**
+ * Supports:
+ * - Wrapped: `{ "schemaVersion": "1", "presets": { "name": { ... } } }`
+ * - Legacy: `{ "name": { ... }, ... }` with optional top-level `schemaVersion` / `$schema` (editor hints).
+ */
+export function splitPresetFileRaw(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error("invalid_root");
+    }
+    const o = raw;
+    if ("presets" in o &&
+        o.presets !== null &&
+        typeof o.presets === "object" &&
+        !Array.isArray(o.presets)) {
+        const sv = o.schemaVersion;
+        return {
+            mapRaw: o.presets,
+            schemaVersion: typeof sv === "string" ? sv : undefined,
+        };
+    }
+    const rest = { ...o };
+    const sv = rest.schemaVersion;
+    delete rest.schemaVersion;
+    delete rest.$schema;
+    return {
+        mapRaw: rest,
+        schemaVersion: typeof sv === "string" ? sv : undefined,
+    };
+}
+export function loadPresetsFromGitTop(gitTop) {
+    const presetPath = join(gitTop, PRESET_FILE_PATH);
+    if (!existsSync(presetPath)) {
+        return { ok: false, reason: "missing" };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(presetPath, "utf8"));
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        return { ok: false, reason: "invalid_json", message };
+    }
+    let mapRaw;
+    let schemaVersion;
+    try {
+        const s = splitPresetFileRaw(raw);
+        mapRaw = s.mapRaw;
+        schemaVersion = s.schemaVersion;
+    }
+    catch {
+        return {
+            ok: false,
+            reason: "invalid_json",
+            message: "Preset file root must be a JSON object",
+        };
+    }
+    const parsed = PresetFileSchema.safeParse(mapRaw);
+    if (!parsed.success) {
+        return { ok: false, reason: "schema", issues: parsed.error.issues };
+    }
+    return { ok: true, data: parsed.data, schemaVersion };
+}
+export function presetLoadErrorPayload(gitTop, fail) {
+    const presetFile = join(gitTop, PRESET_FILE_PATH);
+    if (fail.reason === "invalid_json") {
+        return {
+            error: "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: "preset_file_invalid", presetFile };
+}
+export function getPresetEntry(gitTop, presetName) {
+    const loaded = loadPresetsFromGitTop(gitTop);
+    if (!loaded.ok) {
+        if (loaded.reason === "missing") {
+            return {
+                error: {
+                    error: "preset_not_found",
+                    preset: presetName,
+                    presetFile: join(gitTop, PRESET_FILE_PATH),
+                    message: "Preset file missing",
+                },
+            };
+        }
+        return { error: presetLoadErrorPayload(gitTop, loaded) };
+    }
+    const entry = loaded.data[presetName];
+    if (!entry) {
+        return {
+            error: {
+                error: "preset_not_found",
+                preset: presetName,
+                presetFile: join(gitTop, PRESET_FILE_PATH),
+            },
+        };
+    }
+    return { entry, presetSchemaVersion: loaded.schemaVersion };
+}
+export function mergeNestedRoots(preset, inline) {
+    const a = preset ?? [];
+    const b = inline ?? [];
+    if (a.length === 0 && b.length === 0)
+        return undefined;
+    const seen = new Set();
+    const out = [];
+    for (const x of [...a, ...b]) {
+        if (!seen.has(x)) {
+            seen.add(x);
+            out.push(x);
+        }
+    }
+    return out;
+}
+export function mergePairs(preset, inline) {
+    const a = preset ?? [];
+    const b = inline ?? [];
+    if (a.length === 0 && b.length === 0)
+        return undefined;
+    return [...a, ...b];
+}
+export function applyPresetNestedRoots(gitTop, presetName, presetMerge, inlineNestedRoots) {
+    const got = getPresetEntry(gitTop, presetName);
+    if ("error" in got)
+        return { ok: false, error: got.error };
+    const fromPreset = got.entry.nestedRoots;
+    let nestedRoots = inlineNestedRoots;
+    if (presetMerge) {
+        nestedRoots = mergeNestedRoots(fromPreset, nestedRoots);
+    }
+    else if (!nestedRoots?.length) {
+        nestedRoots = fromPreset;
+    }
+    return { ok: true, nestedRoots, presetSchemaVersion: got.presetSchemaVersion };
+}
+export function applyPresetParityPairs(gitTop, presetName, presetMerge, inlinePairs) {
+    const got = getPresetEntry(gitTop, presetName);
+    if ("error" in got)
+        return { ok: false, error: got.error };
+    const fromPreset = got.entry.parityPairs;
+    let pairs = inlinePairs;
+    if (presetMerge) {
+        pairs = mergePairs(fromPreset, pairs);
+    }
+    else if (!pairs?.length) {
+        pairs = fromPreset;
+    }
+    return { ok: true, pairs, presetSchemaVersion: got.presetSchemaVersion };
+}

package/dist/server/roots.js

@@ -0,0 +1,134 @@
+import { basename, isAbsolute, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { gateGit, gitTopLevel } from "./git.js";
+import { loadPresetsFromGitTop, presetLoadErrorPayload } from "./presets.js";
+export function uriToPath(uri) {
+    if (!uri.startsWith("file://"))
+        return null;
+    try {
+        return fileURLToPath(uri);
+    }
+    catch {
+        return null;
+    }
+}
+export 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)
+            paths.push(p);
+    }
+    return paths;
+}
+/** Basename or trailing path segment; compares using normalized slashes so Windows backslashes match. */
+export function pathMatchesWorkspaceRootHint(rootPath, hint) {
+    const h = hint.trim();
+    if (!h)
+        return true;
+    if (basename(rootPath) === h)
+        return true;
+    const absRoot = resolve(rootPath);
+    if (absRoot === h)
+        return true;
+    try {
+        if (isAbsolute(h) && resolve(h) === absRoot)
+            return true;
+    }
+    catch {
+        /* invalid absolute hint */
+    }
+    const normRoot = absRoot.replace(/\\/g, "/").replace(/\/+$/, "");
+    const normHint = h.replace(/\\/g, "/").replace(/\/+$/, "").replace(/^\/+/, "");
+    if (!normHint)
+        return true;
+    if (normRoot === normHint)
+        return true;
+    return normRoot.endsWith(`/${normHint}`);
+}
+export function resolveWorkspaceRoots(server, args) {
+    if (args.workspaceRoot?.trim()) {
+        return { ok: true, roots: [resolve(args.workspaceRoot.trim())] };
+    }
+    const fileRoots = listFileRoots(server);
+    if (args.allWorkspaceRoots) {
+        if (fileRoots.length === 0) {
+            return { ok: true, roots: [process.cwd()] };
+        }
+        return { ok: true, roots: fileRoots };
+    }
+    if (args.rootIndex != null) {
+        const r = fileRoots[args.rootIndex];
+        if (!r) {
+            return {
+                ok: false,
+                error: {
+                    error: "root_index_out_of_range",
+                    rootIndex: args.rootIndex,
+                    rootCount: fileRoots.length,
+                },
+            };
+        }
+        return { ok: true, roots: [r] };
+    }
+    const primary = fileRoots[0];
+    if (primary !== undefined) {
+        return { ok: true, roots: [primary] };
+    }
+    return { ok: true, roots: [process.cwd()] };
+}
+/**
+ * When a preset name is requested and multiple MCP roots exist, pick the first root
+ * whose git toplevel loads a preset file containing that name.
+ */
+export function resolveRootsForPreset(server, args, presetName) {
+    if (args.workspaceRoot?.trim() || args.allWorkspaceRoots || args.rootIndex != null) {
+        return resolveWorkspaceRoots(server, args);
+    }
+    const fileRoots = listFileRoots(server);
+    if (fileRoots.length <= 1) {
+        return resolveWorkspaceRoots(server, args);
+    }
+    const matches = [];
+    for (const r of fileRoots) {
+        const top = gitTopLevel(r);
+        if (!top)
+            continue;
+        const loaded = loadPresetsFromGitTop(top);
+        if (!loaded.ok && loaded.reason !== "missing") {
+            return { ok: false, error: presetLoadErrorPayload(top, loaded) };
+        }
+        if (!loaded.ok)
+            continue;
+        const entry = loaded.data[presetName];
+        if (!entry)
+            continue;
+        const hint = entry.workspaceRootHint?.trim();
+        if (hint) {
+            if (!pathMatchesWorkspaceRootHint(r, hint))
+                continue;
+        }
+        matches.push(r);
+    }
+    const pick = matches[0];
+    if (pick !== undefined) {
+        return { ok: true, roots: [pick] };
+    }
+    return resolveWorkspaceRoots(server, args);
+}
+/** `gateGit` plus workspace / preset root resolution; shared tool and resource prelude. */
+export function requireGitAndRoots(server, args, presetName) {
+    const gg = gateGit();
+    if (!gg.ok) {
+        return { ok: false, error: gg.body };
+    }
+    const rootsRes = presetName
+        ? resolveRootsForPreset(server, args, presetName)
+        : resolveWorkspaceRoots(server, args);
+    if (!rootsRes.ok) {
+        return { ok: false, error: rootsRes.error };
+    }
+    return { ok: true, roots: rootsRes.roots };
+}

package/dist/server/schemas.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { MAX_INVENTORY_ROOTS_DEFAULT } from "./inventory.js";
+const FormatSchema = z.enum(["markdown", "json"]).optional().default("markdown");
+export const WorkspacePickSchema = z.object({
+    workspaceRoot: z
+        .string()
+        .optional()
+        .describe("Override workspace path. Wins over MCP roots, rootIndex, and allWorkspaceRoots."),
+    rootIndex: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("Use the Nth file:// MCP root (0-based) when multiple workspace roots exist."),
+    allWorkspaceRoots: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Run against every file:// MCP root and aggregate results."),
+    format: FormatSchema.describe('Return "markdown" (default) or structured "json".'),
+});
+export { MAX_INVENTORY_ROOTS_DEFAULT };

package/dist/server/tools.js

@@ -0,0 +1,12 @@
+import { registerGitInventoryTool } from "./git-inventory-tool.js";
+import { registerGitParityTool } from "./git-parity-tool.js";
+import { registerGitStatusTool } from "./git-status-tool.js";
+import { registerListPresetsTool } from "./list-presets-tool.js";
+import { registerPresetsResource } from "./presets-resource.js";
+export function registerRethunkGitTools(server) {
+    registerGitStatusTool(server);
+    registerGitInventoryTool(server);
+    registerGitParityTool(server);
+    registerListPresetsTool(server);
+    registerPresetsResource(server);
+}

package/dist/server.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { FastMCP } from "fastmcp";
+import { readMcpServerVersion } from "./server/json.js";
+import { registerRethunkGitTools } from "./server/tools.js";
+const server = new FastMCP({
+    name: "rethunk-git",
+    version: readMcpServerVersion(),
+    roots: { enabled: true },
+});
+registerRethunkGitTools(server);
+void server.start({ transportType: "stdio" });

package/docs/install.md

@@ -0,0 +1,199 @@
+# Installing @rethunk/mcp-multi-root-git
+
+This package is an MCP **stdio** server. The client starts the process and passes **workspace roots** at `initialize` — **do not** set a fixed working-directory (`cwd`) in the server launch config; roots come from the client session.
+
+**See also:** [mcp-tools.md](mcp-tools.md) (tool ids, JSON, resources, workspace root *resolution*), [HUMANS.md](../HUMANS.md) (preset file, dev, CI, publishing), [AGENTS.md](../AGENTS.md) (contributors).
+
+## Table of contents
+
+- [Prerequisites](#prerequisites)
+- [GitHub Packages](#github-packages)
+- [Ways to run the binary](#ways-to-run-the-binary)
+- [Configuration shape (stdio)](#configuration-shape-stdio)
+- [Cursor](#cursor)
+- [Visual Studio Code (GitHub Copilot)](#visual-studio-code-github-copilot)
+- [Claude Desktop](#claude-desktop)
+- [Zed](#zed)
+- [Other clients and CLIs](#other-clients-and-clis)
+- [From source (this repository)](#from-source-this-repository)
+- [Troubleshooting](#troubleshooting)
+
+## Prerequisites
+
+- **Git** on `PATH` (`git --version`). The server shells out to `git`; if it is missing, tools return `git_not_found`.
+- **Node.js ≥ 22** if you use **`npx`**, or **Bun** if you use **`bunx`** / **`bun`** (see `package.json` `engines` / `packageManager`).
+
+## GitHub Packages
+
+Every **version tag** on this repo is published to the **GitHub npm registry** as **`@rethunk-ai/mcp-multi-root-git`** (scope matches the GitHub org). The **npmjs** package name **`@rethunk/mcp-multi-root-git`** is updated **manually** by maintainers and may lag; prefer GitHub Packages for CI-aligned installs.
+
+1. Create a [GitHub personal access token](https://github.com/settings/tokens) with at least **`read:packages`** (and **`repo`** if the package were private).
+2. In **`~/.npmrc`** or the project **`.npmrc`** (do not commit secrets):
+
+   ```ini
+   @rethunk-ai:registry=https://npm.pkg.github.com
+   //npm.pkg.github.com/:_authToken=YOUR_TOKEN_HERE
+   ```
+
+3. Install or run, for example:
+
+   ```bash
+   npx -y @rethunk-ai/mcp-multi-root-git
+   ```
+
+   Or **`bunx @rethunk-ai/mcp-multi-root-git`** with the same registry configuration for that scope.
+
+**`$schema` in preset JSON:** point at the copy under **`node_modules/@rethunk-ai/mcp-multi-root-git/git-mcp-presets.schema.json`** when you install from GitHub Packages; use **`@rethunk/mcp-multi-root-git/...`** when installing from npmjs.
+
+## Ways to run the binary
+
+Use any of these from a terminal to confirm the package runs (each starts the stdio server until EOF). **npmjs** name:
+
+```bash
+npx -y @rethunk/mcp-multi-root-git
+bunx @rethunk/mcp-multi-root-git
+npm install -g @rethunk/mcp-multi-root-git && mcp-multi-root-git
+```
+
+**GitHub Packages** name (after configuring **`.npmrc`** as in [GitHub Packages](#github-packages)):
+
+```bash
+npx -y @rethunk-ai/mcp-multi-root-git
+bunx @rethunk-ai/mcp-multi-root-git
+```
+
+Published entrypoint: **`dist/server.js`** (see `bin` / `exports`). Clients typically invoke **`npx`** or **`bunx`** so a global install is optional.
+
+## Configuration shape (stdio)
+
+Across clients you always provide:
+
+- A **command** (e.g. `npx`, `bunx`, `bun`, `node`).
+- **Arguments** that resolve to this package’s server (e.g. `["-y", "@rethunk/mcp-multi-root-git"]` for `npx`).
+
+Register the server under a stable name (this documentation uses **`rethunk-git`**). Tools appear as `{serverName}_{toolName}` (e.g. `rethunk-git_git_status`).
+
+**Bun instead of npx**
+
+```json
+{
+  "command": "bunx",
+  "args": ["@rethunk/mcp-multi-root-git"]
+}
+```
+
+**No `cwd`**
+
+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.
+
+## 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).
+
+Cursor uses a top-level **`mcpServers`** object:
+
+```json
+{
+  "mcpServers": {
+    "rethunk-git": {
+      "command": "npx",
+      "args": ["-y", "@rethunk/mcp-multi-root-git"]
+    }
+  }
+}
+```
+
+After editing, reload MCP (Command Palette: reload / restart MCP). If tools are missing, ensure **`npx`** or **`bun`** is on `PATH`.
+
+## Visual Studio Code (GitHub Copilot)
+
+MCP config lives in **`mcp.json`**: either **`.vscode/mcp.json`** in the workspace or the **user** MCP file (Command Palette: **MCP: Open User Configuration**). See the official [MCP configuration reference](https://code.visualstudio.com/docs/copilot/reference/mcp-configuration).
+
+VS Code expects a **`servers`** object. For a stdio server set **`type`** to **`stdio`**, then **`command`** / **`args`**:
+
+```json
+{
+  "servers": {
+    "rethunk-git": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@rethunk/mcp-multi-root-git"]
+    }
+  }
+}
+```
+
+Use **MCP: List Servers** / **MCP: Reset Cached Tools** if tools do not update after a package upgrade.
+
+## Claude Desktop
+
+Config file (create if missing):
+
+| OS | Path |
+|----|------|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Linux | `~/.config/Claude/claude_desktop_config.json` |
+
+Top-level key **`mcpServers`** (stdio by default):
+
+```json
+{
+  "mcpServers": {
+    "rethunk-git": {
+      "command": "npx",
+      "args": ["-y", "@rethunk/mcp-multi-root-git"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving; invalid JSON often fails silently.
+
+## Zed
+
+Configure **context servers** in Zed **`settings.json`** (e.g. `~/.config/zed/settings.json` on macOS/Linux). See [Model Context Protocol in Zed](https://zed.dev/docs/ai/mcp.html).
+
+```json
+{
+  "context_servers": {
+    "rethunk-git": {
+      "command": "npx",
+      "args": ["-y", "@rethunk/mcp-multi-root-git"]
+    }
+  }
+}
+```
+
+Use the Agent Panel server status indicator to confirm the server is active.
+
+## Other clients and CLIs
+
+Any MCP host that supports **stdio** and workspace roots can use the same **`command` / `args`** as above. Examples include other editors, team-internal launchers, and **Claude Code**-style environments — follow that product’s MCP docs and map:
+
+- **Command:** `npx` (or `bunx`, `node`, etc.)
+- **Args:** e.g. `["-y", "@rethunk/mcp-multi-root-git"]` for `npx`
+
+Official protocol overview: [modelcontextprotocol.io](https://modelcontextprotocol.io/).
+
+## From source (this repository)
+
+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.
+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.
+
+**Reload** the MCP connection after changing server code.
+
+## Troubleshooting
+
+| Issue | What to try |
+|-------|-------------|
+| `git_not_found` | Install Git and ensure it is on `PATH` in the environment that launches the MCP server. |
+| Tools missing / stale | Restart the MCP host or use its “reload MCP / reset tools” action; in VS Code try **MCP: Reset Cached Tools**. |
+| `npx` / `bun` not found | Install Node ≥ 22 or Bun; use full paths to the executable in config if `PATH` is minimal. |
+| Wrong repo / root | Ensure the client opened the intended workspace so MCP **file roots** match your git work trees; see [mcp-tools.md](mcp-tools.md) — *Workspace root resolution*. |

package/docs/mcp-tools.md

@@ -0,0 +1,51 @@
+# MCP tools and resources (canonical reference)
+
+Single source of truth for **registered tool ids**, **client naming**, **JSON output shape**, **resource URI**, and **workspace root resolution**.  
+**Install and MCP clients (only canonical location):** [install.md](install.md). **Preset file, dev, CI, publishing:** [HUMANS.md](../HUMANS.md). **Implementation layout (`src/server/` + entry [`server.ts`](../src/server.ts)), contract bumps:** [AGENTS.md](../AGENTS.md).
+
+## Naming
+
+MCP clients expose tools as `{serverName}_{toolName}`. With the server registered as **`rethunk-git`**, examples use the prefix **`rethunk-git_`**.
+
+## Tools
+
+| 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`. |
+| `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. |
+| `git_parity` | `rethunk-git_git_parity` | Compare `git rev-parse HEAD` for path pairs. `pairs`, `preset`, `presetMerge`, `format`, plus workspace pick args. |
+| `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. |
+
+Pass **`format: "json"`** on any tool for structured JSON instead of markdown (default).
+
+## JSON responses
+
+Every JSON string returned by a tool (including errors) ends with a **`rethunkGitMcp`** object:
+
+- **`jsonFormatVersion`**: `"1"` for the current response shape.
+- **`packageVersion`**: from the running server’s `package.json`.
+
+Payload keys (e.g. `groups`, `inventories`, `parity`, `roots`) are stable within a given `jsonFormatVersion`. Preset-related responses may include **`presetSchemaVersion`**.
+
+For **`git_inventory`** with `format: "json"`, each object inside **`inventories`** may include **`nestedRootsTruncated`** (boolean) and **`nestedRootsOmittedCount`** (number) when **`nestedRoots`** was longer than **`maxRoots`**.
+
+**When to bump `jsonFormatVersion` or change payload shape:** [AGENTS.md](../AGENTS.md) — *Changing contracts*.
+
+## Resource
+
+| URI | Purpose |
+|-----|---------|
+| `rethunk-git://presets` | JSON snapshot of `.rethunk/git-mcp-presets.json` at the resolved git toplevel (or structured errors; same `rethunkGitMcp` envelope pattern as tools). |
+
+## Workspace root resolution
+
+Order applied when resolving which directory(ies) tools run against:
+
+1. Explicit **`workspaceRoot`** on the tool call (highest priority).
+2. **`rootIndex`** (0-based) — one `file://` MCP root when several exist.
+3. **`allWorkspaceRoots`: true** — every `file://` root; markdown sections separated by `---`, or combined JSON.
+4. **`preset`** set and multiple roots — first root whose git toplevel defines that preset (respecting **`workspaceRootHint`** on the preset entry when present).
+5. Otherwise the first `file://` root from MCP **`initialize`** / **`roots/list_changed`**.
+6. **`process.cwd()`** if no file roots (e.g. CI with explicit `workspaceRoot`).
+
+Roots come from the MCP session (**`FastMCP` with `roots: { enabled: true }`** in code); there is no fixed `cwd` in server config.

package/git-mcp-presets.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/Rethunk-AI/mcp-multi-root-git/main/git-mcp-presets.schema.json",
+  "title": "rethunk-git MCP preset file",
+  "description": "Schema for .rethunk/git-mcp-presets.json (at the git repository root). Supports a wrapped layout with an explicit presets object, or a legacy flat map of preset name to entry.",
+  "oneOf": [
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "$schema": {
+          "type": "string",
+          "description": "JSON Schema $schema pointer for editor validation."
+        },
+        "schemaVersion": {
+          "type": "string",
+          "const": "1",
+          "description": "File format version; use 1 for this schema."
+        },
+        "presets": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/$defs/presetEntry"
+          },
+          "description": "Named preset entries for git_inventory / git_parity."
+        }
+      },
+      "required": ["presets"]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "$schema": {
+          "type": "string"
+        },
+        "schemaVersion": {
+          "type": "string",
+          "const": "1",
+          "description": "Optional file format version when using the flat preset map."
+        }
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/presetEntry"
+      },
+      "minProperties": 1
+    }
+  ],
+  "$defs": {
+    "presetEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "nestedRoots": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Paths relative to the git toplevel, in order, for git_inventory."
+        },
+        "parityPairs": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "left": { "type": "string" },
+              "right": { "type": "string" },
+              "label": { "type": "string" }
+            },
+            "required": ["left", "right"]
+          },
+          "description": "Path pairs for git_parity (paths relative to git toplevel unless absolute)."
+        },
+        "workspaceRootHint": {
+          "type": "string",
+          "description": "When multiple MCP file roots exist, restrict preset resolution to a root matching this basename or path suffix."
+        }
+      }
+    }
+  }
+}