google-services-mcp AGENTS.md

AGENTS.md

Guide for AI agents working in this repository.

Project

TypeScript MCP server connecting to Google consumer services (Gmail, Calendar, Meet, Drive, Contacts, Tasks) with multi-account OAuth. Package name google-services-mcp, executable google-services-mcp. ESM ("type": "module"), Node16 module resolution, target ES2022.

Architecture

src/
  main.ts                 # bin entry: stdio serve OR cli dispatch
  server.ts               # createServer(): McpServer + registerTools
  cli.ts                  # dispatchCommand() pure command dispatch (testable)
  auth/
    config.ts             # env/file config resolution
    store.ts              # token/config persistence in data dir
    oauth.ts              # OAuth loopback flow, browser launch, CSRF state
    manager.ts            # AuthManager facade: accounts, clients, status
  services/
    gmail.ts              # send/list/get/modify/reply
    calendar.ts           # events CRUD + Meet links
    drive.ts              # files list/get/upload/update/delete/share
    contacts-tasks.ts     # contacts + tasks
    sheets.ts             # spreadsheets: get/read/write/append/create/batch
    docs.ts               # documents: get/read/create/insert/replace/batch
    slides.ts             # presentations: get/create/replace/add/delete/batch
    youtube.ts            # search/videos/playlists/playlistItems/subscriptions
    forms.ts              # forms: get/responses/create/add-question/batch
  tools/
    index.ts              # registerTools(server): 60 tools, google_ prefix
  util/
    result.ts             # ok/text/err/noAccountsHint
test/                     # vitest suites, mirrored layout

Data flow: MCP tool → withClient(account, fn) resolves a client via authManager.getClient() → service module calls googleapis → ok/err result → tool returns { content: [{ type: "text", text: JSON.stringify(result) }] }.

Conventions

• TDD: write the test first, run it (see it fail), implement, run again until green. Keep suites fast.
• Import style: always .js extensions in relative imports (Node16). The vitest resolution maps .js → .ts.
• Import depth: top-level test/*.test.ts uses ../src/...; nested test/auth/*.test.ts uses ../../src/.... Wrong depth yields a confusing "Cannot find module".
• Tools: register with registerTool(name, { title, description, inputSchema }, cb) from @modelcontextprotocol/sdk/server/mcp.js. Zod 3.25 for schemas. server.tool() is deprecated.
• Tool naming: google_<domain>_<action>, snake_case — avoids collision with client-native tools.
• Errors: return { isError: true, content: [{ type: "text", text: "Error: <message>" }] } via err().
• Vitest: import { describe, expect, it, vi, beforeEach } explicitly. Mock googleapis at module level with vi.mock factory and vi.hoisted() mocks.
• Unhandled rejections in tests: attach the expect(promise).rejects... assertion BEFORE the triggering await fetch(...) call, then await the assertion.