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:

npx @jamie-bitflight/git-forensics-mcp

Or add to Claude Code with a single command:

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:

1. Branch Overview (get_branch_overview)

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

2. Time Period Analysis (analyze_time_period)

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. File Changes Analysis (analyze_file_changes)

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

4. Merge Recommendations (get_merge_recommendations)

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

Option 1: Run Directly (No Installation)

Use npx to run the latest version without installing:

npx @jamie-bitflight/git-forensics-mcp

Option 2: Add to Claude Code (Recommended)

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

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

Option 3: Manual Configuration

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

{
  "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.

Example: Analyzing Branch Relationships

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

Tool: get_branch_overview

Input:

{
  "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

Example: Finding Potential Conflicts

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

Tool: analyze_file_changes

Input:

{
  "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

Example: Sprint Activity Review

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

Tool: analyze_time_period

Input:

{
  "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

Input Parameters Reference

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

Output Format

All tools generate JSON files with consistent structure:

{
  "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

For Users

• 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

For Development

• 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.

Development Setup

# 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

Development Commands

All development tasks are managed through pnpm scripts:

# 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

Release Process

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

<type>(<scope>): <subject>

<body>

<footer>

Types that trigger releases:

• feat: New feature → minor version bump (0.1.0 → 0.2.0)
• fix: Bug fix → patch version bump (0.1.0 → 0.1.1)
• perf: Performance improvement → patch version bump
• docs: Documentation changes → patch version bump
• refactor: Code refactoring → patch version bump

Types that don't trigger releases:

• test: Test changes (no version bump)
• chore: Maintenance tasks (no version bump)
• ci: CI/CD changes (no version bump)
• build: Build system changes (no version bump)

Breaking changes: Add ! after type (e.g., feat!:) or include BREAKING CHANGE: in footer for major version bump (0.1.0 → 1.0.0)

Examples:

feat: add branch divergence analysis
fix: correct merge base calculation
feat!: change output format to JSON-LD
docs: update installation instructions

[!important] Follow the conventional commit format for all contributions. This ensures proper automated versioning and changelog generation.

CHANGELOG and Versioning

• CHANGELOG.md is automatically generated by Nx Release and should not be edited manually
• CHANGELOG.md is included in .gitignore as it's regenerated during the release process
• Version numbers are calculated automatically based on conventional commit types

Testing Published Releases

You can validate any published version using the MCP Inspector in CLI mode:

Step 1: List available tools from published package

npx @modelcontextprotocol/inspector --cli npx @jamie-bitflight/git-forensics-mcp@VERSION --method tools/list

Expected output: JSON showing 4 tools with schemas:

• get_branch_overview
• analyze_time_period
• analyze_file_changes
• get_merge_recommendations

Step 2: Test a tool invocation

npx @modelcontextprotocol/inspector --cli npx @jamie-bitflight/git-forensics-mcp@VERSION \
  --method tools/call \
  --tool-name get_branch_overview \
  --tool-arg repoPath=/path/to/repo \
  --tool-arg 'branches=["main","feature"]' \
  --tool-arg outputPath=/tmp/test.json

Expected output: Success message indicating analysis written to file

Step 3: Verify output file contains valid analysis

cat /tmp/test.json

Expected output: Valid JSON with overview array and summary statistics

Validation Checklist

• Package installs via npx from npmjs.org
• MCP server responds to protocol requests
• All 4 tools listed with correct schemas
• Tool execution succeeds and generates output
• Output file contains valid repository analysis JSON

Project Structure

git-forensics-mcp/
├── src/
│   └── index.ts          # Single-file MCP server implementation
├── build/                # Compiled output (gitignored)
├── package.json          # Package configuration and scripts
├── tsconfig.json         # TypeScript configuration (strict mode)
└── README.md             # This file

The codebase is intentionally minimal:

• Single TypeScript file (src/index.ts) containing the entire MCP server
• Uses @modelcontextprotocol/sdk for MCP implementation
• TypeScript with strict mode enabled for type safety

Architecture Notes

The server is implemented as a single GitAnalysisServer class that:

• Registers four MCP tools with defined input schemas
• Executes git commands synchronously via execSync
• Writes JSON analysis results to specified file paths
• Runs on stdio transport for MCP communication

Key design decisions:

• Synchronous execution - Uses execSync for simplicity (git operations are typically fast)
• File-based output - Writes JSON files to handle large analysis results without overwhelming MCP protocol
• Monolithic structure - Single file/class for simplicity and ease of understanding
• No caching - Each invocation runs fresh git commands to ensure up-to-date analysis
• Strict TypeScript - All strict mode flags enabled for maximum type safety

License

This project is licensed under the Apache License, Version 2.0 - see the LICENSE.txt file for complete details.

What this means for you:

The Apache License 2.0 is a permissive open-source license that allows you to:

• Use commercially - Integrate into commercial products and services
• Modify freely - Adapt the code to your specific needs
• Distribute - Share the original or modified versions
• Create derivative works - Build new projects based on this code
• Include in other projects - Combine with code under different licenses

Requirements:

• Include the original license and copyright notice when distributing
• State significant changes made to the code
• Include a NOTICE file if one exists

Protections:

• Provides an express grant of patent rights from contributors
• Protects contributors from liability

Contributing:

All contributions will be licensed under the Apache License 2.0. By submitting a pull request, you agree to license your contribution under the same terms.

Copyright 2025. Licensed under the Apache License, Version 2.0; you may not use this project except in compliance with the License.