Skip to content

PLAN.md

Latest commit

 

History

History
82 lines (71 loc) · 5.37 KB

PLAN.md

File metadata and controls

82 lines (71 loc) · 5.37 KB
Raw

gitpulse-mcp — Plan & Spec

One-liner

An MCP (Model Context Protocol) server that gives AI agents deep git intelligence about any repo — not git plumbing, but the insight layer: where the risk lives, who owns what, what just changed, and the story behind any line.

Positioning / Differentiation (from research)

Existing git MCP servers (cyanheads/git-mcp-server, wty0512/git-mcp-server, GitHub's official server) focus on git operations — clone, commit, push, merge, rebase, status. They turn an agent into a git CLI wrapper.

gitpulse-mcp is read-only and analytical. It applies the "Code as a Crime Scene" / Code Maat / CodeScene school of code forensics (Adam Tornhill) and makes it available to AI agents over MCP. The agent asks high-level questions ("what are the riskiest files?", "who should review this?", "what changed since v1.2.0?") and gets structured, ranked, ready-to-reason-about answers.

Why this earns stars:

  • Fills a real gap: forensic/analytics angle nobody else exposes via MCP.
  • Read-only & safe by default — no risk of an agent force-pushing.
  • Zero-config: npx gitpulse-mcp, works on any local repo, any OS.
  • Pure git (via child_process) — no native deps, no libgit2 build pain.

MVP tools (all read-only)

  1. git_recent_changes — recent commits summary (author, date, subject, files touched, insertions/deletions) for a ref/branch, optional path filter, limit.
  2. git_blame_summary — per-file blame rolled up by author: who owns how many current lines, last-touched date, % ownership. Far more useful to an agent than raw blame.
  3. git_hotspots — change-frequency "hotspots": files ranked by commit count (churn) over a time window, with churn-score and a complexity proxy (current line count). The churn×size product = risk score. The standout feature.
  4. git_ownership — contributor/ownership map for a path or whole repo: top authors by commits & lines, "knowledge silos" (files with a single dominant author = bus-factor risk).
  5. git_changes_since — diff/changes since a tag/branch/commit: files changed, +/- stats, commit list, grouped by directory. For "what's in this release / PR".
  6. git_search_commits — search commits by message text, author, or by code change (pickaxe -S/-G). Returns matching commits with context.
  7. who_touched_lines — "who last touched these lines": given a file + line range, return the commits/authors responsible (line-level blame for a range) — the reviewer-finder.
  8. git_repo_overview — quick repo vitals: HEAD, branch, total commits, contributor count, age, most-active files, last activity. Great first call for an agent orienting itself.

Standout features (the 3 that make it shine)

  1. Risk-scored hotspots (git_hotspots) — combines churn + size into a single ranked risk list, the core CodeScene insight, exposed to agents.
  2. Knowledge-silo / bus-factor detection (git_ownership) — flags files with a single dominant owner; tells an agent who to ask / what's fragile.
  3. Reviewer suggestion baked into who_touched_lines + git_blame_summary — turns blame into "ask these humans".

Architecture / file layout

src/
  index.ts            # bin entry: parse argv, build server, connect stdio, signal handling
  server.ts           # createServer(): McpServer + register all tools
  git/
    exec.ts           # safe git runner (child_process execFile, no shell, timeouts, maxBuffer)
    repo.ts           # repo resolution & validation (is this a git repo? resolve cwd/--repo)
    parse.ts          # parsers for log/blame/numstat porcelain output
  tools/
    recentChanges.ts
    blameSummary.ts
    hotspots.ts
    ownership.ts
    changesSince.ts
    searchCommits.ts
    whoTouchedLines.ts
    repoOverview.ts
  lib/
    format.ts         # human + structured output helpers
    types.ts          # shared TS types
  config.ts           # CLI args -> config (repo path, defaults)
test/
  *.test.ts           # vitest unit tests against a fixture repo created at runtime
  fixture.ts          # builds a deterministic temp git repo for tests
scripts/
  smoke.mjs           # spawns the built server, speaks MCP over stdio, calls tools

Tool I/O contract

  • Every tool accepts an optional repoPath (defaults to server's configured repo / cwd).
  • Every tool returns BOTH human-readable content[0].text (markdown) AND structuredContent (typed JSON) so agents can parse reliably.
  • Errors → isError: true with a clear message (never throw raw).

Safety / correctness

  • execFile (no shell) → no command injection. All args passed as array.
  • Validate repoPath is inside a git work tree before running.
  • Timeouts + maxBuffer on every git call.
  • Handle empty repos, repos with no tags, binary files, renames.
  • Cross-platform: no bash-isms; rely on git's own porcelain; normalize path separators.

Tech choices

  • @modelcontextprotocol/sdk ^1.29.0 (McpServer + StdioServerTransport, registerTool with raw zod shape).
  • zod ^3.25 for input schemas.
  • Git via node:child_process execFile (no simple-git dep → fewer deps, full control, faster).
  • Build: tsc → ESM in dist/. bin shebang. Node >=18.
  • Test: vitest. Lint: eslint + typescript-eslint. Format: prettier.
  • CI: GitHub Actions matrix (ubuntu + windows), Node 18/20/22: install, build, lint, test.

Logging

  • All diagnostics → stderr only (stdout is sacred JSON-RPC channel).