Content
# GitPulse AI
**An MCP server that gives AI assistants (Claude, ChatGPT, etc.) the ability to analyse the health of any public GitHub repository — plus a React dashboard for visualising the results.**
GitPulse AI answers questions like *"Is this repo healthy?"*, *"Review this pull request"*, and *"Which issues should I fix first?"* by combining live GitHub data with LLM-generated narratives, scores, and recommendations.
---
## What it does
GitPulse exposes five tools over the **Model Context Protocol (MCP)**, so any MCP-compatible AI client can call them directly during a conversation:
| Tool | Description |
|---|---|
| `get_repo_health` | Scores a repo 0–100 and classifies it as `Healthy`, `Stagnant`, `At Risk`, or `Archived`, with an AI-written narrative of strengths, risks, and recommendations. |
| `review_file` | Reviews a single file for code quality, naming, documentation coverage, complexity, and potential bugs. |
| `review_pull_request` | Reviews every changed file in a PR and produces a per-file review plus an overall summary. |
| `triage_issues` | Classifies open issues as High Priority Bug, Stale, Good First Issue, Documentation Request, or Feature Request, with maintainer recommendations. |
| `full_repo_assessment` | Combines health, triage, and quality checks (README, security, CI/CD, contribution health) into one complete report. |
A companion React dashboard (currently running on mock data) visualises this data: repo lists, health scores, activity charts, and an AI insights panel.
---
## Architecture
```
End User
│ "Is this repository healthy?"
▼
MCP Client (Claude / ChatGPT)
│ Tool call (JSON-RPC over stdio)
▼
GitPulse MCP Server (Python)
│
├── GitHub API Layer ──────► GitHub REST API (auth, retries, caching)
├── LLM Processing Layer ───► OpenAI API (narrative generation)
└── Analysis Engine ───────► Health scoring · Code review · Issue triage
│
▼
Structured JSON + natural-language report → back to the AI client
```
Each tool is a stateless, independently testable service — see [`architecture.md`](./architecture.md) for the full breakdown of every component, and [`techstack.md`](./techstack.md) for why each library was chosen.
---
## Project structure
```
GitPulse-AI/
├── gitpulse_mcp/ # The MCP server package (source of truth)
│ ├── main.py # Registers the 5 tools, stdio transport entry point
│ ├── config.py # Pydantic settings (env-driven)
│ ├── api/ # Optional FastAPI HTTP layer (for the dashboard / testing)
│ ├── github/ # GitHub REST API client (repo, commits, issues, PRs, files)
│ ├── llm/ # LLM client, prompt templates, structured response schemas
│ ├── services/ # health / review / triage / assessment business logic
│ ├── cache/ # Session-level response caching
│ └── tests/ # Unit tests for the package
├── src/ # React + TypeScript dashboard (Vite)
│ ├── pages/ # Landing, Dashboard, Repo Details, AI Insights
│ ├── components/ # Navbar, Sidebar, RepoTable, etc.
│ └── data/mockData.ts # Mock data (dashboard isn't wired to the API yet)
├── tests/ # Root-level test suite (mirrors gitpulse_mcp/tests)
├── demo.py # Minimal script to call a tool directly, no MCP client needed
├── architecture.md # Full system design write-up
├── techstack.md # Technology choices and rationale
└── project-context.md # Project background / goals
```
---
## Getting started
### Prerequisites
- Python 3.11+
- Node.js 18+ (for the dashboard)
- A [GitHub Personal Access Token](https://github.com/settings/tokens) (no special scopes needed for public repos)
- An [OpenAI API key](https://platform.openai.com/api-keys)
### 1. Backend — MCP server
```bash
# Install the package with dev dependencies
pip install -e ".[dev]"
# Configure environment variables
cp .env.example .env # then fill in GITHUB_TOKEN and OPENAI_API_KEY
```
`.env` should contain at minimum:
```
GITHUB_TOKEN=ghp_your_token_here
OPENAI_API_KEY=sk-your_key_here
```
Run the MCP server (stdio transport, for use with Claude Desktop or MCP Inspector):
```bash
python -m gitpulse_mcp.main
```
Or try a tool directly without an MCP client:
```bash
python demo.py
```
Optionally, run the FastAPI HTTP layer (useful for local testing or powering the dashboard):
```bash
pip install fastapi uvicorn
uvicorn gitpulse_mcp.api.main:app --reload
```
### 2. Connect to Claude Desktop
Add GitPulse to your Claude Desktop MCP config (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"gitpulse": {
"command": "python",
"args": ["-m", "gitpulse_mcp.main"]
}
}
}
```
Restart Claude Desktop and ask something like *"Use GitPulse to check the health of facebook/react."*
### 3. Frontend — dashboard
```bash
npm install
npm run dev
```
This starts the Vite dev server. The dashboard currently renders against mock data in `src/data/mockData.ts`; wiring it to the FastAPI layer is on the roadmap.
---
## Running tests
```bash
python -m pytest tests/ -v
```
The suite covers the GitHub client, caching, models, and all four services (health, review, triage, assessment) with 65+ tests using `respx` to mock GitHub/OpenAI HTTP calls.
---
## Configuration
All runtime settings live in `gitpulse_mcp/config.py` and are loaded from `.env`:
| Variable | Default | Description |
|---|---|---|
| `GITHUB_TOKEN` | — | GitHub Personal Access Token (required) |
| `OPENAI_API_KEY` | — | OpenAI API key (required) |
| `OPENAI_MODEL` | `gpt-4o-mini` | LLM used for narrative generation |
| `WEIGHT_COMMIT_FREQ` | `0.30` | Health score weight — commit frequency |
| `WEIGHT_PR_MERGE_RATIO` | `0.25` | Health score weight — PR merge ratio |
| `WEIGHT_ISSUE_CLOSE_RATE` | `0.25` | Health score weight — issue close rate |
| `WEIGHT_CONTRIBUTOR_ACTIVITY` | `0.20` | Health score weight — contributor activity |
| `ACTIVITY_LOOKBACK_DAYS` | `30` | Days of history used for activity metrics |
| `CACHE_TTL_SECONDS` | `300` | Session cache TTL (`0` disables caching) |
The four `WEIGHT_*` values must sum to 1.0 — the app raises a validation error on startup if they don't.
---
## Tech stack
- **MCP server:** Python 3.11, [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk), HTTPX (async GitHub calls), Pydantic v2, OpenAI SDK
- **Optional HTTP layer:** FastAPI + Uvicorn
- **Dashboard:** React 18, TypeScript, Vite, Tailwind CSS, Framer Motion, Recharts, lucide-react
- **Testing:** pytest, pytest-asyncio, respx
See [`techstack.md`](./techstack.md) for the full rationale behind each choice.
---
## Status
This is a student-built project (see [`project-context.md`](./project-context.md) for background). The MCP server and its five tools are functional and tested; the React dashboard is a standalone UI currently driven by mock data, with backend integration planned next.
## License
MIT — see [`LICENSE`](./LICENSE).
