CONTRIBUTING.md

Contributing

Thanks for your interest in contributing! This guide covers how to set up the project for local development, understand the architecture, and submit changes.

Development Setup

Prerequisites

• Node.js 20+ (nodejs.org)
• Git (git-scm.com)
• A Google Account with access to test documents

Clone and Build

git clone https://github.com/a-bonus/google-docs-mcp.git
cd google-docs-mcp
npm install
npm run build

Authenticate

You need Google OAuth credentials to test the server against real APIs.

Option A: credentials.json file

1. Download your OAuth client JSON from Google Cloud Console
2. Rename it to credentials.json and place it in the project root
3. Run npm start auth to open the browser-based OAuth flow

Option B: Environment variables

GOOGLE_CLIENT_ID="your-client-id" \
GOOGLE_CLIENT_SECRET="your-client-secret" \
npm start auth

Both options save the refresh token to ~/.config/google-docs-mcp/token.json. OAuth client IDs and client secrets stay in your environment or credentials.json; they are not stored in the token file.

Register Your Local Build

Point your MCP client at the local build for testing:

{
  "mcpServers": {
    "google-docs": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-googledocs-server/dist/index.js"]
    }
  }
}

Scripts

Command	Description
npm start	Start the MCP server
npm start auth	Run the interactive OAuth flow
npm run build	Compile TypeScript to dist/
npm test	Run tests (Vitest)
npm run format	Format code with Prettier
npm run format:check	Check formatting

---

Project Architecture

Entry Points

src/index.ts        Entry point: CLI (auth subcommand) and MCP server startup
src/auth.ts         OAuth / service account authentication
src/clients.ts      Google API client singletons (Docs, Drive, Sheets)

Tools

Tools live in src/tools/, organized by domain. Each tool is a single file exporting a register(server: FastMCP) function.

src/tools/
├── index.ts            Top-level router
├── docs/               Google Docs tools (13)
│   ├── comments/       Comment management (6)
│   └── formatting/     Text and paragraph styling (2)
├── drive/              Google Drive tools (15)
├── sheets/             Google Sheets tools (37)
├── gmail/              Gmail tools (13)
├── calendar/           Google Calendar tools (5)
└── utils/              Cross-cutting utilities (3)

Helpers

File	Purpose
src/googleDocsApiHelpers.ts	Text range finding, batch update execution, style request builders
src/googleSheetsApiHelpers.ts	A1 notation parsing, cell formatting, freeze, validation
src/markdown-transformer/	Markdown parsing and bidirectional Google Docs conversion
src/types.ts	Zod schemas, hex color validation, shared type definitions
src/logger.ts	Leveled logger (debug/info/warn/error) writing to stderr

Authentication Flow

The auth module (src/auth.ts) resolves credentials in this order:

1. SERVICE_ACCOUNT_PATH env var -- service account JWT
2. GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET env vars -- OAuth (for npx consumers)
3. credentials.json in the project root -- OAuth (for local dev)

Tokens are persisted to ~/.config/google-docs-mcp/token.json (respects XDG_CONFIG_HOME). The token file stores OAuth token credentials only, not OAuth client IDs or client secrets.

---

Adding a New Tool

1. Create a new file in the appropriate domain folder (e.g., src/tools/sheets/myNewTool.ts)
2. Export a register(server: FastMCP) function that calls server.addTool({...})
3. Import and call it from the domain's index.ts router
4. Add tests if the tool involves non-trivial logic

Tool Conventions

• Names: camelCase, verb-first (e.g., readDocument, formatCells)
• Descriptions: Start with what the tool does, mention when to use it, note any caveats
• Parameters: Use Zod schemas with .describe() on every field
• Errors: Throw UserError from fastmcp for user-facing errors
• Output: Return JSON.stringify'd structured data for tools that return actionable information

---

Testing

Tests use Vitest and live alongside source files or in src/:

npm test              # Run all tests
npm test -- --watch   # Watch mode

Tests mock Google API clients -- they don't make real API calls.

---

Code Style

• TypeScript with strict mode
• ESM modules (.js extensions in imports)
• Prettier for formatting (npm run format)
• All log output goes to stderr (stdout is reserved for MCP protocol)

---

Releasing

Releases are automated via GitHub Actions. To publish a new version:

1. Update the version in package.json
2. Commit and push to main
3. Tag the commit: git tag v1.2.3 && git push origin v1.2.3
4. The release workflow will run CI checks, publish to npm, and create a GitHub Release

The npm package is published as @a-bonus/google-docs-mcp.