feat: Gmail API Integration (read, compose, send) - v3.2.0

[AojdevStudio]

Summary

Add Gmail email functionality to the gdrive MCP server following the established operation-based architecture pattern. This includes 12 Gmail operations, documentation updates, and technical debt cleanup.

Spec File: specs/gmail-integration-and-tech-debt.md
Plan File: Available in repo
Target Version: v3.2.0

---

Scope Decisions (Approved)

Feature	Decision
Send-as (aliases)	YES - from parameter in sendMessage
Signatures	YES - getSignature operation
Draft scheduling	YES - scheduleSend operation
Attachments	DEFER - Skip for simplicity
Calendar API	FUTURE - Not this version

---

Gmail Operations (12 total)

Operation	Description	Priority
listMessages	List messages with filters	P0
listThreads	List email threads	P0
getMessage	Get full message content	P0
getThread	Get full thread	P0
searchMessages	Gmail query syntax search	P0
createDraft	Create email draft	P0
sendMessage	Send email (with send-as)	P0
sendDraft	Send existing draft	P0
scheduleSend	Schedule draft for later	P1
listLabels	List all labels	P1
modifyLabels	Add/remove labels	P1
getSignature	Get email signature	P1

---

Files to Create

```
src/modules/gmail/
├── index.ts # Barrel exports
├── types.ts # Gmail interfaces
├── list.ts # listMessages, listThreads
├── read.ts # getMessage, getThread
├── search.ts # searchMessages
├── compose.ts # createDraft
├── send.ts # sendMessage, sendDraft, scheduleSend
├── labels.ts # listLabels, modifyLabels
└── signature.ts # getSignature
```

---

Files to Modify

• index.ts - Add OAuth scopes, gmail tool registration, dispatch handler
• src/modules/types.ts - Add GmailContext
• src/tools/listTools.ts - Add Gmail to gdrive://tools
• README.md - Gmail documentation
• CLAUDE.md - Architecture updates
• docs/Developer-Guidelines/API.md - Gmail API reference
• package.json - Version bump to 3.2.0

---

OAuth Scopes to Add

```typescript
"https://www.googleapis.com/auth/gmail.readonly",
"https://www.googleapis.com/auth/gmail.send",
"https://www.googleapis.com/auth/gmail.compose",
"https://www.googleapis.com/auth/gmail.modify",
"https://www.googleapis.com/auth/gmail.settings.basic", // For signatures
```

Note: Users will need to re-authenticate after upgrade.

---

Tech Debt Cleanup (Part of this issue)

• Remove deprecated code in src/tools/listTools.ts:147
• Delete skipped tests in src/__tests__/integration/addQuestion-integration.test.ts
• Archive legacy handlers (src/drive/, src/sheets/, src/forms/, src/docs/)
• Run ESLint --fix

---

Success Criteria

• 12 Gmail operations functional
• Send-as working with aliases
• Signature retrieval working
• Draft scheduling working
• All docs updated
• Tech debt items resolved
• 90%+ test coverage on new code
• No breaking changes to existing tools

---

Implementation Notes

Follow existing architecture pattern:

• Single gmail tool with operation parameter (like drive, sheets, forms, docs)
• Module structure in src/modules/gmail/
• Shared context pattern with GmailContext
• Progressive disclosure via gdrive://tools resource

See full spec at specs/gmail-integration-and-tech-debt.md

[linear]

GDRIVE-8

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Related Issues

• Add createSheet functionality to Google Sheets toolset #14
• [BUG] getAppScript fails with 500 error when given spreadsheet ID instead of script project ID #10

🔗 Related PRs

AojdevStudio/dental-dashboard#4 - Feature/google [merged]
AojdevStudio/app-scripts#2 - feat: add notification service and update lab case management system … [merged]
#5 - Add Google Apps Script Viewing Feature with Caching and Syntax Highlighting [merged]
#15 - Add createSheet tool for Google Sheets with full integration and tests [merged]
#25 - ♻️ Phase 1: Remove 1,056 Lines of Dead Code - Complete Tool Handler Cleanup [merged]

👤 Suggested Assignees

• AojdevStudio

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[coderabbitai]

Coding Plan

Approach

Ticket Summary

Add Gmail functionality to the gdrive MCP server following the established operation-based architecture pattern. This includes implementing 12 Gmail operations (list, read, search, compose, send, labels, signature) with send-as alias support and signature retrieval. Additionally, clean up technical debt by removing deprecated code and archiving legacy handlers.

Observations

Codebase Summary

The project is a Model Context Protocol (MCP) server for Google Workspace APIs with a modular, operation-based architecture. Each Google service (Drive, Sheets, Forms, Docs) is organized as a module in src/modules/ with operations split by category into separate files. All operations follow a consistent pattern: async functions that accept typed options and a context object containing the API client, logger, cache manager, and performance monitor. The root index.ts registers tools with operation enums and dispatches requests through dynamic imports and nested switch statements. The codebase uses a progressive disclosure pattern via the gdrive://tools resource to minimize token usage.

Assumptions

Assumption 1: Scheduled Send Implementation Approach

Options Considered:

• Option A: Implement scheduleSend as a draft creation operation that returns draft ID and metadata, with comprehensive documentation showing how users can integrate external scheduling infrastructure (Google Cloud Scheduler, cron jobs, etc.) to trigger sendDraft at the desired time
• Option B: Add a scheduling library (node-cron, bull, agenda) and build internal scheduling infrastructure to handle deferred draft sending
• Option C: Skip scheduleSend entirely since it requires external infrastructure

Chosen Option: Option A

Rationale: Create draft with metadata and document external scheduling patterns. This aligns with the MCP stateless philosophy (servers respond to requests rather than running as persistent background services), follows the existing pattern of not introducing new architectural abstractions, and provides users flexibility to integrate with their existing infrastructure. The operation name scheduleSend remains accurate as it prepares a message for scheduled sending, with documentation clearly explaining the external scheduling requirement.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Gmail Module Foundation

Create the Gmail module structure following the established pattern for Google Workspace services, defining core types and context.

Task 1: Create Gmail Module Structure and Types

Establish the base Gmail module with TypeScript interfaces and context definition.

• Create src/modules/gmail/types.ts defining Gmail-specific types for messages, threads, drafts, labels, and operations (ListMessagesOptions, GetMessageOptions, SendMessageOptions, etc.) with corresponding Result interfaces
• Add GmailContext interface to src/modules/types.ts that extends BaseContext and includes gmail: gmail_v1.Gmail property
• Create src/modules/gmail/index.ts as barrel export file following the pattern from sheets/forms/docs modules
• Update src/modules/index.ts to export the gmail module namespace and GmailContext type

Task 2: Update OAuth Scopes and API Initialization

Add Gmail OAuth scopes and initialize the Gmail API client in the authentication flow.

• Update index.ts authenticateAndSaveCredentials function to add five Gmail scopes to the scopes array: gmail.readonly, gmail.send, gmail.compose, gmail.modify, gmail.settings.basic
• Add Gmail API initialization in the context creation section where drive, sheets, forms, docs are initialized using google.gmail("v1")
• Document in README.md that users must re-authenticate after upgrading to v3.2.0 to grant new Gmail permissions

🤖 Prompt for AI agents

This phase establishes the Gmail module foundation with types, context, and
authentication setup.

Create `src/modules/gmail/types.ts` with Gmail-specific TypeScript interfaces
for messages, threads, drafts, labels, and all operation options
(ListMessagesOptions, GetMessageOptions, SendMessageOptions, etc.) with
corresponding Result interfaces.

Add `GmailContext` interface to `src/modules/types.ts` extending BaseContext
with `gmail: gmail_v1.Gmail` property.

Create `src/modules/gmail/index.ts` as barrel export file.

Update `src/modules/index.ts` to export gmail module namespace and GmailContext.

In `index.ts` authenticateAndSaveCredentials function, add five Gmail OAuth
scopes: gmail.readonly, gmail.send, gmail.compose, gmail.modify,
gmail.settings.basic.

Initialize Gmail API client using `google.gmail("v1")` in context creation
section.

Document re-authentication requirement in README.md for v3.2.0 upgrade.

Phase 2: Core Gmail Operations - List and Read

Implement foundational Gmail operations for listing and reading messages and threads.

Task 1: List Operations

Create listing functionality for messages and threads with pagination and filtering.

• Create src/modules/gmail/list.ts with listMessages and listThreads functions
• Each function accepts options (userId, maxResults, pageToken, query, labelIds) and GmailContext
• Implement result pagination handling with nextPageToken
• Use gmail.users.messages.list and gmail.users.threads.list API methods
• Add cache invalidation strategy for list operations when messages/threads are modified
• Follow the pattern from sheets/list.ts for pagination and caching

Task 2: Read Operations

Create retrieval functionality for individual messages and threads with format options.

• Create src/modules/gmail/read.ts with getMessage and getThread functions
• Accept options including userId, messageId/threadId, and format (FULL, METADATA, RAW, MINIMAL)
• Implement caching for read operations with appropriate TTL using context.cacheManager
• Use gmail.users.messages.get and gmail.users.threads.get API methods
• Extract and parse message headers, body, and attachments metadata (metadata only, no attachment downloads)

🤖 Prompt for AI agents

This phase implements list and read operations for Gmail messages and threads.

Create `src/modules/gmail/list.ts` with `listMessages` and `listThreads`
functions accepting options (userId, maxResults, pageToken, query, labelIds) and
GmailContext.

Implement pagination with nextPageToken handling.

Use gmail.users.messages.list and gmail.users.threads.list API methods.

Add cache invalidation for modified messages/threads.

Create `src/modules/gmail/read.ts` with `getMessage` and `getThread` functions.

Accept userId, messageId/threadId, and format options (FULL, METADATA, RAW,
MINIMAL).

Use gmail.users.messages.get and gmail.users.threads.get API methods.

Implement caching with context.cacheManager.

Parse message headers, body, and attachment metadata.

Phase 3: Search and Labels

Implement Gmail query search and label management operations.

Task 1: Search Operation

Create advanced search using Gmail query syntax.

• Create src/modules/gmail/search.ts with searchMessages function
• Accept options for query string (Gmail search syntax), maxResults, and pagination
• Leverage the same underlying messages.list API but focus on query construction and result formatting
• Add comprehensive JSDoc examples showing common search patterns (from:, to:, subject:, has:attachment, is:unread, etc.)
• Include performance monitoring for search operations

Task 2: Label Operations

Create label listing and modification operations.

• Create src/modules/gmail/labels.ts with listLabels and modifyLabels functions
• For listLabels: use gmail.users.labels.list to retrieve all labels with their IDs and properties
• For modifyLabels: accept messageId and arrays of labelIds to add/remove, use gmail.users.messages.modify
• Implement cache invalidation for message/thread lists when labels are modified
• Add label validation to prevent invalid label operations

🤖 Prompt for AI agents

This phase implements search and label management for Gmail.

Create `src/modules/gmail/search.ts` with `searchMessages` function accepting
query string (Gmail search syntax), maxResults, and pagination options.

Use messages.list API with query construction and result formatting.

Add JSDoc examples for common search patterns (from:, to:, subject:,
has:attachment, is:unread, etc.).

Include performance monitoring.

Create `src/modules/gmail/labels.ts` with `listLabels` and `modifyLabels`
functions.

For listLabels, use gmail.users.labels.list to retrieve labels with IDs and
properties.

For modifyLabels, accept messageId and arrays of labelIds to add/remove, use
gmail.users.messages.modify.

Implement cache invalidation when labels are modified.

Add label validation.

Phase 4: Compose and Send Operations

Implement draft creation, message sending, and send-as functionality.

Task 1: Draft Creation

Create draft composition with MIME message building.

• Create src/modules/gmail/compose.ts with createDraft function
• Accept options for to, cc, bcc, subject, body (HTML and plain text), and inReplyTo (threadId)
• Implement RFC 2822 MIME message construction with proper header formatting
• Use base64url encoding for message.raw field
• Call gmail.users.drafts.create with constructed message
• Return draft ID and message details in result

Task 2: Send Operations

Create immediate message sending and draft sending with send-as support.

• Create src/modules/gmail/send.ts with sendMessage, sendDraft, and scheduleSend functions
• For sendMessage: accept same options as createDraft plus optional from parameter for send-as aliases, construct MIME message, call gmail.users.messages.send
• For sendDraft: accept draftId and optional message updates, call gmail.users.drafts.send
• For scheduleSend: create draft using same logic as createDraft, return draft ID with metadata including intended send time, add comprehensive JSDoc documentation explaining that external scheduling infrastructure (cron, Cloud Scheduler, etc.) is required to call sendDraft at the scheduled time
• Validate send-as aliases against user's configured aliases
• Implement cache invalidation for sent messages in relevant threads

Task 3: Signature Retrieval

Create signature management operation for retrieving user signatures.

• Create src/modules/gmail/signature.ts with getSignature function
• Accept userId and optional sendAsEmail (alias email) in options
• Use gmail.users.settings.sendAs.list to retrieve send-as settings with signatures
• Parse and return signature HTML content
• Add caching for signature data with appropriate TTL

🤖 Prompt for AI agents

This phase implements draft creation, message sending, and signature operations.

Create `src/modules/gmail/compose.ts` with `createDraft` function accepting to,
cc, bcc, subject, body (HTML/plain text), and inReplyTo (threadId) options.

Implement RFC 2822 MIME message construction with proper headers.

Use base64url encoding for message.raw.

Call gmail.users.drafts.create and return draft ID with message details.

Create `src/modules/gmail/send.ts` with `sendMessage`, `sendDraft`, and
`scheduleSend` functions.

For sendMessage, accept compose options plus optional `from` parameter,
construct MIME message, call gmail.users.messages.send.

For sendDraft, accept draftId and optional updates, call
gmail.users.drafts.send.

For scheduleSend, create draft and return draft ID with metadata including
intended send time, add JSDoc explaining external scheduling infrastructure
requirement.

Validate send-as aliases.

Implement cache invalidation for sent messages.

Create `src/modules/gmail/signature.ts` with `getSignature` function accepting
userId and optional sendAsEmail.

Use gmail.users.settings.sendAs.list to retrieve signatures.

Parse and return signature HTML.

Add caching with appropriate TTL.

Phase 5: Tool Registration and Dispatch

Integrate Gmail into the MCP server tool registration and request dispatch system.

Task 1: Gmail Tool Registration

Register the Gmail tool with operation enumeration in the MCP server.

• Update index.ts tool definitions array to add gmail tool definition after the docs tool
• Define operation enum with all 12 operations: listMessages, listThreads, getMessage, getThread, searchMessages, createDraft, sendMessage, sendDraft, scheduleSend, listLabels, modifyLabels, getSignature
• Add generic params object schema following the pattern from drive/sheets/forms/docs tools
• Import all Gmail operation types at the top of index.ts (ListMessagesOptions, SendMessageOptions, etc.)

Task 2: Gmail Dispatch Handler

Implement request routing to Gmail module operations.

• Add gmail case to the CallToolRequestSchema handler switch statement in index.ts
• Use dynamic import for gmail module: const gmailModule = await import('./src/modules/gmail/index.js')
• Create nested switch statement on operation name to route to appropriate function
• Type cast params using imported Gmail interfaces
• Include GmailContext in context object passed to operations
• Add performance tracking for each Gmail operation following existing pattern

Task 3: Progressive Disclosure Integration

Add Gmail operations to the gdrive://tools resource for discovery.

• Update src/tools/listTools.ts generateToolStructure function to include gmail section
• Add hardcoded Gmail tool structure with all 12 operations, their parameters, and descriptions
• Follow the format established for drive, sheets, forms, docs sections
• Include JSDoc examples for each operation showing common use cases

🤖 Prompt for AI agents

This phase integrates Gmail into the MCP server tool registration and dispatch
system.

Update `index.ts` tool definitions array to add gmail tool after docs.

Define operation enum with all 12 operations: listMessages, listThreads,
getMessage, getThread, searchMessages, createDraft, sendMessage, sendDraft,
scheduleSend, listLabels, modifyLabels, getSignature.

Add generic params object schema.

Import Gmail operation types.

Add gmail case to CallToolRequestSchema handler switch statement.

Use dynamic import for gmail module.

Create nested switch for operation routing.

Type cast params and include GmailContext.

Add performance tracking.

Update `src/tools/listTools.ts` generateToolStructure to include gmail section
with all 12 operations, parameters, descriptions, and JSDoc examples.

Phase 6: Testing

Implement comprehensive test coverage for Gmail operations.

Task 1: Unit Tests

Create unit tests for all Gmail operations with API mocking.

• Create test files in src/__tests__/gmail/ directory mirroring module structure: list.test.ts, read.test.ts, search.test.ts, compose.test.ts, send.test.ts, labels.test.ts, signature.test.ts
• Mock gmail API client methods using jest.fn() with mockResolvedValue/mockRejectedValue
• Test successful operation paths with various parameter combinations
• Test error handling scenarios (API errors, network failures, invalid parameters)
• Test cache behavior (get, set, invalidate calls) for appropriate operations
• Achieve 90%+ coverage meeting thresholds: functions 85%, lines 75%, statements 75%, branches 65%

Task 2: Integration Tests

Create integration tests for key Gmail workflows.

• Create integration test files in src/__tests__/integration/ for critical paths: message-operations-integration.test.ts, draft-workflow-integration.test.ts, send-operations-integration.test.ts
• Test end-to-end workflows: list → read → modify labels, create draft → send draft, search → get message
• Use full context setup with mocked API responses
• Verify performance monitoring and logging calls
• Test error recovery and cache invalidation flows
• Follow the pattern from createSheet-integration.test.ts for handler-based architecture

🤖 Prompt for AI agents

This phase implements comprehensive test coverage for Gmail operations.

Create unit test files in `src/__tests__/gmail/` mirroring module structure:
list.test.ts, read.test.ts, search.test.ts, compose.test.ts, send.test.ts,
labels.test.ts, signature.test.ts.

Mock gmail API client methods using jest.fn() with
mockResolvedValue/mockRejectedValue.

Test successful paths with various parameters.

Test error handling (API errors, network failures, invalid parameters).

Test cache behavior (get, set, invalidate).

Achieve 90%+ coverage meeting thresholds: functions 85%, lines 75%, statements
75%, branches 65%.

Create integration tests in `src/__tests__/integration/`:
message-operations-integration.test.ts, draft-workflow-integration.test.ts,
send-operations-integration.test.ts.

Test end-to-end workflows: list → read → modify labels, create draft → send
draft, search → get message.

Use full context setup with mocked API responses.

Verify performance monitoring and logging.

Test error recovery and cache invalidation.

Phase 7: Documentation

Update all documentation to include Gmail functionality and integration guides.

Task 1: Core Documentation Updates

Update primary documentation files with Gmail information.

• Update README.md Features section to list Gmail operations, add Gmail examples to Quick Start, document OAuth re-authentication requirement for v3.2.0
• Update CLAUDE.md Architecture section to include Gmail module in the Google Workspace APIs list, update tool registration section
• Update docs/Developer-Guidelines/API.md to add Gmail API Reference section with all 12 operations, their parameters, return types, and usage examples following the pattern from Drive/Sheets sections

Task 2: Gmail-Specific Documentation

Create detailed Gmail integration guides and examples.

• Create docs/Guides/gmail-integration.md with sections covering: authentication and scopes, message operations (list, read, search), thread operations, draft workflow, sending with send-as aliases, label management, signature retrieval, scheduled send integration patterns with external schedulers
• Add code examples for common workflows: reading recent emails, searching and filtering, composing and sending, draft-to-send workflow, integrating with external schedulers (cron, Cloud Scheduler, Cloud Tasks)
• Document MIME message format requirements and base64url encoding
• Include troubleshooting section for common issues (scope errors, send-as validation, quota limits)

🤖 Prompt for AI agents

This phase updates documentation for Gmail functionality.

Update `README.md` Features section with Gmail operations, add Gmail examples to
Quick Start, document OAuth re-authentication requirement for v3.2.0.

Update `CLAUDE.md` Architecture section to include Gmail module, update tool
registration section.

Update `docs/Developer-Guidelines/API.md` with Gmail API Reference section
covering all 12 operations, parameters, return types, and usage examples.

Create `docs/Guides/gmail-integration.md` with sections on
authentication/scopes, message operations, thread operations, draft workflow,
sending with send-as aliases, label management, signature retrieval, and
scheduled send integration patterns.

Add code examples for common workflows: reading emails, searching,
composing/sending, draft-to-send, external scheduler integration.

Document MIME format requirements and base64url encoding.

Include troubleshooting section for scope errors, send-as validation, and quota
limits.

Phase 8: Technical Debt Cleanup

Remove deprecated code and archive legacy handler directories.

Task 1: Remove Deprecated Code

Clean up deprecated functions and files.

• Delete the deprecated parseToolDefinitions() function and supporting code (lines 147-238) in src/tools/listTools.ts
• Remove associated imports and type definitions that are only used by the deprecated function
• Update any comments referencing the old parsing approach
• Delete src/__tests__/integration/addQuestion-integration.test.ts file entirely (skipped test for deprecated architecture)

Task 2: Update Test File Imports

Fix test files that reference legacy handlers before archival.

• Update src/__tests__/sheets-handler-range-resolution.test.ts to import from src/modules/sheets/ instead of legacy sheets handler
• Update src/__tests__/integration/addQuestion-integration.test.ts references (if not deleted) or remove the file as it's already marked for deletion
• Run all tests to verify no broken imports remain
• Ensure test coverage remains above thresholds after updates

Task 3: Archive Legacy Handlers

Move legacy handler directories to archive location.

• Create archive/legacy-handlers-v1/ directory in project root
• Move src/drive/, src/sheets/, src/forms/, src/docs/ directories to archive location
• Update .gitignore if needed to track archive directory
• Document archival in CHANGELOG.md noting that v1.x handler pattern has been fully replaced by v2.0.0 module pattern
• Verify no remaining imports reference archived directories by running build and tests

Task 4: Code Quality and Version

Run linting, update version, and finalize changes.

• Run npm run lint -- --fix to auto-fix any linting issues
• Update package.json version to "3.2.0"
• Update CHANGELOG.md to document v3.2.0 release with Gmail feature additions and technical debt cleanup
• Verify all tests pass and coverage meets thresholds (90%+ for new Gmail code)
• Run full build to ensure no compilation errors

🤖 Prompt for AI agents

This phase cleans up technical debt by removing deprecated code and archiving
legacy handlers.

Delete deprecated `parseToolDefinitions()` function and supporting code in
`src/tools/listTools.ts`.

Remove associated imports and type definitions.

Update comments referencing old parsing approach.

Delete `src/__tests__/integration/addQuestion-integration.test.ts`.

Update `src/__tests__/sheets-handler-range-resolution.test.ts` to import from
`src/modules/sheets/`.

Run tests to verify no broken imports.

Create `archive/legacy-handlers-v1/` directory.

Move `src/drive/`, `src/sheets/`, `src/forms/`, `src/docs/` to archive.

Update `.gitignore` if needed.

Document archival in `CHANGELOG.md`.

Verify no imports reference archived directories.

Run `npm run lint -- --fix`.

Update `package.json` version to "3.2.0".

Update `CHANGELOG.md` with v3.2.0 release notes.

Verify tests pass and coverage meets thresholds.

Run full build.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

This phase establishes the Gmail module foundation with types, context, and
authentication setup.

Create `src/modules/gmail/types.ts` with Gmail-specific TypeScript interfaces
for messages, threads, drafts, labels, and all operation options
(ListMessagesOptions, GetMessageOptions, SendMessageOptions, etc.) with
corresponding Result interfaces.

Add `GmailContext` interface to `src/modules/types.ts` extending BaseContext
with `gmail: gmail_v1.Gmail` property.

Create `src/modules/gmail/index.ts` as barrel export file.

Update `src/modules/index.ts` to export gmail module namespace and GmailContext.

In `index.ts` authenticateAndSaveCredentials function, add five Gmail OAuth
scopes: gmail.readonly, gmail.send, gmail.compose, gmail.modify,
gmail.settings.basic.

Initialize Gmail API client using `google.gmail("v1")` in context creation
section.

Document re-authentication requirement in README.md for v3.2.0 upgrade.
===============================================================================

Task: 2

This phase implements list and read operations for Gmail messages and threads.

Create `src/modules/gmail/list.ts` with `listMessages` and `listThreads`
functions accepting options (userId, maxResults, pageToken, query, labelIds) and
GmailContext.

Implement pagination with nextPageToken handling.

Use gmail.users.messages.list and gmail.users.threads.list API methods.

Add cache invalidation for modified messages/threads.

Create `src/modules/gmail/read.ts` with `getMessage` and `getThread` functions.

Accept userId, messageId/threadId, and format options (FULL, METADATA, RAW,
MINIMAL).

Use gmail.users.messages.get and gmail.users.threads.get API methods.

Implement caching with context.cacheManager.

Parse message headers, body, and attachment metadata.
===============================================================================

Task: 3

This phase implements search and label management for Gmail.

Create `src/modules/gmail/search.ts` with `searchMessages` function accepting
query string (Gmail search syntax), maxResults, and pagination options.

Use messages.list API with query construction and result formatting.

Add JSDoc examples for common search patterns (from:, to:, subject:,
has:attachment, is:unread, etc.).

Include performance monitoring.

Create `src/modules/gmail/labels.ts` with `listLabels` and `modifyLabels`
functions.

For listLabels, use gmail.users.labels.list to retrieve labels with IDs and
properties.

For modifyLabels, accept messageId and arrays of labelIds to add/remove, use
gmail.users.messages.modify.

Implement cache invalidation when labels are modified.

Add label validation.
===============================================================================

Task: 4

This phase implements draft creation, message sending, and signature operations.

Create `src/modules/gmail/compose.ts` with `createDraft` function accepting to,
cc, bcc, subject, body (HTML/plain text), and inReplyTo (threadId) options.

Implement RFC 2822 MIME message construction with proper headers.

Use base64url encoding for message.raw.

Call gmail.users.drafts.create and return draft ID with message details.

Create `src/modules/gmail/send.ts` with `sendMessage`, `sendDraft`, and
`scheduleSend` functions.

For sendMessage, accept compose options plus optional `from` parameter,
construct MIME message, call gmail.users.messages.send.

For sendDraft, accept draftId and optional updates, call
gmail.users.drafts.send.

For scheduleSend, create draft and return draft ID with metadata including
intended send time, add JSDoc explaining external scheduling infrastructure
requirement.

Validate send-as aliases.

Implement cache invalidation for sent messages.

Create `src/modules/gmail/signature.ts` with `getSignature` function accepting
userId and optional sendAsEmail.

Use gmail.users.settings.sendAs.list to retrieve signatures.

Parse and return signature HTML.

Add caching with appropriate TTL.
===============================================================================

Task: 5

This phase integrates Gmail into the MCP server tool registration and dispatch
system.

Update `index.ts` tool definitions array to add gmail tool after docs.

Define operation enum with all 12 operations: listMessages, listThreads,
getMessage, getThread, searchMessages, createDraft, sendMessage, sendDraft,
scheduleSend, listLabels, modifyLabels, getSignature.

Add generic params object schema.

Import Gmail operation types.

Add gmail case to CallToolRequestSchema handler switch statement.

Use dynamic import for gmail module.

Create nested switch for operation routing.

Type cast params and include GmailContext.

Add performance tracking.

Update `src/tools/listTools.ts` generateToolStructure to include gmail section
with all 12 operations, parameters, descriptions, and JSDoc examples.
===============================================================================

Task: 6

This phase implements comprehensive test coverage for Gmail operations.

Create unit test files in `src/__tests__/gmail/` mirroring module structure:
list.test.ts, read.test.ts, search.test.ts, compose.test.ts, send.test.ts,
labels.test.ts, signature.test.ts.

Mock gmail API client methods using jest.fn() with
mockResolvedValue/mockRejectedValue.

Test successful paths with various parameters.

Test error handling (API errors, network failures, invalid parameters).

Test cache behavior (get, set, invalidate).

Achieve 90%+ coverage meeting thresholds: functions 85%, lines 75%, statements
75%, branches 65%.

Create integration tests in `src/__tests__/integration/`:
message-operations-integration.test.ts, draft-workflow-integration.test.ts,
send-operations-integration.test.ts.

Test end-to-end workflows: list → read → modify labels, create draft → send
draft, search → get message.

Use full context setup with mocked API responses.

Verify performance monitoring and logging.

Test error recovery and cache invalidation.
===============================================================================

Task: 7

This phase updates documentation for Gmail functionality.

Update `README.md` Features section with Gmail operations, add Gmail examples to
Quick Start, document OAuth re-authentication requirement for v3.2.0.

Update `CLAUDE.md` Architecture section to include Gmail module, update tool
registration section.

Update `docs/Developer-Guidelines/API.md` with Gmail API Reference section
covering all 12 operations, parameters, return types, and usage examples.

Create `docs/Guides/gmail-integration.md` with sections on
authentication/scopes, message operations, thread operations, draft workflow,
sending with send-as aliases, label management, signature retrieval, and
scheduled send integration patterns.

Add code examples for common workflows: reading emails, searching,
composing/sending, draft-to-send, external scheduler integration.

Document MIME format requirements and base64url encoding.

Include troubleshooting section for scope errors, send-as validation, and quota
limits.
===============================================================================

Task: 8

This phase cleans up technical debt by removing deprecated code and archiving
legacy handlers.

Delete deprecated `parseToolDefinitions()` function and supporting code in
`src/tools/listTools.ts`.

Remove associated imports and type definitions.

Update comments referencing old parsing approach.

Delete `src/__tests__/integration/addQuestion-integration.test.ts`.

Update `src/__tests__/sheets-handler-range-resolution.test.ts` to import from
`src/modules/sheets/`.

Run tests to verify no broken imports.

Create `archive/legacy-handlers-v1/` directory.

Move `src/drive/`, `src/sheets/`, `src/forms/`, `src/docs/` to archive.

Update `.gitignore` if needed.

Document archival in `CHANGELOG.md`.

Verify no imports reference archived directories.

Run `npm run lint -- --fix`.

Update `package.json` version to "3.2.0".

Update `CHANGELOG.md` with v3.2.0 release notes.

Verify tests pass and coverage meets thresholds.

Run full build.

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord or schedule a call!

[AojdevStudio]

✅ Implementation Complete!

PR #29 contains the full Gmail API integration for v3.2.0.

Completed Operations (10 of 12 planned)

Operation	Status	Notes
listMessages	✅ Complete	With pagination, filters
listThreads	✅ Complete	With pagination, filters
getMessage	✅ Complete	Full content with headers/body
getThread	✅ Complete	All messages in thread
searchMessages	✅ Complete	Gmail query syntax
createDraft	✅ Complete	HTML/plain text
sendMessage	✅ Complete	With send-as alias support
sendDraft	✅ Complete	Send existing drafts
listLabels	✅ Complete	System + user labels
modifyLabels	✅ Complete	Add/remove labels
scheduleSend	⏸️ Deferred	To v3.3.0
getSignature	⏸️ Deferred	To v3.3.0

Tech Debt Completed

• ✅ Removed deprecated parseToolDefinitions() (84 lines)
• ✅ Deleted skipped addQuestion-integration.test.ts
• ⏸️ Handler directories (src/drive/, etc.) kept - they're ACTIVE code, not legacy!

Testing

• ✅ Build passes
• ✅ Lint passes (warnings only)
• ✅ Manual Docker testing successful

Ready for Review

PR: #29

Once merged, users will need to re-authenticate to grant Gmail OAuth scopes.