mcpeasy 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75c32597b80568d81e9dd7b100c73b2ea60a8cdb8e3718683bfa28875e4ef098
-  data.tar.gz: 5c345c73d578163d9b04b7262b39e1489258b14522dcd24189042a51fc9524f4
+  metadata.gz: 96510ec1696160a8727b73d66eb7fbe9e9ac267bcdbe7c2e3db1f3a7840657f2
+  data.tar.gz: 64d8e8b25d58845501acba165271cc31010efbff4d3b65799ed932ab244aee09
 SHA512:
-  metadata.gz: 2109cd9167c500802fd0b9ea0145e92fe03de3cb46adca578d924200f4e258c96c3bca39fdf22b094b33920d803cb8792cffad53ec4b262be9363f285fcf7752
-  data.tar.gz: 480c54c57d54194472dc4db20629dc4337cbf93697514ca40d4eb73e53b01028af9137dc83f6a7db1041dc4ca2047a613d40f0756a77bc8627c4fa6fe1e7969e
+  metadata.gz: 6558ab4692baf95e5144db4f888bf594e28f8031a564d5d1127d90197c509b422225ae00438b61e640b1adc1ac355a444f1361db60485586441004d26b379b54
+  data.tar.gz: 8a12fc568bd98fd4ca14ea21f8e8ae6a13ae39bf34eb877a0e1b5e4e69c581f491578710147040a84550c7c4e5e4d791695208b25951ae492d877e860fc71a4f

data/.mcp.json

@@ -27,6 +27,15 @@
       ],
       "env": {}
     },
+    "gmail": {
+      "type": "stdio",
+      "command": "./bin/mcpz",
+      "args": [
+        "gmail",
+        "mcp"
+      ],
+      "env": {}
+    },
     "gmeet": {
       "type": "stdio",
       "command": "./bin/mcpz",

data/CHANGELOG.md

@@ -5,7 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.3.0] - 2025-06-07
+
+### Added
+- Gmail MCP server integration with comprehensive email support
+  - List and search emails with various filters
+  - Read email content including headers and body
+  - Send new emails and reply to existing ones
+  - Manage email labels, mark as read/unread
+  - Archive and trash emails
+  - Full OAuth2 authentication flow integration
 
 ## [0.2.0] - 2025-06-03
 
@@ -47,4 +56,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Google Calendar integration with event listing and search
 - Google Drive integration with file search and content retrieval
 - Basic MCP server implementations for all services
-- Development tooling with standardrb for code quality
+- Development tooling with standardrb for code quality

data/lib/mcpeasy/cli.rb

@@ -103,6 +103,32 @@ module Mcpeasy
     end
   end
 
+  # Load the existing GmailCLI and extend it with MCP functionality
+  require_relative "../utilities/gmail/cli"
+
+  class GmailCommands < Gmail::CLI
+    namespace "gmail"
+
+    desc "mcp", "Run Gmail MCP server"
+    def mcp
+      require_relative "../utilities/gmail/mcp"
+      Gmail::MCPServer.new.run
+    end
+
+    desc "auth", "Authenticate with Gmail API"
+    def auth
+      require_relative "../utilities/gmail/service"
+      tool = Gmail::Service.new(skip_auth: true)
+      result = tool.authenticate
+      if result[:success]
+        puts "✅ Successfully authenticated with Gmail"
+      else
+        puts "❌ Authentication failed: #{result[:error]}"
+        exit 1
+      end
+    end
+  end
+
   class CLI < Thor
     desc "version", "Show mcpeasy version"
     def version
@@ -166,6 +192,9 @@ module Mcpeasy
     desc "notion COMMAND", "Notion commands"
     subcommand "notion", NotionCommands
 
+    desc "gmail COMMAND", "Gmail commands"
+    subcommand "gmail", GmailCommands
+
     class << self
       private
 

data/lib/mcpeasy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mcpeasy
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/utilities/gmail/README.md

@@ -0,0 +1,278 @@
+# Gmail MCP Server
+
+A Model Context Protocol (MCP) server for Gmail integration with AI assistants.
+
+## Features
+
+- **List emails** with filtering by date range, sender, subject, labels, and read/unread status
+- **Search emails** using Gmail's powerful search syntax
+- **Get email content** including full body, headers, and attachment information
+- **Send emails** with support for CC, BCC, and reply-to fields
+- **Reply to emails** with automatic threading and optional quoted text
+- **Email management** - mark as read/unread, add/remove labels, archive, and trash
+- **Test connection** to verify Gmail API connectivity
+
+## Prerequisites
+
+1. **Google Cloud Project** with Gmail API enabled
+2. **OAuth 2.0 credentials** (client ID and client secret)
+3. **Ruby environment** with required gems
+
+## Setup
+
+### 1. Enable Gmail API
+
+1. Go to the [Google Cloud Console](https://console.cloud.google.com)
+2. Create a new project or select an existing one
+3. Enable the Gmail API:
+   - Navigate to "APIs & Services" > "Library"
+   - Search for "Gmail API" and click "Enable"
+
+### 2. Create OAuth 2.0 Credentials
+
+1. Go to "APIs & Services" > "Credentials"
+2. Click "Create Credentials" > "OAuth 2.0 Client IDs"
+3. Set application type to "Desktop application"
+4. Download the JSON file containing your credentials
+
+### 3. Install and Configure MCPEasy
+
+```bash
+# Install the gem
+gem install mcpeasy
+
+# Set up configuration directories
+mcpz setup
+
+# Save your Google credentials
+mcpz set_google_credentials path/to/your/credentials.json
+
+# Authenticate with Gmail (will open browser for OAuth)
+mcpz gmail auth
+```
+
+### 4. Verify Setup
+
+```bash
+# Test the connection
+mcpz gmail test
+```
+
+## CLI Usage
+
+### Authentication
+```bash
+# Authenticate with Gmail API
+mcpz gmail auth
+```
+
+### Listing Emails
+```bash
+# List recent emails
+mcpz gmail list
+
+# Filter by date range
+mcpz gmail list --start_date 2024-01-01 --end_date 2024-01-31
+
+# Filter by sender
+mcpz gmail list --sender "someone@example.com"
+
+# Filter by subject
+mcpz gmail list --subject "Important"
+
+# Filter by labels
+mcpz gmail list --labels "inbox,important"
+
+# Filter by read status
+mcpz gmail list --read_status unread
+
+# Limit results
+mcpz gmail list --max_results 10
+```
+
+### Searching Emails
+```bash
+# Basic search
+mcpz gmail search "quarterly report"
+
+# Advanced Gmail search syntax
+mcpz gmail search "from:boss@company.com subject:urgent"
+mcpz gmail search "has:attachment filename:pdf"
+mcpz gmail search "is:unread after:2024/01/01"
+```
+
+### Reading Emails
+```bash
+# Read a specific email by ID
+mcpz gmail read 18c8b5d4e8f9a2b6
+```
+
+### Sending Emails
+```bash
+# Send a basic email
+mcpz gmail send \
+  --to "recipient@example.com" \
+  --subject "Hello from MCPEasy" \
+  --body "This is a test email sent via Gmail API."
+
+# Send with CC and BCC
+mcpz gmail send \
+  --to "recipient@example.com" \
+  --cc "cc@example.com" \
+  --bcc "bcc@example.com" \
+  --subject "Team Update" \
+  --body "Weekly team update..." \
+  --reply_to "noreply@example.com"
+```
+
+### Replying to Emails
+```bash
+# Reply to an email
+mcpz gmail reply 18c8b5d4e8f9a2b6 \
+  --body "Thank you for your message."
+
+# Reply without including quoted original message
+mcpz gmail reply 18c8b5d4e8f9a2b6 \
+  --body "Thank you for your message." \
+  --include_quoted false
+```
+
+### Email Management
+```bash
+# Mark as read/unread
+mcpz gmail mark_read 18c8b5d4e8f9a2b6
+mcpz gmail mark_unread 18c8b5d4e8f9a2b6
+
+# Add/remove labels
+mcpz gmail add_label 18c8b5d4e8f9a2b6 "important"
+mcpz gmail remove_label 18c8b5d4e8f9a2b6 "important"
+
+# Archive email (remove from inbox)
+mcpz gmail archive 18c8b5d4e8f9a2b6
+
+# Move to trash
+mcpz gmail trash 18c8b5d4e8f9a2b6
+```
+
+## MCP Server Usage
+
+### Running the Server
+
+```bash
+# Start the Gmail MCP server
+mcpz gmail mcp
+```
+
+### MCP Configuration
+
+Add to your `.mcp.json` configuration:
+
+```json
+{
+  "mcpServers": {
+    "gmail": {
+      "command": "mcpz",
+      "args": ["gmail", "mcp"]
+    }
+  }
+}
+```
+
+### Available MCP Tools
+
+- `test_connection` - Test Gmail API connectivity
+- `list_emails` - List emails with filtering options
+- `search_emails` - Search emails using Gmail syntax
+- `get_email_content` - Get full email content including attachments
+- `send_email` - Send new emails
+- `reply_to_email` - Reply to existing emails
+- `mark_as_read` / `mark_as_unread` - Change read status
+- `add_label` / `remove_label` - Manage email labels
+- `archive_email` - Archive emails
+- `trash_email` - Move emails to trash
+
+### Available MCP Prompts
+
+- `check_email` - Check inbox for new messages
+- `compose_email` - Compose and send emails
+- `email_search` - Search through emails
+- `email_management` - Manage emails (read/unread, archive, etc.)
+
+## Gmail Search Syntax
+
+The Gmail MCP server supports Gmail's advanced search operators:
+
+- `from:sender@example.com` - From specific sender
+- `to:recipient@example.com` - To specific recipient
+- `subject:keyword` - Subject contains keyword
+- `has:attachment` - Has attachments
+- `filename:pdf` - Attachment filename contains "pdf"
+- `is:unread` / `is:read` - Read status
+- `is:important` / `is:starred` - Importance/starred
+- `label:labelname` - Has specific label
+- `after:2024/01/01` / `before:2024/12/31` - Date ranges
+- `newer_than:7d` / `older_than:1m` - Relative dates
+
+## API Scopes
+
+This MCP server requires the following Gmail API scopes:
+
+- `https://www.googleapis.com/auth/gmail.readonly` - Read access to Gmail
+- `https://www.googleapis.com/auth/gmail.send` - Send emails
+- `https://www.googleapis.com/auth/gmail.modify` - Modify email labels and status
+
+## Security Notes
+
+- **OAuth tokens are stored locally** in `~/.config/mcpeasy/`
+- **Tokens are automatically refreshed** when they expire
+- **Only your authenticated user** can access emails through this server
+- **No emails are stored** by the MCP server - all data comes directly from Gmail
+
+## Troubleshooting
+
+### Authentication Issues
+
+```bash
+# Re-authenticate if you see authentication errors
+mcpz gmail auth
+
+# Check configuration status
+mcpz config
+```
+
+### API Quota Errors
+
+Gmail API has usage quotas. If you hit rate limits:
+- Reduce the number of requests
+- Add delays between operations
+- Check your Google Cloud Console quota usage
+
+### Common Error Messages
+
+- **"Gmail authentication required"** - Run `mcpz gmail auth`
+- **"Google API credentials not configured"** - Run `mcpz set_google_credentials <path>`
+- **"Gmail API Error: Insufficient Permission"** - Re-run authentication to grant necessary scopes
+
+## Development
+
+The Gmail MCP server follows the same patterns as other MCPEasy services:
+
+- `service.rb` - Core Gmail API functionality
+- `cli.rb` - Thor-based CLI commands  
+- `mcp.rb` - MCP server implementation
+- `README.md` - Documentation
+
+For development setup:
+
+```bash
+# Clone the repository
+git clone https://github.com/your-repo/mcpeasy.git
+cd mcpeasy
+
+# Install dependencies
+bundle install
+
+# Build and install locally
+gem build mcpeasy.gemspec
+gem install mcpeasy-*.gem
+```

data/lib/utilities/gmail/cli.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "thor"
+require_relative "service"
+
+module Gmail
+  class CLI < Thor
+    desc "test", "Test the Gmail API connection"
+    def test
+      response = tool.test_connection
+
+      if response[:ok]
+        puts "✅ Successfully connected to Gmail"
+        puts "   Email: #{response[:email]}"
+        puts "   Messages: #{response[:messages_total]}"
+        puts "   Threads: #{response[:threads_total]}"
+      else
+        warn "❌ Connection test failed"
+      end
+    rescue RuntimeError => e
+      puts "❌ Failed to connect to Gmail: #{e.message}\n\n#{e.backtrace.join("\n")}"
+      exit 1
+    end
+
+    desc "list", "List recent emails"
+    method_option :start_date, type: :string, aliases: "-s", desc: "Start date (YYYY-MM-DD)"
+    method_option :end_date, type: :string, aliases: "-e", desc: "End date (YYYY-MM-DD)"
+    method_option :max_results, type: :numeric, default: 20, aliases: "-n", desc: "Max number of emails"
+    method_option :sender, type: :string, aliases: "-f", desc: "Filter by sender email"
+    method_option :subject, type: :string, aliases: "-j", desc: "Filter by subject"
+    method_option :labels, type: :string, aliases: "-l", desc: "Filter by labels (comma-separated)"
+    method_option :read_status, type: :string, aliases: "-r", desc: "Filter by read status (read/unread)"
+    def list
+      labels = options[:labels]&.split(",")&.map(&:strip)
+
+      result = tool.list_emails(
+        start_date: options[:start_date],
+        end_date: options[:end_date],
+        max_results: options[:max_results],
+        sender: options[:sender],
+        subject: options[:subject],
+        labels: labels,
+        read_status: options[:read_status]
+      )
+      emails = result[:emails]
+
+      if emails.empty?
+        puts "📧 No emails found for the specified criteria"
+      else
+        puts "📧 Found #{result[:count]} email(s):"
+        emails.each_with_index do |email, index|
+          puts "   #{index + 1}. #{email[:subject] || "No subject"}"
+          puts "      From: #{email[:from]}"
+          puts "      Date: #{email[:date]}"
+          puts "      Snippet: #{email[:snippet]}" if email[:snippet]
+          puts "      Labels: #{email[:labels].join(", ")}" if email[:labels]&.any?
+          puts "      ID: #{email[:id]}"
+          puts
+        end
+      end
+    rescue RuntimeError => e
+      warn "❌ Failed to list emails: #{e.message}"
+      exit 1
+    end
+
+    desc "search QUERY", "Search emails by text content"
+    method_option :max_results, type: :numeric, default: 10, aliases: "-n", desc: "Max number of emails"
+    def search(query)
+      result = tool.search_emails(
+        query,
+        max_results: options[:max_results]
+      )
+      emails = result[:emails]
+
+      if emails.empty?
+        puts "🔍 No emails found matching '#{query}'"
+      else
+        puts "🔍 Found #{result[:count]} email(s) matching '#{query}':"
+        emails.each_with_index do |email, index|
+          puts "   #{index + 1}. #{email[:subject] || "No subject"}"
+          puts "      From: #{email[:from]}"
+          puts "      Date: #{email[:date]}"
+          puts "      Snippet: #{email[:snippet]}" if email[:snippet]
+          puts "      ID: #{email[:id]}"
+          puts
+        end
+      end
+    rescue RuntimeError => e
+      warn "❌ Failed to search emails: #{e.message}"
+      exit 1
+    end
+
+    desc "read EMAIL_ID", "Read a specific email"
+    def read(email_id)
+      email = tool.get_email_content(email_id)
+
+      puts "📧 Email Details:"
+      puts "   ID: #{email[:id]}"
+      puts "   Thread ID: #{email[:thread_id]}"
+      puts "   Subject: #{email[:subject] || "No subject"}"
+      puts "   From: #{email[:from]}"
+      puts "   To: #{email[:to]}"
+      puts "   CC: #{email[:cc]}" if email[:cc]
+      puts "   BCC: #{email[:bcc]}" if email[:bcc]
+      puts "   Date: #{email[:date]}"
+      puts "   Labels: #{email[:labels].join(", ")}" if email[:labels]&.any?
+
+      if email[:attachments]&.any?
+        puts "   Attachments:"
+        email[:attachments].each do |attachment|
+          puts "      - #{attachment[:filename]} (#{attachment[:mime_type]}, #{attachment[:size]} bytes)"
+        end
+      end
+
+      puts "\n📄 Body:"
+      puts email[:body]
+    rescue RuntimeError => e
+      warn "❌ Failed to read email: #{e.message}"
+      exit 1
+    end
+
+    desc "send", "Send a new email"
+    method_option :to, type: :string, required: true, aliases: "-t", desc: "Recipient email address"
+    method_option :subject, type: :string, required: true, aliases: "-s", desc: "Email subject"
+    method_option :body, type: :string, required: true, aliases: "-b", desc: "Email body"
+    method_option :cc, type: :string, aliases: "-c", desc: "CC email address"
+    method_option :bcc, type: :string, aliases: "-B", desc: "BCC email address"
+    method_option :reply_to, type: :string, aliases: "-r", desc: "Reply-to email address"
+    def send
+      result = tool.send_email(
+        to: options[:to],
+        subject: options[:subject],
+        body: options[:body],
+        cc: options[:cc],
+        bcc: options[:bcc],
+        reply_to: options[:reply_to]
+      )
+
+      if result[:success]
+        puts "✅ Email sent successfully"
+        puts "   Message ID: #{result[:message_id]}"
+        puts "   Thread ID: #{result[:thread_id]}"
+      else
+        puts "❌ Failed to send email"
+      end
+    rescue RuntimeError => e
+      warn "❌ Failed to send email: #{e.message}"
+      exit 1
+    end
+
+    desc "reply EMAIL_ID", "Reply to an email"
+    method_option :body, type: :string, required: true, aliases: "-b", desc: "Reply body"
+    method_option :include_quoted, type: :boolean, default: true, aliases: "-q", desc: "Include quoted original message"
+    def reply(email_id)
+      result = tool.reply_to_email(
+        email_id: email_id,
+        body: options[:body],
+        include_quoted: options[:include_quoted]
+      )
+
+      if result[:success]
+        puts "✅ Reply sent successfully"
+        puts "   Message ID: #{result[:message_id]}"
+        puts "   Thread ID: #{result[:thread_id]}"
+      else
+        puts "❌ Failed to send reply"
+      end
+    rescue RuntimeError => e
+      warn "❌ Failed to send reply: #{e.message}"
+      exit 1
+    end
+
+    desc "mark_read EMAIL_ID", "Mark an email as read"
+    def mark_read(email_id)
+      result = tool.mark_as_read(email_id)
+
+      if result[:success]
+        puts "✅ Email marked as read"
+      else
+        puts "❌ Failed to mark email as read"
+      end
+    rescue RuntimeError => e
+      warn "❌ Failed to mark email as read: #{e.message}"
+      exit 1
+    end
+
+    desc "mark_unread EMAIL_ID", "Mark an email as unread"
+    def mark_unread(email_id)
+      result = tool.mark_as_unread(email_id)
+
+      if result[:success]
+        puts "✅ Email marked as unread"
+      else
+        puts "❌ Failed to mark email as unread"
+      end
+    rescue RuntimeError => e
+      warn "❌ Failed to mark email as unread: #{e.message}"
+      exit 1
+    end
+
+    desc "add_label EMAIL_ID LABEL", "Add a label to an email"
+    def add_label(email_id, label)
+      result = tool.add_label(email_id, label)
+
+      if result[:success]
+        puts "✅ Label '#{label}' added to email"
+      else
+        puts "❌ Failed to add label to email"
+      end
+    rescue RuntimeError => e
+      warn "❌ Failed to add label to email: #{e.message}"
+      exit 1
+    end
+
+    desc "remove_label EMAIL_ID LABEL", "Remove a label from an email"
+    def remove_label(email_id, label)
+      result = tool.remove_label(email_id, label)
+
+      if result[:success]
+        puts "✅ Label '#{label}' removed from email"
+      else
+        puts "❌ Failed to remove label from email"
+      end
+    rescue RuntimeError => e
+      warn "❌ Failed to remove label from email: #{e.message}"
+      exit 1
+    end
+
+    desc "archive EMAIL_ID", "Archive an email"
+    def archive(email_id)
+      result = tool.archive_email(email_id)
+
+      if result[:success]
+        puts "✅ Email archived"
+      else
+        puts "❌ Failed to archive email"
+      end
+    rescue RuntimeError => e
+      warn "❌ Failed to archive email: #{e.message}"
+      exit 1
+    end
+
+    desc "trash EMAIL_ID", "Move an email to trash"
+    def trash(email_id)
+      result = tool.trash_email(email_id)
+
+      if result[:success]
+        puts "✅ Email moved to trash"
+      else
+        puts "❌ Failed to move email to trash"
+      end
+    rescue RuntimeError => e
+      warn "❌ Failed to move email to trash: #{e.message}"
+      exit 1
+    end
+
+    private
+
+    def tool
+      @tool ||= Service.new
+    end
+  end
+end