mcp-google-crux: Instructions file for Claude Code

CLAUDE.md — mcp-google-crux

MCP server for the Chrome UX Report (CrUX) API (TypeScript, stdio). Read-only: convenience tools compute Core Web Vitals assessments, device breakdowns and p75 trends on top of two raw pass-through tools. The server talks to chromeuxreport.googleapis.com — exactly two POST-only endpoints (/v1/records:queryRecord, /v1/records:queryHistoryRecord); auth is a Google Cloud API key riding as the key= query parameter (no OAuth).

Commands

npm run dev        # run from source (tsx watch)
npm test           # unit tests + dist smoke, no network
npm run typecheck  # types for src + tests
npm run build      # emit dist/
npm run smoke      # live READ-ONLY call (needs CRUX_API_KEY)

Architecture

• src/config.ts — env → config. A missing CRUX_API_KEY is NOT an error: the field stays undefined, the server starts degraded and the client raises CredentialsError (lives in types.ts) at call time. ConfigError (with a reason code) is reserved for malformed values, caught by loadConfigOrDegraded in index.ts (no such checks exist today). Optional CRUX_API_BASE, CRUX_TIMEOUT_MS, CRUX_MAX_RETRIES.
• src/client.ts — queryRecord/queryHistoryRecord → v1/records:* paths: POST only (GET answers a misleading 404), key injected as key= query param, formFactor mapped from normalized phone|desktop|tablet to PHONE|DESKTOP|TABLET, origin XOR url enforced before any fetch. request() first rejects a missing CRUX_API_KEY with CredentialsError (before the URL is built, the retries and fetch — the message is the product: it names the variable to set and the needed restart), then rejects paths that escape to a foreign origin (SSRF guard), retries 429/5xx/network errors with backoff (honors Retry-After), enforces an AbortController timeout that also covers reading the body, throws CruxError(status, body) — and CruxNoDataError for 404, which is a normal "no data" answer.
• src/cwv.ts — pure CWV logic (no I/O): metric vocabulary, p75 thresholds, ratings, record summarization and trend extraction. All format quirks are handled here.
• src/tools/vitals.ts — get_core_web_vitals, compare_form_factors (4 requests), compare_origin_vs_url (2 requests), get_cwv_trend. src/tools/records.ts — query_record, query_history_record (raw pass-through). src/tools/util.ts — ok/fail/noDataResult, the READ_ONLY annotation and shared zod schema factories.
• src/index.ts — wires every register* into the McpServer. loadConfigOrDegraded starts the server even on a config problem; without a key the initialize instructions open with the unconfigured prefix (set CRUX_API_KEY and restart), plus Configuration problem: … when a ConfigError was caught.
• src/telemetry.ts — anonymous usage pings (ids/names/versions only, never the key, queried origins/URLs or arguments; fire-and-forget, must never block or throw; opt-out ASKADS_TELEMETRY=0). server_start means "a usable install started"; an install without a key sends unconfigured_start instead. The reason is a closed vocabulary (missing_api_key) — never a variable's name or value. startup_failed remains for a config unusable at load time (malformed values), also fire-and-forget.