# Git Intelligence MCP Server

> A lightweight Model Context Protocol (MCP) server that turns Git history into actionable repository insights.

<p align="center">
  <img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white" alt="Python">
  <img src="https://img.shields.io/badge/MCP-Server-8A2BE2" alt="MCP Server">
  <img src="https://img.shields.io/badge/GitPython-Supported-F05032?logo=git&logoColor=white" alt="GitPython">
  <img src="https://img.shields.io/badge/Transport-stdio-4B5563" alt="stdio">
</p>

## Overview

**Git Intelligence MCP** is a local MCP server that allows AI assistants to analyze Git repository history through natural-language requests.

Instead of manually running Git commands and interpreting commit history, an MCP-compatible client can call dedicated tools to discover:

* Frequently changed files
* Contributor ownership patterns
* Code churn over time

The project is intentionally lightweight and implemented in a single Python file using the official **MCP Python SDK** and **GitPython**.

---

## Why Git Intelligence?

Git history contains useful engineering signals, but extracting them manually can be repetitive.

With Git Intelligence, you can ask questions such as:

> "Which files have changed the most?"

> "How many developers have worked on `server.py`?"

> "How much code has changed since January 2026?"

The MCP server translates these natural-language requests into structured tool calls and analyzes the repository's Git history.

```text
Natural Language
       │
       ▼
   MCP Client
       │
       ▼
Git Intelligence MCP
       │
   ┌───┼────────┐
   ▼   ▼        ▼
Hotspots  Bus Factor  Churn
   │   │        │
   └───┼────────┘
       ▼
 Git Repository
       │
       ▼
 Repository Insights
```

---

## Features

| Feature                  | Description                                           |
| ------------------------ | ----------------------------------------------------- |
| Hotspot Analysis         | Finds files changed most frequently                   |
| Bus Factor Analysis      | Counts distinct contributors for a file               |
| Code Churn Analysis      | Calculates lines added and removed since a date       |
| Natural-Language Access  | Allows AI clients to invoke Git analysis tools        |
| Local Repository Support | Works directly with cloned Git repositories           |
| Lightweight Architecture | No database or external service required              |
| MCP Inspector Support    | Easy local tool testing and debugging                 |
| VS Code Support          | Can be connected directly to VS Code as an MCP client |

---

## Available MCP Tools

### 1. `hotspots`

Identifies the files that have been changed most frequently throughout the repository's commit history.

**Arguments**

| Argument    | Type      |  Default | Description                      |
| ----------- | --------- | -------: | -------------------------------- |
| `repo_path` | `string`  | Required | Path to the local Git repository |
| `top_n`     | `integer` |     `10` | Number of files to return        |

**Example prompt**

```text
Use Git Intelligence to find the top 5 hotspot files in this repository.
```

**Example tool call**

```text
hotspots(
    repo_path="E:/projects/my-repo",
    top_n=5
)
```

**Example result**

```text
42 commits — server.py
27 commits — README.md
18 commits — config.py
12 commits — utils.py
9 commits — tests/test_server.py
```

A frequently modified file can be a useful signal for identifying areas that may deserve additional review or testing.

---

### 2. `bus_factor`

Determines how many distinct contributors have modified a specific file.

**Arguments**

| Argument    | Type     | Description                      |
| ----------- | -------- | -------------------------------- |
| `repo_path` | `string` | Path to the local Git repository |
| `file_path` | `string` | File to analyze                  |

**Example prompt**

```text
Use Git Intelligence to find how many developers have modified server.py.
```

**Example tool call**

```text
bus_factor(
    repo_path="E:/projects/my-repo",
    file_path="server.py"
)
```

**Example result**

```text
server.py: 3 distinct author(s) — Alice, Bob, Charlie
```

A low contributor count can indicate potential knowledge concentration around a particular file.

---

### 3. `churn_since`

Calculates the total number of lines added and removed since a specified date.

**Arguments**

| Argument     | Type     | Description                       |
| ------------ | -------- | --------------------------------- |
| `repo_path`  | `string` | Path to the local Git repository  |
| `since_date` | `string` | Start date in `YYYY-MM-DD` format |

**Example prompt**

```text
Use Git Intelligence to calculate the code churn since 2026-01-01.
```

**Example tool call**

```text
churn_since(
    repo_path="E:/projects/my-repo",
    since_date="2026-01-01"
)
```

**Example result**

```text
Since 2026-01-01: +842 / -391 lines
```

This provides a simple view of how much code has been added and removed during a given period.

---

## Example Workflow

Once connected to an MCP-compatible client, you can interact with the repository using natural language.

### Find repository hotspots

```text
Use Git Intelligence to find the top 5 most frequently changed files.
```

↓

```text
hotspots()
```

↓

```text
Repository history
```

↓

```text
Top 5 hotspot files
```

### Investigate file ownership

```text
How many different developers have worked on server.py?
```

↓

```text
bus_factor()
```

↓

```text
Distinct contributors
```

### Analyze development activity

```text
How many lines have been added and removed since 2026-06-01?
```

↓

```text
churn_since()
```

↓

```text
Code churn statistics
```

---

## MCP Client Compatibility

The server uses **stdio transport**, making it suitable for local MCP-compatible clients.

It has been tested with:

* **MCP Inspector** — local development and tool testing
* **VS Code** — MCP client integration

The architecture remains simple:

```text
┌───────────────────┐
│   MCP Client      │
│                   │
│ MCP Inspector     │
│ VS Code           │
└─────────┬─────────┘
          │
        stdio
          │
          ▼
┌───────────────────┐
│ Git Intelligence  │
│    MCP Server     │
├───────────────────┤
│ hotspots()        │
│ bus_factor()      │
│ churn_since()     │
└─────────┬─────────┘
          │
          ▼
┌───────────────────┐
│  Local Git Repo   │
└───────────────────┘
```

---

## Demo

### MCP Inspector

The MCP server was tested locally using MCP Inspector to verify tool discovery and execution.

![MCP Inspector](assets/mcp-inspector.png)

### VS Code Integration

The server was also connected to VS Code as an MCP client and its tools were successfully discovered.

![VS Code MCP Integration](assets/vscode-mcp.png)

---

## Tech Stack

* **Python 3.10+**
* **MCP Python SDK**
* **FastMCP**
* **GitPython**
* **Git**
* **stdio transport**

The server uses the decorator-based `FastMCP` API to expose Python functions as MCP tools.

---

## Project Structure

The project intentionally keeps the implementation minimal:

```text
git-intel-mcp/
│
├── .vscode/
│   └── mcp.json
│
├── assets/
│
├── server.py
├── requirements.txt
├── README.md
└── .gitignore
```

### Why a single `server.py`?

This project is designed as a focused MCP learning implementation rather than a large production application.

Keeping the core implementation in one file makes the MCP architecture easy to understand:

```text
Define Tool
    ↓
@mcp.tool()
    ↓
MCP Tool Schema
    ↓
MCP Client
    ↓
Tool Call
    ↓
GitPython
    ↓
Git Repository
    ↓
Result
```

As the functionality grows, the tools can be separated into dedicated modules.

---

## Installation

### 1. Clone the repository

```bash
git clone https://github.com/s-zaid-13/git-intel-mcp.git
cd git-intel-mcp
```

### 2. Create a virtual environment

#### Windows

```bash
python -m venv venv
venv\Scripts\activate
```

#### macOS / Linux

```bash
python -m venv venv
source venv/bin/activate
```

### 3. Install dependencies

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

---

## Requirements

```text
mcp[cli]<2.0.0
gitpython
```

---

## Run Locally

Start the MCP server with:

```bash
python server.py
```

The server uses **stdio transport**, so it does not start a traditional web server.

It waits for an MCP-compatible client to establish a connection.

---

## Test with MCP Inspector

MCP Inspector provides an interactive environment for testing MCP servers locally.

Run:

```bash
mcp dev server.py
```

Then:

1. Connect to the server
2. Inspect the available tools
3. Review their generated schemas
4. Provide arguments
5. Execute the tools
6. Verify the returned results

The following tools should be available:

```text
hotspots
bus_factor
churn_since
```

---

## Connect to VS Code

The MCP server can also be connected directly to VS Code.

Create:

```text
.vscode/mcp.json
```

Example configuration for Windows:

```json
{
  "servers": {
    "gitIntelligence": {
      "type": "stdio",
      "command": "E:\\Spiral Lab\\git-intel-mcp\\venv\\Scripts\\python.exe",
      "args": [
        "E:\\Spiral Lab\\git-intel-mcp\\server.py"
      ],
      "cwd": "E:\\Spiral Lab\\git-intel-mcp"
    }
  }
}
```

After connecting, the following MCP tools should be discoverable in VS Code:

```text
gitIntelligence
├── hotspots
├── bus_factor
└── churn_since
```

Example request:

```text
Use Git Intelligence to find the top 5 hotspot files in this repository.
```

---

## How It Works

The server is built using `FastMCP`.

A tool is exposed using the MCP SDK decorator:

```python
@mcp.tool()
def hotspots(repo_path: str, top_n: int = 10) -> str:
    ...
```

FastMCP uses the function signature and documentation to generate the tool definition that an MCP client can discover.

The complete flow is:

```text
Python Function
      │
      ▼
@mcp.tool()
      │
      ▼
MCP Tool Definition
      │
      ▼
MCP Client
      │
      ▼
Tool Call
      │
      ▼
GitPython
      │
      ▼
Git History
      │
      ▼
Analysis Result
```

---


## MCP Concepts Demonstrated

### Tools

The server exposes three callable MCP tools:

```text
hotspots
bus_factor
churn_since
```

These allow an AI client to perform repository analysis.

### Client-Server Architecture

The MCP client does not need to know how the Git analysis is implemented internally.

It only needs to know:

* Which tools are available
* What arguments they accept
* What results they return

```text
MCP Client
     │
     │ MCP
     ▼
MCP Server
     │
     ▼
Git Repository
```

### stdio Transport

The local server communicates using **stdio**, which is well suited for locally running MCP servers and development clients.

---

## Limitations

This implementation intentionally keeps the scope small.

* Only local Git repositories are supported.
* Large repositories may require additional processing time.
* Churn measures quantity of change, not code quality.

These limitations keep the project focused on understanding MCP rather than building a complete repository analytics platform.

---



## Learning Outcome

This project demonstrates the fundamentals of building an MCP server with Python:

* Creating an MCP server with the official Python SDK
* Defining tools with `FastMCP`
* Understanding MCP tool schemas
* Using stdio transport
* Connecting an MCP server to MCP clients
* Testing tools with MCP Inspector
* Integrating a custom MCP with VS Code
* Preparing an MCP project for public sharing

The main takeaway is simple:

> **MCP provides a standardized way for AI applications to discover and interact with external tools and capabilities.**

---

## Author

**Samama Zaid**

Built as a hands-on project for learning and implementing the **Model Context Protocol with Python**.