mail_mcp 0.1.0

data/lib/mail_mcp/imap_client.rb

@@ -0,0 +1,151 @@
+require "net/imap"
+
+module MailMCP
+  class ImapClient
+    class AuthError < StandardError; end
+    class ConnectionError < StandardError; end
+
+    attr_reader :imap
+
+    def initialize(imap)
+      @imap = imap
+    end
+
+    def self.validate!(config)
+      conn = Net::IMAP.new(config[:host], port: config[:port], ssl: config[:ssl])
+      conn.login(config[:username], config[:password])
+      conn.logout
+      conn.disconnect
+    rescue Net::IMAP::NoResponseError, Net::IMAP::BadResponseError => e
+      raise AuthError, "IMAP authentication failed: #{e.message}"
+    rescue StandardError => e
+      raise ConnectionError, "IMAP connection failed: #{e.message}"
+    end
+
+    def self.connect(config)
+      conn = Net::IMAP.new(config[:host], port: config[:port], ssl: config[:ssl])
+      conn.login(config[:username], config[:password])
+      client = new(conn)
+      yield client
+    rescue Net::IMAP::NoResponseError, Net::IMAP::BadResponseError => e
+      raise AuthError, "IMAP authentication failed: #{e.message}"
+    rescue StandardError => e
+      raise ConnectionError, "IMAP connection failed: #{e.message}"
+    ensure
+      begin
+        conn&.logout
+      rescue StandardError
+        nil
+      end
+      begin
+        conn&.disconnect
+      rescue StandardError
+        nil
+      end
+    end
+
+    def list_mailboxes
+      @imap.list("", "*").map(&:name)
+    end
+
+    def list_messages(folder:, page: 1, per_page: 20)
+      @imap.examine(folder)
+      uids = @imap.uid_search(["ALL"]).reverse
+      total = uids.length
+      offset = (page - 1) * per_page
+      page_uids = uids[offset, per_page] || []
+      return { messages: [], total: total } if page_uids.empty?
+
+      envelopes = @imap.uid_fetch(page_uids, ["ENVELOPE", "FLAGS", "RFC822.SIZE"])
+      messages = (envelopes || []).map { |msg| format_envelope(msg) }
+      { messages: messages, total: total, page: page, per_page: per_page }
+    end
+
+    def get_message(folder:, uid:)
+      @imap.examine(folder)
+      data = @imap.uid_fetch([uid.to_i], %w[RFC822 FLAGS]).first
+      return nil unless data
+
+      raw = data.attr["RFC822"]
+      flags = data.attr["FLAGS"]
+      parsed = Mail.new(raw)
+      attachments = extract_attachments(parsed)
+      {
+        uid: uid,
+        subject: parsed.subject,
+        from: parsed.from,
+        to: parsed.to,
+        cc: parsed.cc,
+        date: parsed.date&.iso8601,
+        text_body: parsed.text_part&.decoded,
+        html_body: parsed.html_part&.decoded,
+        flags: flags,
+        attachments: attachments
+      }
+    end
+
+    def search_messages(folder:, query:)
+      @imap.examine(folder)
+      @imap.search(query.split)
+    end
+
+    def delete_message(folder:, uid:)
+      @imap.select(folder)
+      @imap.uid_store(uid.to_i, "+FLAGS", [:Deleted])
+      @imap.expunge
+    end
+
+    def move_message(folder:, uid:, destination:)
+      @imap.select(folder)
+      if @imap.capability.include?("MOVE")
+        @imap.uid_move(uid.to_i, destination)
+      else
+        @imap.uid_copy(uid.to_i, destination)
+        @imap.uid_store(uid.to_i, "+FLAGS", [:Deleted])
+        @imap.expunge
+      end
+    end
+
+    def update_flags(folder:, uid:, add: [], remove: [])
+      @imap.select(folder)
+      @imap.uid_store(uid.to_i, "+FLAGS", add) unless add.empty?
+      @imap.uid_store(uid.to_i, "-FLAGS", remove) unless remove.empty?
+    end
+
+    def append_message(folder:, raw_message:)
+      @imap.append(folder, raw_message, [:Draft], Time.now)
+    end
+
+    private
+
+    def format_envelope(msg)
+      env = msg.attr["ENVELOPE"]
+      {
+        uid: msg.attr["UID"],
+        subject: env.subject,
+        from: format_addresses(env.from),
+        to: format_addresses(env.to),
+        date: env.date,
+        size: msg.attr["RFC822.SIZE"],
+        flags: msg.attr["FLAGS"]
+      }
+    end
+
+    def format_addresses(addrs)
+      return [] unless addrs
+
+      addrs.map { |a| "#{a.name} <#{a.mailbox}@#{a.host}>" }
+    end
+
+    def extract_attachments(mail)
+      mail.attachments.map do |att|
+        url = AttachmentStore.upload(
+          content: att.decoded,
+          filename: att.filename || "attachment",
+          content_type: att.content_type
+        )
+        { filename: att.filename, content_type: att.content_type, size: att.decoded.bytesize, url: url }
+      end
+    end
+  end
+end

data/lib/mail_mcp/jwt_service.rb

@@ -0,0 +1,126 @@
+require "json/jwt"
+
+module MailMCP
+  module JwtService
+    class Error < StandardError; end
+
+    DEFAULT_EXPIRY         = 8 * 3600
+    DEFAULT_REFRESH_EXPIRY = 30 * 24 * 3600
+
+    CRED_KEYS = %w[
+      imap_host imap_port imap_ssl imap_username imap_password
+      smtp_host smtp_port smtp_ssl smtp_username smtp_password
+    ].freeze
+
+    # Access token — JWE (dir/A256GCM), credentials embedded directly in payload
+    def self.issue(creds, expires_in: DEFAULT_EXPIRY)
+      issue_jwe(creds.merge("typ" => "access"), expires_in: expires_in)
+    end
+
+    def self.verify(token)
+      payload = decode_jwe(token)
+      raise Error, "Not an access token" unless payload["typ"] == "access"
+
+      payload.slice(*CRED_KEYS)
+    end
+
+    # Refresh token — JWE, longer-lived, carries same credential payload
+    def self.issue_refresh(creds, expires_in: DEFAULT_REFRESH_EXPIRY)
+      issue_jwe(creds.merge("typ" => "refresh"), expires_in: expires_in)
+    end
+
+    def self.verify_refresh(token)
+      payload = decode_jwe(token)
+      raise Error, "Not a refresh token" unless payload["typ"] == "refresh"
+
+      payload.slice(*CRED_KEYS)
+    end
+
+    # Authorization code — short-lived JWE carrying creds + PKCE state (stateless PKCE)
+    CODE_EXPIRY = 300 # 5 minutes
+
+    def self.issue_code(creds:, code_challenge:, redirect_uri:, client_id:)
+      issue_jwe(
+        creds.merge(
+          "typ" => "code",
+          "code_challenge" => code_challenge,
+          "redirect_uri" => redirect_uri,
+          "client_id" => client_id
+        ),
+        expires_in: CODE_EXPIRY
+      )
+    end
+
+    def self.verify_code(token)
+      payload = decode_jwe(token)
+      raise Error, "Not an authorization code" unless payload["typ"] == "code"
+
+      payload
+    end
+
+    # Client ID token — JWE, no expiry, carries imap/smtp config + client_secret
+    def self.issue_client_id(imap_host:, imap_port:, imap_ssl:, smtp_host:, smtp_port:, smtp_ssl:, client_secret:)
+      payload = JSON.generate(
+        iss: ENV.fetch("BASE_URL"),
+        aud: ENV.fetch("BASE_URL"),
+        typ: "client_id",
+        imap_host: imap_host,
+        imap_port: imap_port.to_i,
+        imap_ssl: imap_ssl,
+        smtp_host: smtp_host,
+        smtp_port: smtp_port.to_i,
+        smtp_ssl: smtp_ssl,
+        cs: client_secret
+      )
+      encrypt_jwe(payload)
+    end
+
+    def self.decode_client_id(token)
+      payload = decode_jwe(token, verify_exp: false)
+      raise Error, "Not a client_id token" unless payload["typ"] == "client_id"
+
+      payload
+    end
+
+    def self.issue_jwe(payload_hash, expires_in:)
+      now = Time.now.to_i
+      payload = JSON.generate(
+        payload_hash.merge(
+          "iss" => ENV.fetch("BASE_URL"),
+          "aud" => ENV.fetch("BASE_URL"),
+          "iat" => now,
+          "exp" => now + expires_in
+        )
+      )
+      encrypt_jwe(payload)
+    end
+    private_class_method :issue_jwe
+
+    def self.encrypt_jwe(payload_json)
+      jwe = JSON::JWE.new(payload_json)
+      jwe.alg = :dir
+      jwe.enc = :A256GCM
+      jwe.encrypt!(encryption_key)
+      jwe.to_s
+    end
+    private_class_method :encrypt_jwe
+
+    def self.decode_jwe(token, verify_exp: true)
+      jwe = JSON::JWE.decode(token, encryption_key)
+      payload = JSON.parse(jwe.plain_text)
+      raise Error, "Token expired"    if verify_exp && payload["exp"].to_i < Time.now.to_i
+      raise Error, "Invalid issuer"   if payload["iss"] != ENV.fetch("BASE_URL")
+      raise Error, "Invalid audience" if payload["aud"] != ENV.fetch("BASE_URL")
+
+      payload
+    rescue JSON::JWT::Exception => e
+      raise Error, e.message
+    end
+    private_class_method :decode_jwe
+
+    def self.encryption_key
+      Base64.strict_decode64(ENV.fetch("ENCRYPTION_KEY"))
+    end
+    private_class_method :encryption_key
+  end
+end

data/lib/mail_mcp/mail_builder.rb

@@ -0,0 +1,42 @@
+require "mail"
+require "open-uri"
+
+module MailMCP
+  module MailBuilder
+    module_function
+
+    def build(from:, to:, subject:, text_body:, cc: nil, bcc: nil, html_body: nil, attachment_urls: [])
+      mail = Mail.new
+      mail.from    = from
+      mail.to      = to
+      mail.subject = subject
+      mail.cc      = cc if cc
+      mail.bcc     = bcc if bcc
+      if html_body
+        mail.html_part = Mail::Part.new do
+          content_type "text/html
+ charset=UTF-8"
+          body html_body
+        end
+        mail.text_part = Mail::Part.new do
+          content_type "text/plain
+ charset=UTF-8"
+          body text_body
+        end
+      else
+        mail.body = text_body
+      end
+      attachment_urls.each { |url| attach_from_url(mail, url) }
+      mail
+    end
+
+    def attach_from_url(mail, url)
+      URI.open(url) do |f|
+        filename = File.basename(URI.parse(url).path)
+        mail.attachments[filename] = { content: f.read, mime_type: f.content_type }
+      end
+    rescue StandardError => e
+      raise "Failed to fetch attachment from #{url}: #{e.message}"
+    end
+  end
+end

data/lib/mail_mcp/pkce.rb

@@ -0,0 +1,19 @@
+require "digest"
+require "securerandom"
+
+module MailMCP
+  module Pkce
+    def self.challenge(verifier)
+      Base64.urlsafe_encode64(Digest::SHA256.digest(verifier), padding: false)
+    end
+
+    def self.valid?(verifier:, challenge:)
+      expected = challenge(verifier)
+      begin
+        ActiveSupport::SecurityUtils.secure_compare(expected, challenge)
+      rescue StandardError
+        (expected == challenge)
+      end
+    end
+  end
+end

data/lib/mail_mcp/smtp_client.rb

@@ -0,0 +1,28 @@
+require "net/smtp"
+
+module MailMCP
+  module SmtpClient
+    class ConnectionError < StandardError; end
+
+    def self.validate!(config)
+      smtp_open(config) { nil }
+    end
+
+    def self.send(config, mail)
+      smtp_open(config) do |s|
+        s.send_message(mail.to_s, mail.from.first, mail.to)
+      end
+    rescue Net::SMTPError, SocketError => e
+      raise ConnectionError, "SMTP send failed: #{e.message}"
+    end
+
+    def self.smtp_open(config, &)
+      smtp = Net::SMTP.new(config[:host], config[:port])
+      smtp.enable_starttls_auto unless config[:ssl]
+      smtp.start(config[:host], config[:username], config[:password], :login, &)
+    rescue StandardError => e
+      raise ConnectionError, "SMTP connection failed: #{e.message}"
+    end
+    private_class_method :smtp_open
+  end
+end

data/lib/mail_mcp/tool.rb

@@ -0,0 +1,6 @@
+require "mcp"
+
+module MailMCP
+  class Tool < MCP::Tool
+  end
+end

data/lib/mail_mcp/tools/create_draft_mail_message_tool.rb

@@ -0,0 +1,42 @@
+module MailMCP
+  class CreateDraftMailMessageTool < Tool
+    tool_name "create_draft_mail_message"
+    description "Save an email as a draft to the Drafts folder via IMAP APPEND"
+    annotations(
+      title: "Create Draft Mail Message",
+      read_only_hint: false,
+      destructive_hint: false,
+      idempotent_hint: false,
+      open_world_hint: true
+    )
+
+    input_schema(
+      type: "object",
+      properties: {
+        to: { type: "string" },
+        subject: { type: "string" },
+        text_body: { type: "string" },
+        cc: { type: "string" },
+        bcc: { type: "string" },
+        html_body: { type: "string" },
+        attachment_urls: { type: "array", items: { type: "string" },
+                           description: "S3 presigned URLs to attach" },
+        folder: { type: "string", description: "Target folder (default: Drafts)", default: "Drafts" }
+      },
+      required: %w[to subject text_body]
+    )
+
+    def self.call(to:, subject:, text_body:, server_context:, cc: nil, bcc: nil, html_body: nil,
+                  attachment_urls: [], folder: "Drafts")
+      imap_config = server_context.imap_config
+      mail = MailBuilder.build(
+        from: imap_config[:username],
+        to: to, subject: subject, text_body: text_body,
+        cc: cc, bcc: bcc, html_body: html_body,
+        attachment_urls: attachment_urls
+      )
+      ImapClient.connect(imap_config) { |c| c.append_message(folder: folder, raw_message: mail.to_s) }
+      MCP::Tool::Response.new([{ type: "text", text: "Draft saved to #{folder}" }])
+    end
+  end
+end

data/lib/mail_mcp/tools/delete_mail_message_tool.rb

@@ -0,0 +1,27 @@
+module MailMCP
+  class DeleteMailMessageTool < Tool
+    tool_name "delete_mail_message"
+    description "Delete a message by UID (marks as deleted and expunges)"
+    annotations(
+      title: "Delete Mail Message",
+      read_only_hint: false,
+      destructive_hint: true,
+      idempotent_hint: false,
+      open_world_hint: true
+    )
+
+    input_schema(
+      type: "object",
+      properties: {
+        folder: { type: "string" },
+        uid: { type: "integer" }
+      },
+      required: %w[folder uid]
+    )
+
+    def self.call(folder:, uid:, server_context:)
+      ImapClient.connect(server_context.imap_config) { |c| c.delete_message(folder: folder, uid: uid) }
+      MCP::Tool::Response.new([{ type: "text", text: "Message #{uid} deleted from #{folder}" }])
+    end
+  end
+end

data/lib/mail_mcp/tools/get_mail_message_tool.rb

@@ -0,0 +1,29 @@
+module MailMCP
+  class GetMailMessageTool < Tool
+    tool_name "get_mail_message"
+    description "Fetch a full email message including body and attachment URLs"
+    annotations(
+      title: "Get Mail Message",
+      read_only_hint: true,
+      destructive_hint: false,
+      idempotent_hint: false,
+      open_world_hint: true
+    )
+
+    input_schema(
+      type: "object",
+      properties: {
+        folder: { type: "string", description: "Mailbox folder name" },
+        uid: { type: "integer", description: "Message UID" }
+      },
+      required: %w[folder uid]
+    )
+
+    def self.call(folder:, uid:, server_context:)
+      msg = ImapClient.connect(server_context.imap_config) { |c| c.get_message(folder: folder, uid: uid) }
+      return MCP::Tool::Response.new([{ type: "text", text: "Message not found" }], error: true) unless msg
+
+      MCP::Tool::Response.new([{ type: "text", text: JSON.generate(msg) }])
+    end
+  end
+end

data/lib/mail_mcp/tools/list_mail_messages_tool.rb

@@ -0,0 +1,30 @@
+module MailMCP
+  class ListMailMessagesTool < Tool
+    tool_name "list_mail_messages"
+    description "List messages in an IMAP folder with pagination"
+    annotations(
+      title: "List Mail Messages",
+      read_only_hint: true,
+      destructive_hint: false,
+      idempotent_hint: false,
+      open_world_hint: true
+    )
+
+    input_schema(
+      type: "object",
+      properties: {
+        folder: { type: "string", description: "Mailbox folder name" },
+        page: { type: "integer", description: "Page number (default 1)", default: 1 },
+        per_page: { type: "integer", description: "Messages per page (default 20)", default: 20 }
+      },
+      required: ["folder"]
+    )
+
+    def self.call(folder:, server_context:, page: 1, per_page: 20)
+      result = ImapClient.connect(server_context.imap_config) do |c|
+        c.list_messages(folder: folder, page: page, per_page: per_page)
+      end
+      MCP::Tool::Response.new([{ type: "text", text: JSON.generate(result) }])
+    end
+  end
+end

data/lib/mail_mcp/tools/list_mailboxes_tool.rb

@@ -0,0 +1,18 @@
+module MailMCP
+  class ListMailboxesTool < Tool
+    tool_name "list_mailboxes"
+    description "List all IMAP mailboxes/folders"
+    annotations(
+      title: "List Mailboxes",
+      read_only_hint: true,
+      destructive_hint: false,
+      idempotent_hint: false,
+      open_world_hint: true
+    )
+
+    def self.call(server_context:)
+      mailboxes = ImapClient.connect(server_context.imap_config, &:list_mailboxes)
+      MCP::Tool::Response.new([{ type: "text", text: JSON.generate(mailboxes) }])
+    end
+  end
+end

data/lib/mail_mcp/tools/move_mail_message_tool.rb

@@ -0,0 +1,30 @@
+module MailMCP
+  class MoveMailMessageTool < Tool
+    tool_name "move_mail_message"
+    description "Move a message to another folder"
+    annotations(
+      title: "Move Mail Message",
+      read_only_hint: false,
+      destructive_hint: true,
+      idempotent_hint: false,
+      open_world_hint: true
+    )
+
+    input_schema(
+      type: "object",
+      properties: {
+        folder: { type: "string", description: "Source folder" },
+        uid: { type: "integer" },
+        destination: { type: "string", description: "Destination folder" }
+      },
+      required: %w[folder uid destination]
+    )
+
+    def self.call(folder:, uid:, destination:, server_context:)
+      ImapClient.connect(server_context.imap_config) do |c|
+        c.move_message(folder: folder, uid: uid, destination: destination)
+      end
+      MCP::Tool::Response.new([{ type: "text", text: "Message #{uid} moved from #{folder} to #{destination}" }])
+    end
+  end
+end

data/lib/mail_mcp/tools/search_mail_messages_tool.rb

@@ -0,0 +1,31 @@
+module MailMCP
+  class SearchMailMessagesTool < Tool
+    tool_name "search_mail_messages"
+    description "Search messages in an IMAP folder using raw IMAP SEARCH criteria"
+    annotations(
+      title: "Search Mail Messages",
+      read_only_hint: true,
+      destructive_hint: false,
+      idempotent_hint: false,
+      open_world_hint: true
+    )
+
+    input_schema(
+      type: "object",
+      properties: {
+        folder: { type: "string", description: "Mailbox folder name, e.g. INBOX" },
+        query: { type: "string",
+                 description: "Raw IMAP SEARCH criteria, e.g. 'UNSEEN' or " \
+                              "'FROM alice@example.com SINCE 01-Jan-2025'" }
+      },
+      required: %w[folder query]
+    )
+
+    def self.call(folder:, query:, server_context:)
+      uids = ImapClient.connect(server_context.imap_config) { |c| c.search_messages(folder: folder, query: query) }
+      MCP::Tool::Response.new([{ type: "text",
+                                 text: JSON.generate({ folder: folder, query: query, uids: uids,
+                                                       count: uids.length }) }])
+    end
+  end
+end

data/lib/mail_mcp/tools/send_mail_message_tool.rb

@@ -0,0 +1,43 @@
+module MailMCP
+  class SendMailMessageTool < Tool
+    tool_name "send_mail_message"
+    description "Send an email via SMTP"
+    annotations(
+      title: "Send Mail Message",
+      read_only_hint: false,
+      destructive_hint: true,
+      idempotent_hint: false,
+      open_world_hint: true
+    )
+
+    input_schema(
+      type: "object",
+      properties: {
+        to: { type: "string", description: "Recipient address(es), comma-separated" },
+        subject: { type: "string" },
+        text_body: { type: "string", description: "Plain-text body" },
+        cc: { type: "string" },
+        bcc: { type: "string" },
+        html_body: { type: "string", description: "HTML body (optional)" },
+        attachment_urls: { type: "array", items: { type: "string" },
+                           description: "S3 presigned URLs to attach" },
+        folder: { type: "string", description: "IMAP folder to save the sent message (default: Sent)",
+                  default: "Sent" }
+      },
+      required: %w[to subject text_body]
+    )
+
+    def self.call(to:, subject:, text_body:, server_context:, cc: nil, bcc: nil, html_body: nil,
+                  attachment_urls: [], folder: "Sent")
+      mail = MailBuilder.build(
+        from: server_context.imap_config[:username],
+        to: to, subject: subject, text_body: text_body,
+        cc: cc, bcc: bcc, html_body: html_body,
+        attachment_urls: attachment_urls
+      )
+      SmtpClient.send(server_context.smtp_config, mail)
+      ImapClient.connect(server_context.imap_config) { |c| c.append_message(folder: folder, raw_message: mail.to_s) }
+      MCP::Tool::Response.new([{ type: "text", text: "Email sent successfully to #{to} and saved to #{folder}" }])
+    end
+  end
+end

data/lib/mail_mcp/tools/update_mail_message_flags_tool.rb

@@ -0,0 +1,34 @@
+module MailMCP
+  class UpdateMailMessageFlagsTool < Tool
+    tool_name "update_mail_message_flags"
+    description "Update IMAP flags on a message (mark as read, flagged, etc.)"
+    annotations(
+      title: "Update Mail Message Flags",
+      read_only_hint: false,
+      destructive_hint: true,
+      idempotent_hint: false,
+      open_world_hint: true
+    )
+
+    input_schema(
+      type: "object",
+      properties: {
+        folder: { type: "string" },
+        uid: { type: "integer" },
+        add: { type: "array", items: { type: "string" },
+               description: "Flags to add, e.g. ['\\\\Seen', '\\\\Flagged']" },
+        remove: { type: "array", items: { type: "string" }, description: "Flags to remove" }
+      },
+      required: %w[folder uid]
+    )
+
+    def self.call(folder:, uid:, server_context:, add: [], remove: [])
+      add_flags    = add.map(&:to_sym)
+      remove_flags = remove.map(&:to_sym)
+      ImapClient.connect(server_context.imap_config) do |c|
+        c.update_flags(folder: folder, uid: uid, add: add_flags, remove: remove_flags)
+      end
+      MCP::Tool::Response.new([{ type: "text", text: "Flags updated for message #{uid}" }])
+    end
+  end
+end

data/lib/mail_mcp/version.rb

@@ -0,0 +1,3 @@
+module MailMCP
+  VERSION = "0.1.0".freeze
+end