# tai-mcp-github

A minimal [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that exposes a focused set of GitHub PR review tools to AI agents.

## Why

The official `github/github-mcp-server` exposes 60+ tools (Actions, Discussions, Dependabot, secret scanning, gists, etc.). This inflates the MCP schema sent to the LLM on every request, increasing token usage and noise. This server limits the surface to exactly what is needed for a PR review workflow — nothing more.

## Tools

| Tool | Description |
|---|---|
| `list_pull_requests` | List open (or closed/all) PRs for a repository |
| `get_pull_request` | Get full details of a specific PR |
| `list_pr_comments` | List general thread comments on a PR (conversation tab) |
| `list_unresolved_review_threads` | List unresolved inline review threads (diff comments) |
| `resolve_review_thread` | Mark an inline review thread as resolved |

## Requirements

- Python 3.12+
- [uv](https://docs.astral.sh/uv/)
- A GitHub Personal Access Token with **Pull requests: Read** (and **Write** if you want to resolve threads)

## Setup

```bash
git clone <repo-url>
cd tai-mcp-github

cp .env.example .env
# Edit .env and set GITHUB_TOKEN=your_pat_here
```

## Usage

### Run the server

```bash
uv run server.py
```

### Use with Claude Code

Add to your MCP configuration (e.g. `~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "github-pr-review": {
      "command": "uv",
      "args": ["run", "server.py"],
      "cwd": "/path/to/tai-mcp-github"
    }
  }
}
```

## Development

### Run tests

```bash
uv run --with pytest --with pytest-asyncio pytest tests/ -v
```

### Lint and type-check

```bash
uv run --with ruff ruff check .
uv run --with ruff ruff format --check .
uv run --with mypy mypy server.py
```

### Git hooks

Pre-commit (ruff + mypy) and pre-push (tests) hooks are provided. Install them once:

```bash
cp .git/hooks/pre-commit .git/hooks/pre-commit  # already in place after clone
```

> Note: git hooks are local only. Run the script below on a fresh clone to activate them.

```bash
chmod +x .git/hooks/pre-commit .git/hooks/pre-push
```

## Tech stack

- **[fastmcp](https://github.com/jlowin/fastmcp)** — MCP server framework
- **[PyGithub](https://pygithub.readthedocs.io)** — GitHub REST API client
- **[httpx](https://www.python-httpx.org)** — HTTP client used for GitHub GraphQL API calls
- **[python-dotenv](https://saurabh-kumar.com/python-dotenv/)** — `.env` file support
- **[ruff](https://docs.astral.sh/ruff/)** — linting and formatting
- **[mypy](https://mypy-lang.org)** — static type checking
- **[pytest](https://pytest.org)** — testing

## Architecture

```
server.py          # Single-file MCP server — all tools live here
tests/
└── test_server.py # Unit tests (fully mocked, no GitHub calls)
```

The server is intentionally stateless — no caching, sessions, or background tasks. Each tool maps directly to one GitHub API call:

- PR listing and detail use the **GitHub REST API** via PyGithub
- Review thread listing and resolving use the **GitHub GraphQL API** via a single `httpx` POST (the GraphQL `resolveReviewThread` mutation is not available on the REST API)

Authentication is via a GitHub Personal Access Token passed through the `GITHUB_TOKEN` environment variable. No OAuth or GitHub App flows are needed.

## Scope

This server is read-focused. Explicitly out of scope:

- Git operations (commits, pushes, branch management) — do these locally
- Any GitHub feature outside the PR review workflow (Actions, Issues, Releases, etc.)