# GitHub Issues MCP Server

An MCP (Model Context Protocol) server for discovering and triaging open-source GitHub issues — built by hand, connected to Claude Desktop, and used to find good-fit issues to contribute to (SGLang, vLLM, and beyond).

## Features

- **`fetch_issue(repo, issue_number)`** — Get details of a single issue: title, body, state, comments, labels, and whether it's a PR.
- **`list_issues(repo, state, labels, sort, direction, include_prs)`** — Fetch and filter a repo's issues by state, labels, and sort order (up to 100 per call).
- **`find_related_prs(repo, issue_number)`** — Checks an issue's timeline for linked pull requests, and reports whether any are open or merged.

## Setup

1. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

2. Create a `.env` file in the project root:
   ```
   GITHUB_TOKEN=your_personal_access_token
   ```
   Generate a token at GitHub → Settings → Developer settings → Personal access tokens (read-only, `public_repo` scope is enough).

3. Test locally with the MCP inspector:
   ```bash
   mcp dev server.py
   ```

## Connecting to Claude Desktop

Add the server to Claude Desktop's MCP config (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "github-issues": {
      "command": "uv",
      "args": ["run", "--with", "mcp", "mcp", "run", "/absolute/path/to/server.py"]
    }
  }
}
```

Fully quit and reopen Claude Desktop. Once connected, you can ask things like:
> "Find open good first issues in sgl-project/sglang"

and Claude will call the tools directly and return live results.

## Project Structure

```
├── server.py                  # MCP server entry point, tool registration
├── github_client.py           # GitHub API wrapper (auth, requests, error handling)
├── tools/
│   ├── fetch_issue.py
│   ├── list_issues.py
│   └── find_related_prs.py
└── requirements.txt
```

## Notes

- Uses the GitHub REST API with a personal access token (free, 5,000 requests/hour authenticated).
- Rate limiting and deep error handling are intentionally out of scope for this version — basic status code checks only (200 / 404 / 401 / other).
- `find_related_prs` relies on the issue timeline endpoint's `cross-referenced` events; issues closed manually (without a linked PR) will correctly show no linked PR.

## License

MIT