github-mcp

Four GitHub "superpowers" as an mcp-use MCP App — each a tool + React widget that renders inside Claude, ChatGPT, or any MCP Apps-compatible client. Write once, render everywhere.

Quick start

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" }.

Related MCP server: GitHub Projects MCP Server

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

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

To deploy on Manufact: 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.