mcp-google-slides: Instructions file for Claude Code

CLAUDE.md — mcp-google-slides

MCP server for the Google Slides API v1 (TypeScript, stdio). Mixed read/write: tools cover presentation/slide CRUD, text, shapes, tables, images, transforms, speaker notes, layouts, thumbnails, comments and export; raw_request is the escape hatch. The server talks to https://slides.googleapis.com with a Bearer token; comments, export and local-image upload ride the Drive API v3 (https://www.googleapis.com) as an internal dependency — never exposed as generic Drive tools. The token is minted from an OAuth2 refresh token via https://oauth2.googleapis.com/token (or a static GOOGLE_SLIDES_ACCESS_TOKEN, mostly for testing).

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 check: read-only by default; GOOGLE_SLIDES_SMOKE_WRITE=1
                   # runs the disposable create→edit→delete scenario with cleanup

Architecture

• src/config.ts — env → config. Credentials: either the refresh triple GOOGLE_SLIDES_CLIENT_ID + GOOGLE_SLIDES_CLIENT_SECRET + GOOGLE_SLIDES_REFRESH_TOKEN (all three or ConfigError incomplete_oauth_config) or GOOGLE_SLIDES_ACCESS_TOKEN; optional GOOGLE_SLIDES_API_BASE, GOOGLE_SLIDES_DRIVE_API_BASE, GOOGLE_SLIDES_TIMEOUT_MS, GOOGLE_SLIDES_MAX_RETRIES. No credentials at all is NOT an error: the fields stay undefined and the server starts degraded. Also home to CredentialsError / MISSING_CREDENTIALS_MESSAGE (names the variables and the restart) and hasCredentials().
• src/client.ts — all HTTP and all wire mapping. Token lifecycle (cache until ~60s before expiry, dedupe concurrent refreshes, one forced re-mint + replay on 401); request() resolves the path against the Slides base and rejects foreign origins (SSRF guard — the private driveRequest() does the same against the Drive base), enforces an AbortController timeout that also covers reading the body, retries 429 always but 5xx/network errors only for GET, and throws GoogleSlidesError(status, body). Typed per-endpoint methods build the batchUpdate requests, field masks and EMU/PT conversions; validateImageUrl() (https-only, no private hosts, ≤2 kB) and sniffImageType() (PNG/JPEG/GIF magic bytes, ≤50 MB) gate images; withImageUrl() implements the local-image flow: Drive multipart upload → anyone-with-link reader → use → best-effort delete of the temp file on success AND failure. setText() exploits batchUpdate atomicity: a 400-rejected delete+insert batch applied nothing, so it is re-sent insert-only for empty targets. summarizePresentation() compacts a fields-masked deck for list_slides.
• src/tools/presentations.ts — create_presentation, get_presentation, list_slides, get_page, batch_update. src/tools/slides.ts — add_slide, duplicate_slide, move_slides, delete_object, list_layouts. src/tools/text.ts — insert_text, set_text, replace_text, update_text_style. src/tools/elements.ts — create_shape, create_image, replace_image, update_transform. src/tools/tables.ts — create_table, edit_table (action-based). src/tools/notes.ts — get_speaker_notes, set_speaker_notes. src/tools/comments.ts — manage_comments (action-based; Drive comments for this file). src/tools/export.ts — get_thumbnail, export_presentation. src/tools/raw.ts — raw_request (GET/POST — the Slides API has no other methods). src/tools/util.ts — ok/fail, the four annotation presets (READ_ONLY/WRITE/UPDATE/DESTRUCTIVE) and shared zod schema factories (presentationIdSchema, objectIdSchema, newObjectIdSchema, indexSchema, pointsSchema, hexColorSchema).
• src/index.ts — wires every register* into the McpServer. loadConfigOrDegraded() catches ConfigError, pings startup_failed (fire-and-forget) and degrades the config to "no credentials"; an unconfigured start prepends UNCONFIGURED_PREFIX — plus Configuration problem: <message> when a ConfigError was caught — to the initialize instructions, and oninitialized sends server_start for a configured install or unconfigured_start (with the reason) otherwise.
• src/telemetry.ts — anonymous usage pings (ids/names/versions only, never data or arguments; fire-and-forget, must never block or throw; opt-out ASKADS_TELEMETRY=0). server_start means "a usable install started"; unconfigured_start is a degraded start and startup_failed a malformed config caught at load — both carry a reason from a closed vocabulary (missing_credentials, incomplete_oauth_config) — never a variable's name or value.