# GitHub Portfolio Intelligence MCP Server

A custom MCP server that gives Claude deep analysis superpowers over GitHub repositories.

## What It Does

Expose 5 MCP tools so Claude can answer questions like:

- "Analyze this repo's code quality and tell me what's missing for production readiness"
- "Which contributor is most active and what areas do they own?"
- "What are the most common bug patterns from the last 30 issues?"
- "Generate a technical README for this repo based on the actual code"
- "Compare these two repos and tell me which is better architected"

## Tools

| Tool | Description |
|------|-------------|
| `get_repo_summary` | Stars, forks, languages, topics, last commit date |
| `get_recent_commits` | Last N commits with author, message, files changed |
| `get_open_issues` | Open issues with labels, comment count, age |
| `get_contributors` | Contributor stats, commit counts, top files per person |
| `analyze_code_quality` | Pulls key files, optional LLM analysis, structured quality report |

## Prerequisites

- Python 3.12+
- [uv](https://docs.astral.sh/uv/) package manager
- GitHub Personal Access Token ([create one here](https://github.com/settings/tokens))
- Groq API key (optional, free tier — enables LLM-powered code quality analysis via [Groq Console](https://console.groq.com/keys))

## Setup

### 1. Install dependencies

```powershell
cd "C:\Users\TAHA\GitHub Portfolio Intelligence Server"
uv sync
```

### 2. Configure environment

```powershell
copy .env.example .env
```

Edit `.env` and set your tokens:

```
GITHUB_TOKEN=ghp_your_token_here
GROQ_API_KEY=gsk_your_key_here
```

**GitHub token scopes:** `public_repo` for public repos, `repo` for private repos.

### 3. Test locally

**Quick check** (verify imports and dependencies):

```powershell
uv run python -c "import server; print('Server modules OK')"
```

**Interactive testing** (opens MCP Inspector in your browser):

```powershell
uv run mcp dev server.py
```

**Direct run** (how Claude Desktop launches it):

```powershell
uv run python server.py
```

The server uses **stdio transport** — it waits silently for JSON-RPC messages from an MCP client. If you press Enter in the terminal, you may see harmless `Invalid JSON` errors (that's just a blank line hitting stdin). Do not type into the terminal; use MCP Inspector or Claude Desktop instead.

## Claude Desktop Integration

### Config file location (Windows)

**Standard install:**
```
%APPDATA%\Claude\claude_desktop_config.json
```

**MSIX / Windows Store install** (config may be ignored if you edit the wrong path):
```
%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json
```

Open Claude Desktop → **Settings → Developer → Edit Config** to find the correct file.

### Add the server

Merge this into your `claude_desktop_config.json` (see `claude_desktop_config.example.json`):

```json
{
  "mcpServers": {
    "github-intelligence": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\TAHA\\GitHub Portfolio Intelligence Server",
        "run",
        "server.py"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here",
        "GROQ_API_KEY": "gsk_your_key_here"
      }
    }
  }
}
```

**Windows tips:**
- Use absolute paths for `--directory`
- If Claude Desktop can't find `uv`, use the full path: `C:\\Users\\TAHA\\.local\\bin\\uv.exe`
- Env vars in the config `env` block are required — Claude Desktop subprocesses don't read `.env`
- Fully quit Claude Desktop (tray icon → Quit) after saving config

### Verify

After restarting Claude Desktop, you should see **github-intelligence** in the MCP tools list. Try:

> "Use get_repo_summary on microsoft/vscode"

## Error Handling

All tools return structured error objects instead of crashing:

| Error | Response |
|-------|----------|
| Rate limited | `{"error": "rate_limited", "reset_at": "..."}` |
| Not found / private | `{"error": "not_found", "message": "..."}` |
| Bad token | `{"error": "auth_failed", "message": "..."}` |
| Timeout | `{"error": "timeout", "message": "..."}` |

## Project Structure

```
├── server.py                        # FastMCP entry point + 5 tools
├── github_client.py                 # Async GitHub API client
├── claude_desktop_config.example.json
├── .env.example
├── pyproject.toml
└── README.md
```

## License

MIT