# github-mcp

Four GitHub "superpowers" as an [mcp-use](https://github.com/mcp-use/mcp-use) MCP App — each a **tool + React widget** that renders inside Claude, ChatGPT, or any MCP Apps-compatible client. Write once, render everywhere.

| Tool | Ask it | Widget |
|---|---|---|
| `repo-scorecard` | "how healthy is vercel/next.js?" | Health ring + stat grid + contributors |
| `compare-repos` | "next.js vs remix?" | Side-by-side table, winner per metric |
| `commit-heatmap` | "how active is langchain?" | 52-week commit heatmap |
| `trending-mcp` | "hottest MCP servers this week?" | Ranked list with star deltas |

## Quick start

```bash
npm install
cp .env.example .env      # then paste a GITHUB_TOKEN
npm run dev               # server on :3000, Inspector at /inspector
```

Open `http://localhost:3000/inspector`, list tools, and call e.g. `repo-scorecard` with `{ "repo": "vercel/next.js" }`.

## GitHub token

A token is strongly recommended — it lifts the REST rate limit from **60/hr → 5,000/hr**.

- A **fine-grained PAT** with *Public Repositories (read-only)* is enough, **or** a classic PAT.
- Set it as `GITHUB_TOKEN` (in `.env` locally, in project settings when deployed).

## Project layout

```
github-mcp/
├── index.ts              # MCPServer + all 5 tool definitions
├── src/
│   ├── github.ts         # shared client: auth, TTL cache, 202 retry, pagination
│   └── metrics.ts        # health score, bus factor, median issue-close
├── resources/            # widgets (auto-discovered)
│   ├── scorecard.tsx
│   ├── compare.tsx
│   ├── heatmap.tsx
│   └── trending.tsx
├── public/
└── .env                  # GITHUB_TOKEN=...
```

## How it works

- **`src/github.ts`** — one thin client every tool uses. Handles `Bearer` auth, a per-path TTL cache (light tools ~1–5 min, `star-growth`/`trending` cached hard), the `/stats/*` `202 Accepted` retry, and `Link`-header pagination.
- **Caching TTLs** — scorecard/compare/heatmap: 1–5 min; `trending-mcp`: 1 h (search has its own ~30/min limit).
- **Widgets** — each reads typed props via `useWidget<Props>()`, adapts to light/dark via `useWidgetTheme()`, and wraps in `<McpUseProvider autoSize>`.

## Build & deploy

```bash
npm run build             # production build (bundles widgets + server)
npm run deploy            # deploy via mcp-use
```

To deploy on [Manufact](https://manufact.com): push this repo, connect it via the Manufact GitHub App, set `GITHUB_TOKEN` in project settings, and every push auto-deploys with a preview URL. Then publish the connector to Claude / the ChatGPT Apps Store — same codebase, no host-specific changes.

> **Windows note:** `npm run build` bundles all widgets and completes the TS build successfully; the final `tsc` type-check step can fail on Windows because mcp-use invokes `tsc` via an unquoted path containing `C:\Program Files`. Run `npx tsc --noEmit` directly to type-check.