repo-forensics-mcp
# repo-forensics-mcp
A local-only MCP companion for understanding a Git repository before a review, refactor, or release.
## Tools
- `repository_summary`: branch, working tree status, remotes, and latest commit metadata.
- `recent_changes`: bounded recent commit history.
- `file_hotspots`: files appearing most often in recent history.
- `top_level_hygiene`: top-level large files, `.gitignore` presence, and dirty state without reading file contents.
The server invokes local Git with fixed argument arrays. By default, paths must stay under the parent workspace of the package process; set `REPO_FORENSICS_ROOT` to an explicit workspace root when launching it. It returns remote names rather than remote URLs to avoid leaking credentials. It does not fetch, push, write files, inspect remote services, or send repository data over the network. Hotspots and hygiene are heuristics, not a complete code-quality or security audit.
## Run
```bash
npm install
npm run build
node dist/index.js
```
TDQS
Scored across 4 tools
Each tool targets a distinct aspect of repository forensics: overall state, recent history, file hotspots, and top-level hygiene. There is no overlap in their functions, making them easy to distinguish.
All names use snake_case and are descriptive, but they mix noun phrases (repository_summary, file_hotspots) with adjective-noun forms (recent_changes, top_level_hygiene). The pattern is not strictly verb_noun, but it is readable and consistent in style.
With only 4 tools, the server is well-scoped for a focused forensics purpose. Each tool provides a distinct slice of information without unnecessary bloat.
The set covers the basic forensics workflow: repo overview, change history, hotspot identification, and hygiene checks. Minor gaps exist, such as lacking diff or blame tools for deeper investigation, but the current surface is functional for its stated purpose.