mcp-google-tasks: Instructions file for Claude Code

CLAUDE.md — mcp-google-tasks

MCP server for the Google Tasks API v1 (TypeScript, stdio). Mixed read/write: tools cover task-list CRUD, task CRUD, subtask hierarchy and ordering, reversible completion and destructive deletion; raw_request is the escape hatch. The server talks to https://tasks.googleapis.com with a Bearer token; the token is minted from an OAuth2 refresh token via https://oauth2.googleapis.com/token (or a static GOOGLE_TASKS_ACCESS_TOKEN, mostly for testing). Due dates are date-only — the API discards the time portion and cannot store a due time.

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 check (lists task lists, prints only the count)
npm run smoke -- --write  # opt-in disposable-list write scenario (always cleans up)

Architecture

• src/config.ts — env → config. Credentials: either the refresh triple GOOGLE_TASKS_CLIENT_ID + GOOGLE_TASKS_CLIENT_SECRET + GOOGLE_TASKS_REFRESH_TOKEN (all three or ConfigError incomplete_oauth_config) or GOOGLE_TASKS_ACCESS_TOKEN; optional GOOGLE_TASKS_API_BASE, GOOGLE_TASKS_TIMEOUT_MS, GOOGLE_TASKS_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 (opens with the historical startup error verbatim, then 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 base and rejects foreign origins (SSRF guard), enforces an AbortController timeout that also covers reading the body, retries 429 always but 5xx/network errors only for GET — replaying a write after an ambiguous failure would duplicate it — and throws GoogleTasksError(status, body). Typed per-endpoint methods own the wire shape: snake_case tool params → camelCase query params (showCompleted, dueMin, maxResults), normalizeDueDate() expands YYYY-MM-DD, setTaskStatus() maps complete/reopen to the wire status enum (completed/needsAction + the completed: null clear), and update_task's clear_due/clear_notes become explicit JSON nulls in the PATCH.
• src/tools/tasklists.ts — list_tasklists, get_tasklist, create_tasklist, update_tasklist, delete_tasklist. src/tools/tasks.ts — list_tasks, get_task, create_task, update_task, move_task, delete_task. src/tools/completion.ts — complete_task, reopen_task (the reversible pair) and clear_completed_tasks (the bulk sweep) — the reversible/destructive split gets its own module. src/tools/raw.ts — raw_request (GET/POST/PATCH/PUT/DELETE). src/tools/util.ts — ok/fail, the four annotation presets (READ_ONLY/WRITE/UPDATE/DESTRUCTIVE) and shared zod schema factories (tasklistIdSchema, taskIdSchema, rfc3339Timestamp, dueDateSchema).
• 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.
• src/smoke.ts — live check. Default READ-ONLY (task-list count only — user content never reaches stdout); --write/GOOGLE_TASKS_SMOKE_WRITE=1 opts into the disposable-list lifecycle (create list → task → complete → reopen → move → delete task) with the list deletion in finally, so cleanup runs after success and failure alike.