pastcode 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [YEAR] [YOUR NAME]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# pastcode
+
+A minimal MCP server for git history, git blame, and debugging the moment a bug was introduced.
+
+[![npm version](https://img.shields.io/npm/v/pastcode.svg)](https://www.npmjs.com/package/pastcode)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-43853d.svg)](https://nodejs.org/)
+
+AI coding agents can read the current snapshot of a repo, but they usually cannot answer the question that matters most when debugging: when did this bug get introduced, who changed it, and what did the file look like before the breakage?
+
+pastcode gives any MCP-compatible AI agent read access to your git history so it can investigate bugs the way a senior engineer would: by walking back through time, checking blame, diffing commits, and narrowing the culprit with git bisect.
+
+## Quick start
+
+Add a server entry like this to your MCP client configuration:
+
+### Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "pastcode": {
+      "command": "npx",
+      "args": ["-y", "pastcode"]
+    }
+  }
+}
+```
+
+This works the same way in Claude Code, Cursor, Windsurf, or any other MCP-compatible client that launches stdio-based MCP servers. There are no environment variables to set up, no repo config to install, and no global state to manage. The repo path is passed per tool call, so one running server can work across unlimited repositories.
+
+Not published yet, or testing locally? Use the local path variant above instead.
+
+```json
+{
+  "mcpServers": {
+    "pastcode": {
+      "command": "node",
+      "args": ["/absolute/path/to/pastcode/index.js"]
+    }
+  }
+}
+```
+
+## Available tools
+
+| Tool                      | What it does                                                                                                                                   | Example prompt                                                                              |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `get_file_at_commit`      | Returns the contents of a file at a specific commit or ref. Useful when an AI agent wants to inspect older code without checking out the repo. | “Show me the version of src/auth.js from commit abc123 and compare it to the current file.” |
+| `list_commits_for_file`   | Lists the recent history of a file using `git log --follow`, including commit hashes, authors, dates, and messages.                            | “Which commits touched src/api/users.ts, and when were they introduced?”                    |
+| `blame_line_range`        | Shows who last changed a line range and which commit introduced it. Great for narrowing suspect edits.                                         | “Who changed the validateEmail function and which commit owns this block?”                  |
+| `diff_between_commits`    | Compares two refs, optionally scoped to a file, to show exactly what changed between them.                                                     | “What changed between release-1.2 and release-1.3 in src/checkout.ts?”                      |
+| `find_introducing_commit` | Runs a git bisect in a temporary worktree using a supplied test command to locate the first bad commit.                                        | “When did the isValidEmail function start returning false for valid emails?”                |
+
+## How agents actually use this
+
+### 1) “When did this bug get introduced?”
+
+A user asks: “The login form breaks for valid email addresses after the last deploy. When did this start?”
+
+The AI may call:
+
+- `list_commits_for_file` on the file that owns email validation
+- `blame_line_range` on the suspicious lines
+- `get_file_at_commit` on historical revisions to inspect behavior before and after the regression
+- `find_introducing_commit` with a minimal test command to confirm the exact first bad commit
+
+### 2) “Who changed this logic and why?”
+
+A user asks: “I want to know why the pricing calculation changed in the checkout flow.”
+
+The AI may call:
+
+- `blame_line_range` on the calculation block
+- `diff_between_commits` between the relevant revisions
+- `get_file_at_commit` to inspect the code as it existed before the refactor or hotfix
+
+### 3) “What did this file look like before the refactor?”
+
+A user asks: “The refactor in the auth service looks risky. Show me the pre-refactor implementation.”
+
+The AI may call:
+
+- `list_commits_for_file` to locate the refactor commit
+- `get_file_at_commit` at the parent ref or historical tag
+- `diff_between_commits` between the refactor and its parent to highlight the exact behavioral change
+
+This is not a CLI tool you run manually. The AI agent drives it as part of a normal debugging workflow.
+
+## Security note
+
+> ⚠️ `find_introducing_commit` executes an arbitrary shell command (`testCommand`) during bisect. Only use it against trusted repositories and trusted test commands, just as you would with any AI-driven script execution or automated debugging workflow.
+
+## Contributing
+
+This project is intentionally small and dependency-light. The goal is to stay easy to reason about and easy to wire into AI tools without over-engineering the stack.
+
+To work on it locally:
+
+```bash
+git clone https://github.com/USERNAME/pastcode.git
+cd pastcode
+npm install
+```
+
+For manual inspection of the MCP server, you can run it via the official MCP inspector:
+
+```bash
+npx @modelcontextprotocol/inspector node index.js
+```
+
+Then connect the inspector to the local server entry and inspect tool calls in real time.
+
+If you want to propose a new tool, open an issue first to discuss scope and fit before sending a PR. This project keeps the surface area intentionally small, and it’s best to align on the workflow before adding new capabilities.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

package/index.js

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const execFileAsync = promisify(execFile);
+
+function ensureRepo(repoPath) {
+  if (!repoPath || typeof repoPath !== "string") {
+    throw new Error("repoPath is required");
+  }
+
+  if (!fs.existsSync(repoPath) || !fs.existsSync(path.join(repoPath, ".git"))) {
+    throw new Error(`Not a git repo: ${repoPath}`);
+  }
+}
+
+async function runGit(repoPath, args, stdoutOnly = false) {
+  ensureRepo(repoPath);
+
+  try {
+    const { stdout, stderr } = await execFileAsync(
+      "git",
+      ["-C", repoPath, ...args],
+      {
+        maxBuffer: 20 * 1024 * 1024,
+      },
+    );
+    if (stdoutOnly) {
+      return (stdout || "").trim();
+    }
+    return `${stdout || ""}${stderr ? `\n${stderr}` : ""}`.trim();
+  } catch (error) {
+    const message = [error.stderr, error.stdout, error.message]
+      .filter(Boolean)
+      .join("\n");
+    if (stdoutOnly) {
+      throw new Error(
+        (error.stderr || error.message || "git command failed").trim(),
+      );
+    }
+    throw new Error(message.trim() || "git command failed");
+  }
+}
+
+async function getFileAtCommit(repoPath, filePath, ref) {
+  return runGit(repoPath, ["show", `${ref}:${filePath}`], true);
+}
+
+async function listCommitsForFile(repoPath, filePath, maxCount) {
+  const args = ["log", "--follow"];
+  if (maxCount != null && Number.isFinite(Number(maxCount))) {
+    args.push("-n", String(Number(maxCount)));
+  }
+  args.push("--format=%H%x09%an%x09%ad%x09%s", "--date=short", "--", filePath);
+  return runGit(repoPath, args);
+}
+
+async function blameLineRange(repoPath, filePath, startLine, endLine, ref) {
+  const args = ["blame"];
+  if (ref) {
+    args.push(ref);
+  }
+  args.push("-L", `${startLine},${endLine}`, "--", filePath);
+  return runGit(repoPath, args);
+}
+
+async function diffBetweenCommits(repoPath, refA, refB, filePath) {
+  const args = ["diff", refA, refB];
+  if (filePath) {
+    args.push("--", filePath);
+  }
+  return runGit(repoPath, args);
+}
+
+async function findIntroducingCommit(
+  repoPath,
+  filePath,
+  testCommand,
+  goodRef,
+  badRef,
+) {
+  ensureRepo(repoPath);
+
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "pastcode-bisect-"));
+  const worktreePath = path.join(tempRoot, "repo");
+
+  try {
+    await runGit(repoPath, [
+      "worktree",
+      "add",
+      "--detach",
+      worktreePath,
+      goodRef,
+    ]);
+    await runGit(worktreePath, ["bisect", "start"]);
+    await runGit(worktreePath, ["bisect", "bad", badRef]);
+    await runGit(worktreePath, ["bisect", "good", goodRef]);
+
+    const bisectOutput = await execFileAsync(
+      "git",
+      ["-C", worktreePath, "bisect", "run", "bash", "-lc", testCommand],
+      { maxBuffer: 20 * 1024 * 1024 },
+    );
+
+    const head = await runGit(worktreePath, ["rev-parse", "HEAD"]);
+    const summary = [
+      `Introduced by commit: ${head}`,
+      `File: ${filePath || "(not restricted)"}`,
+      "",
+      bisectOutput.stdout || bisectOutput.stderr || "",
+    ].join("\n");
+
+    return summary.trim();
+  } catch (error) {
+    const msg = [error.stderr, error.stdout, error.message]
+      .filter(Boolean)
+      .join("\n");
+    throw new Error(msg.trim() || "bisect failed");
+  } finally {
+    try {
+      if (fs.existsSync(worktreePath)) {
+        try {
+          await runGit(worktreePath, ["bisect", "reset"]);
+        } catch (cleanupError) {
+          // ignore bisect reset failures so the worktree can still be removed
+        }
+        await runGit(repoPath, ["worktree", "remove", "--force", worktreePath]);
+      }
+    } catch (cleanupError) {
+      // ignore cleanup errors during short-lived tooling
+    }
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+
+const server = new Server(
+  { name: "pastcode", version: "0.1.0" },
+  { capabilities: { tools: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "get_file_at_commit",
+      description: "Return the contents of a file at a specific commit or ref.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          repoPath: { type: "string" },
+          path: { type: "string" },
+          ref: { type: "string" },
+        },
+        required: ["repoPath", "path", "ref"],
+      },
+    },
+    {
+      name: "list_commits_for_file",
+      description: "List recent commits affecting a file.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          repoPath: { type: "string" },
+          path: { type: "string" },
+          maxCount: { type: "number" },
+        },
+        required: ["repoPath", "path"],
+      },
+    },
+    {
+      name: "blame_line_range",
+      description: "Blame a line range in a file.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          repoPath: { type: "string" },
+          path: { type: "string" },
+          startLine: { type: "number" },
+          endLine: { type: "number" },
+          ref: { type: "string" },
+        },
+        required: ["repoPath", "path", "startLine", "endLine"],
+      },
+    },
+    {
+      name: "diff_between_commits",
+      description: "Show the diff between two refs for a file or repo.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          repoPath: { type: "string" },
+          refA: { type: "string" },
+          refB: { type: "string" },
+          path: { type: "string" },
+        },
+        required: ["repoPath", "refA", "refB"],
+      },
+    },
+    {
+      name: "find_introducing_commit",
+      description:
+        "Use git bisect in a temporary worktree to find the introducing commit for a bug.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          repoPath: { type: "string" },
+          path: { type: "string" },
+          testCommand: { type: "string" },
+          goodRef: { type: "string" },
+          badRef: { type: "string" },
+        },
+        required: ["repoPath", "path", "testCommand", "goodRef", "badRef"],
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args = {} } = request.params;
+
+  try {
+    let result;
+
+    switch (name) {
+      case "get_file_at_commit":
+        result = await getFileAtCommit(args.repoPath, args.path, args.ref);
+        break;
+      case "list_commits_for_file":
+        result = await listCommitsForFile(
+          args.repoPath,
+          args.path,
+          args.maxCount,
+        );
+        break;
+      case "blame_line_range":
+        result = await blameLineRange(
+          args.repoPath,
+          args.path,
+          args.startLine,
+          args.endLine,
+          args.ref,
+        );
+        break;
+      case "diff_between_commits":
+        result = await diffBetweenCommits(
+          args.repoPath,
+          args.refA,
+          args.refB,
+          args.path,
+        );
+        break;
+      case "find_introducing_commit":
+        result = await findIntroducingCommit(
+          args.repoPath,
+          args.path,
+          args.testCommand,
+          args.goodRef,
+          args.badRef,
+        );
+        break;
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+
+    return {
+      content: [{ type: "text", text: String(result) }],
+    };
+  } catch (error) {
+    return {
+      content: [{ type: "text", text: String(error.message || error) }],
+      isError: true,
+    };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "pastcode",
+  "version": "0.1.0",
+  "description": "MCP server for git history inspection, blame, diffs, and bisect-driven bug investigation for AI coding agents.",
+  "type": "module",
+  "bin": {
+    "pastcode": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "git",
+    "git-history",
+    "git-blame",
+    "ai-agent",
+    "claude",
+    "debugging",
+    "bug-tracing",
+    "developer-tools"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/USERNAME/pastcode.git"
+  },
+  "homepage": "https://github.com/USERNAME/pastcode",
+  "bugs": {
+    "url": "https://github.com/USERNAME/pastcode/issues"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.0"
+  }
+}