mcpeasy 0.1.0 → 0.3.0

data/lib/utilities/gdrive/service.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "google/apis/drive_v3"
+require "googleauth"
+require "signet/oauth_2/client"
+require "fileutils"
+require "json"
+require "time"
+require_relative "../_google/auth_server"
+require_relative "../../mcpeasy/config"
+
+module Gdrive
+  class Service
+    SCOPES = [
+      "https://www.googleapis.com/auth/calendar.readonly",
+      "https://www.googleapis.com/auth/drive.readonly"
+    ]
+    SCOPE = SCOPES.join(" ")
+
+    # MIME type mappings for Google Workspace documents
+    EXPORT_FORMATS = {
+      "application/vnd.google-apps.document" => {
+        format: "text/markdown",
+        extension: ".md"
+      },
+      "application/vnd.google-apps.spreadsheet" => {
+        format: "text/csv",
+        extension: ".csv"
+      },
+      "application/vnd.google-apps.presentation" => {
+        format: "text/plain",
+        extension: ".txt"
+      },
+      "application/vnd.google-apps.drawing" => {
+        format: "image/png",
+        extension: ".png"
+      }
+    }.freeze
+
+    def initialize(skip_auth: false)
+      ensure_env!
+      @service = Google::Apis::DriveV3::DriveService.new
+      @service.authorization = authorize unless skip_auth
+    end
+
+    def search_files(query, max_results: 10)
+      results = @service.list_files(
+        q: "fullText contains '#{query.gsub("'", "\\'")}' and trashed=false",
+        page_size: max_results,
+        fields: "files(id,name,mimeType,size,modifiedTime,webViewLink)"
+      )
+
+      files = results.files.map do |file|
+        {
+          id: file.id,
+          name: file.name,
+          mime_type: file.mime_type,
+          size: file.size&.to_i,
+          modified_time: file.modified_time,
+          web_view_link: file.web_view_link
+        }
+      end
+
+      {files: files, count: files.length}
+    rescue Google::Apis::Error => e
+      raise "Google Drive API Error: #{e.message}"
+    rescue => e
+      log_error("search_files", e)
+      raise e
+    end
+
+    def get_file_content(file_id)
+      # First get file metadata
+      file = @service.get_file(file_id, fields: "id,name,mimeType,size")
+
+      content = if EXPORT_FORMATS.key?(file.mime_type)
+        # Export Google Workspace document
+        export_format = EXPORT_FORMATS[file.mime_type][:format]
+        @service.export_file(file_id, export_format)
+      else
+        # Download regular file
+        @service.get_file(file_id, download_dest: StringIO.new)
+      end
+
+      {
+        id: file.id,
+        name: file.name,
+        mime_type: file.mime_type,
+        size: file.size&.to_i,
+        content: content.is_a?(StringIO) ? content.string : content
+      }
+    rescue Google::Apis::Error => e
+      raise "Google Drive API Error: #{e.message}"
+    rescue => e
+      log_error("get_file_content", e)
+      raise e
+    end
+
+    def list_files(max_results: 20)
+      results = @service.list_files(
+        q: "trashed=false",
+        page_size: max_results,
+        order_by: "modifiedTime desc",
+        fields: "files(id,name,mimeType,size,modifiedTime,webViewLink)"
+      )
+
+      files = results.files.map do |file|
+        {
+          id: file.id,
+          name: file.name,
+          mime_type: file.mime_type,
+          size: file.size&.to_i,
+          modified_time: file.modified_time,
+          web_view_link: file.web_view_link
+        }
+      end
+
+      {files: files, count: files.length}
+    rescue Google::Apis::Error => e
+      raise "Google Drive API Error: #{e.message}"
+    rescue => e
+      log_error("list_files", e)
+      raise e
+    end
+
+    def test_connection
+      about = @service.get_about(fields: "user,storageQuota")
+      {
+        ok: true,
+        user: about.user.display_name,
+        email: about.user.email_address,
+        storage_used: about.storage_quota&.usage,
+        storage_limit: about.storage_quota&.limit
+      }
+    rescue Google::Apis::Error => e
+      raise "Google Drive API Error: #{e.message}"
+    rescue => e
+      log_error("test_connection", e)
+      raise e
+    end
+
+    def authenticate
+      perform_auth_flow
+      {success: true}
+    rescue => e
+      {success: false, error: e.message}
+    end
+
+    def perform_auth_flow
+      client_id = Mcpeasy::Config.google_client_id
+      client_secret = Mcpeasy::Config.google_client_secret
+
+      unless client_id && client_secret
+        raise "Google credentials not found. Please save your credentials.json file using: mcpz config set_google_credentials <path_to_credentials.json>"
+      end
+
+      # Create credentials using OAuth2 flow with localhost redirect
+      redirect_uri = "http://localhost:8080"
+      client = Signet::OAuth2::Client.new(
+        client_id: client_id,
+        client_secret: client_secret,
+        scope: SCOPE,
+        redirect_uri: redirect_uri,
+        authorization_uri: "https://accounts.google.com/o/oauth2/auth",
+        token_credential_uri: "https://oauth2.googleapis.com/token"
+      )
+
+      # Generate authorization URL
+      url = client.authorization_uri.to_s
+
+      puts "DEBUG: Client ID: #{client_id[0..20]}..."
+      puts "DEBUG: Scope: #{SCOPE}"
+      puts "DEBUG: Redirect URI: #{redirect_uri}"
+      puts
+
+      # Start callback server to capture OAuth code
+      puts "Starting temporary web server to capture OAuth callback..."
+      puts "Opening authorization URL in your default browser..."
+      puts url
+      puts
+
+      # Automatically open URL in default browser on macOS/Unix
+      if system("which open > /dev/null 2>&1")
+        system("open", url)
+      else
+        puts "Could not automatically open browser. Please copy the URL above manually."
+      end
+      puts
+      puts "Waiting for OAuth callback... (will timeout in 60 seconds)"
+
+      # Wait for the authorization code with timeout
+      code = GoogleAuthServer.capture_auth_code
+
+      unless code
+        raise "Failed to receive authorization code. Please try again."
+      end
+
+      puts "✅ Authorization code received!"
+      client.code = code
+      client.fetch_access_token!
+
+      # Save credentials to config
+      credentials_data = {
+        client_id: client.client_id,
+        client_secret: client.client_secret,
+        scope: client.scope,
+        refresh_token: client.refresh_token,
+        access_token: client.access_token,
+        expires_at: client.expires_at
+      }
+
+      Mcpeasy::Config.save_google_token(credentials_data)
+      puts "✅ Authentication successful! Token saved to config"
+
+      client
+    rescue => e
+      log_error("perform_auth_flow", e)
+      raise "Authentication flow failed: #{e.message}"
+    end
+
+    private
+
+    def authorize
+      credentials_data = Mcpeasy::Config.google_token
+      unless credentials_data
+        raise <<~ERROR
+          Google Drive authentication required!
+          Run the auth command first:
+          mcpz gdrive auth
+        ERROR
+      end
+
+      client = Signet::OAuth2::Client.new(
+        client_id: credentials_data.client_id,
+        client_secret: credentials_data.client_secret,
+        scope: credentials_data.scope.respond_to?(:to_a) ? credentials_data.scope.to_a.join(" ") : credentials_data.scope.to_s,
+        refresh_token: credentials_data.refresh_token,
+        access_token: credentials_data.access_token,
+        token_credential_uri: "https://oauth2.googleapis.com/token"
+      )
+
+      # Check if token needs refresh
+      if credentials_data.expires_at
+        expires_at = if credentials_data.expires_at.is_a?(String)
+          Time.parse(credentials_data.expires_at)
+        else
+          Time.at(credentials_data.expires_at)
+        end
+
+        if Time.now >= expires_at
+          client.refresh!
+          # Update saved credentials with new access token
+          updated_data = {
+            client_id: credentials_data.client_id,
+            client_secret: credentials_data.client_secret,
+            scope: credentials_data.scope.respond_to?(:to_a) ? credentials_data.scope.to_a.join(" ") : credentials_data.scope.to_s,
+            refresh_token: credentials_data.refresh_token,
+            access_token: client.access_token,
+            expires_at: client.expires_at
+          }
+          Mcpeasy::Config.save_google_token(updated_data)
+        end
+      end
+
+      client
+    rescue JSON::ParserError
+      raise "Invalid token data. Please re-run: mcpz gdrive auth"
+    rescue => e
+      log_error("authorize", e)
+      raise "Authentication failed: #{e.message}"
+    end
+
+    def ensure_env!
+      unless Mcpeasy::Config.google_client_id && Mcpeasy::Config.google_client_secret
+        raise <<~ERROR
+          Google API credentials not configured!
+          Please save your Google credentials.json file using:
+          mcpz config set_google_credentials <path_to_credentials.json>
+        ERROR
+      end
+    end
+
+    def log_error(method, error)
+      Mcpeasy::Config.ensure_config_dirs
+      File.write(
+        Mcpeasy::Config.log_file_path("gdrive", "error"),
+        "#{Time.now}: #{method} error: #{error.class}: #{error.message}\n#{error.backtrace.join("\n")}\n",
+        mode: "a"
+      )
+    end
+  end
+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
+```