mail_mcp 0.1.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52c052a557e253241811bc0b5342a6980846ab1475761ea9b337410ed5488ed3
-  data.tar.gz: 4e8ab0e13a25ba3ab8eea26228a55d284bcd2dc4ca403a42e695585e56253643
+  metadata.gz: c33a2c64482699085c980befb438655c2d599512422281bd3c3cb48a32582500
+  data.tar.gz: 3dfbfeba54ef8f83d3bf99c7a727f7207c7245032c5df8eb6fbb53af4c089fb7
 SHA512:
-  metadata.gz: 5f47ac7a7114328a2cd8b10febe15fcd1d742f0d3ebdbbcb48556ce9a71ff7ca65af36ce5edeafc719bc8a279dbc4366132d1e56fe514347d7d16dbd952d30c0
-  data.tar.gz: 03f3ae4b06d27920d667f767757eaa6f2bcaf7bc0955f8774f4f6fe457b29247760ea65203e078979025c3420b4ce5ca27f055a73e629e1807582e1791aba555
+  metadata.gz: ba9e0f6e1dd9b84146a637d748e2559d60080f5358fd83718d7e162a513d964d8f4e492335c96435bac2954176981553700eb89227c2e8a54d12e48c230dbc76
+  data.tar.gz: 5063a62efb64854f0dfe47d2880621e9ee32a239280f78fd4d8202b405dbed45e8cc697a4269ceb59ba482e126c2cfcc6d2edbfbf29fd32abbf016ee4596d1fc

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edgars Beigarts
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,4 +1,4 @@
-# Mitigate Mail MCP
+# Mail MCP
 
 A hosted [Model Context Protocol](https://modelcontextprotocol.io/) server for IMAP and SMTP email, built in Ruby. It acts as both an OAuth 2.1 Authorization Server and an MCP Resource Server.
 
@@ -8,7 +8,7 @@ A hosted [Model Context Protocol](https://modelcontextprotocol.io/) server for I
 Client (Claude Desktop / MCP Inspector)
   │
   ├─ OAuth 2.1 flow
-  │   GET  /.well-known/oauth-protected-resource   RFC 9728 metadata
+  │   GET  /.well-known/oauth-protected-resource    RFC 9728 metadata
   │   GET  /.well-known/oauth-authorization-server  RFC 8414 metadata
   │   GET  /oauth/authorize                         Login UI
   │   POST /oauth/authorize                         Validate IMAP/SMTP → issue code
@@ -36,15 +36,17 @@ The OAuth flow:
 6. Client exchanges the authorization code (`POST /oauth/token`) with `client_id` + `client_secret`; receives `access_token` + `refresh_token`
 7. Every MCP request carries `Authorization: Bearer <access_token>`; the server decrypts credentials per-request
 
+![Login form](assets/form.png)
+
 ### Token formats
 
 All tokens are **5-part JWE** (`dir` / `A256GCM`), encrypted with `ENCRYPTION_KEY`. There is no separate signing key.
 
-| Token | `typ` claim | Expiry | Contents |
-|---|---|---|---|
-| `client_id` | `client_id` | none | imap/smtp host+port, `client_secret` |
-| Access token | `access` | 8 hours | IMAP + SMTP credentials |
-| Refresh token | `refresh` | 30 days | IMAP + SMTP credentials |
+| Token         | `typ` claim | Expiry  | Contents                             |
+|---------------|-------------|---------|--------------------------------------|
+| `client_id`   | `client_id` | none    | imap/smtp host+port, `client_secret` |
+| Access token  | `access`    | 8 hours | IMAP + SMTP credentials              |
+| Refresh token | `refresh`   | 30 days | IMAP + SMTP credentials              |
 
 ## Directory Structure
 
@@ -79,16 +81,17 @@ mail_mcp/
 
 Copy `.env.sample` to `.env` and fill in the values:
 
-| Variable | Description |
-|---|---|
-| `BASE_URL` | Public URL of this server, e.g. `https://mail.mcp.mitigate.dev` |
-| `ENCRYPTION_KEY` | AES-256 key (base64-encoded 32 bytes) — used for **all** JWE tokens |
-| `AWS_ACCESS_KEY_ID` | AWS credentials for S3 attachment storage |
-| `AWS_SECRET_ACCESS_KEY` | AWS credentials for S3 attachment storage |
-| `AWS_REGION` | S3 bucket region, e.g. `us-east-1` |
-| `AWS_S3_BUCKET` | S3 bucket name for attachments |
-| `PORT` | HTTP port (default `3000`) |
-| `RACK_ENV` | `development` or `production` |
+| Variable                | Description                                                         |
+|-------------------------|---------------------------------------------------------------------|
+| `BASE_URL`              | Public URL of this server, e.g. `https://mail.mcp.example.com`      |
+| `ENCRYPTION_KEY`        | AES-256 key (base64-encoded 32 bytes) — used for **all** JWE tokens |
+| `AWS_ACCESS_KEY_ID`     | AWS credentials for S3 attachment storage                           |
+| `AWS_SECRET_ACCESS_KEY` | AWS credentials for S3 attachment storage                           |
+| `AWS_REGION`            | S3 bucket region, e.g. `us-east-1`                                  |
+| `AWS_S3_BUCKET`         | S3 bucket name for attachments                                      |
+| `PORT`                  | HTTP port (default `3000`)                                          |
+| `RACK_ENV`              | `development` or `production`                                       |
+| `MAIL_MCP_LOG_LEVEL`    | Log level (`DEBUG`, `INFO`, `WARN`, `ERROR`, default `INFO`)        |
 
 Generate `ENCRYPTION_KEY`:
 ```bash
@@ -123,23 +126,23 @@ bundle exec bin/mail_mcp generate \
   --imap-host=imap.gmail.com \
   --imap-port=993 \
   --smtp-host=smtp.gmail.com \
-  --smtp-port=587
+  --smtp-port=465
 
 #   Client ID:     eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0...<encrypted>
 #   Client Secret: 713576e2f94802b9d9abfd755e38e29b63e491df...
 #
 #   IMAP: imap.gmail.com:993 (ssl=true)
-#   SMTP: smtp.gmail.com:587 (ssl=false)
+#   SMTP: smtp.gmail.com:465 (ssl=true)
 ```
 
-| Flag | Default | Description |
-|---|---|---|
-| `--imap-host=HOST` | required | IMAP server hostname |
-| `--imap-port=PORT` | `993` | IMAP port |
-| `--[no-]imap-ssl` | `true` when port 993 | Enable SSL/TLS for IMAP |
-| `--smtp-host=HOST` | required | SMTP server hostname |
-| `--smtp-port=PORT` | `587` | SMTP port |
-| `--[no-]smtp-ssl` | `true` when port 465 | Enable SSL/TLS for SMTP |
+| Flag               | Default              | Description             |
+|--------------------|----------------------|-------------------------|
+| `--imap-host=HOST` | required             | IMAP server hostname    |
+| `--imap-port=PORT` | `993`                | IMAP port               |
+| `--[no-]imap-ssl`  | `true` when port 993 | Enable SSL/TLS for IMAP |
+| `--smtp-host=HOST` | required             | SMTP server hostname    |
+| `--smtp-port=PORT` | `465`                | SMTP port               |
+| `--[no-]smtp-ssl`  | `true` when port 465 | Enable SSL/TLS for SMTP |
 
 ## OAuth 2.1 Flow
 
@@ -152,17 +155,17 @@ bundle exec bin/mail_mcp generate \
 
 ## MCP Tools
 
-| Tool | Parameters | Description |
-|---|---|---|
-| `list_mailboxes` | — | List all IMAP folders |
-| `list_mail_messages` | `folder`, `page`, `per_page` | List messages with pagination |
-| `get_mail_message` | `folder`, `uid` | Fetch full message; attachments uploaded to S3 and returned as presigned URLs |
-| `search_mail_messages` | `folder`, `query` | Raw IMAP SEARCH criteria, e.g. `UNSEEN` or `FROM alice@example.com SINCE 01-Jan-2025` |
-| `send_mail_message` | `to`, `subject`, `text_body`, `cc`, `bcc`, `html_body`, `attachment_urls`, `folder` | Send via SMTP and append to the Sent folder via IMAP; attachments fetched from S3 presigned URLs |
-| `create_draft_mail_message` | `to`, `subject`, `text_body`, `cc`, `bcc`, `html_body`, `attachment_urls`, `folder` | Append to Drafts via IMAP APPEND; attachments fetched from S3 presigned URLs |
-| `delete_mail_message` | `folder`, `uid` | Mark `\Deleted` + EXPUNGE |
-| `move_mail_message` | `folder`, `uid`, `destination` | IMAP MOVE (or COPY+DELETE fallback) |
-| `update_mail_message_flags` | `folder`, `uid`, `add`, `remove` | Add/remove IMAP flags, e.g. `\Seen`, `\Flagged` |
+| Tool                        | Parameters                                                                          | Description                                                                                      |
+|-----------------------------|-------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|
+| `list_mailboxes`            | —                                                                                   | List all IMAP folders                                                                            |
+| `list_mail_messages`        | `folder`, `page`, `per_page`                                                        | List messages with pagination                                                                    |
+| `get_mail_message`          | `folder`, `uid`                                                                     | Fetch full message; attachments uploaded to S3 and returned as presigned URLs                    |
+| `search_mail_messages`      | `folder`, `query`                                                                   | Raw IMAP SEARCH criteria, e.g. `UNSEEN` or `FROM alice@example.com SINCE 01-Jan-2025`            |
+| `send_mail_message`         | `to`, `subject`, `text_body`, `cc`, `bcc`, `html_body`, `attachment_urls`, `folder` | Send via SMTP and append to the Sent folder via IMAP; attachments fetched from S3 presigned URLs |
+| `create_draft_mail_message` | `to`, `subject`, `text_body`, `cc`, `bcc`, `html_body`, `attachment_urls`, `folder` | Append to Drafts via IMAP APPEND; attachments fetched from S3 presigned URLs                     |
+| `delete_mail_message`       | `folder`, `uid`                                                                     | Mark `\Deleted` + EXPUNGE                                                                        |
+| `move_mail_message`         | `folder`, `uid`, `destination`                                                      | IMAP MOVE (or COPY+DELETE fallback)                                                              |
+| `update_mail_message_flags` | `folder`, `uid`, `add`, `remove`                                                    | Add/remove IMAP flags, e.g. `\Seen`, `\Flagged`                                                  |
 
 Attachments are never returned as binary data — they are uploaded to S3 on first access and returned as presigned URLs valid for 7 days.
 

data/bin/mail_mcp

@@ -31,7 +31,7 @@ def generate_option_parser(options)
     opts.on("--imap-host=HOST",   "IMAP server hostname, e.g. imap.gmail.com")
     opts.on("--imap-port=PORT",   Integer, "IMAP port (default: 993)")
     opts.on("--smtp-host=HOST",   "SMTP server hostname, e.g. smtp.gmail.com")
-    opts.on("--smtp-port=PORT",   Integer, "SMTP port (default: 587)")
+    opts.on("--smtp-port=PORT",   Integer, "SMTP port (default: 465)")
     opts.separator ""
     opts.separator "Optional:"
     opts.on("--[no-]imap-ssl",    "Enable SSL/TLS for IMAP (default: true when port 993)")
@@ -56,7 +56,7 @@ def normalize_generate_options(options, parser)
   end
 
   imap_port = options[:"imap-port"] || 993
-  smtp_port = options[:"smtp-port"] || 587
+  smtp_port = options[:"smtp-port"] || 465
   {
     imap_host: imap_host,
     imap_port: imap_port,

data/lib/mail_mcp/app.rb

@@ -70,86 +70,29 @@ module MailMCP
       client_config = decode_client_id!(params[:client_id])
       return if client_config.nil?
 
-      @params = {
-        client_id: params[:client_id],
-        redirect_uri: params[:redirect_uri],
-        state: params[:state],
-        code_challenge: params[:code_challenge],
-        code_challenge_method: params[:code_challenge_method],
-        imap_host: client_config["imap_host"],
-        smtp_host: client_config["smtp_host"],
-        error: nil
-      }
+      params[:use_same_credentials] = "1"
+      @form = LoginForm.new(params, client_config)
       erb :login
     end
 
     post "/oauth/authorize" do
-      client_id    = params[:client_id]
-      redirect_uri = params[:redirect_uri]
-      state        = params[:state]
-      code_challenge        = params[:code_challenge]
-      code_challenge_method = params[:code_challenge_method]
-
-      client_config = decode_client_id!(client_id)
+      client_config = decode_client_id!(params[:client_id])
       return if client_config.nil?
 
-      imap_host = client_config["imap_host"]
-      imap_port = client_config["imap_port"]
-      imap_ssl  = client_config["imap_ssl"]
-      imap_user = params[:imap_username].to_s.strip
-      imap_pass = params[:imap_password].to_s
-
-      use_same  = params[:use_same_credentials] == "1"
-      smtp_host = client_config["smtp_host"]
-      smtp_port = client_config["smtp_port"]
-      smtp_ssl  = client_config["smtp_ssl"]
-      smtp_user = use_same ? imap_user : params[:smtp_username].to_s.strip
-      smtp_pass = use_same ? imap_pass : params[:smtp_password].to_s
-
-      errors = []
-
-      imap_cfg = { host: imap_host, port: imap_port, ssl: imap_ssl, username: imap_user, password: imap_pass }
-      begin
-        ImapClient.validate!(imap_cfg)
-      rescue ImapClient::AuthError, ImapClient::ConnectionError => e
-        errors << "IMAP: #{e.message}"
-      end
-
-      smtp_cfg = { host: smtp_host, port: smtp_port, ssl: smtp_ssl, username: smtp_user, password: smtp_pass }
-      begin
-        SmtpClient.validate!(smtp_cfg)
-      rescue SmtpClient::ConnectionError => e
-        errors << "SMTP: #{e.message}"
-      end
-
-      unless errors.empty?
-        @params = {
-          client_id: client_id, redirect_uri: redirect_uri, state: state,
-          code_challenge: code_challenge, code_challenge_method: code_challenge_method,
-          imap_host: imap_host, smtp_host: smtp_host,
-          error: errors.join(". ")
-        }
-        return erb :login
-      end
-
-      creds = {
-        "imap_host" => imap_host, "imap_port" => imap_port, "imap_ssl" => imap_ssl,
-        "imap_username" => imap_user, "imap_password" => imap_pass,
-        "smtp_host" => smtp_host, "smtp_port" => smtp_port, "smtp_ssl" => smtp_ssl,
-        "smtp_username" => smtp_user, "smtp_password" => smtp_pass
-      }
+      @form = LoginForm.new(params, client_config)
+      return erb :login unless @form.valid?
 
       code = JwtService.issue_code(
-        creds: creds,
-        code_challenge: code_challenge,
-        redirect_uri: redirect_uri,
-        client_id: client_id
+        creds: @form.creds,
+        code_challenge: params[:code_challenge],
+        redirect_uri: params[:redirect_uri],
+        client_id: params[:client_id]
       )
 
-      redirect_to = URI.parse(redirect_uri)
+      redirect_to = URI.parse(params[:redirect_uri])
       query = URI.decode_www_form(redirect_to.query.to_s)
       query << ["code", code]
-      query << ["state", state] if state
+      query << ["state", params[:state]] if params[:state]
       redirect_to.query = URI.encode_www_form(query)
       redirect redirect_to.to_s
     end
@@ -212,7 +155,9 @@ module MailMCP
         smtp_config: {
           host: creds["smtp_host"], port: creds["smtp_port"].to_i,
           ssl: creds["smtp_ssl"], username: creds["smtp_username"], password: creds["smtp_password"]
-        }
+        },
+        email: creds["email"],
+        full_name: creds["full_name"]
       )
       [context, nil]
     rescue JwtService::Error => e

data/lib/mail_mcp/credential_context.rb

@@ -1,5 +1,5 @@
 module MailMCP
   # Immutable credential value object passed as server_context to each per-request MCP server.
   # MCP::ServerContext delegates imap_config / smtp_config to this via method_missing.
-  CredentialContext = Struct.new(:imap_config, :smtp_config, keyword_init: true)
+  CredentialContext = Struct.new(:imap_config, :smtp_config, :email, :full_name, keyword_init: true)
 end

data/lib/mail_mcp/imap_client.rb

@@ -5,6 +5,9 @@ module MailMCP
     class AuthError < StandardError; end
     class ConnectionError < StandardError; end
 
+    OPEN_TIMEOUT = 10
+    IDLE_TIMEOUT = 30
+
     attr_reader :imap
 
     def initialize(imap)
@@ -12,24 +15,32 @@ module MailMCP
     end
 
     def self.validate!(config)
-      conn = Net::IMAP.new(config[:host], port: config[:port], ssl: config[:ssl])
+      conn = open_connection(config)
       conn.login(config[:username], config[:password])
       conn.logout
       conn.disconnect
     rescue Net::IMAP::NoResponseError, Net::IMAP::BadResponseError => e
+      MailMCP.logger.warn { "IMAP authentication failed user=#{config[:username]}: #{e.message}" }
       raise AuthError, "IMAP authentication failed: #{e.message}"
     rescue StandardError => e
+      MailMCP.logger.error do
+        "IMAP connection failed host=#{config[:host]}:#{config[:port]} ssl=#{config[:ssl]}: #{e.class}: #{e.message}"
+      end
       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 = open_connection(config)
       conn.login(config[:username], config[:password])
       client = new(conn)
       yield client
     rescue Net::IMAP::NoResponseError, Net::IMAP::BadResponseError => e
+      MailMCP.logger.warn { "IMAP authentication failed user=#{config[:username]}: #{e.message}" }
       raise AuthError, "IMAP authentication failed: #{e.message}"
     rescue StandardError => e
+      MailMCP.logger.error do
+        "IMAP connection failed host=#{config[:host]}:#{config[:port]} ssl=#{config[:ssl]}: #{e.class}: #{e.message}"
+      end
       raise ConnectionError, "IMAP connection failed: #{e.message}"
     ensure
       begin
@@ -45,15 +56,18 @@ module MailMCP
     end
 
     def list_mailboxes
+      MailMCP.logger.info { "IMAP list_mailboxes" }
       @imap.list("", "*").map(&:name)
     end
 
     def list_messages(folder:, page: 1, per_page: 20)
+      MailMCP.logger.info { "IMAP list_messages folder=#{folder.inspect} page=#{page} per_page=#{per_page}" }
       @imap.examine(folder)
       uids = @imap.uid_search(["ALL"]).reverse
       total = uids.length
       offset = (page - 1) * per_page
       page_uids = uids[offset, per_page] || []
+      MailMCP.logger.debug { "IMAP list_messages folder=#{folder.inspect} total=#{total} returned=#{page_uids.size}" }
       return { messages: [], total: total } if page_uids.empty?
 
       envelopes = @imap.uid_fetch(page_uids, ["ENVELOPE", "FLAGS", "RFC822.SIZE"])
@@ -62,44 +76,39 @@ module MailMCP
     end
 
     def get_message(folder:, uid:)
+      MailMCP.logger.info { "IMAP get_message folder=#{folder.inspect} uid=#{uid}" }
       @imap.examine(folder)
       data = @imap.uid_fetch([uid.to_i], %w[RFC822 FLAGS]).first
-      return nil unless data
+      unless data
+        MailMCP.logger.warn { "IMAP get_message not found folder=#{folder.inspect} uid=#{uid}" }
+        return nil
+      end
 
-      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
-      }
+      format_message(uid: uid, parsed: Mail.new(data.attr["RFC822"]), flags: data.attr["FLAGS"])
     end
 
     def search_messages(folder:, query:)
+      MailMCP.logger.info { "IMAP search_messages folder=#{folder.inspect} query=#{query.inspect}" }
       @imap.examine(folder)
-      @imap.search(query.split)
+      results = @imap.search(query.split)
+      MailMCP.logger.debug { "IMAP search_messages matched=#{results.size}" }
+      results
     end
 
     def delete_message(folder:, uid:)
+      MailMCP.logger.info { "IMAP delete_message folder=#{folder.inspect} uid=#{uid}" }
       @imap.select(folder)
       @imap.uid_store(uid.to_i, "+FLAGS", [:Deleted])
       @imap.expunge
     end
 
     def move_message(folder:, uid:, destination:)
+      MailMCP.logger.info { "IMAP move_message folder=#{folder.inspect} uid=#{uid} destination=#{destination.inspect}" }
       @imap.select(folder)
       if @imap.capability.include?("MOVE")
         @imap.uid_move(uid.to_i, destination)
       else
+        MailMCP.logger.debug { "IMAP move_message falling back to copy+delete (server lacks MOVE)" }
         @imap.uid_copy(uid.to_i, destination)
         @imap.uid_store(uid.to_i, "+FLAGS", [:Deleted])
         @imap.expunge
@@ -107,24 +116,66 @@ module MailMCP
     end
 
     def update_flags(folder:, uid:, add: [], remove: [])
+      MailMCP.logger.info do
+        "IMAP update_flags folder=#{folder.inspect} uid=#{uid} add=#{add.inspect} remove=#{remove.inspect}"
+      end
       @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)
+    def append_message(folder:, raw_message:, flags: [:Seen])
+      MailMCP.logger.info do
+        "IMAP append_message folder=#{folder.inspect} flags=#{flags.inspect} bytes=#{raw_message.bytesize}"
+      end
+      @imap.append(folder, raw_message, flags, Time.now)
     end
 
+    def self.open_connection(config)
+      MailMCP.logger.debug do
+        "IMAP connect host=#{config[:host]} port=#{config[:port]} ssl=#{config[:ssl]} user=#{config[:username]}"
+      end
+      Net::IMAP.new(config[:host], port: config[:port], ssl: config[:ssl], open_timeout: OPEN_TIMEOUT,
+                                   idle_response_timeout: IDLE_TIMEOUT)
+    end
+    private_class_method :open_connection
+
     private
 
+    def format_message(uid:, parsed:, flags:)
+      {
+        uid: uid,
+        message_id: parsed.message_id,
+        in_reply_to: parsed.in_reply_to,
+        references: parsed.references,
+        subject: parsed.subject,
+        from: parsed.from,
+        sender: parsed.sender,
+        reply_to: parsed.reply_to,
+        to: parsed.to,
+        cc: parsed.cc,
+        bcc: parsed.bcc,
+        date: parsed.date&.iso8601,
+        text_body: parsed.text_part&.decoded,
+        html_body: parsed.html_part&.decoded,
+        flags: flags,
+        attachments: extract_attachments(parsed)
+      }
+    end
+
     def format_envelope(msg)
       env = msg.attr["ENVELOPE"]
       {
         uid: msg.attr["UID"],
+        message_id: env.message_id,
+        in_reply_to: env.in_reply_to,
         subject: env.subject,
         from: format_addresses(env.from),
+        sender: format_addresses(env.sender),
+        reply_to: format_addresses(env.reply_to),
         to: format_addresses(env.to),
+        cc: format_addresses(env.cc),
+        bcc: format_addresses(env.bcc),
         date: env.date,
         size: msg.attr["RFC822.SIZE"],
         flags: msg.attr["FLAGS"]

data/lib/mail_mcp/jwt_service.rb

@@ -10,6 +10,7 @@ module MailMCP
     CRED_KEYS = %w[
       imap_host imap_port imap_ssl imap_username imap_password
       smtp_host smtp_port smtp_ssl smtp_username smtp_password
+      email full_name
     ].freeze
 
     # Access token — JWE (dir/A256GCM), credentials embedded directly in payload

data/lib/mail_mcp/login_form.rb

@@ -0,0 +1,72 @@
+module MailMCP
+  class LoginForm
+    attr_reader :errors
+
+    def initialize(params, client_config)
+      @params = params
+      @client_config = client_config
+      @errors = []
+    end
+
+    def valid?
+      @errors = []
+      @errors << "Email: address is required" if email.empty?
+      validate_imap
+      validate_smtp
+      @errors.empty?
+    end
+
+    def client_id            = @params[:client_id]
+    def redirect_uri         = @params[:redirect_uri]
+    def state                = @params[:state]
+    def code_challenge       = @params[:code_challenge]
+    def code_challenge_method = @params[:code_challenge_method]
+
+    def imap_host = @client_config["imap_host"]
+    def smtp_host = @client_config["smtp_host"]
+
+    def imap_username = @params[:imap_username].to_s.strip
+    def imap_password = @params[:imap_password].to_s
+    def smtp_username = use_same_credentials? ? imap_username : @params[:smtp_username].to_s.strip
+    def smtp_password = use_same_credentials? ? imap_password : @params[:smtp_password].to_s
+    def email = @params[:email].to_s.strip
+    def full_name = @params[:full_name].to_s.strip
+    def use_same_credentials? = @params[:use_same_credentials] == "1"
+
+    def imap_config
+      { host: imap_host, port: @client_config["imap_port"], ssl: @client_config["imap_ssl"],
+        username: imap_username, password: imap_password }
+    end
+
+    def smtp_config
+      { host: smtp_host, port: @client_config["smtp_port"], ssl: @client_config["smtp_ssl"],
+        username: smtp_username, password: smtp_password }
+    end
+
+    def creds
+      {
+        "imap_host" => imap_host, "imap_port" => @client_config["imap_port"],
+        "imap_ssl" => @client_config["imap_ssl"],
+        "imap_username" => imap_username, "imap_password" => imap_password,
+        "smtp_host" => smtp_host, "smtp_port" => @client_config["smtp_port"],
+        "smtp_ssl" => @client_config["smtp_ssl"],
+        "smtp_username" => smtp_username, "smtp_password" => smtp_password,
+        "email" => email, "full_name" => full_name
+      }
+    end
+
+    private
+
+    def validate_imap
+      ImapClient.validate!(imap_config)
+    rescue ImapClient::AuthError, ImapClient::ConnectionError => e
+      @errors << "IMAP: #{e.message}"
+    end
+
+    def validate_smtp
+      SmtpClient.validate!(smtp_config)
+    rescue SmtpClient::ConnectionError => e
+      @errors << "SMTP: #{e.message}"
+    end
+  end
+end

data/lib/mail_mcp/smtp_client.rb

@@ -10,17 +10,46 @@ module MailMCP
 
     def self.send(config, mail)
       smtp_open(config) do |s|
-        s.send_message(mail.to_s, mail.from.first, mail.to)
+        recipients = mail.destinations
+        MailMCP.logger.info do
+          "SMTP send to=#{recipients.join(",")} from=#{mail.from&.first} subject=#{mail.subject.inspect}"
+        end
+        s.send_message(encoded_for_wire(mail), mail.from.first, recipients)
       end
     rescue Net::SMTPError, SocketError => e
+      MailMCP.logger.error { "SMTP send failed: #{e.class}: #{e.message}" }
       raise ConnectionError, "SMTP send failed: #{e.message}"
     end
 
+    def self.encoded_for_wire(mail)
+      return mail.encoded if mail.bcc.nil? || mail.bcc.empty?
+
+      wire = Mail.new(mail.encoded)
+      wire.bcc = nil
+      wire.encoded
+    end
+    private_class_method :encoded_for_wire
+
+    OPEN_TIMEOUT = 10
+    READ_TIMEOUT = 30
+
     def self.smtp_open(config, &)
+      MailMCP.logger.debug do
+        "SMTP connect host=#{config[:host]} port=#{config[:port]} ssl=#{config[:ssl]} user=#{config[:username]}"
+      end
       smtp = Net::SMTP.new(config[:host], config[:port])
-      smtp.enable_starttls_auto unless config[:ssl]
+      smtp.open_timeout = OPEN_TIMEOUT
+      smtp.read_timeout = READ_TIMEOUT
+      if config[:ssl]
+        smtp.enable_tls
+      else
+        smtp.enable_starttls_auto
+      end
       smtp.start(config[:host], config[:username], config[:password], :login, &)
     rescue StandardError => e
+      MailMCP.logger.error do
+        "SMTP connection failed host=#{config[:host]}:#{config[:port]} ssl=#{config[:ssl]}: #{e.class}: #{e.message}"
+      end
       raise ConnectionError, "SMTP connection failed: #{e.message}"
     end
     private_class_method :smtp_open

data/lib/mail_mcp/tool.rb

@@ -2,5 +2,15 @@ require "mcp"
 
 module MailMCP
   class Tool < MCP::Tool
+    def self.format_from(server_context)
+      address = server_context.email
+      name = server_context.full_name
+      return address if name.nil? || name.empty?
+
+      addr = Mail::Address.new
+      addr.address = address
+      addr.display_name = name
+      addr.format
+    end
   end
 end

data/lib/mail_mcp/tools/create_draft_mail_message_tool.rb

@@ -28,14 +28,15 @@ module MailMCP
 
     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],
+        from: format_from(server_context),
         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) }
+      ImapClient.connect(server_context.imap_config) do |c|
+        c.append_message(folder: folder, raw_message: mail.to_s, flags: [:Draft])
+      end
       MCP::Tool::Response.new([{ type: "text", text: "Draft saved to #{folder}" }])
     end
   end

data/lib/mail_mcp/tools/send_mail_message_tool.rb

@@ -30,13 +30,30 @@ module MailMCP
     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],
+        from: format_from(server_context),
         to: to, subject: subject, text_body: text_body,
         cc: cc, bcc: bcc, html_body: html_body,
         attachment_urls: attachment_urls
       )
+      ImapClient.connect(server_context.imap_config) do |c|
+        unless c.list_mailboxes.include?(folder)
+          raise ImapClient::ConnectionError,
+                "IMAP folder #{folder.inspect} does not exist. Use list_mailboxes to see available folders."
+        end
+      end
+
       SmtpClient.send(server_context.smtp_config, mail)
-      ImapClient.connect(server_context.imap_config) { |c| c.append_message(folder: folder, raw_message: mail.to_s) }
+
+      begin
+        ImapClient.connect(server_context.imap_config) do |c|
+          c.append_message(folder: folder, raw_message: mail.to_s, flags: [:Seen])
+        end
+      rescue StandardError => e
+        MailMCP.logger.warn { "Email sent but failed to save to IMAP folder=#{folder.inspect}: #{e.message}" }
+        text = "Email sent successfully to #{to}, but could not be saved to #{folder}: #{e.message}"
+        return MCP::Tool::Response.new([{ type: "text", text: text }])
+      end
+
       MCP::Tool::Response.new([{ type: "text", text: "Email sent successfully to #{to} and saved to #{folder}" }])
     end
   end

data/lib/mail_mcp/tools/update_mail_message_flags_tool.rb

@@ -10,25 +10,56 @@ module MailMCP
       open_world_hint: true
     )
 
+    # IMAP allows only these six backslash-prefixed system flags; anything else
+    # must be sent as a keyword (a bare atom with no leading backslash).
+    SYSTEM_FLAGS = %w[Seen Answered Flagged Deleted Draft Recent].freeze
+
+    # Friendly color names map to Mozilla/Thunderbird $labelN keywords, the
+    # de-facto cross-client convention for colored flags.
+    COLOR_KEYWORDS = {
+      "red" => "$label1",
+      "orange" => "$label2",
+      "green" => "$label3",
+      "blue" => "$label4",
+      "purple" => "$label5"
+    }.freeze
+
     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']" },
+               description: "Flags to add. Settable system flags: '\\\\Seen', '\\\\Answered', " \
+                            "'\\\\Flagged', '\\\\Deleted', '\\\\Draft' (\\\\Recent is recognized " \
+                            "but cannot be set by clients). Color names " \
+                            "('red', 'orange', 'green', 'blue', 'purple') map to " \
+                            "$labelN keywords. Any other value is sent as a custom keyword." },
         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)
+      add_flags    = add.map { |f| normalize_flag(f) }
+      remove_flags = remove.map { |f| normalize_flag(f) }
       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
+
+    # System flags become Symbols (net/imap renders them with a leading
+    # backslash). Custom keywords stay Strings (rendered as bare atoms).
+    # Friendly color names are translated to their $labelN keyword first.
+    def self.normalize_flag(flag)
+      name = flag.to_s.delete_prefix("\\")
+      return COLOR_KEYWORDS.fetch(name.downcase) if COLOR_KEYWORDS.key?(name.downcase)
+
+      # System flags are case-insensitive per RFC 3501; normalize to the
+      # canonical capitalization so e.g. "seen" / "\\SEEN" still set :Seen.
+      system_flag = SYSTEM_FLAGS.find { |f| f.casecmp?(name) }
+      system_flag ? system_flag.to_sym : name
+    end
   end
 end

data/lib/mail_mcp/version.rb

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

data/lib/mail_mcp.rb

@@ -1,9 +1,17 @@
 require "base64"
 require "json"
+require "logger"
 
 require_relative "mail_mcp/version"
 
 module MailMCP
+  def self.logger
+    @logger ||= Logger.new($stdout, level: ENV.fetch("MAIL_MCP_LOG_LEVEL", "INFO"), progname: "mail_mcp")
+  end
+
+  class << self
+    attr_writer :logger
+  end
 end
 
 require_relative "mail_mcp/jwt_service"
@@ -12,6 +20,7 @@ require_relative "mail_mcp/imap_client"
 require_relative "mail_mcp/smtp_client"
 require_relative "mail_mcp/attachment_store"
 require_relative "mail_mcp/credential_context"
+require_relative "mail_mcp/login_form"
 require_relative "mail_mcp/mail_builder"
 require_relative "mail_mcp/tool"
 require_relative "mail_mcp/tools/list_mailboxes_tool"

data/views/login.erb

@@ -71,46 +71,64 @@
   <h1>Mail MCP</h1>
   <p class="subtitle">Connect your email account to continue</p>
   <div class="server-info">
-    IMAP <span><%= @params[:imap_host] %></span> &nbsp;·&nbsp;
-    SMTP <span><%= @params[:smtp_host] %></span>
+    IMAP <span><%= @form.imap_host %></span> &nbsp;·&nbsp;
+    SMTP <span><%= @form.smtp_host %></span>
   </div>
 
-  <% if @params[:error] %>
-    <div class="error"><%= @params[:error] %></div>
+  <% unless @form.errors.empty? %>
+    <div class="error">
+      <% @form.errors.each do |err| %>
+        <div><%= err %></div>
+      <% end %>
+    </div>
   <% end %>
 
   <form method="POST" action="/oauth/authorize">
-    <input type="hidden" name="client_id"             value="<%= @params[:client_id] %>">
-    <input type="hidden" name="redirect_uri"          value="<%= @params[:redirect_uri] %>">
-    <input type="hidden" name="state"                 value="<%= @params[:state] %>">
-    <input type="hidden" name="code_challenge"        value="<%= @params[:code_challenge] %>">
-    <input type="hidden" name="code_challenge_method" value="<%= @params[:code_challenge_method] %>">
+    <input type="hidden" name="client_id"             value="<%= @form.client_id %>">
+    <input type="hidden" name="redirect_uri"          value="<%= @form.redirect_uri %>">
+    <input type="hidden" name="state"                 value="<%= @form.state %>">
+    <input type="hidden" name="code_challenge"        value="<%= @form.code_challenge %>">
+    <input type="hidden" name="code_challenge_method" value="<%= @form.code_challenge_method %>">
+
+    <label for="full_name">Full Name</label>
+    <input type="text" id="full_name" name="full_name"
+           placeholder="John Doe" autocomplete="name"
+           value="<%= escape_html(@form.full_name) %>">
+
+    <label for="email">Email Address</label>
+    <input type="text" id="email" name="email"
+           placeholder="you@example.com" autocomplete="email" required
+           value="<%= escape_html(@form.email) %>">
 
     <div class="section-title">IMAP (Incoming)</div>
 
     <label for="imap_username">IMAP Username</label>
     <input type="text" id="imap_username" name="imap_username"
-           placeholder="you@example.com" autocomplete="username" required>
+           placeholder="you@example.com" autocomplete="username" required
+           value="<%= escape_html(@form.imap_username) %>">
 
     <label for="imap_password">IMAP Password</label>
     <input type="password" id="imap_password" name="imap_password"
-           placeholder="••••••••" autocomplete="current-password" required>
+           placeholder="••••••••" autocomplete="current-password" required
+           value="<%= escape_html(@form.imap_password) %>">
 
     <div class="checkbox-row">
-      <input type="checkbox" id="use_same" name="use_same_credentials" value="1" checked>
+      <input type="checkbox" id="use_same" name="use_same_credentials" value="1" <%= "checked" if @form.use_same_credentials? %>>
       <label for="use_same">Use the same username and password for SMTP</label>
     </div>
 
-    <div id="smtp-fields" style="display:none">
+    <div id="smtp-fields" style="display:<%= @form.use_same_credentials? ? "none" : "block" %>">
       <div class="section-title">SMTP (Outgoing)</div>
 
       <label for="smtp_username">SMTP Username</label>
       <input type="text" id="smtp_username" name="smtp_username"
-             placeholder="you@example.com" autocomplete="username">
+             placeholder="you@example.com" autocomplete="username"
+             value="<%= escape_html(@form.smtp_username) %>">
 
       <label for="smtp_password">SMTP Password</label>
       <input type="password" id="smtp_password" name="smtp_password"
-             placeholder="••••••••" autocomplete="current-password">
+             placeholder="••••••••" autocomplete="current-password"
+             value="<%= escape_html(@form.smtp_password) %>">
     </div>
 
     <button type="submit">Connect</button>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mail_mcp
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Edgars Beigarts
@@ -158,6 +158,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
 - README.md
 - bin/mail_mcp
 - config.ru
@@ -168,6 +169,7 @@ files:
 - lib/mail_mcp/credential_context.rb
 - lib/mail_mcp/imap_client.rb
 - lib/mail_mcp/jwt_service.rb
+- lib/mail_mcp/login_form.rb
 - lib/mail_mcp/mail_builder.rb
 - lib/mail_mcp/pkce.rb
 - lib/mail_mcp/smtp_client.rb
@@ -183,10 +185,13 @@ files:
 - lib/mail_mcp/tools/update_mail_message_flags_tool.rb
 - lib/mail_mcp/version.rb
 - views/login.erb
+homepage: https://github.com/mitigate-dev/mail_mcp
 licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/mitigate-dev/mail_mcp
+  source_code_uri: https://github.com/mitigate-dev/mail_mcp
 rdoc_options: []
 require_paths:
 - lib