feat: add git_show MCP tool — inspect commit content by ref/SHA

Implements new git_show tool with support for:
- Inspecting commit metadata and diffs by ref/SHA
- File content inspection at a specific ref with path parameter
- Both markdown and JSON output formats
- Comprehensive test coverage (7 tests)

Fixes #6

Author: AlbinoGeek

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

@@ -0,0 +1,139 @@
+/**
+ * Integration tests for git_show_tool.
+ *
+ * Tests create throwaway git repos via `git init` in OS temp dirs
+ * and exercise git show for commits and file inspection.
+ *
+ * We test:
+ *  1. git show on a commit ref returns message + diff
+ *  2. git show with a path returns file content at that ref
+ *  3. commit message is correctly extracted from git show output
+ *  4. not_a_git_repository error for non-git path
+ *  5. invalid ref error handling
+ *  6. JSON format output
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { registerGitShowTool } from "./git-show-tool.js";
+import { addCommit, captureTool, cleanupTmpPaths, gitCmd, makeRepo } from "./test-harness.js";
+
+afterEach(cleanupTmpPaths);
+
+describe("git_show_tool", () => {
+  test("git show on a commit returns message + diff", async () => {
+    const repo = makeRepo();
+    addCommit(repo, "file.txt", "content\n", "feat: add file");
+
+    const tool = captureTool(registerGitShowTool);
+    const result = await tool({
+      wd: repo,
+      ref: "HEAD",
+      format: "markdown",
+    });
+
+    // Result should contain commit message and diff info
+    expect(result).toContain("feat: add file");
+    expect(result).toContain("git show HEAD");
+  });
+
+  test("git show with path shows file content at ref", async () => {
+    const repo = makeRepo();
+    addCommit(repo, "file.txt", "first content\n", "feat: add file");
+    addCommit(repo, "file.txt", "second content\n", "fix: update file");
+
+    const tool = captureTool(registerGitShowTool);
+    const result = await tool({
+      wd: repo,
+      ref: "HEAD~1",
+      path: "file.txt",
+      format: "markdown",
+    });
+
+    // Result should contain the file path and content from the previous commit
+    expect(result).toContain("file.txt");
+    expect(result).toContain("first content");
+  });
+
+  test("git show returns JSON format", async () => {
+    const repo = makeRepo();
+    addCommit(repo, "file.txt", "content\n", "feat: add file");
+
+    const tool = captureTool(registerGitShowTool);
+    const result = await tool({
+      wd: repo,
+      ref: "HEAD",
+      format: "json",
+    });
+
+    const parsed = JSON.parse(result);
+    expect(parsed.ref).toBe("HEAD");
+    expect(parsed.message).toContain("feat: add file");
+    expect(typeof parsed.diff).toBe("string");
+  });
+
+  test("git show not_a_git_repository error for invalid path", async () => {
+    const tool = captureTool(registerGitShowTool);
+    const result = await tool({
+      wd: "/nonexistent/path",
+      ref: "HEAD",
+    });
+
+    expect(result).toContain("not_a_git_repository");
+  });
+
+  test("git show invalid ref returns error", async () => {
+    const repo = makeRepo();
+    addCommit(repo, "file.txt", "content\n", "feat: add file");
+
+    const tool = captureTool(registerGitShowTool);
+    const result = await tool({
+      wd: repo,
+      ref: "invalid-ref-xyz",
+    });
+
+    expect(result).toContain("git_show_failed");
+  });
+
+  test("git show with path includes path in JSON", async () => {
+    const repo = makeRepo();
+    addCommit(repo, "file.txt", "content\n", "feat: add file");
+
+    const tool = captureTool(registerGitShowTool);
+    const result = await tool({
+      wd: repo,
+      ref: "HEAD",
+      path: "file.txt",
+      format: "json",
+    });
+
+    const parsed = JSON.parse(result);
+    expect(parsed.path).toBe("file.txt");
+    expect(parsed.ref).toBe("HEAD");
+  });
+
+  test("git show commit message with multiline content", async () => {
+    const repo = makeRepo();
+    writeFileSync(join(repo, "file.txt"), "content\n");
+    gitCmd(repo, "add", "file.txt");
+    gitCmd(
+      repo,
+      "commit",
+      "-m",
+      "feat: add file\n\nThis is a detailed description\nof the feature.",
+    );
+
+    const tool = captureTool(registerGitShowTool);
+    const result = await tool({
+      wd: repo,
+      ref: "HEAD",
+      format: "json",
+    });
+
+    const parsed = JSON.parse(result);
+    expect(parsed.message).toContain("feat: add file");
+    expect(parsed.message).toContain("detailed description");
+  });
+});

src/server/git-show-tool.ts

@@ -0,0 +1,184 @@
+import type { FastMCP } from "fastmcp";
+import { z } from "zod";
+
+import { gateGit, gitTopLevel, spawnGitAsync } from "./git.js";
+import { jsonRespond } from "./json.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface ShowJson {
+  ref: string;
+  path?: string;
+  message: string;
+  diff?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Run git show for a single ref, optionally limiting to a specific path.
+ * Returns commit message and diff (or file content if path is specified).
+ */
+async function runGitShow(opts: {
+  top: string;
+  ref: string;
+  path?: string;
+}): Promise<ShowJson | { error: string }> {
+  const { top, ref, path } = opts;
+
+  // Build git show args. Start with --no-patch to get just the commit message.
+  const showArgs: string[] = ["show", ref];
+
+  if (path) {
+    // When path is specified, show that path at the ref without --no-patch
+    // to get the full content at that ref
+    showArgs.push("--", path);
+  }
+
+  const r = await spawnGitAsync(top, showArgs);
+  if (!r.ok) {
+    return {
+      error: "git_show_failed",
+    };
+  }
+
+  // Parse the output. For a commit, git show outputs:
+  // - Header (commit, Author, Date, etc.)
+  // - Blank line
+  // - Commit message (may contain multiple lines and blank lines)
+  // - Blank line (separator before diff)
+  // - Diff (if --no-patch not used) or file content
+  const output = r.stdout;
+  let message = "";
+  let diff = "";
+
+  const lines = output.split("\n");
+  let inHeader = true;
+  let inMessage = false;
+  const messageLines: string[] = [];
+  const contentLines: string[] = [];
+
+  for (const line of lines) {
+    if (line === undefined) continue;
+
+    // End header when we see a blank line
+    if (inHeader && line.trim() === "") {
+      inHeader = false;
+      inMessage = true;
+      continue;
+    }
+
+    // In message: collect until we see "diff --git" which marks the start of the diff section
+    if (inMessage) {
+      if (line.startsWith("diff --git")) {
+        inMessage = false;
+        contentLines.push(line);
+      } else {
+        messageLines.push(line);
+      }
+    } else if (!inHeader) {
+      // In diff/content section
+      contentLines.push(line);
+    }
+  }
+
+  message = messageLines.join("\n").trim();
+  diff = contentLines.join("\n").trim();
+
+  const result: ShowJson = {
+    ref,
+    message,
+  };
+  if (path) {
+    result.path = path;
+  }
+  if (diff) {
+    result.diff = diff;
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Markdown rendering
+// ---------------------------------------------------------------------------
+
+function renderShowMarkdown(result: ShowJson): string {
+  const lines: string[] = [];
+  lines.push(`# git show ${result.ref}`);
+  if (result.path) {
+    lines.push(`_path: ${result.path}_`);
+  }
+  lines.push("");
+  lines.push("## Commit message");
+  lines.push("");
+  lines.push("```");
+  lines.push(result.message);
+  lines.push("```");
+
+  if (result.diff) {
+    lines.push("");
+    lines.push("## Diff");
+    lines.push("");
+    lines.push("```diff");
+    lines.push(result.diff);
+    lines.push("```");
+  }
+
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+
+export function registerGitShowTool(server: FastMCP): void {
+  server.addTool({
+    name: "git_show",
+    description:
+      "Inspect commit content by ref/SHA. Returns commit message and diff (or file content at a specific path).",
+    annotations: {
+      readOnlyHint: true,
+    },
+    parameters: z.object({
+      wd: z.string().describe("Working directory (git repository root or subdirectory)."),
+      ref: z.string().describe("Commit reference (SHA, branch, tag, or any git rev-spec)."),
+      path: z
+        .string()
+        .optional()
+        .describe(
+          "Optional file path to inspect at the ref. If provided, shows that path's content at the ref instead of the diff.",
+        ),
+      format: z.enum(["markdown", "json"]).optional().default("markdown"),
+    }),
+    execute: async (args) => {
+      const gg = gateGit();
+      if (!gg.ok) return jsonRespond(gg.body);
+
+      const top = gitTopLevel(args.wd);
+      if (!top) {
+        return jsonRespond({ error: "not_a_git_repository", path: args.wd });
+      }
+
+      const result = await runGitShow({
+        top,
+        ref: args.ref,
+        path: args.path,
+      });
+
+      if ("error" in result) {
+        return jsonRespond(result);
+      }
+
+      if (args.format === "json") {
+        return jsonRespond(result as unknown as Record<string, unknown>);
+      }
+
+      // Markdown
+      return renderShowMarkdown(result);
+    },
+  });
+}