Gmail MCP Server

A comprehensive Model Context Protocol (MCP) server that integrates with Gmail API to provide intelligent email management capabilities. Features advanced email categorization, search, archiving, deletion, and automated cleanup with 25+ MCP tools for complete email lifecycle management.

🚀 Key Features

📧 Intelligent Email Management

• AI-Powered Categorization: Automatically categorize emails by importance (high/medium/low) using advanced analysis

• Smart Search & Filtering: Advanced search with multiple criteria, saved searches, and filter combinations

• Real-time Processing: Background job processing for long-running operations with progress tracking

🗄️ Archive & Export System

• Smart Archiving: Archive emails based on rules with multiple export formats (MBOX, JSON, CSV)

• Automated Rules Engine: Create and manage automatic archiving rules with scheduling

• Restore Capability: Restore previously archived emails with full metadata

🧹 Advanced Cleanup Automation

• Policy-Based Cleanup: 13+ cleanup tools with configurable policies for automated email management

• Access Pattern Tracking: Track email access patterns for intelligent cleanup decisions

• Safety-First Design: Dry-run options, confirmation steps, and rollback capabilities

📊 Analytics & Monitoring

• Comprehensive Statistics: Detailed email usage analytics by category, year, size, and more

• System Health Monitoring: Real-time metrics, performance tracking, and system health reports

• Cleanup Recommendations: AI-driven recommendations for optimal email management

🔒 Security & Safety

• OAuth2 Authentication: Secure Gmail API integration with encrypted token storage

• Multi-layered Safety: Confirmation prompts, dry-run modes, and maximum deletion limits

• Audit Logging: Complete operation logging and error tracking

📋 Table of Contents

• 🚀 Quick Start

• 📦 Installation

• 🔧 Configuration

• 🛠️ MCP Tools Reference

  • 🔐 Authentication Tools

  • 📧 Email Management Tools

  • 🔍 Search & Filter Tools

  • 📁 Archive & Export Tools

  • 🗑️ Delete & Cleanup Tools

  • 📊 Statistics & Analytics Tools

  • ⚙️ Job Management Tools

• 🏗️ Architecture Overview

• 🔧 Development & Contributing

• 📚 Example Workflows

• 🔒 Security & Safety

• ❓ Troubleshooting

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm

• Google Cloud Platform account with Gmail API enabled

• OAuth2 credentials (Client ID and Client Secret)

Automated Setup

# Clone and install
git clone <repository-url>
cd gmail-mcp-server
npm run setup  # Interactive setup wizard
npm install && npm run build

First Run

# Start the MCP server
npm start

# Authenticate with Gmail (run in your MCP client)
{
  "tool": "authenticate"
}

📦 Installation

Method 1: Quick Setup (Recommended)

# 1. Clone repository
git clone <repository-url>
cd gmail-mcp-server

# 2. Run interactive setup
npm run setup

# 3. Install and build
npm install
npm run build

The setup script will guide you through:

• 🔑 Setting up Google Cloud credentials

• 📁 Creating necessary directories

• ⚙️ Configuring environment variables

• 🔧 Initial configuration

Method 2: Manual Setup

1. Set up Google Cloud credentials:

   • Go to Google Cloud Console

   • Create project or select existing

   • Enable Gmail API

   • Create OAuth2 credentials (Desktop application)

   • Download credentials.json to project root

2. Configure environment:

   cp .env.example .env
   # Edit .env with your settings

3. Create directories:

   mkdir -p data logs archives

4. Install and build:

   npm install
   npm run build

🔧 Configuration

MCP Client Setup

For Claude Desktop:

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/path/to/gmail-mcp-server/build/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

For other MCP clients:

# Direct stdio connection
node /path/to/gmail-mcp-server/build/index.js

Environment Configuration

Key environment variables in .env:

GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REDIRECT_URI=http://localhost:3000/oauth2callback
STORAGE_PATH=./data
CACHE_TTL=3600
LOG_LEVEL=info

🛠️ MCP Tools Reference

The Gmail MCP Server provides 25+ specialized tools organized into logical categories for comprehensive email management. Each tool includes safety features, parameter validation, and detailed error handling.

🔐 Authentication Tools

authenticate

Initiates OAuth2 authentication flow with Gmail API.

Parameters:

• scopes (array, optional): Additional OAuth scopes beyond Gmail read/write

Returns: Authentication status and user email

{
  "tool": "authenticate",
  "arguments": {
    "scopes": ["https://www.googleapis.com/auth/gmail.modify"]
  }
}

📧 Email Management Tools

list_emails

List emails with comprehensive filtering and pagination.

Parameters:

• category (string): Filter by importance level (high|medium|low)

• year (number): Filter by specific year

• size_min (number): Minimum size in bytes

• size_max (number): Maximum size in bytes

• archived (boolean): Include archived emails

• has_attachments (boolean): Filter by attachment presence

• labels (array): Filter by Gmail labels

• query (string): Custom Gmail query string

• limit (number, default: 50): Maximum results

• offset (number, default: 0): Skip first N results

{
  "tool": "list_emails",
  "arguments": {
    "category": "high",
    "year": 2024,
    "has_attachments": true,
    "limit": 25
  }
}

get_email_details

Retrieve complete email content and metadata.

Parameters:

• id (string, required): Gmail message ID

Returns: Full email object with headers, body, attachments

{
  "tool": "get_email_details",
  "arguments": {
    "id": "18c2e4f5d9a8b7c3"
  }
}

categorize_emails

Analyze and categorize emails by importance using AI algorithms.

Parameters:

• year (number, required): Year to categorize

• force_refresh (boolean): Re-analyze already categorized emails

Returns: Categorization job status and statistics

{
  "tool": "categorize_emails",
  "arguments": {
    "year": 2024,
    "force_refresh": true
  }
}

🔍 Search & Filter Tools

search_emails

Advanced multi-criteria email search with intelligent filtering.

Parameters:

• query (string): Text search query

• category (string): Importance filter (high|medium|low)

• year_range (object): Date range with start and/or end year

• size_range (object): Size range with min and/or max bytes

• sender (string): Filter by sender email address

• has_attachments (boolean): Attachment presence filter

• archived (boolean): Include archived emails

• limit (number, default: 50): Maximum results

{
  "tool": "search_emails",
  "arguments": {
    "query": "project deadline",
    "category": "high",
    "year_range": { "start": 2024 },
    "size_range": { "min": 1048576 },
    "sender": "manager@company.com"
  }
}

save_search

Save search criteria for quick reuse.

Parameters:

• name (string, required): Name for saved search

• criteria (object, required): Search criteria to save

{
  "tool": "save_search",
  "arguments": {
    "name": "Large Recent Emails",
    "criteria": {
      "size_range": { "min": 5242880 },
      "year_range": { "start": 2024 }
    }
  }
}

list_saved_searches

Retrieve all saved search queries.

Parameters: None

Returns: Array of saved searches with usage statistics

{
  "tool": "list_saved_searches"
}

📁 Archive & Export Tools

archive_emails

Archive emails using multiple methods and formats.

Parameters:

• search_criteria (object): Email selection criteria

• category (string): Archive by importance level

• year (number): Archive emails from specific year

• older_than_days (number): Archive emails older than N days

• method (string, required): Archive method (gmail|export)

• export_format (string): Format when exporting (mbox|json)

• export_path (string): Custom export destination

• dry_run (boolean, default: false): Preview mode

{
  "tool": "archive_emails",
  "arguments": {
    "category": "low",
    "older_than_days": 180,
    "method": "export",
    "export_format": "mbox",
    "dry_run": false
  }
}

restore_emails

Restore emails from previous archives.

Parameters:

• archive_id (string): Specific archive to restore from

• email_ids (array): Individual email IDs to restore

• restore_labels (array): Labels to apply to restored emails

{
  "tool": "restore_emails",
  "arguments": {
    "archive_id": "archive_2023_low_priority",
    "restore_labels": ["restored", "reviewed"]
  }
}

create_archive_rule

Create automated archiving rules with scheduling.

Parameters:

• name (string, required): Descriptive rule name

• criteria (object, required): Archiving conditions

• action (object, required): Archive method and format

• schedule (string): Execution frequency (daily|weekly|monthly)

{
  "tool": "create_archive_rule",
  "arguments": {
    "name": "Auto-archive old promotional emails",
    "criteria": {
      "category": "low",
      "older_than_days": 90,
      "labels": ["promotions"]
    },
    "action": {
      "method": "gmail"
    },
    "schedule": "weekly"
  }
}

list_archive_rules

View all configured archive rules and their status.

Parameters:

• active_only (boolean, default: false): Show only enabled rules

{
  "tool": "list_archive_rules",
  "arguments": {
    "active_only": true
  }
}

export_emails

Export emails to external formats with cloud upload support.

Parameters:

• search_criteria (object): Email selection filters

• format (string, required): Export format (mbox|json|csv)

• include_attachments (boolean, default: false): Include attachments

• output_path (string): Local output path

• cloud_upload (object): Cloud storage configuration

{
  "tool": "export_emails",
  "arguments": {
    "format": "json",
    "search_criteria": { "year": 2023 },
    "include_attachments": true,
    "cloud_upload": {
      "provider": "gdrive",
      "path": "/backups/gmail-2023"
    }
  }
}

🗑️ Delete & Cleanup Tools

delete_emails

Safely delete emails with comprehensive safety checks.

⚠️ Safety Note: Always use dry_run: true first to preview deletions

Parameters:

• search_criteria (object): Email selection filters

• category (string): Delete by importance level

• year (number): Delete from specific year

• size_threshold (number): Delete emails larger than N bytes

• skip_archived (boolean, default: true): Skip archived emails

• dry_run (boolean, default: false): Preview mode

• max_count (number, default: 10): Safety limit

{
  "tool": "delete_emails",
  "arguments": {
    "category": "low",
    "year": 2022,
    "dry_run": true,
    "max_count": 50
  }
}

empty_trash

Permanently delete all emails in Gmail trash folder.

⚠️ Destructive Operation: This permanently deletes emails

Parameters:

• dry_run (boolean, default: false): Preview mode

• max_count (number, default: 10): Safety limit

{
  "tool": "empty_trash",
  "arguments": {
    "dry_run": true,
    "max_count": 100
  }
}

trigger_cleanup

Execute manual cleanup using specific policies.

Parameters:

• policy_id (string, required): Cleanup policy to execute

• dry_run (boolean, default: false): Preview mode

• max_emails (number): Processing limit

• force (boolean, default: false): Execute even if policy disabled

{
  "tool": "trigger_cleanup",
  "arguments": {
    "policy_id": "old_low_priority_emails",
    "dry_run": true,
    "max_emails": 500
  }
}

get_cleanup_status

Monitor cleanup automation system status.

Parameters: None

Returns: System status, active jobs, and health metrics

{
  "tool": "get_cleanup_status"
}

get_system_health

Get comprehensive system health and performance metrics.

Parameters: None

Returns: Performance metrics, storage usage, and system status

{
  "tool": "get_system_health"
}

create_cleanup_policy

Create advanced cleanup policies with detailed criteria.

Parameters:

• name (string, required): Policy name

• enabled (boolean, default: true): Policy status

• priority (number, default: 50): Execution priority (0-100)

• criteria (object, required): Cleanup conditions

• action (object, required): Action to take

• safety (object, required): Safety configuration

• schedule (object): Optional scheduling

{
  "tool": "create_cleanup_policy",
  "arguments": {
    "name": "Aggressive Low Priority Cleanup",
    "priority": 80,
    "criteria": {
      "age_days_min": 90,
      "importance_level_max": "low",
      "spam_score_min": 0.7
    },
    "action": {
      "type": "delete"
    },
    "safety": {
      "max_emails_per_run": 100,
      "require_confirmation": false,
      "dry_run_first": true
    }
  }
}

update_cleanup_policy

Modify existing cleanup policy configuration.

Parameters:

• policy_id (string, required): Policy to update

• updates (object, required): Changes to apply

{
  "tool": "update_cleanup_policy",
  "arguments": {
    "policy_id": "policy_123",
    "updates": {
      "enabled": false,
      "safety": { "max_emails_per_run": 50 }
    }
  }
}

list_cleanup_policies

View all cleanup policies and their configurations.

Parameters:

• active_only (boolean, default: false): Show only enabled policies

{
  "tool": "list_cleanup_policies",
  "arguments": {
    "active_only": true
  }
}

delete_cleanup_policy

Remove a cleanup policy permanently.

Parameters:

• policy_id (string, required): Policy to delete

{
  "tool": "delete_cleanup_policy",
  "arguments": {
    "policy_id": "outdated_policy_456"
  }
}

create_cleanup_schedule

Schedule automatic cleanup policy execution.

Parameters:

• name (string, required): Schedule name

• type (string, required): Schedule type (daily|weekly|monthly|interval|cron)

• expression (string, required): Schedule expression

• policy_id (string, required): Policy to schedule

• enabled (boolean, default: true): Schedule status

{
  "tool": "create_cleanup_schedule",
  "arguments": {
    "name": "Nightly Low Priority Cleanup",
    "type": "daily",
    "expression": "02:00",
    "policy_id": "low_priority_policy",
    "enabled": true
  }
}

update_cleanup_automation_config

Update global cleanup automation settings.

Parameters:

• config (object, required): Configuration updates

{
  "tool": "update_cleanup_automation_config",
  "arguments": {
    "config": {
      "continuous_cleanup": {
        "enabled": true,
        "target_emails_per_minute": 10
      }
    }
  }
}

get_cleanup_metrics

Retrieve cleanup system analytics and performance data.

Parameters:

• hours (number, default: 24): History window in hours

{
  "tool": "get_cleanup_metrics",
  "arguments": {
    "hours": 168
  }
}

get_cleanup_recommendations

Get AI-powered cleanup policy recommendations.

Parameters: None

Returns: Recommended policies based on email analysis

{
  "tool": "get_cleanup_recommendations"
}

📊 Statistics & Analytics Tools

get_email_stats

Comprehensive email usage statistics and analytics.

Parameters:

• group_by (string): Grouping method (year|category|label|all)

• year (number): Filter by specific year

Returns: Detailed statistics by categories, years, sizes, and storage

{
  "tool": "get_email_stats",
  "arguments": {
    "group_by": "all"
  }
}

⚙️ Job Management Tools

list_jobs

View all background jobs with filtering options.

Parameters:

• limit (number, default: 50): Maximum results

• offset (number, default: 0): Skip first N jobs

• status (string): Filter by status (pending|running|completed|failed)

• job_type (string): Filter by job type

{
  "tool": "list_jobs",
  "arguments": {
    "status": "running",
    "limit": 25
  }
}

get_job_status

Get detailed status of a specific background job.

Parameters:

• id (string, required): Job ID to query

Returns: Job details, progress, and results

{
  "tool": "get_job_status",
  "arguments": {
    "id": "categorization_job_789"
  }
}

cancel_job

Cancel a running background job.

Parameters:

• id (string, required): Job ID to cancel

{
  "tool": "cancel_job",
  "arguments": {
    "id": "cleanup_job_101112"
  }
}

Example Workflows

Initial Setup

// 1. Authenticate
{
  "tool": "authenticate"
}

// 2. Categorize all emails
{
  "tool": "categorize_emails",
  "arguments": {
    "force_refresh": true
  }
}

// 3. View statistics
{
  "tool": "get_email_stats",
  "arguments": {
    "group_by": "all"
  }
}

Clean Up Old Emails

// 1. Search for old large emails
{
  "tool": "search_emails",
  "arguments": {
    "year_range": { "end": 2022 },
    "size_range": { "min": 5242880 }
  }
}

// 2. Archive them
{
  "tool": "archive_emails",
  "arguments": {
    "year": 2022,
    "size_threshold": 5242880,
    "method": "export",
    "export_format": "mbox"
  }
}

Automated Cleanup Setup

// 1. Start cleanup automation [TODO]
{
  "tool": "start_cleanup_automation",
  "arguments": {
    "policies": ["old_emails", "large_attachments"],
    "schedule": "daily"
  }
}

// 2. Monitor cleanup status
{
  "tool": "get_cleanup_status"
}

Development

Project Structure

gmail-mcp-server/
├── src/
│   ├── auth/           # Authentication management
│   ├── cache/          # Caching layer
│   ├── categorization/ # Email categorization engine
│   ├── cleanup/        # Cleanup automation
│   ├── database/       # SQLite database management
│   ├── delete/         # Email deletion logic
│   ├── email/          # Email fetching and processing
│   ├── search/         # Search functionality
│   ├── archive/        # Archive management
│   ├── tools/          # MCP tool definitions
│   ├── types/          # TypeScript type definitions
│   └── utils/          # Utility functions
├── build/              # Compiled JavaScript
├── data/               # Local storage
├── logs/               # Application logs
└── archives/           # Email archives

Running in Development

npm run watch  # Watch mode for TypeScript
npm run dev    # Run with tsx (hot reload)

Testing with MCP Inspector

npm run inspector

Testing

The project includes comprehensive test suites to ensure reliability and correctness of all features.

Running Tests

# Run all tests
npm test

# Run with coverage
npm test -- --coverage

# Run specific test suite
npm test -- --testPathPattern=delete

Integration Tests

Delete Email Tests

The delete functionality has extensive integration tests covering all scenarios:

# Run delete integration tests with the dedicated runner
node scripts/test-delete-integration.js

# With coverage report
node scripts/test-delete-integration.js --coverage

# Run specific test scenarios
node scripts/test-delete-integration.js --filter "delete by category"

For detailed information about delete email testing, see Delete Email Testing Documentation.

Test Structure

tests/
├── unit/               # Unit tests for individual components
├── integration/        # Integration tests for complete features
│   └── delete/        # Delete email integration tests
├── fixtures/          # Shared test data
└── setup.ts          # Test environment setup

Writing Tests

• Follow the existing test patterns

• Use descriptive test names

• Mock external dependencies

• Test both success and error cases

• Maintain test coverage above 80%

Security

• OAuth2 tokens are encrypted at rest

• All bulk operations require confirmation

• Audit logging for all operations

• Rate limiting implemented for Gmail API

• Access pattern tracking for security monitoring

Troubleshooting

Authentication Issues

• Ensure credentials.json is in the correct location

• Check that Gmail API is enabled in GCP

• Verify redirect URI matches your configuration

Performance

• First categorization may take time for large mailboxes

• Use pagination for large result sets

• Enable caching in production

License

MIT

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

🏗️ Architecture Overview

The Gmail MCP Server follows a modular, layered architecture designed for scalability, maintainability, and extensibility.

Core Architecture

graph TB
    subgraph "MCP Server Layer"
        MCP[MCP Server] --> TR[Tool Registry]
        TR --> AUTH[Auth Tools]
        TR --> EMAIL[Email Tools] 
        TR --> SEARCH[Search Tools]
        TR --> ARCHIVE[Archive Tools]
        TR --> DELETE[Delete Tools]
        TR --> JOB[Job Tools]
    end
    
    subgraph "Business Logic Layer"
        AUTH --> AM[Auth Manager]
        EMAIL --> EF[Email Fetcher]
        EMAIL --> CE[Categorization Engine]
        SEARCH --> SE[Search Engine]
        ARCHIVE --> ARM[Archive Manager]
        DELETE --> DM[Delete Manager]
        JOB --> JS[Job Status Store]
    end
    
    subgraph "Data Layer"
        AM --> DB[(SQLite Database)]
        CE --> DB
        SE --> DB
        ARM --> DB
        DM --> DB
        JS --> DB
        EF --> CACHE[Cache Manager]
    end
    
    subgraph "External Services"
        AM --> OAUTH[Google OAuth2]
        EF --> GMAIL[Gmail API]
        ARM --> CLOUD[Cloud Storage]
    end

Project Structure

gmail-mcp-server/
├── 📁 src/
│   ├── 🔐 auth/                    # OAuth2 authentication & token management
│   │   └── AuthManager.ts          # Core authentication logic
│   ├── 📧 email/                   # Email processing & fetching
│   │   └── EmailFetcher.ts         # Gmail API integration
│   ├── 🧠 categorization/          # AI-powered email categorization
│   │   ├── CategorizationEngine.ts # Main categorization logic
│   │   ├── CategorizationWorker.ts # Background processing
│   │   └── analyzers/              # Specialized analyzers
│   │       ├── ImportanceAnalyzer.ts
│   │       ├── DateSizeAnalyzer.ts
│   │       └── LabelClassifier.ts
│   ├── 🔍 search/                  # Advanced search functionality
│   │   └── SearchEngine.ts         # Multi-criteria search
│   ├── 📁 archive/                 # Email archiving & export
│   │   └── ArchiveManager.ts       # Archive operations
│   ├── 🗑️ delete/                  # Safe email deletion
│   │   └── DeleteManager.ts        # Deletion with safety checks
│   ├── 🧹 cleanup/                 # Automated cleanup system
│   │   ├── CleanupAutomationEngine.ts
│   │   ├── CleanupPolicyEngine.ts
│   │   ├── StalenessScorer.ts
│   │   └── SystemHealthMonitor.ts
│   ├── 🛠️ tools/                   # MCP tool definitions
│   │   ├── ToolRegistry.ts         # Tool registration system
│   │   ├── definitions/            # Tool definitions by category
│   │   └── base/                   # Tool builder utilities
│   ├── 💾 database/                # Data persistence
│   │   ├── DatabaseManager.ts      # SQLite management
│   │   └── JobStatusStore.ts       # Job tracking
│   ├── ⚡ cache/                   # Performance caching
│   │   └── CacheManager.ts         # In-memory & persistent cache
│   └── 📊 types/                   # TypeScript definitions
│       └── index.ts                # Comprehensive type system
├── 📁 tests/                       # Comprehensive test suite
│   ├── unit/                       # Unit tests
│   ├── integration/                # Integration tests
│   └── performance/                # Performance tests
├── 📁 docs/                        # Documentation
├── 📁 scripts/                     # Utility scripts
└── 📁 examples/                    # Usage examples

Key Design Patterns

• 🔧 Modular Architecture: Each component has a single responsibility

• 🏭 Factory Pattern: Tool creation and configuration management

• 📦 Repository Pattern: Data access abstraction

• 🔄 Observer Pattern: Event-driven cleanup automation

• 🛡️ Strategy Pattern: Multiple categorization algorithms

• ⚡ Caching Strategy: Multi-level caching for performance

Data Flow

1. Authentication: OAuth2 flow with secure token storage

2. Email Fetching: Batch processing with Gmail API rate limiting

3. Categorization: Multi-analyzer pipeline with ML-like scoring

4. Search: Indexed search with complex filter combinations

5. Operations: Safe execution with dry-run and confirmation steps

🔧 Development & Contributing

Development Setup

# Clone and setup
git clone <repository-url>
cd gmail-mcp-server
npm install

# Development mode
npm run dev          # Hot reload with tsx
npm run watch        # TypeScript watch mode

# Testing
npm test            # Run all tests
npm run test:watch  # Watch mode testing
npm run inspector   # MCP Inspector for testing tools

Development Workflow

1. 🌟 Feature Development

   # Create feature branch
   git checkout -b feature/new-tool-name
   
   # Make changes
   # Add tests
   # Update documentation
   
   # Test thoroughly
   npm test
   npm run build

2. 🧪 Testing Strategy

   • Unit Tests: Individual component testing

   • Integration Tests: End-to-end workflow testing

   • Performance Tests: Load and stress testing

   • Manual Testing: MCP Inspector validation

3. 📝 Documentation

   • Update README.md for new tools

   • Add JSDoc comments for public APIs

   • Include usage examples

   • Update architecture diagrams

Adding New MCP Tools

1. Create Tool Definition

   // src/tools/definitions/my-category.tools.ts
   export const myToolConfigs: ToolConfig[] = [
     {
       name: 'my_new_tool',
       description: 'Description of what the tool does',
       category: 'my_category',
       parameters: {
         required_param: ParameterTypes.string('Required parameter'),
         optional_param: ParameterTypes.boolean('Optional parameter', false)
       },
       required: ['required_param']
     }
   ];

2. Implement Tool Handler

   // src/tools/handlers/my-tool.handler.ts
   export async function handleMyNewTool(args: MyToolArgs): Promise<MyToolResult> {
     // Implementation
   }

3. Register Tool

   // src/tools/definitions/index.ts
   import { myToolConfigs } from './my-category.tools.js';
   
   export function registerAllTools() {
     myToolConfigs.forEach(config => {
       toolRegistry.registerTool(ToolBuilder.fromConfig(config), config.category);
     });
   }

4. Add Tests

   // tests/unit/tools/my-tool.test.ts
   describe('my_new_tool', () => {
     it('should handle valid input', async () => {
       // Test implementation
     });
   });

Code Quality Standards

• 🔍 TypeScript: Strict type checking with comprehensive interfaces

• 📏 ESLint: Code style and quality enforcement

• 🎯 Testing: >80% test coverage requirement

• 📚 Documentation: JSDoc for all public APIs

• 🔒 Security: Input validation and sanitization

• ⚡ Performance: Efficient algorithms and caching

Architecture Guidelines

• 🏗️ Separation of Concerns: Each module has a single responsibility

• 🔌 Dependency Injection: Loose coupling between components

• 📈 Scalability: Designed for large email datasets

• 🛡️ Error Handling: Comprehensive error handling and logging

• 🔄 Async Operations: Non-blocking I/O with proper resource cleanup

Contributing Guidelines

1. 🎯 Issues & Feature Requests

   • Use issue templates

   • Provide detailed descriptions

   • Include use cases and examples

2. 💻 Pull Requests

   • Follow PR template

   • Include tests and documentation

   • Ensure CI passes

   • Request reviews

3. 📋 Code Review Checklist

   • ✅ Tests pass and coverage maintained

   • ✅ Documentation updated

   • ✅ Type safety maintained

   • ✅ Security considerations addressed

   • ✅ Performance implications considered

Extension Points

The server is designed for extensibility:

• 🔧 Custom Tools: Add domain-specific tools

• 🧠 Analyzers: Implement custom categorization algorithms

• 📊 Exporters: Add new export formats

• 🔍 Search Providers: Integrate external search engines

• ☁️ Storage Backends: Add cloud storage providers

📚 Example Workflows

🚀 Initial Setup & Email Organization

// 1. Authenticate with Gmail
{
  "tool": "authenticate"
}

// 2. Get initial statistics
{
  "tool": "get_email_stats",
  "arguments": {
    "group_by": "all"
  }
}

// 3. Categorize all emails (this may take time for large mailboxes)
{
  "tool": "categorize_emails",
  "arguments": {
    "year": 2024,
    "force_refresh": false
  }
}

// 4. Review categorization results
{
  "tool": "list_emails",
  "arguments": {
    "category": "high",
    "limit": 20
  }
}

🧹 Advanced Cleanup Workflow

// 1. Analyze old emails (dry run first)
{
  "tool": "search_emails",
  "arguments": {
    "year_range": { "end": 2022 },
    "size_range": { "min": 5242880 },
    "category": "low"
  }
}

// 2. Create archive rule for old large emails
{
  "tool": "create_archive_rule",
  "arguments": {
    "name": "Old Large Low Priority",
    "criteria": {
      "category": "low",
      "older_than_days": 365,
      "size_greater_than": 5242880
    },
    "action": {
      "method": "export",
      "export_format": "mbox"
    },
    "schedule": "monthly"
  }
}

// 3. Archive old emails (with dry run first)
{
  "tool": "archive_emails",
  "arguments": {
    "year": 2022,
    "category": "low",
    "method": "export",
    "export_format": "mbox",
    "dry_run": true
  }
}

// 4. Execute actual archival after reviewing dry run
{
  "tool": "archive_emails",
  "arguments": {
    "year": 2022,
    "category": "low",
    "method": "export",
    "export_format": "mbox",
    "dry_run": false
  }
}

🤖 Automated Cleanup Policy Setup

// 1. Create aggressive cleanup policy for spam
{
  "tool": "create_cleanup_policy",
  "arguments": {
    "name": "Spam Cleanup",
    "priority": 90,
    "criteria": {
      "age_days_min": 30,
      "importance_level_max": "low",
      "spam_score_min": 0.8
    },
    "action": {
      "type": "delete"
    },
    "safety": {
      "max_emails_per_run": 200,
      "dry_run_first": true
    }
  }
}

// 2. Create moderate policy for old promotional emails
{
  "tool": "create_cleanup_policy",
  "arguments": {
    "name": "Old Promotions Archive",
    "priority": 50,
    "criteria": {
      "age_days_min": 90,
      "importance_level_max": "low",
      "promotional_score_min": 0.7
    },
    "action": {
      "type": "archive",
      "method": "gmail"
    },
    "safety": {
      "max_emails_per_run": 100
    }
  }
}

// 3. Schedule nightly cleanup
{
  "tool": "create_cleanup_schedule",
  "arguments": {
    "name": "Nightly Cleanup",
    "type": "daily",
    "expression": "02:00",
    "policy_id": "spam_cleanup_policy_id"
  }
}

// 4. Monitor cleanup status
{
  "tool": "get_cleanup_status"
}

🔍 Advanced Search & Analysis

// 1. Save frequently used searches
{
  "tool": "save_search",
  "arguments": {
    "name": "Large Recent Important",
    "criteria": {
      "category": "high",
      "year_range": { "start": 2024 },
      "size_range": { "min": 1048576 }
    }
  }
}

// 2. Search for specific patterns
{
  "tool": "search_emails",
  "arguments": {
    "query": "invoice OR receipt OR payment",
    "category": "high",
    "year_range": { "start": 2023 },
    "has_attachments": true
  }
}

// 3. Export search results
{
  "tool": "export_emails",
  "arguments": {
    "search_criteria": {
      "query": "invoice OR receipt",
      "year_range": { "start": 2023 }
    },
    "format": "csv",
    "include_attachments": false
  }
}

📊 Analytics & Monitoring

// 1. Get comprehensive statistics
{
  "tool": "get_email_stats",
  "arguments": {
    "group_by": "all"
  }
}

// 2. Monitor system health
{
  "tool": "get_system_health"
}

// 3. Get cleanup recommendations
{
  "tool": "get_cleanup_recommendations"
}

// 4. View cleanup metrics
{
  "tool": "get_cleanup_metrics",
  "arguments": {
    "hours": 168
  }
}

🔒 Security & Safety

🛡️ Authentication & Authorization

• OAuth2 Flow: Secure Google OAuth2 implementation

• Token Encryption: All tokens encrypted at rest using AES-256

• Scope Limitation: Minimal required Gmail API scopes

• Token Rotation: Automatic token refresh and rotation

• Session Management: Secure session handling with expiration

🔐 Data Protection

• Local Storage: Encrypted SQLite database for metadata

• No Email Content Storage: Only metadata stored locally

• Audit Logging: Comprehensive operation logging

• Data Isolation: User data completely isolated

• Secure Communication: HTTPS/TLS for all API communications

⚠️ Safety Mechanisms

1. Dry Run Mode: All destructive operations support preview mode

2. Confirmation Prompts: Multi-step confirmation for bulk operations

3. Safety Limits: Configurable maximum deletion/modification limits

4. Backup Integration: Automatic backup before major operations

5. Rollback Capability: Ability to restore from archives

🚨 Risk Mitigation

• Rate Limiting: Gmail API rate limit compliance

• Error Handling: Comprehensive error recovery

• Validation: Input sanitization and validation

• Monitoring: Real-time operation monitoring

• Alerts: Automatic alerts for critical issues

🔍 Security Best Practices

// Always use dry run first for destructive operations
{
  "tool": "delete_emails",
  "arguments": {
    "category": "low",
    "dry_run": true  // ← Always start with dry run
  }
}

// Limit operations with max_count
{
  "tool": "empty_trash",
  "arguments": {
    "max_count": 50,  // ← Safety limit
    "dry_run": true
  }
}

// Use specific criteria instead of broad deletions
{
  "tool": "delete_emails",
  "arguments": {
    "year": 2022,           // ← Specific year
    "category": "low",      // ← Specific category
    "size_threshold": 10485760,  // ← Specific size
    "max_count": 100,       // ← Safety limit
    "dry_run": true
  }
}

❓ Troubleshooting

🔐 Authentication Issues

Problem: Authentication failed or Invalid credentials

# Solutions:
1. Verify credentials.json location (project root)
2. Check Gmail API is enabled in Google Cloud Console
3. Verify OAuth2 redirect URI matches configuration
4. Clear cached tokens: rm -rf data/tokens/
5. Re-run authentication: authenticate tool

Problem: Token expired errors

# Solutions:
1. Tokens auto-refresh, but if persistent:
2. Clear token cache: rm -rf data/tokens/
3. Re-authenticate: use authenticate tool
4. Check system clock is accurate

📧 Email Processing Issues

Problem: Categorization taking too long

# Solutions:
1. Use year-specific categorization:
   { "tool": "categorize_emails", "arguments": { "year": 2024 } }
2. Monitor progress:
   { "tool": "list_jobs", "arguments": { "status": "running" } }
3. Increase timeout in .env: CATEGORIZATION_TIMEOUT=300000

Problem: Search results incomplete

# Solutions:
1. Check Gmail API quota limits
2. Increase search limit: "limit": 500
3. Use pagination: "offset": 0, "limit": 100
4. Clear search cache: restart server

🗑️ Deletion & Cleanup Issues

Problem: Deletion failed or Cleanup stuck

# Solutions:
1. Always start with dry_run: true
2. Check job status: get_job_status
3. Cancel stuck jobs: cancel_job
4. Reduce max_count limits
5. Check Gmail API rate limits

Problem: Archives not restoring

# Solutions:
1. Check archive location exists
2. Verify archive format compatibility
3. Check available storage space
4. Use smaller batch sizes

⚡ Performance Issues

Problem: Slow search or categorization

# Solutions:
1. Enable caching: CACHE_ENABLED=true
2. Increase cache TTL: CACHE_TTL=7200
3. Use specific filters to reduce result sets
4. Consider database optimization: VACUUM

Problem: High memory usage

# Solutions:
1. Reduce batch sizes in operations
2. Clear cache periodically
3. Restart server regularly for large operations
4. Monitor with: get_system_health

📊 Database Issues

Problem: Database locked or SQLite errors

# Solutions:
1. Check for multiple server instances
2. Restart server to release locks
3. Check file permissions: data/ directory
4. Backup and recreate database if corrupted

🔧 Development Issues

Problem: MCP Inspector not working

# Solutions:
1. Install inspector: npm install -g @modelcontextprotocol/inspector
2. Build project first: npm run build
3. Run inspector: npm run inspector
4. Check server logs for errors

Problem: TypeScript compilation errors

# Solutions:
1. Clear build cache: rm -rf build/
2. Reinstall dependencies: npm ci
3. Check TypeScript version: npx tsc --version
4. Update dependencies: npm update

📞 Getting Help

• 📝 Documentation: Check docs/ directory for detailed guides

• 🐛 Issues: Create detailed issue reports on GitHub

• 💬 Discussions: Join community discussions

• 🔍 Debugging: Enable debug logging: LOG_LEVEL=debug

🚨 Emergency Procedures

If you accidentally delete important emails:

1. Check Gmail Trash folder first

2. Use restore_emails if archived

3. Check local database for metadata

4. Contact Gmail support for account recovery

If system is unresponsive:

1. Cancel all running jobs: cancel_job

2. Restart server: npm start

3. Check system health: get_system_health

4. Clear caches if needed: rm -rf data/cache/

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details on:

• 🐛 Bug reports and feature requests

• 💻 Code contributions and pull requests

• 📚 Documentation improvements

• 🧪 Testing and quality assurance

• 🌍 Community support and discussions

⭐ Star this project if you find it useful!

To run the test suite efficiently, always set the environment variable NODE_ENV=test before running tests. This enables fast mode, which:

• Skips artificial delays (e.g., between batches)

• Reduces logging output for cleaner and faster test runs

• Uses smaller data sets in most tests for speed (except explicit performance tests)

Example:

NODE_ENV=test npm test

Or with jest directly:

NODE_ENV=test npx jest

CI/CD:

Your CI pipeline should always set NODE_ENV=test to ensure the fastest possible test execution.