gmail-mcp-server: Instructions file for Codex

AGENTS.md

Guidelines for AI coding agents working in this Gmail MCP server codebase.

Project Overview

A minimal Gmail MCP (Model Context Protocol) server that enables AI agents to interact with Gmail. Built with TypeScript and Node.js, using the official Gmail API.

Build/Lint/Test Commands

# Install dependencies
npm install

# Build TypeScript to dist/
npm run build

# Run the compiled server
npm start

# Build and run in one command (development)
npm run dev

# Run OAuth authentication flow
npm run auth

Note: This project currently has no automated test suite or linting commands configured. Consider adding tests before making significant changes.

Code Style Guidelines

TypeScript Configuration

• Target: ES2022
• Module: NodeNext (ESM with Node.js resolution)
• Strict mode: enabled
• Output directory: dist/
• Source directory: src/

Imports

// Prefer ESM imports with .js extension for local files
import { something } from "./module.js";

// External imports: organize by scope (SDK, then external libs, then Node builtins)
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { OAuth2Client } from "google-auth-library";
import { google } from "googleapis";
import { readFileSync } from "fs";

• Use explicit .js extensions in import paths for ESM compatibility
• Group imports logically: external packages first, then Node builtins
• Destructure named imports rather than importing entire modules when possible

Formatting

• 2-space indentation
• No semicolons required (TypeScript/ESM handles ASI)
• Max line length: ~100 characters
• Use double quotes for strings consistently
• Trailing commas in multi-line objects/arrays

Types

• Prefer explicit types for function parameters and return values
• Use interfaces for object shapes that are reused
• Avoid any; use unknown when type is uncertain
• Leverage Zod schemas for runtime validation and type inference