github-mcp-gateway: Instructions file for Claude Code

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, Administration RW. github_update_repo works directly (verified 2026-10-21 with a no-op description update).

Commands

npm run typecheck   # tsc --noEmit
npm test            # vitest run, via @cloudflare/vitest-pool-workers (real workerd, not a Node polyfill)
npm test test/oauth-boundaries.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
bash scripts/test-toolchain.sh  # Apple container preferred; Docker fallback; dry-run only

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 is exposed to a deploy step (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 validation, token refresh, and tool error-wrapping — see vitest.config.ts for how bindings are sourced from wrangler.jsonc. CI runs the suite as a verification gate. The authorize routes are covered in test/authorize-routes.test.ts; test/oauth-boundaries.test.ts also covers token audience isolation and legacy path-bound grant rejection. Cross-location KV refresh races remain a known limitation. typecheck + test + a live tool call against the deployed worker is the verification bar.