MCP 服务器

Gmail MCP Server

Provides comprehensive Gmail integration with 25+ tools for intelligent email management, including AI-powered categorization, advanced search and filtering, automated archiving and cleanup, analytics, and secure OAuth2 authentication.

README

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

🚀 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

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

Configure environment:

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

Create directories:
```
mkdir -p data logs archives
```
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

Authentication: OAuth2 flow with secure token storage
Email Fetching: Batch processing with Gmail API rate limiting
Categorization: Multi-analyzer pipeline with ML-like scoring
Search: Indexed search with complex filter combinations
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

🌟 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

🧪 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
📝 Documentation
- Update README.md for new tools
- Add JSDoc comments for public APIs
- Include usage examples
- Update architecture diagrams

Adding New MCP Tools

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']
  }
];

Implement Tool Handler

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

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);
  });
}

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

🎯 Issues & Feature Requests
- Use issue templates
- Provide detailed descriptions
- Include use cases and examples
💻 Pull Requests
- Follow PR template
- Include tests and documentation
- Ensure CI passes
- Request reviews
📋 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

Dry Run Mode: All destructive operations support preview mode
Confirmation Prompts: Multi-step confirmation for bulk operations
Safety Limits: Configurable maximum deletion/modification limits
Backup Integration: Automatic backup before major operations
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:

Check Gmail Trash folder first
Use restore_emails if archived
Check local database for metadata
Contact Gmail support for account recovery

If system is unresponsive:

Cancel all running jobs: cancel_job
Restart server: npm start
Check system health: get_system_health
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!

</div>

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.