mcp-google-chat: Instructions file for Claude Code

CLAUDE.md — mcp-google-chat

MCP server for the Google Chat API v1 (TypeScript, stdio). Mixed read/write: tools cover space discovery (list/get/search/find-DM), message CRUD with threads, emoji reactions, attachment metadata and membership management; raw_request is the escape hatch. The server talks to https://chat.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_CHAT_ACCESS_TOKEN — e.g. a service-account/Chat-app token, or for testing). With user credentials the server acts AS THE SIGNED-IN USER: sends appear under their name and only their own messages/reactions can be edited/deleted.

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; full disposable write cycle
                   # with cleanup when a space is given (argv/GOOGLE_CHAT_SMOKE_SPACE)

Architecture

• src/config.ts — env → config. Credentials: either the refresh triple GOOGLE_CHAT_CLIENT_ID + GOOGLE_CHAT_CLIENT_SECRET + GOOGLE_CHAT_REFRESH_TOKEN (all three or ConfigError incomplete_oauth_config) or GOOGLE_CHAT_ACCESS_TOKEN; optional GOOGLE_CHAT_API_BASE, GOOGLE_CHAT_TIMEOUT_MS, GOOGLE_CHAT_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 the send — and throws GoogleChatError(status, body). Resource-name normalizers (asSpaceName, asUserName, asMessageName, asThreadName, asMemberName, asReactionName, asAttachmentName) accept the shapes users paste, validate them strictly (no path smuggling) and are exported for tests. Wire enums (SPACE/GROUP_CHAT/ DIRECT_MESSAGE, ROLE_MEMBER/ROLE_MANAGER, REPLY_MESSAGE_*) and filter strings (createTime > "...", thread.name = ..., role = "...", emoji.unicode = "...") are built here only. createMessage defaults messageReplyOption to the fallback whenever a thread is targeted — the API's own default silently ignores the thread.
• src/tools/spaces.ts — list_spaces, get_space, search_spaces (admin-only, useAdminAccess), find_direct_message. src/tools/messages.ts — list_messages, get_message, send_message, update_message, delete_message. src/tools/reactions.ts — manage_reactions (add/list/remove). src/tools/attachments.ts — get_attachment (metadata; the endpoint itself is app-auth only — user flows read the same fields from get_message). src/tools/members.ts — list_members, manage_members (get/add/update_role/remove). src/tools/raw.ts — raw_request (GET/POST/PATCH/DELETE). src/tools/util.ts — ok/fail, the four annotation presets (READ_ONLY/WRITE/UPDATE/DESTRUCTIVE) and shared zod schema factories (spaceSchema, messageNameSchema, memberNameSchema, userSchema, rfc3339Timestamp, pageTokenSchema).
• 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.