# mcp-git-chronicle

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

A zero-dependency Model Context Protocol (MCP) server providing deep Git archaeology, churn hotspot detection, and co-change coupling analysis to AI coding agents (OpenCode, Cursor, Claude Code).

---

## Why mcp-git-chronicle?

AI coding agents make bad assumptions when editing code without knowing the repository's history:
1. **Volatile Code**: They modify fragile files that historically cause high bug rates.
2. **Hidden Coupling**: They edit a function or schema in File A, completely unaware that File B and File C *always* need matching changes.
3. **Missing Context**: They fail to understand *why* a particular architecture decision was made 3 months ago.

`mcp-git-chronicle` connects your agents directly to local Git plumbing via standard MCP tools over `stdio`.

---

## Tools Exposed

| Tool Name | Parameters | Description |
| :--- | :--- | :--- |
| `git_churn_hotspots` | `cwd`, `since`, `limit` | Identifies top files with highest churn (additions + deletions) and commit volume. |
| `git_co_changes` | `file`, `cwd`, `limit` | Calculates semantic file coupling (which files historically commit together with target). |
| `git_recent_context` | `cwd`, `count`, `path` | Summarizes recent commit subjects, hashes, and authors to anchor agent awareness. |

---

## Setup with Coding Agents

### OpenCode / Cursor (`~/.config/opencode/config.json` or `.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "git-chronicle": {
      "command": "npx",
      "args": ["-y", "mcp-git-chronicle"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add git-chronicle npx mcp-git-chronicle
```

---

## License

MIT © [luckdevx](https://github.com/luckdevx)