# GitHub Tools MCP Server

A real [Model Context Protocol](https://modelcontextprotocol.io) server
exposing read-only tools against the GitHub REST API — installable into
Claude Desktop or Claude Code in under a minute — plus a separate web demo
exercising the same tool logic through an ordinary chat UI.

**Live demo:** https://mcp-demo-phi.vercel.app/demo

## Status: what this is and isn't

**Working and deployed.** All 5 tools verified against real GitHub data,
42 automated checks across 3 test suites, and the full app confirmed live
on the real production URL. See [`DESIGN_LOG.md`](DESIGN_LOG.md) for the
running, honest account of every decision and bug along the way.

**The web demo is NOT an MCP transport.** It's plain FastAPI calling the
same `tools.py` functions directly as Python, not speaking the MCP protocol.
Genuinely useful distinction to be precise about — see `DESIGN_LOG.md`
section 3 for why a real remote MCP transport isn't attempted here.

## Architecture

```
                    ┌─────────────────────┐
                    │      tools.py        │  <- 5 pure functions, no
                    │  (GitHub REST calls   │     MCP-specific code
                    │   via github_client)   │
                    └──────────┬───────────┘
                               │
              ┌────────────────┴────────────────┐
              │                                  │
    ┌─────────▼─────────┐            ┌───────────▼──────────┐
    │     server.py       │            │     api/index.py       │
    │  MCPServer, stdio    │            │  FastAPI, POST /chat    │
    │  transport            │            │  real Claude tool-      │
    │  -> Claude Desktop/    │            │  calling loop over       │
    │     Claude Code        │            │  the same tools           │
    └─────────────────────┘            └────────────────────────┘
     THE MCP SERVER                      A PLAIN HTTP DEMO OF
     (the real deliverable)              THE SAME TOOL LOGIC
```

## Setup

```bash
cp .env.example .env   # GITHUB_TOKEN (both halves), ANTHROPIC_API_KEY (web demo only)
pip install -r requirements.txt
```

## Run the MCP server locally

```bash
python3 server.py
```

**Add to Claude Desktop**: edit
`%APPDATA%\Claude\claude_desktop_config.json` (Windows) /
`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS),
merging in the contents of `claude_desktop_config.example.json` (fill in
your real `GITHUB_TOKEN` and the absolute path to `server.py`), then
restart Claude Desktop. **Add to Claude Code**: `claude mcp add` or edit
your project's `.mcp.json` the same way.

Manual interactive dev workflow: the SDK ships an inspector for poking at
the server by hand without a full client —
`npx @modelcontextprotocol/inspector python3 server.py`.

## Run the web demo locally

```bash
export $(cat .env | xargs)
uvicorn api.index:app --reload --port 8020
```

## Design log

Every non-obvious decision, plus the SDK API surface verified against the
actually-installed package rather than assumed from possibly-stale docs, is
in [`DESIGN_LOG.md`](DESIGN_LOG.md).