mailcatcher-ng 1.4.0 → 1.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6539793c4e31686b97ba0502cc4c48c47c49ace16230fea4cf2f2cb8d06704c7
-  data.tar.gz: d74ed846c8205f2b37b9b433b618424929d12515a928d23b4a481fe03a5993d1
+  metadata.gz: 69f0a5c91a168bb7b409d219e6419a404c80a1623184b3899e58527562bd9a43
+  data.tar.gz: 0b849b98f7b13db2022a49edf28ca88015521d4426db272b3fcc3355f95bc587
 SHA512:
-  metadata.gz: fd19f4d57d9710adc6c60a21aeeefbfb2623e57d6725463f5bd01b3ce5e5fcb93360d1543301bc9655b64fc814994d036e3c8cf8de3940643f69ccf1f4063297
-  data.tar.gz: 7aed22f4e9a54ca7e239f7401d95931cfce90f309d2beae5d28049aa939b4903bb2d256aac8ff694c3740bf62835d6bf2c5f90d8c9b53fd3f855a2b282e6860e
+  metadata.gz: 7de12fb6e7d6816804161880de898a35f887647be32e4a776df5b852236ad567577964533896a5e8580d68e75b5315a049658cd33cc3bae6059c12b1c742b454
+  data.tar.gz: 0bbb9881849597362e8db7ed8151a06ad793417f7bbeced87286a04d8226eb5d4094db73d039f9334cb02da7d82ce3e597478f82f277da2070856e9657917c21

data/README.md

@@ -14,12 +14,17 @@ MailCatcher NG runs a super simple SMTP server which catches any message sent to
 
 - [Quick Start](#quick-start)
 - [Features](#features)
+- [Claude Integration](#claude-integration)
 - [Documentation](#documentation)
   - [Installation & Setup](reference/INSTALLATION.md)
   - [Usage & Configuration](reference/USAGE.md)
   - [Framework Integration](reference/INTEGRATIONS.md)
   - [REST API](reference/API.md)
   - [Advanced Features](reference/ADVANCED.md)
+  - [Claude Integration Guide](CLAUDE_INTEGRATION.md)
+  - [Claude Plugin Setup](reference/CLAUDE_PLUGIN_SETUP.md)
+  - [MCP Server Setup](reference/MCP_SETUP.md)
+  - [Integration Architecture](reference/INTEGRATION_ARCHITECTURE.md)
   - [Credits](reference/CREDITS.md)
 - [License](#license)
 
@@ -51,6 +56,55 @@ MailCatcher NG runs a super simple SMTP server which catches any message sent to
 
 For a comprehensive list of all features, see [FEATURES.md](FEATURES.md).
 
+## Claude Integration
+
+MailCatcher NG integrates seamlessly with Claude through two complementary methods:
+
+### Claude Plugin (Easiest)
+
+Use MailCatcher with Claude.com or Claude Desktop without any installation:
+
+```bash
+mailcatcher --plugin --foreground
+```
+
+Then add the plugin in Claude settings: `http://localhost:1080/.well-known/ai-plugin.json`
+
+### MCP Server (Programmatic)
+
+Enable programmatic access via Model Context Protocol:
+
+```bash
+mailcatcher --mcp --foreground
+```
+
+Configure in Claude Desktop's `~/.claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mailcatcher": {
+      "command": "mailcatcher",
+      "args": ["--mcp", "--foreground"]
+    }
+  }
+}
+```
+
+### Available Tools
+
+Both methods expose 7 powerful tools:
+
+- **search_messages** - Full-text search with filtering
+- **get_latest_message_for** - Find latest message for recipient
+- **extract_token_or_link** - Extract OTPs, magic links, reset tokens
+- **get_parsed_auth_info** - Structured authentication data
+- **get_message_preview_html** - Responsive HTML preview
+- **delete_message** - Delete specific message
+- **clear_messages** - Delete all messages
+
+See [CLAUDE_INTEGRATION.md](CLAUDE_INTEGRATION.md) for complete setup and usage guide.
+
 ## Documentation
 
 Detailed documentation is organized by topic:
@@ -75,6 +129,18 @@ Programmatic access to messages. Query, download, and manage messages via HTTP.
 
 SSL/TLS encryption, UTF-8 and international content, email authentication, and more.
 
+### [Claude Plugin Setup](reference/CLAUDE_PLUGIN_SETUP.md)
+
+Use MailCatcher NG as a Claude Plugin for natural language interactions with caught emails. Perfect for testing email workflows with Claude.
+
+### [MCP Server Setup](reference/MCP_SETUP.md)
+
+Configure MailCatcher NG as an MCP server for programmatic access via Claude Desktop and other MCP-compatible clients.
+
+### [Integration Architecture](reference/INTEGRATION_ARCHITECTURE.md)
+
+Deep dive into how the Claude Plugin and MCP integrations work, including protocol specifications, tool definitions, and extension points.
+
 ### [Credits](reference/CREDITS.md)
 
 About MailCatcher NG and the original MailCatcher project.

data/lib/mail_catcher/integrations/mcp_server.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "json"
+require "mail_catcher/integrations/mcp_tools"
+
+module MailCatcher
+  module Integrations
+    # MCP Server
+    # Implements the Model Context Protocol (MCP) over stdio
+    # Allows Claude and other MCP clients to interact with MailCatcher tools
+    class MCPServer
+      attr_accessor :running
+
+      def initialize(options = {})
+        @options = options
+        @running = false
+        @request_id_counter = 0
+      end
+
+      def self.start(options = {})
+        server = new(options)
+        server.run
+        server
+      end
+
+      # Main server loop - handles JSON-RPC messages from stdin
+      def run
+        @running = true
+        $stderr.puts "[MCP Server] Starting MailCatcher MCP Server"
+
+        # Output MCP initialization
+        send_response(
+          jsonrpc: "2.0",
+          id: 0,
+          result: {
+            protocolVersion: "2024-11-05",
+            capabilities: {
+              tools: {},
+              resources: {},
+              logging: {}
+            },
+            serverInfo: {
+              name: "mailcatcher-ng",
+              version: MailCatcher::VERSION
+            }
+          }
+        )
+
+        # Main loop - read and process requests
+        while @running && (line = $stdin.gets)
+          begin
+            request = JSON.parse(line)
+            handle_request(request)
+          rescue JSON::ParserError => e
+            $stderr.puts "[MCP Server] JSON parse error: #{e.message}"
+            send_error_response(nil, -32700, "Parse error")
+          rescue => e
+            $stderr.puts "[MCP Server] Error: #{e.message}"
+            $stderr.puts e.backtrace.first(5)
+          end
+        end
+
+        $stderr.puts "[MCP Server] MCP Server stopped"
+        @running = false
+      end
+
+      def stop
+        @running = false
+      end
+
+      private
+
+      def handle_request(request)
+        method = request["method"]
+        params = request["params"] || {}
+        request_id = request["id"]
+
+        $stderr.puts "[MCP Server] Received: #{method} (id: #{request_id})"
+
+        case method
+        when "initialize"
+          handle_initialize(request_id, params)
+        when "tools/list"
+          handle_tools_list(request_id)
+        when "tools/call"
+          handle_tools_call(request_id, params)
+        when "completion/complete"
+          handle_completion(request_id, params)
+        else
+          send_error_response(request_id, -32601, "Method not found: #{method}")
+        end
+      end
+
+      def handle_initialize(request_id, params)
+        send_response(
+          jsonrpc: "2.0",
+          id: request_id,
+          result: {
+            protocolVersion: "2024-11-05",
+            capabilities: {
+              tools: {},
+              resources: {},
+              logging: {}
+            },
+            serverInfo: {
+              name: "mailcatcher-ng",
+              version: MailCatcher::VERSION
+            }
+          }
+        )
+      end
+
+      def handle_tools_list(request_id)
+        tools = MCPTools.all_tools.map do |name, definition|
+          {
+            name: name.to_s,
+            description: definition[:description],
+            inputSchema: definition[:input_schema]
+          }
+        end
+
+        send_response(
+          jsonrpc: "2.0",
+          id: request_id,
+          result: {
+            tools: tools
+          }
+        )
+      end
+
+      def handle_tools_call(request_id, params)
+        tool_name = params["name"]
+        tool_input = params["arguments"] || {}
+
+        $stderr.puts "[MCP Server] Calling tool: #{tool_name} with input: #{tool_input.inspect}"
+
+        result = MCPTools.call_tool(tool_name, tool_input)
+
+        send_response(
+          jsonrpc: "2.0",
+          id: request_id,
+          result: {
+            content: [
+              {
+                type: "text",
+                text: JSON.pretty_generate(result)
+              }
+            ]
+          }
+        )
+      end
+
+      def handle_completion(request_id, params)
+        # Placeholder for completion support
+        send_response(
+          jsonrpc: "2.0",
+          id: request_id,
+          result: {
+            completion: {
+              values: [],
+              total: 0
+            }
+          }
+        )
+      end
+
+      def send_response(response)
+        output = JSON.generate(response)
+        puts output
+        $stderr.puts "[MCP Server] Sent: #{response[:id]}"
+      rescue => e
+        $stderr.puts "[MCP Server] Error sending response: #{e.message}"
+      end
+
+      def send_error_response(request_id, code, message)
+        send_response(
+          jsonrpc: "2.0",
+          id: request_id,
+          error: {
+            code: code,
+            message: message
+          }
+        )
+      end
+    end
+  end
+end

data/lib/mail_catcher/integrations/mcp_tools.rb

@@ -0,0 +1,370 @@
+# frozen_string_literal: true
+
+require "mail_catcher/mail"
+
+module MailCatcher
+  module Integrations
+    # MCP Tool Registry
+    # Defines the set of tools available to Claude through MCP and Claude Plugins
+    # Each tool maps to existing Mail module methods
+    module MCPTools
+      extend self
+
+      # Tool definitions for MCP and Plugin
+      TOOLS = {
+        search_messages: {
+          description: "Search through caught emails with flexible filtering",
+          input_schema: {
+            type: "object",
+            properties: {
+              query: {
+                type: "string",
+                description: "Search term (searches subject, sender, recipients, body)"
+              },
+              limit: {
+                type: "integer",
+                description: "Maximum number of results to return",
+                default: 5
+              },
+              has_attachments: {
+                type: "boolean",
+                description: "Filter to only messages with attachments",
+                default: false
+              },
+              from_date: {
+                type: "string",
+                description: "ISO 8601 datetime to search from (e.g., '2024-01-12T00:00:00Z')",
+                default: nil
+              },
+              to_date: {
+                type: "string",
+                description: "ISO 8601 datetime to search until (e.g., '2024-01-12T23:59:59Z')",
+                default: nil
+              }
+            },
+            required: ["query"]
+          }
+        },
+
+        get_latest_message_for: {
+          description: "Get the latest email received by a specific recipient",
+          input_schema: {
+            type: "object",
+            properties: {
+              recipient: {
+                type: "string",
+                description: "Email address to match in recipients"
+              },
+              subject_contains: {
+                type: "string",
+                description: "Optional: Only return message if subject contains this text",
+                default: nil
+              }
+            },
+            required: ["recipient"]
+          }
+        },
+
+        extract_token_or_link: {
+          description: "Extract authentication tokens or links from a message",
+          input_schema: {
+            type: "object",
+            properties: {
+              message_id: {
+                type: "integer",
+                description: "ID of the message to extract from"
+              },
+              kind: {
+                type: "string",
+                enum: ["magic_link", "otp", "reset_token", "all"],
+                description: "Type of token/link to extract"
+              }
+            },
+            required: ["message_id", "kind"]
+          }
+        },
+
+        get_parsed_auth_info: {
+          description: "Get structured authentication information from a message",
+          input_schema: {
+            type: "object",
+            properties: {
+              message_id: {
+                type: "integer",
+                description: "ID of the message to parse"
+              }
+            },
+            required: ["message_id"]
+          }
+        },
+
+        get_message_preview_html: {
+          description: "Get HTML preview of a message (responsive for mobile if requested)",
+          input_schema: {
+            type: "object",
+            properties: {
+              message_id: {
+                type: "integer",
+                description: "ID of the message to preview"
+              },
+              mobile: {
+                type: "boolean",
+                description: "Return mobile-optimized preview",
+                default: false
+              }
+            },
+            required: ["message_id"]
+          }
+        },
+
+        delete_message: {
+          description: "Delete a specific message by ID",
+          input_schema: {
+            type: "object",
+            properties: {
+              message_id: {
+                type: "integer",
+                description: "ID of the message to delete"
+              }
+            },
+            required: ["message_id"]
+          }
+        },
+
+        clear_messages: {
+          description: "Delete all caught messages (destructive operation)",
+          input_schema: {
+            type: "object",
+            properties: {}
+          }
+        }
+      }.freeze
+
+      # Get tool definition by name
+      def tool(name)
+        TOOLS[name.to_sym]
+      end
+
+      # Get all tool names
+      def tool_names
+        TOOLS.keys.map(&:to_s)
+      end
+
+      # Get all tools
+      def all_tools
+        TOOLS
+      end
+
+      # Execute a tool with the given parameters
+      def call_tool(tool_name, input)
+        case tool_name.to_sym
+        when :search_messages
+          call_search_messages(input)
+        when :get_latest_message_for
+          call_get_latest_message_for(input)
+        when :extract_token_or_link
+          call_extract_token_or_link(input)
+        when :get_parsed_auth_info
+          call_get_parsed_auth_info(input)
+        when :get_message_preview_html
+          call_get_message_preview_html(input)
+        when :delete_message
+          call_delete_message(input)
+        when :clear_messages
+          call_clear_messages(input)
+        else
+          { error: "Unknown tool: #{tool_name}" }
+        end
+      rescue => e
+        {
+          error: "Tool execution failed: #{e.message}",
+          type: e.class.name,
+          backtrace: e.backtrace.first(3)
+        }
+      end
+
+      # Tool implementations
+
+      def call_search_messages(input)
+        query = input["query"] || input[:query]
+        limit = (input["limit"] || input[:limit] || 5).to_i
+        has_attachments = input["has_attachments"] || input[:has_attachments]
+        from_date = input["from_date"] || input[:from_date]
+        to_date = input["to_date"] || input[:to_date]
+
+        results = Mail.search_messages(
+          query: query,
+          has_attachments: has_attachments,
+          from_date: from_date,
+          to_date: to_date
+        )
+
+        # Limit results
+        results = results.slice(0, limit)
+
+        {
+          count: results.size,
+          messages: results.map { |msg| format_message_summary(msg) }
+        }
+      end
+
+      def call_get_latest_message_for(input)
+        recipient = input["recipient"] || input[:recipient]
+        subject_contains = input["subject_contains"] || input[:subject_contains]
+
+        # Search all messages to find matching recipient
+        all_messages = Mail.messages
+        matching = all_messages.select do |msg|
+          recipients = msg["recipients"]
+          recipients_array = recipients.is_a?(Array) ? recipients : [recipients]
+          recipients_array.any? { |r| r.to_s.include?(recipient) }
+        end
+
+        # Filter by subject if provided
+        matching = matching.select do |msg|
+          msg["subject"].to_s.include?(subject_contains)
+        end if subject_contains
+
+        # Get the latest
+        latest = matching.max_by { |msg| msg["created_at"] }
+
+        if latest
+          {
+            found: true,
+            message: format_message_detail(latest["id"])
+          }
+        else
+          {
+            found: false,
+            error: "No matching message found for recipient: #{recipient}"
+          }
+        end
+      end
+
+      def call_extract_token_or_link(input)
+        message_id = (input["message_id"] || input[:message_id]).to_i
+        kind = input["kind"] || input[:kind]
+
+        return { error: "Message not found" } unless Mail.message(message_id)
+
+        # Map kind parameter to Mail.extract_tokens type
+        type_map = {
+          "magic_link" => "link",
+          "otp" => "otp",
+          "reset_token" => "token",
+          "all" => "all"
+        }
+
+        type = type_map[kind]
+        return { error: "Invalid kind: #{kind}" } unless type
+
+        if kind == "all"
+          # Extract all types
+          {
+            magic_links: Mail.extract_tokens(message_id, type: 'link'),
+            otps: Mail.extract_tokens(message_id, type: 'otp'),
+            reset_tokens: Mail.extract_tokens(message_id, type: 'token')
+          }
+        else
+          {
+            extracted: Mail.extract_tokens(message_id, type: type)
+          }
+        end
+      end
+
+      def call_get_parsed_auth_info(input)
+        message_id = (input["message_id"] || input[:message_id]).to_i
+
+        return { error: "Message not found" } unless Mail.message(message_id)
+
+        parsed = Mail.parse_message_structured(message_id)
+        {
+          verification_url: parsed[:verification_url],
+          otp_code: parsed[:otp_code],
+          reset_token: parsed[:reset_token],
+          unsubscribe_link: parsed[:unsubscribe_link],
+          links_count: parsed[:all_links]&.count || 0,
+          links: parsed[:all_links]&.slice(0, 10) # Return first 10 links
+        }
+      end
+
+      def call_get_message_preview_html(input)
+        message_id = (input["message_id"] || input[:message_id]).to_i
+        mobile = input["mobile"] || input[:mobile] || false
+
+        html_part = Mail.message_part_html(message_id)
+        return { error: "No HTML content found in message" } unless html_part
+
+        body = html_part["body"].to_s
+
+        # For mobile, add viewport meta tag if not present
+        if mobile && !body.include?("viewport")
+          body = "<head><meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\"></head>\n" + body
+        end
+
+        # Truncate if very large (limit to ~200KB for performance)
+        if body.bytesize > 200_000
+          body = body[0, 200_000] + "\n<!-- Truncated for display -->"
+        end
+
+        {
+          message_id: message_id,
+          charset: html_part["charset"] || "utf-8",
+          mobile_optimized: mobile,
+          size_bytes: body.bytesize,
+          html: body
+        }
+      end
+
+      def call_delete_message(input)
+        message_id = (input["message_id"] || input[:message_id]).to_i
+
+        return { error: "Message not found" } unless Mail.message(message_id)
+
+        Mail.delete_message!(message_id)
+        {
+          deleted: true,
+          message_id: message_id
+        }
+      end
+
+      def call_clear_messages(input)
+        Mail.delete!
+        {
+          cleared: true,
+          message: "All messages have been deleted"
+        }
+      end
+
+      # Helper methods
+
+      def format_message_summary(message)
+        {
+          id: message["id"],
+          from: message["sender"],
+          to: message["recipients"],
+          subject: message["subject"],
+          size: message["size"],
+          created_at: message["created_at"]
+        }
+      end
+
+      def format_message_detail(message_id)
+        msg = Mail.message(message_id)
+        return nil unless msg
+
+        {
+          id: msg["id"],
+          from: msg["sender"],
+          to: msg["recipients"],
+          subject: msg["subject"],
+          size: msg["size"],
+          created_at: msg["created_at"],
+          has_html: Mail.message_has_html?(message_id),
+          has_plain: Mail.message_has_plain?(message_id),
+          attachments_count: Mail.message_attachments(message_id)&.count || 0
+        }
+      end
+    end
+  end
+end