Codebase Archaeology MCP

An MCP server that answers "why is this line here?" for a local git repo by tracing a line back to the commit that actually introduced it, then to the PR and review discussion behind that commit.

The problem

git blame attributes a line to whoever last touched it. In real repos that is usually a formatter run, an import reorder, or a rename. The naive pipeline — blame → commit → PR — returns "Bob, prettier migration, 2024" and tells you nothing about intent.

This server defeats that:

• blame runs with -w -C -C (whitespace ignored, moved/copied code followed) and honours .git-blame-ignore-revs.

• line history follows a range backwards through edits and renames (git log -L), detects cosmetic commits (git show -w produces no output → the change was whitespace-only), and compensates for -L range drift, so likely_origin is the commit that genuinely introduced the content — not the formatter, and not the neighboring lines' history.

• PR lookup uses GitHub's commits/{sha}/pulls endpoint, which works for squash and rebase merges where commit-message parsing silently fails.

• When the trace bottoms out at the commit that created the file, the answer says so — git log -L cannot see across a file split, and pretending otherwise would be lying.

Related MCP server: review-dojo-mcp

Tools

repo may be any path inside the work tree; file paths are resolved against the repo root and anything escaping it is rejected.

Setup

Python 3.11+ and git on PATH.

pip install -r requirements.txt

Run over stdio:

python server.py

or explore interactively:

fastmcp dev server.py

Client configuration (stdio)

{
  "mcpServers": {
    "codebase-archaeology": {
      "command": "python",
      "args": ["C:/path/to/code-arch/server.py"],
      "env": {
        "ARCHAEOLOGY_REPOS": "C:/Users/you/src/repo-a;C:/Users/you/src/repo-b",
        "GITHUB_TOKEN": "ghp_...",
        "ARCHAEOLOGY_CACHE": "C:/Users/you/.cache/archaeology.sqlite"
      }
    }
  }
}

Environment variables

Honest limits

• git log -L cannot trace across a file split (content extracted into a new file). The origin will be the splitting commit, flagged with origin_is_file_creation: true and an interpretation pointing at find_removal to dig further.

• Cosmetic detection is whitespace-based (git show -w). A formatter that changes quote characters is not "cosmetic" by this test, but the lineage trace still walks through it to the real origin.

• git log -L on a huge file with deep history is genuinely slow; that is why limit defaults to 15 and git calls time out at 30s.

Tests

python -m pytest

The suite builds a throwaway repo reproducing the failure mode (real origin → whitespace-only reformat → reword) and asserts, among other things, that naive blame credits the formatter while every tool here names the true origin. GitHub tests run against a fake transport — no network needed.