# GitHub MCP Server

MCP (Model Context Protocol) server exposing GitHub repository data as tools, a resource, and a prompt. Backed by GitHub's REST API via `httpx`.

## Setup

1. Install deps:
   ```bash
   uv sync
   ```
2. Copy env template and fill in your token:
   ```bash
   cp .env.example .env
   ```
   Generate a token at https://github.com/settings/tokens (needs `repo` scope for private repos, no scope needed for public read-only).

## Run

Start the MCP server (stdio transport):
```bash
uv run python server.py
```

Run the sample client (spawns the server and calls a tool):
```bash
uv run python client.py
```

## Tools

| Tool | Description |
|---|---|
| `get_repository(owner, repo)` | Repo summary — stars, forks, open issues, language |
| `search_issues(owner, repo, state="open")` | List issues (excludes PRs) |
| `list_pull_requests(owner, repo, state="open")` | List pull requests |
| `search_repository_issues(owner, repo, keyword)` | Keyword search over repo issues |

## Resource

`github://repo/{owner}/{repo}` — repository details as text.

## Prompt

`review_repository(owner, repo)` — generates a prompt to analyze repo health (issues, PRs, activity, risks).

## Project layout

- `server.py` — MCP server, all tools/resource/prompt
- `client.py` — sample MCP client exercising the server over stdio
- `github_service.py`, `test_github.py` — early prototype scratch, superseded by `server.py` (kept commented for reference)

## Giving this to a colleague

No manual clone needed — `uv` fetches and runs the server directly from the git repo. Each person still runs their own local copy with their own token; nothing is centrally hosted.

1. **Register the server with Claude Code** (one command, no clone/install step):
   ```bash
   claude mcp add github-assistant --scope local -- uvx --from git+https://github.com/ritesh31/github-mcp github-mcp
   ```
   Replace the URL with this repo's actual location once pushed. `uv` caches the repo behind the scenes on first run — no visible clone step. `--scope local` keeps it private to their machine.
2. **Provide `GITHUB_TOKEN`.** Since there's no local clone, there's no `.env` file to edit — pass the token as an environment variable on the `claude mcp add` command instead:
   ```bash
   claude mcp add github-assistant --scope local -e GITHUB_TOKEN=ghp_yourColleaguesOwnTokenHere -- uvx --from git+https://github.com/ritesh31/github-mcp github-mcp
   ```
   Each person uses their own token (generate at https://github.com/settings/tokens — read-only, fine-grained, scoped to needed repos).
3. **Verify:**
   ```bash
   claude mcp list
   ```
   Should show `github-assistant` as Connected. Open a Claude Code session and run `/mcp` to confirm all 4 tools, the resource, and the prompt are discovered.
4. **Test:** ask Claude something like *"what's the star count on `<owner>/<repo>`?"* — it should pick the `get_repository` tool on its own.