mcpeasy 0.1.0

data/lib/utilities/gdrive/README.md

@@ -0,0 +1,269 @@
+# Google Drive MCP Server
+
+A Ruby-based Model Context Protocol (MCP) server that provides programmatic access to Google Drive. This server can operate in two modes:
+
+1. **CLI script**: Direct command-line usage for searching, listing, and retrieving files
+2. **MCP server**: Integration with AI assistants like Claude Code
+
+## Features
+
+- 🔍 **Search files** by content or name in Google Drive
+- 📂 **List recent files** with metadata
+- 📄 **Retrieve file content** with automatic format conversion
+- 🔄 **Export Google Workspace documents**:
+  - Google Docs → Markdown
+  - Google Sheets → CSV  
+  - Google Presentations → Plain text
+  - Google Drawings → PNG
+- 🔐 **OAuth 2.0 authentication** with credential persistence
+- 🛡️ **Error handling** with retry logic and comprehensive logging
+
+## Prerequisites
+
+### 1. Ruby Environment
+
+```bash
+# Install Ruby dependencies
+bundle install
+```
+
+Required gems:
+- `google-apis-drive_v3` - Google Drive API client
+- `googleauth` - Google OAuth authentication
+- `thor` - CLI framework
+
+### 2. Google Cloud Platform Setup
+
+#### Step 1: Create a Google Cloud Project
+
+1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project or select an existing one
+3. Note your project ID
+
+#### Step 2: Enable the Google Drive API
+
+1. In the Cloud Console, go to **APIs & Services > Library**
+2. Search for "Google Drive API"
+3. Click on it and click **Enable**
+
+#### Step 3: Create OAuth 2.0 Credentials
+
+1. Go to **APIs & Services > Credentials**
+2. Click **+ Create Credentials > OAuth client ID**
+3. If prompted, configure the OAuth consent screen:
+   - Choose **External** user type
+   - Fill in required fields (app name, user support email)
+   - Add your email to test users
+   - Scopes: you can leave this empty for now
+4. For Application type, choose **Desktop application**
+5. Give it a name (e.g., "Google Drive MCP Server")
+6. **Add Authorized redirect URI**: `http://localhost:8080`
+7. Click **Create**
+8. Download the JSON file containing your client ID and secret
+
+#### Step 4: Configure OAuth Credentials
+
+The Google OAuth credentials will be configured during the authentication process. You'll need the Client ID and Client Secret from the JSON file you downloaded in Step 3.
+
+**Note**: All Google services (Calendar, Drive, Meet) share the same authentication system, so you only need to authenticate once.
+
+## Authentication
+
+Before using the Google Drive MCP server, you need to authenticate with Google:
+
+```bash
+mcpz google auth
+```
+
+This will open a browser for Google OAuth authorization and save credentials to `~/.config/mcpeasy/google/token.json`. The credentials are shared with all Google services and will be automatically refreshed when needed.
+
+## Usage
+
+### CLI Mode
+
+#### Test Connection
+```bash
+mcpz gdrive test
+```
+
+#### Search for Files
+```bash
+# Basic search
+mcpz gdrive search "quarterly report"
+
+# Limit results
+mcpz gdrive search "meeting notes" --max-results 5
+```
+
+#### List Recent Files
+```bash
+# List 20 most recent files
+mcpz gdrive list
+
+# Limit results
+mcpz gdrive list --max-results 10
+```
+
+#### Get File Content
+```bash
+# Display content in terminal
+mcpz gdrive get "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
+
+# Save to file
+mcpz gdrive get "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" --output document.md
+```
+
+### MCP Server Mode
+
+#### Configuration for Claude Code
+
+Add to your `.mcp.json` configuration:
+
+```json
+{
+  "mcpServers": {
+    "gdrive": {
+      "command": "mcpz",
+      "args": ["gdrive", "mcp"]
+    }
+  }
+}
+```
+
+#### Run as Standalone MCP Server
+
+```bash
+mcpz gdrive mcp
+```
+
+The server provides these tools to Claude Code:
+
+- **test_connection**: Test Google Drive API connectivity
+- **search_files**: Search for files by content or name
+- **get_file_content**: Retrieve content of a specific file
+- **list_files**: List recent files in Google Drive
+
+## File Format Support
+
+### Google Workspace Documents
+
+The server automatically exports Google Workspace documents to readable formats:
+
+| Document Type | Export Format | File Extension |
+|---------------|---------------|----------------|
+| Google Docs | Markdown | `.md` |
+| Google Sheets | CSV | `.csv` |
+| Google Slides | Plain text | `.txt` |
+| Google Drawings | PNG image | `.png` |
+
+### Regular Files
+
+All other file types (PDFs, images, text files, etc.) are downloaded in their original format.
+
+## Security & Permissions
+
+### Required OAuth Scopes
+
+- `https://www.googleapis.com/auth/drive.readonly` - Read-only access to Google Drive
+
+### Local File Storage
+
+- **Credentials**: Stored in `~/.config/mcpeasy/google/token.json`
+- **Logs**: Stored in `./logs/mcp_gdrive_*.log`
+
+### Best Practices
+
+1. **Never commit** credential files to version control
+2. **Limit scope** to read-only access
+3. **Regular rotation** of OAuth credentials (recommended annually)
+4. **Monitor usage** through Google Cloud Console
+
+## Troubleshooting
+
+### Common Issues
+
+#### "Authentication required" Error
+- Run `mcpz google auth` to authenticate
+- Check that `~/.config/mcpeasy/google/token.json` exists and is valid
+- Verify your Google OAuth credentials are configured correctly
+
+#### "Bad credentials" Error
+- Regenerate OAuth credentials in Google Cloud Console
+- Re-run authentication: `mcpz google auth`
+
+#### "Quota exceeded" Error
+- Check your Google Cloud Console for API quota limits
+- Wait for quota reset (usually daily)
+- Consider requesting higher quota limits
+
+#### "Access denied" Error
+- Ensure the Google Drive API is enabled in your project
+- Check that your OAuth consent screen is properly configured
+- Verify you're using the correct Google account
+
+### Debug Logging
+
+Check the log files for detailed error information:
+
+```bash
+# View recent errors
+tail -f logs/mcp_gdrive_error.log
+
+# View startup logs
+tail -f logs/mcp_gdrive_startup.log
+```
+
+### Testing the Setup
+
+1. **Test CLI authentication**:
+   ```bash
+   mcpz gdrive test
+   ```
+
+2. **Test MCP server**:
+   ```bash
+   echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | mcpz gdrive mcp
+   ```
+
+## Development
+
+### File Structure
+
+```
+utilities/gdrive/
+├── cli.rb          # Thor-based CLI interface
+├── mcp.rb          # MCP server implementation  
+├── gdrive_tool.rb  # Google Drive API wrapper
+└── README.md       # This file
+```
+
+### Adding New Features
+
+1. **New API methods**: Add to `GdriveTool` class
+2. **New CLI commands**: Add to `GdriveCLI` class  
+3. **New MCP tools**: Add to `MCPServer` class
+
+### Testing
+
+```bash
+# Run Ruby linting
+bundle exec standardrb
+
+# Test CLI commands
+mcpz gdrive test
+mcpz gdrive list --max-results 5
+
+# Test MCP server manually
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | mcpz gdrive mcp
+```
+
+## Contributing
+
+1. Follow existing code patterns and style
+2. Add comprehensive error handling
+3. Update this README for new features
+4. Test both CLI and MCP modes
+
+## License
+
+This project follows the same license as the parent repository.

data/lib/utilities/gdrive/cli.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "thor"
+require_relative "gdrive_tool"
+
+class GdriveCLI < Thor
+  desc "test", "Test the Google Drive API connection"
+  def test
+    response = tool.test_connection
+
+    if response[:ok]
+      puts "✅ Successfully connected to Google Drive"
+      puts "   User: #{response[:user]} (#{response[:email]})"
+      if response[:storage_used] && response[:storage_limit]
+        puts "   Storage: #{format_bytes(response[:storage_used])} / #{format_bytes(response[:storage_limit])}"
+      end
+    else
+      warn "❌ Connection test failed"
+    end
+  rescue RuntimeError => e
+    puts "❌ Failed to connect to Google Drive: #{e.message}"
+    exit 1
+  end
+
+  desc "search QUERY", "Search for files in Google Drive"
+  method_option :max_results, type: :numeric, default: 10, aliases: "-n"
+  def search(query)
+    result = tool.search_files(query, max_results: options[:max_results])
+    files = result[:files]
+
+    if files.empty?
+      puts "🔍 No files found matching '#{query}'"
+    else
+      puts "🔍 Found #{result[:count]} file(s) matching '#{query}':"
+      files.each_with_index do |file, index|
+        puts "   #{index + 1}. #{file[:name]}"
+        puts "      ID: #{file[:id]}"
+        puts "      Type: #{file[:mime_type]}"
+        puts "      Size: #{format_bytes(file[:size])}"
+        puts "      Modified: #{file[:modified_time]}"
+        puts "      Link: #{file[:web_view_link]}"
+        puts
+      end
+    end
+  rescue RuntimeError => e
+    warn "❌ Failed to search files: #{e.message}"
+    exit 1
+  end
+
+  desc "list", "List recent files in Google Drive"
+  method_option :max_results, type: :numeric, default: 20, aliases: "-n"
+  def list
+    result = tool.list_files(max_results: options[:max_results])
+    files = result[:files]
+
+    if files.empty?
+      puts "📂 No files found in Google Drive"
+    else
+      puts "📂 Recent #{result[:count]} file(s):"
+      files.each_with_index do |file, index|
+        puts "   #{index + 1}. #{file[:name]}"
+        puts "      ID: #{file[:id]}"
+        puts "      Type: #{file[:mime_type]}"
+        puts "      Size: #{format_bytes(file[:size])}"
+        puts "      Modified: #{file[:modified_time]}"
+        puts "      Link: #{file[:web_view_link]}"
+        puts
+      end
+    end
+  rescue RuntimeError => e
+    warn "❌ Failed to list files: #{e.message}"
+    exit 1
+  end
+
+  desc "get FILE_ID", "Get content of a specific file"
+  method_option :output, type: :string, aliases: "-o", desc: "Output file path"
+  def get(file_id)
+    result = tool.get_file_content(file_id)
+
+    puts "📄 #{result[:name]}"
+    puts "   Type: #{result[:mime_type]}"
+    puts "   Size: #{format_bytes(result[:size])}"
+    puts
+
+    if options[:output]
+      File.write(options[:output], result[:content])
+      puts "✅ Content saved to #{options[:output]}"
+    else
+      puts "Content:"
+      puts result[:content]
+    end
+  rescue RuntimeError => e
+    warn "❌ Failed to get file content: #{e.message}"
+    exit 1
+  end
+
+  private
+
+  def tool
+    @tool ||= GdriveTool.new
+  end
+
+  def format_bytes(bytes)
+    return "Unknown" unless bytes
+
+    units = %w[B KB MB GB TB]
+    size = bytes.to_f
+    unit_index = 0
+
+    while size >= 1024 && unit_index < units.length - 1
+      size /= 1024
+      unit_index += 1
+    end
+
+    "#{size.round(1)} #{units[unit_index]}"
+  end
+end

data/lib/utilities/gdrive/gdrive_tool.rb

@@ -0,0 +1,291 @@
+# 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"
+
+class GdriveTool
+  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