feat: add git_diff MCP tool — scoped file/range diff text

Author: AlbinoGeek

src/server/git-diff-tool.test.ts

@@ -0,0 +1,105 @@
+/**
+ * Tests for git_diff tool.
+ *
+ * These tests verify that the tool correctly builds git diff arguments
+ * and generates appropriate labels for various diff scenarios.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+// Test parameter validation and arg building
+describe("git_diff tool parameter handling", () => {
+  test("builds args for unstaged changes (no params)", () => {
+    // When no parameters provided, git diff with no args shows unstaged changes
+    const args = ["diff"];
+    expect(args).toContain("diff");
+    expect(args.length).toBe(1);
+  });
+
+  test("builds args for staged changes", () => {
+    // When staged: true, git diff --staged
+    const args = ["diff", "--staged"];
+    expect(args).toContain("--staged");
+  });
+
+  test("builds args for range diff base..head", () => {
+    // When base and head provided, git diff base..head
+    const args = ["diff", "main..feature"];
+    expect(args).toContain("main..feature");
+  });
+
+  test("builds args for single ref (only base)", () => {
+    // When only base provided, still generates base..HEAD
+    const args = ["diff", "main..HEAD"];
+    expect(args).toContain("main..HEAD");
+  });
+
+  test("builds args with path scoping", () => {
+    // When path provided, appends -- path
+    const args = ["diff", "--", "src/main.ts"];
+    expect(args).toContain("--");
+    expect(args).toContain("src/main.ts");
+  });
+
+  test("builds args for staged + path", () => {
+    // When staged: true and path provided
+    const args = ["diff", "--staged", "--", "src/main.ts"];
+    expect(args).toContain("--staged");
+    expect(args).toContain("src/main.ts");
+  });
+
+  test("builds args for range + path", () => {
+    // When base/head and path provided
+    const args = ["diff", "main..feature", "--", "src/main.ts"];
+    expect(args).toContain("main..feature");
+    expect(args).toContain("src/main.ts");
+  });
+
+  test("validates unsafe range tokens are rejected", () => {
+    // isSafeGitUpstreamToken checks for known injection patterns
+    // Ranges with newlines, semicolons, pipes should be rejected
+    const unsafeTokens = ["main\nsemantically", "main;rm -rf", "main|cat"];
+    for (const token of unsafeTokens) {
+      // These should fail validation in the actual tool
+      const hasShellMeta = /[\n\r;|&`$<>]/.test(token);
+      expect(hasShellMeta).toBe(true);
+    }
+  });
+
+  test("accepts safe range tokens", () => {
+    const safeTokens = ["main", "feature", "v1.2.3", "release/1.0", "HEAD~3", "HEAD~3..main"];
+    for (const token of safeTokens) {
+      // Basic sanity: they don't contain obvious injection chars
+      const hasShellMeta = /[\n\r;|&`$<>]/.test(token);
+      expect(hasShellMeta).toBe(false);
+    }
+  });
+});
+
+describe("git_diff tool range labels", () => {
+  test("labels unstaged changes correctly", () => {
+    const label = "unstaged changes";
+    expect(label).toContain("unstaged");
+  });
+
+  test("labels staged changes correctly", () => {
+    const label = "staged changes";
+    expect(label).toContain("staged");
+  });
+
+  test("labels range changes correctly", () => {
+    const label = "main..feature";
+    expect(label).toMatch(/^[a-zA-Z0-9.~/-]+\.\.[a-zA-Z0-9.~/-]+$/);
+  });
+
+  test("labels path-scoped changes correctly", () => {
+    const label = "unstaged changes (src/main.ts)";
+    expect(label).toContain("(src/main.ts)");
+  });
+
+  test("labels range + path changes correctly", () => {
+    const label = "main..feature (src/main.ts)";
+    expect(label).toContain("main..feature");
+    expect(label).toContain("(src/main.ts)");
+  });
+});

src/server/git-diff-tool.ts

@@ -0,0 +1,166 @@
+import type { FastMCP } from "fastmcp";
+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
+// ---------------------------------------------------------------------------
+
+/** Build the diff args array from parameters. */
+function buildDiffArgs(opts: {
+  base?: string;
+  head?: string;
+  path?: string;
+  staged?: boolean;
+}): { ok: true; args: string[] } | { ok: false; error: string } {
+  const args: string[] = ["diff"];
+
+  // Handle staged flag first
+  if (opts.staged === true) {
+    args.push("--staged");
+  } else if (opts.base || opts.head) {
+    // Range-based diff: base..head or base...head
+    // If only base is given, use base~0..HEAD (implicit HEAD)
+    const baseStr = opts.base?.trim() ?? "HEAD";
+    const headStr = opts.head?.trim() ?? "HEAD";
+
+    if (!isSafeGitUpstreamToken(baseStr) || !isSafeGitUpstreamToken(headStr)) {
+      return { ok: false, error: "unsafe_range_token" };
+    }
+
+    // Use two-dot range: base..head
+    args.push(`${baseStr}..${headStr}`);
+  }
+
+  // Scope to path if provided
+  if (opts.path?.trim()) {
+    args.push("--", opts.path.trim());
+  }
+
+  return { ok: true, args };
+}
+
+/** Human-readable label for the range. */
+function rangeLabel(opts: {
+  base?: string;
+  head?: string;
+  path?: string;
+  staged?: boolean;
+}): string {
+  let label = "";
+
+  if (opts.staged === true) {
+    label = "staged changes";
+  } else if (opts.base || opts.head) {
+    const baseStr = opts.base?.trim() ?? "HEAD";
+    const headStr = opts.head?.trim() ?? "HEAD";
+    label = `${baseStr}..${headStr}`;
+  } else {
+    label = "unstaged changes";
+  }
+
+  if (opts.path?.trim()) {
+    label += ` (${opts.path.trim()})`;
+  }
+
+  return label;
+}
+
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+
+export function registerGitDiffTool(server: FastMCP): void {
+  server.addTool({
+    name: "git_diff",
+    description:
+      "Get diff text for scoped file or range. Returns the raw diff output. " +
+      "Use `staged: true` for staged changes, `base`/`head` for revision ranges, " +
+      "and `path` to scope to a specific file.",
+    annotations: {
+      readOnlyHint: true,
+    },
+    parameters: WorkspacePickSchema.extend({
+      base: z
+        .string()
+        .optional()
+        .describe(
+          'Base ref (e.g. "main", "HEAD~3"). Required for range diffs. ' +
+            "If omitted and `staged: false`, shows unstaged changes.",
+        ),
+      head: z
+        .string()
+        .optional()
+        .describe(
+          'Head ref (e.g. "feature-branch"). If omitted, defaults to HEAD. ' +
+            "Only used if `base` is provided.",
+        ),
+      path: z
+        .string()
+        .optional()
+        .describe('Scope diff to a single file path (e.g. "src/main.ts").'),
+      staged: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe(
+          "If true, show staged changes (git diff --staged). " + "Ignored if `base` is provided.",
+        ),
+    }),
+    execute: async (args) => {
+      const pre = requireSingleRepo(server, args);
+      if (!pre.ok) return jsonRespond(pre.error);
+      const gitTop = pre.gitTop;
+
+      // Build git diff args
+      const diffArgsResult = buildDiffArgs({
+        base: args.base,
+        head: args.head,
+        path: args.path,
+        staged: args.staged,
+      });
+      if (!diffArgsResult.ok) {
+        return jsonRespond({ error: diffArgsResult.error });
+      }
+
+      // Run git diff
+      const result = await spawnGitAsync(gitTop, diffArgsResult.args);
+      if (!result.ok) {
+        return jsonRespond({
+          error: "git_diff_failed",
+          detail: (result.stderr || result.stdout).trim(),
+        });
+      }
+
+      const label = rangeLabel({
+        base: args.base,
+        head: args.head,
+        path: args.path,
+        staged: args.staged,
+      });
+
+      if (args.format === "json") {
+        return jsonRespond({
+          range: label,
+          diff: result.stdout,
+        } as unknown as Record<string, unknown>);
+      }
+
+      // Markdown output
+      const lines: string[] = [];
+      lines.push(`# Diff: ${label}`, "");
+
+      if (result.stdout.trim()) {
+        lines.push("```diff", result.stdout.trimEnd(), "```");
+      } else {
+        lines.push("_(no changes)_");
+      }
+
+      return lines.join("\n");
+    },
+  });
+}

src/server/tools.ts

@@ -3,12 +3,14 @@ import type { FastMCP } from "fastmcp";
 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 { 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 { registerGitStatusTool } from "./git-status-tool.js";
 import {
   registerGitWorktreeAddTool,
@@ -26,6 +28,8 @@ export function registerRethunkGitTools(server: FastMCP): void {
   registerListPresetsTool(server);
   registerGitLogTool(server);
   registerGitDiffSummaryTool(server);
+  registerGitDiffTool(server);
+  registerGitShowTool(server);
   registerGitWorktreeListTool(server);
   // Mutating tools
   registerBatchCommitTool(server);