google-services-mcp: Instructions file for Codex

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, Sheets, Docs, Slides, YouTube, Forms) 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/draft/reply/labels/attachments/trash
    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): 134 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