admob-mcp: Instructions file for Codex

AdMob MCP Server

Local MCP server that connects Claude to the Google AdMob API via OAuth 2.0.

Build & Run

npm install
npm run build           # tsc → dist/ (mirrors src/, api/, tests/)
npm test                # vitest unit tests
npm run start           # run stdio server on stdio
npm run dev:vercel      # vercel dev (HTTP mode, requires .env.local)
npm run deploy          # vercel deploy --prod
./setup.sh              # interactive: pick local / vercel / both
./setup.sh --mode=local # non-interactive
./setup.sh --reauth     # re-authorize (mode-aware)

Project Layout

• src/index.ts — stdio MCP entry point. Calls registerTools(server, getClient) with FileTokenStore.
• src/tools.ts — all tool definitions (6 core + 10 reporting + 20 optimization). Exports registerTools(server, getClient).
• src/auth.ts — OAuth helpers. getAuthenticatedClient(creds, store) is the headless refresh path used by both modes; authorizeViaLocalServer(creds, store) is the interactive CLI flow.
• src/authorize.ts — Standalone CLI script for OAuth authorization (run by setup.sh for local mode).
• src/admob-client.ts — Thin REST client over https://admob.googleapis.com/v1.
• src/helpers.ts — Date math, report row parsing, table formatting, period-over-period change utils.
• src/token-store.ts — TokenStore interface, FileTokenStore (local), KvTokenStore (Vercel KV).
• src/oauth-store.ts — KV-backed storage for the connector OAuth flow: short-lived auth codes (oauth:authcode:<code>, 10-min TTL) and long-lived access tokens (oauth:token:<token>).
• src/http-auth.ts — checkBearer (sync, against CONNECTOR_TOKEN) used by /oauth/authorize and /api/setup; checkBearerAsync (also accepts KV-issued access tokens) used by /api/mcp.
• api/mcp.ts — Vercel function: Streamable HTTP MCP endpoint. Bearer-gated. Returns WWW-Authenticate: Bearer realm="admob-mcp", resource_metadata="…" on 401 per the MCP authorization spec.
• api/setup.ts — Vercel function: GET form + POST handler that initiates the Google ↔ server OAuth flow. Server's grant on AdMob.
• api/oauth/callback.ts — Vercel function: Google's redirect URI; stores tokens in KV.
• api/oauth/authorize.ts, api/oauth/token.ts, api/oauth/register.ts — Vercel functions implementing the Claude.ai ↔ server OAuth 2.1 flow with PKCE (S256) and Dynamic Client Registration. Required because Claude.ai's connector UI doesn't accept static bearer tokens — it negotiates its own access token.
• api/well-known/oauth-authorization-server.ts, api/well-known/oauth-protected-resource.ts — RFC 8414 / RFC 9728 metadata endpoints; reached at root paths (/.well-known/...) via vercel.json rewrites so Claude.ai's discovery works.
• vercel.json — Vercel function runtime + per-function timeouts + rewrites mapping /.well-known/* and /oauth/* to the api/ directory.
• .env.example — Template for Vercel mode env vars.
• secrets/ — Git-ignored. Local-mode client_secret.json and token.json live here.
• setup.sh — Interactive setup: pick [L]ocal / [V]ercel / [B]oth. Supports --mode= and --reauth.
• docs/VERCEL.md — Forker-facing deploy guide for the Connector path.
• tests/ — vitest unit tests (token-store.test.ts, http-auth.test.ts).
• CLAUDE.md — Symlink to this file.