github-mcp-gateway CLAUDE.md

github-mcp-gateway

Remote MCP server on Cloudflare Workers giving MCP clients (Claude Code, Claude.ai/Cowork, and any spec-compliant client) authenticated GitHub access via a GitHub App user-to-server OAuth flow.

Deployment facts (live)

• Worker: github-mcp-gateway — https://github-mcp-gateway.mazzewhiteley93.workers.dev
• MCP endpoint: /mcp (streamable HTTP) and /sse (legacy SSE)
• KV namespace: OAUTH_KV = 0773ec3dd785418c984559f47d1623e9
• Secrets set on the worker: GITHUB_APP_CLIENT_ID, GITHUB_APP_CLIENT_SECRET, COOKIE_ENCRYPTION_KEY
• Allowlist var: ALLOWED_GITHUB_LOGINS="mazze93" (in wrangler.jsonc)
• GitHub App permissions: Contents RW, Issues RW, Pull requests RW, Metadata R. It does not have Administration — github_update_repo will 403 until that permission is added to the App and re-approved on the installation. Use the locally-authenticated gh CLI as the fallback for repo description/topic edits.

Commands

npm run typecheck   # tsc --noEmit
npm test            # vitest run, via @cloudflare/vitest-pool-workers (real workerd, not a Node polyfill)
npm test test/loopback.test.ts   # one file
npm test -- -t "localhost"       # one test by name
npm run dev         # wrangler dev at http://localhost:8788 (needs .dev.vars)
npm run tail        # live worker logs

npx wrangler deploy --dry-run --outdir dist   # local build check; catches
                    # bundling/binding errors tsc cannot see. Never publishes.

Deployment is automatic. .github/workflows/deploy.yml typechecks, tests, and deploys on every push to main — it is the only place a Cloudflare token exists (ci.yml runs on PRs including forks and is deliberately credential-free). npm run deploy is a manual fallback, not the normal path; production drifting behind main because someone forgot to run it by hand is the exact failure that workflow was added to close.

test/*.test.ts covers the OAuth allowlist gate, CSRF/state/signed-cookie handling, loopback redirect normalisation, token refresh, and tool error-wrapping — see vitest.config.ts for how bindings are sourced from wrangler.jsonc. CI runs it as a required gate. Not covered: the GET/POST /authorize route wiring, and a few timing/concurrency edges noted in PR #13's description. typecheck + test + a live tool call against the deployed worker is the verification bar.