# git-repo-analyzer-mcp

`git-repo-analyzer-mcp` is a local MCP server that exposes lightweight Git history analysis tools over `stdio`.

It is designed for MCP clients such as Codex that need to inspect a local repository without modifying it. The server shells out to the local `git` executable and returns structured JSON results.

## Tools

The server exposes four tools:

- `commit_frequency`: count commits per author
- `avg_diff_stats`: compute average added and removed lines per commit
- `blame_summary`: summarize current line ownership for one file
- `co_changed_files`: find file pairs that are frequently changed together

## Requirements

- Python 3.10+ recommended
- Git installed and available on `PATH`
- Filesystem access to the target repositories

## Install

Install the only runtime dependency:

```powershell
pip install mcp
```

Or install from this repository:

```powershell
pip install -r requirements.txt
```

## Run

Start the server directly:

```powershell
python .\server.py
```

The server uses `stdio`, so it is meant to be launched by an MCP client rather than used as a standalone CLI.

## Register With Codex

Example:

```powershell
codex mcp add git-analyzer C:\Python313\python.exe D:\GitFile\git-repo-analyzer-mcp\server.py
```

Adjust the Python path and repository path for your machine.

## Tool Reference

### `commit_frequency`

Counts commits by author using `git log --pretty=format:%an`.

Parameters:

- `repo_path`: path to the local Git repository
- `author`: optional exact author-name filter

Example:

```json
{
  "repo_path": "D:\\GitFile\\Book-Tracker"
}
```

Returns:

```json
{
  "total_commits": 4,
  "by_author": {
    "AntonyWhatsup": 4
  }
}
```

### `avg_diff_stats`

Computes average added and removed lines per commit from `git log --numstat`.

Parameters:

- `repo_path`: path to the local Git repository
- `author`: optional exact author-name filter

Example:

```json
{
  "repo_path": "D:\\GitFile\\Book-Tracker",
  "author": "AntonyWhatsup"
}
```

Returns:

```json
{
  "commits": 4,
  "avg_added": 721.5,
  "avg_removed": 0.2
}
```

### `blame_summary`

Runs `git blame --line-porcelain` and groups the current file's lines by author.

Parameters:

- `repo_path`: path to the local Git repository
- `file_path`: repository-relative path to the file

Example:

```json
{
  "repo_path": "D:\\GitFile\\Book-Tracker",
  "file_path": "src/App.tsx"
}
```

Returns:

```json
{
  "file": "src/App.tsx",
  "total_lines": 91,
  "by_author": {
    "AntonyWhatsup": {
      "lines": 91,
      "percent": 100.0
    }
  }
}
```

### `co_changed_files`

Scans commit history and counts how often pairs of files appear in the same commit.

Parameters:

- `repo_path`: path to the local Git repository
- `top_n`: maximum number of file pairs to return, default `20`

Example:

```json
{
  "repo_path": "D:\\GitFile\\Book-Tracker",
  "top_n": 5
}
```

Each result item contains:

- `file_a`
- `file_b`
- `times_changed_together`

## Behavior

- All tools analyze the current local Git history in the target repository.
- Author filtering is exact string matching against the author name Git reports.
- Git commands time out after 15 seconds.
- Git failures are surfaced as runtime errors from the server.

## Limitations

- `co_changed_files` can be skewed by large commits that touch many files.
- `blame_summary` reports current blame ownership, not historical ownership over time.
- Binary files and rename edge cases are only handled as far as the underlying Git commands support them.
- This project is intentionally read-only; it does not expose repository mutation tools.