Git Forensics MCP


A Model Context Protocol (MCP) server for deep git repository investigation and analysis. This tool provides detailed insights into repository history, branch relationships, and development patterns to help teams make informed merge decisions and understand code evolution.

Table of Contents

- Quick Start
- Features
- Installation
- Usage
- Requirements
- Contributing
- Development Setup
- Development Commands
- Release Process
- Testing Published Releases
- Project Structure
- Architecture Notes
- License

Quick Start

Run the MCP server directly without installation:

``bash
npx @jamie-bitflight/git-forensics-mcp
`

Or add to Claude Code with a single command:

`bash
claude mcp add --scope user git-forensics -- npx -y @jamie-bitflight/git-forensics-mcp
`

No authentication or configuration required - the package is publicly available on npm.

Features

Git Forensics MCP provides four powerful analysis tools to understand repository history and guide merge decisions:

$3

Get a high-level snapshot of branch states and relationships to understand your repository's current structure.

What it provides:

- Last commit details for each branch (hash, date, message)
- Total commit counts per branch
- Merge base identification between branches
- Statistical summaries of branch activities

Use cases:

- Quickly assess branch divergence before merging
- Identify stale branches that may need rebasing
- Understand relative activity levels across branches

$3

Dive deep into development activity within specific time periods to understand what changed and when.

What it provides:

- Detailed commit history for specified date ranges
- Automatic commit categorization (feature, fix, refactor, docs, other)
- Activity summaries showing commit patterns and trends
- Breakdown of work types across time periods

Use cases:

- Review sprint/milestone activities
- Analyze development velocity over time
- Understand what types of work dominated a release cycle

$3

Track how specific files evolved across branches to identify conflict risks and coordinate reviews.

What it provides:

- Complete modification history for tracked files
- Conflict detection when multiple branches modified the same files
- Risk assessment levels (low/medium/high) based on overlap patterns
- Recommended review order prioritized by risk level

Use cases:

- Identify potential merge conflicts before they happen
- Coordinate reviews when multiple teams touched the same code
- Plan merge order to minimize conflict resolution work

$3

Get strategic guidance for merging branches based on comprehensive repository analysis.

What it provides:

- Optimal merge strategy recommendations
- Conflict risk assessment across all branches
- Code hotspot identification (files changed in multiple branches)
- Step-by-step merge guidance with risk mitigation

Use cases:

- Plan complex multi-branch merges
- Understand which branches to merge first
- Identify high-risk areas requiring extra review attention

Installation

$3

Use npx to run the latest version without installing:

`bash
npx @jamie-bitflight/git-forensics-mcp
`

$3

Use the Claude Code CLI to add as an MCP server:

`bash
claude mcp add --scope user git-forensics -- npx -y @jamie-bitflight/git-forensics-mcp
`

$3

Add to your MCP configuration file (~/.claude.json or Claude Desktop settings):

`json
{
"mcpServers": {
"git-forensics": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@jamie-bitflight/git-forensics-mcp"]
}
}
}
`

After adding the server, restart Claude Code or Claude Desktop to load the tools.

Usage

The server integrates with any MCP-compatible client. All analysis results are written to JSON files for easy consumption and sharing.

$3

Scenario: You're preparing to merge a feature branch and want to understand divergence from main.

Tool: get_branch_overview

Input:

`json
{
"repoPath": "/home/user/my-project",
"branches": ["main", "feature/user-auth"],
"outputPath": "/tmp/branch-analysis.json"
}
`

Result: JSON file containing:

- Last commits on both branches
- Number of commits on each since divergence
- Merge base commit details
- Summary statistics

$3

Scenario: Multiple developers modified authentication code. You need to identify conflict risks.

Tool: analyze_file_changes

Input:

`json
{
"repoPath": "/home/user/my-project",
"branches": ["feature/oauth2", "feature/jwt-auth"],
"files": ["src/auth/login.ts", "src/auth/session.ts"],
"outputPath": "/tmp/conflict-analysis.json"
}
`

Result: JSON file containing:

- Change history for each file across branches
- Identified overlapping time periods (potential conflicts)
- Risk levels (high: both branches touched same files)
- Recommended review order

$3

Scenario: Review all development activity during last sprint (Jan 1-15).

Tool: analyze_time_period

Input:

`json
{
"repoPath": "/home/user/my-project",
"branches": ["main", "develop"],
"timeRange": {
"start": "2025-01-01",
"end": "2025-01-15"
},
"outputPath": "/tmp/sprint-analysis.json"
}
`

Result: JSON file containing:

- All commits in date range categorized by type
- Summary showing breakdown (e.g., 15 features, 8 fixes, 3 refactors)
- Activity timeline

$3

All tools accept common parameters:

- repoPath (required): Absolute path to the git repository
- branches (required): Array of branch names to analyze (e.g., ["main", "develop"])
- outputPath (required): Where to write the analysis JSON file

Tool-specific parameters:

- timeRange (for analyze_time_period): Object with start and end dates (ISO 8601 format)
- files (for analyze_file_changes): Array of file paths relative to repository root

$3

All tools generate JSON files with consistent structure:

`json
{
"analysis": [
/ Tool-specific detailed results /
],
"summary": {
/ Statistical summaries /
/ Risk assessments (where applicable) /
/ Recommendations based on analysis /
}
}
`

> [!note]
> Output files can be large for repositories with extensive history. Consider using specific time ranges or file filters to focus analysis.

Requirements

$3

- Node.js 20+ - Required to run the MCP server
- Git - Must be installed and accessible via PATH
- MCP-compatible client - Such as Cursor, Gemini, Codex, Claude Code or Claude Desktop

$3

- Node.js 20+ - As specified in GitHub Actions workflows
- pnpm 9+ - Package manager (installation guide)

Contributing

Contributions are welcome! Whether you're fixing bugs, adding features, or improving documentation, we appreciate your help.

$3

`bash


Fork and clone the repository

git clone https://github.com/YOUR-USERNAME/git-forensics-mcp.git
cd git-forensics-mcp

Install dependencies (use pnpm, not npm)

pnpm install

Build the project

pnpm build

Test by listing available tools

pnpm tools:list
`

$3

All development tasks are managed through pnpm scripts:

`bash


Build the TypeScript source code

pnpm build

Start the MCP server (waits for JSON-RPC input on stdin)

Note: Running this directly will hang waiting for input. Use with piped JSON:

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | pnpm start

pnpm start

List available MCP tools from the running server

pnpm tools:list

Format code with Prettier

pnpm format

Check code formatting without making changes

pnpm format:check

Run pre-commit hooks manually

pnpm precommit

Test the release process in dry-run mode (preview without publishing)

pnpm nx release --dry-run

Perform a full release (version bump, changelog, git tag) without publishing

pnpm nx release --skip-publish
`

Development Tools:

- Prettier - Code formatting (configuration in .prettierrc)
- Husky - Pre-commit hooks that run formatting and validation automatically
- Nx Release - Automated versioning and publishing with conventional commits
- TypeScript strict mode - Type safety across all source files

$3

This project uses automated semantic versioning via Nx Release with conventional commits.

#### How It Works

1. Commit with conventional format - Use structured commit messages (see below)
2. Merge to main - GitHub Actions automatically:
- Analyzes commits since last release
- Calculates new version based on commit types
- Updates package.json and CHANGELOG.md
- Creates version bump commit and git tag
- Publishes to npmjs.org

#### Conventional Commit Format

`text
():