mail_mcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 52c052a557e253241811bc0b5342a6980846ab1475761ea9b337410ed5488ed3
+  data.tar.gz: 4e8ab0e13a25ba3ab8eea26228a55d284bcd2dc4ca403a42e695585e56253643
+SHA512:
+  metadata.gz: 5f47ac7a7114328a2cd8b10febe15fcd1d742f0d3ebdbbcb48556ce9a71ff7ca65af36ce5edeafc719bc8a279dbc4366132d1e56fe514347d7d16dbd952d30c0
+  data.tar.gz: 03f3ae4b06d27920d667f767757eaa6f2bcaf7bc0955f8774f4f6fe457b29247760ea65203e078979025c3420b4ce5ca27f055a73e629e1807582e1791aba555

data/README.md

@@ -0,0 +1,174 @@
+# Mitigate 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.
+
+## Architecture
+
+```
+Client (Claude Desktop / MCP Inspector)
+  │
+  ├─ OAuth 2.1 flow
+  │   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
+  │   POST /oauth/token                             Code + PKCE + client_secret → tokens
+  │                                                 (also: refresh_token grant)
+  │
+  └─ MCP calls (all HTTP methods)
+      /mcp   Bearer access token → decrypt creds → IMAP/SMTP operations
+```
+
+### How authentication works
+
+Clients are provisioned once via the `bin/mail_mcp generate` CLI, which produces:
+
+- **`client_id`** — a JWE token (encrypted, opaque) encoding the IMAP/SMTP server configuration and the `client_secret`. Only the server can decrypt it.
+- **`client_secret`** — a random secret used to authenticate the client at the token endpoint.
+
+The OAuth flow:
+
+1. Client redirects the user to `/oauth/authorize?client_id=<jwe>&...`
+2. Server decrypts the `client_id` JWE to learn which IMAP/SMTP servers to connect to
+3. User enters their IMAP/SMTP username and password in the login form
+4. Server validates both connections live; shows an error banner on failure
+5. On success: credentials are encrypted directly in a JWE access token and a JWE refresh token
+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
+
+### 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 |
+
+## Directory Structure
+
+```
+mail_mcp/
+├── Gemfile
+├── .env.sample            # Environment variable template
+├── bin/
+│   └── mail_mcp           # CLI: `generate` (client_id) and `server` (puma)
+├── config.ru              # Rack entry point — run MailMCP::App.new
+├── config/
+│   └── puma.rb            # Puma config (single worker, 5 threads)
+├── lib/
+│   ├── mail_mcp.rb        # Module root + requires
+│   └── mail_mcp/
+│       ├── jwt_service.rb         # All JWE tokens (access, refresh, client_id)
+│       ├── pkce.rb                # PKCE S256 challenge/verify
+│       ├── credential_context.rb  # Struct passed as MCP server_context per request
+│       ├── imap_client.rb         # net-imap wrapper
+│       ├── smtp_client.rb         # net-smtp wrapper
+│       ├── attachment_store.rb    # S3 upload + presigned URLs (7 days)
+│       ├── tool.rb                # MailMCP::Tool base class
+│       ├── app.rb                 # Sinatra: OAuth + MCP /mcp route (all methods)
+│       └── tools/*.rb             # MCP tool classes
+├── views/
+│   └── login.erb          # Login form (username + password only)
+├── spec/                  # RSpec test suite
+└── Dockerfile
+```
+
+## Configuration
+
+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` |
+
+Generate `ENCRYPTION_KEY`:
+```bash
+ruby -e "require 'base64','securerandom'; puts Base64.strict_encode64(SecureRandom.bytes(32))"
+```
+
+IMAP/SMTP host and port are embedded in the `client_id` JWE and are never passed as headers or query parameters.
+
+## Setup
+
+```bash
+# Install dependencies
+bundle install
+
+# Copy and edit environment variables
+cp .env.sample .env
+$EDITOR .env
+
+# Run tests
+bundle exec rspec
+
+# Start the server
+bundle exec puma -C config/puma.rb
+```
+
+## Provisioning a Client
+
+Run `bin/mail_mcp generate` once per mail server configuration. The resulting `client_id` and `client_secret` are configured in the MCP client (e.g. Claude Desktop).
+
+```bash
+bundle exec bin/mail_mcp generate \
+  --imap-host=imap.gmail.com \
+  --imap-port=993 \
+  --smtp-host=smtp.gmail.com \
+  --smtp-port=587
+
+#   Client ID:     eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0...<encrypted>
+#   Client Secret: 713576e2f94802b9d9abfd755e38e29b63e491df...
+#
+#   IMAP: imap.gmail.com:993 (ssl=true)
+#   SMTP: smtp.gmail.com:587 (ssl=false)
+```
+
+| 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 |
+
+## OAuth 2.1 Flow
+
+1. **Discovery** — client fetches `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`
+2. **Authorization** — client redirects user to `/oauth/authorize?client_id=<jwe>&code_challenge=<s256>&...`
+3. **Login** — server decrypts `client_id` JWE to get IMAP/SMTP hosts; user enters credentials; server validates both connections live
+4. **Code exchange** — `POST /oauth/token` with `grant_type=authorization_code`, `code`, `code_verifier`, `client_id`, `client_secret`; server issues `access_token` + `refresh_token`
+5. **Token refresh** — `POST /oauth/token` with `grant_type=refresh_token`, `refresh_token`, `client_id`, `client_secret`; server issues a new `access_token` + `refresh_token`
+6. **MCP calls** — client sends `Authorization: Bearer <access_token>` on every request; server decrypts credentials per-request via a stateless per-request MCP server
+
+## 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` |
+
+Attachments are never returned as binary data — they are uploaded to S3 on first access and returned as presigned URLs valid for 7 days.
+
+## Docker
+
+```bash
+docker build -t mail_mcp .
+docker run -p 3000:3000 --env-file .env mail_mcp
+```

data/bin/mail_mcp

@@ -0,0 +1,113 @@
+#!/usr/bin/env ruby
+require "optparse"
+
+COMMANDS = {
+  "generate" => "Generate a new client_id and client_secret",
+  "server" => "Start the MCP server (puma)"
+}.freeze
+
+def print_usage
+  warn "Usage: mail_mcp <command> [options]"
+  warn ""
+  warn "Commands:"
+  COMMANDS.each { |name, desc| warn format("  %-10<name>s %<desc>s", name: name, desc: desc) }
+  warn ""
+  warn "Run `mail_mcp <command> --help` for command-specific options."
+end
+
+def load_app_env
+  if ENV["RACK_ENV"] != "production"
+    require "dotenv"
+    Dotenv.load(File.expand_path("../.env", __dir__))
+  end
+  require_relative "../lib/mail_mcp"
+end
+
+def generate_option_parser(options)
+  OptionParser.new do |opts|
+    opts.banner = "Usage: mail_mcp generate [options]"
+    opts.separator ""
+    opts.separator "Required:"
+    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.separator ""
+    opts.separator "Optional:"
+    opts.on("--[no-]imap-ssl",    "Enable SSL/TLS for IMAP (default: true when port 993)")
+    opts.on("--[no-]smtp-ssl",    "Enable SSL/TLS for SMTP (default: true when port 465)")
+    opts.separator ""
+    opts.on("-h", "--help", "Show this help") do
+      puts opts
+      exit
+    end
+    opts.parse!(ARGV, into: options)
+  end
+end
+
+def normalize_generate_options(options, parser)
+  imap_host = options[:"imap-host"]
+  smtp_host = options[:"smtp-host"]
+  unless imap_host && smtp_host
+    warn "Error: --imap-host and --smtp-host are required"
+    warn ""
+    warn parser
+    exit 1
+  end
+
+  imap_port = options[:"imap-port"] || 993
+  smtp_port = options[:"smtp-port"] || 587
+  {
+    imap_host: imap_host,
+    imap_port: imap_port,
+    imap_ssl: options.fetch(:"imap-ssl", imap_port == 993),
+    smtp_host: smtp_host,
+    smtp_port: smtp_port,
+    smtp_ssl: options.fetch(:"smtp-ssl", smtp_port == 465)
+  }
+end
+
+def print_generated_client(opts, client_id, client_secret)
+  puts ""
+  puts "  Client ID:     #{client_id}"
+  puts "  Client Secret: #{client_secret}"
+  puts ""
+  puts "  IMAP: #{opts[:imap_host]}:#{opts[:imap_port]} (ssl=#{opts[:imap_ssl]})"
+  puts "  SMTP: #{opts[:smtp_host]}:#{opts[:smtp_port]} (ssl=#{opts[:smtp_ssl]})"
+  puts ""
+end
+
+def run_generate
+  load_app_env
+  options = {}
+  parser = generate_option_parser(options)
+  opts = normalize_generate_options(options, parser)
+
+  client_secret = SecureRandom.hex(32)
+  client_id = MailMCP::JwtService.issue_client_id(**opts, client_secret: client_secret)
+  print_generated_client(opts, client_id, client_secret)
+end
+
+def run_server(argv)
+  require "puma/cli"
+  config = File.expand_path("../config/puma.rb", __dir__)
+  rackup = File.expand_path("../config.ru", __dir__)
+  Puma::CLI.new(["-C", config, rackup, *argv]).run
+end
+
+command = ARGV.shift
+
+case command
+when "generate"
+  run_generate
+when "server"
+  run_server(ARGV)
+when "-h", "--help", nil
+  print_usage
+  exit(command.nil? ? 1 : 0)
+else
+  warn "Unknown command: #{command}"
+  warn ""
+  print_usage
+  exit 1
+end

data/config/puma.rb

@@ -0,0 +1,8 @@
+port        ENV.fetch("PORT", 3000)
+environment ENV.fetch("RACK_ENV", "development")
+
+# StreamableHTTPTransport requires a single worker (sessions are in-memory)
+workers 0
+threads 1, 5
+
+preload_app!

data/config.ru

@@ -0,0 +1,8 @@
+if ENV["RACK_ENV"] != "production"
+  require "dotenv"
+  Dotenv.load
+end
+
+require_relative "lib/mail_mcp"
+
+run MailMCP::App.new

data/lib/mail_mcp/app.rb

@@ -0,0 +1,281 @@
+require "sinatra/base"
+require "sinatra/json"
+require "sinatra/multi_route"
+require "mcp"
+require "uri"
+
+module MailMCP
+  class App < Sinatra::Base
+    register Sinatra::MultiRoute
+
+    set :views, File.expand_path("../../views", __dir__)
+    set :public_folder, false
+    set :logging, true
+
+    MCP_TOOLS = [
+      ListMailboxesTool,
+      ListMailMessagesTool,
+      GetMailMessageTool,
+      SearchMailMessagesTool,
+      SendMailMessageTool,
+      CreateDraftMailMessageTool,
+      DeleteMailMessageTool,
+      MoveMailMessageTool,
+      UpdateMailMessageFlagsTool
+    ].freeze
+
+    # ── MCP ──────────────────────────────────────────────────────────────────
+
+    route :head, :delete, :get, :options, :patch, :post, :put, "/mcp" do
+      server_context, error_response = resolve_mcp_context
+      halt(*error_response) if error_response
+
+      mcp_server = MCP::Server.new(
+        name: "mail_mcp",
+        version: "1.0.0",
+        description: "IMAP and SMTP mail server for AI agents",
+        tools: MCP_TOOLS,
+        server_context: server_context
+      )
+      transport = MCP::Server::Transports::StreamableHTTPTransport.new(mcp_server, stateless: true)
+      status_code, resp_headers, body = transport.call(env)
+      halt status_code, resp_headers, body
+    end
+
+    # ── OAuth 2.1 Discovery ───────────────────────────────────────────────────
+
+    get "/.well-known/oauth-protected-resource" do
+      content_type :json
+      JSON.generate({
+                      resource: base_url,
+                      authorization_servers: [base_url]
+                    })
+    end
+
+    get "/.well-known/oauth-authorization-server" do
+      content_type :json
+      JSON.generate({
+                      issuer: base_url,
+                      authorization_endpoint: "#{base_url}/oauth/authorize",
+                      token_endpoint: "#{base_url}/oauth/token",
+                      response_types_supported: ["code"],
+                      grant_types_supported: ["authorization_code"],
+                      code_challenge_methods_supported: ["S256"]
+                    })
+    end
+
+    # ── Authorization (Login UI) ──────────────────────────────────────────────
+
+    get "/oauth/authorize" do
+      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
+      }
+      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)
+      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
+      }
+
+      code = JwtService.issue_code(
+        creds: creds,
+        code_challenge: code_challenge,
+        redirect_uri: redirect_uri,
+        client_id: client_id
+      )
+
+      redirect_to = URI.parse(redirect_uri)
+      query = URI.decode_www_form(redirect_to.query.to_s)
+      query << ["code", code]
+      query << ["state", state] if state
+      redirect_to.query = URI.encode_www_form(query)
+      redirect redirect_to.to_s
+    end
+
+    # ── Token Exchange ────────────────────────────────────────────────────────
+
+    post "/oauth/token" do
+      content_type :json
+
+      grant_type    = params[:grant_type]
+      client_id     = params[:client_id]
+      client_secret = params[:client_secret]
+
+      client_config = begin
+        JwtService.decode_client_id(client_id.to_s)
+      rescue JwtService::Error
+        halt 401, JSON.generate({ error: "invalid_client", error_description: "Invalid client_id" })
+      end
+
+      unless client_secret.to_s == client_config["cs"]
+        halt 401, JSON.generate({ error: "invalid_client", error_description: "Invalid client_secret" })
+      end
+
+      creds = case grant_type
+              when "authorization_code"
+                exchange_code(params, client_id)
+              when "refresh_token"
+                exchange_refresh_token(params[:refresh_token])
+              else
+                halt 400, JSON.generate({ error: "unsupported_grant_type" })
+              end
+
+      token_response(creds)
+    end
+
+    # ── Health ────────────────────────────────────────────────────────────────
+
+    get "/health" do
+      content_type :json
+      JSON.generate({ status: "ok" })
+    end
+
+    not_found do
+      content_type :json
+      JSON.generate({ error: "not_found" })
+    end
+
+    private
+
+    def resolve_mcp_context
+      auth = request.env["HTTP_AUTHORIZATION"]
+      return [nil, nil] unless auth&.start_with?("Bearer ")
+
+      creds = JwtService.verify(auth[7..])
+      context = CredentialContext.new(
+        imap_config: {
+          host: creds["imap_host"], port: creds["imap_port"].to_i,
+          ssl: creds["imap_ssl"], username: creds["imap_username"], password: creds["imap_password"]
+        },
+        smtp_config: {
+          host: creds["smtp_host"], port: creds["smtp_port"].to_i,
+          ssl: creds["smtp_ssl"], username: creds["smtp_username"], password: creds["smtp_password"]
+        }
+      )
+      [context, nil]
+    rescue JwtService::Error => e
+      error = [
+        401,
+        { "Content-Type" => "application/json", "WWW-Authenticate" => mcp_www_authenticate },
+        [JSON.generate({ error: "invalid_token", error_description: e.message })]
+      ]
+      [nil, error]
+    end
+
+    def exchange_code(params, client_id)
+      code          = params[:code]
+      code_verifier = params[:code_verifier]
+      redirect_uri  = params[:redirect_uri]
+
+      payload = begin
+        JwtService.verify_code(code.to_s)
+      rescue JwtService::Error => e
+        halt 400, JSON.generate({ error: "invalid_grant", error_description: e.message })
+      end
+
+      if payload["redirect_uri"] != redirect_uri
+        halt 400,
+             JSON.generate({ error: "invalid_grant",
+                             error_description: "redirect_uri mismatch" })
+      end
+      halt 400, JSON.generate({ error: "invalid_client" }) if payload["client_id"] != client_id
+      unless Pkce.valid?(verifier: code_verifier.to_s, challenge: payload["code_challenge"].to_s)
+        halt 400, JSON.generate({ error: "invalid_grant", error_description: "PKCE verification failed" })
+      end
+
+      payload.slice(*JwtService::CRED_KEYS)
+    end
+
+    def exchange_refresh_token(refresh_token)
+      JwtService.verify_refresh(refresh_token.to_s)
+    rescue JwtService::Error => e
+      halt 400, JSON.generate({ error: "invalid_grant", error_description: e.message })
+    end
+
+    def token_response(creds)
+      JSON.generate({
+                      access_token: JwtService.issue(creds),
+                      refresh_token: JwtService.issue_refresh(creds),
+                      token_type: "Bearer",
+                      expires_in: JwtService::DEFAULT_EXPIRY
+                    })
+    end
+
+    def mcp_www_authenticate
+      "Bearer resource_metadata=\"#{base_url}/.well-known/oauth-protected-resource\""
+    end
+
+    def base_url
+      ENV.fetch("BASE_URL")
+    end
+
+    def decode_client_id!(client_id)
+      JwtService.decode_client_id(client_id.to_s)
+    rescue JwtService::Error => e
+      halt 400, "Invalid client_id: #{e.message}"
+      nil
+    end
+  end
+end

data/lib/mail_mcp/attachment_store.rb

@@ -0,0 +1,32 @@
+require "aws-sdk-s3"
+require "securerandom"
+
+module MailMCP
+  module AttachmentStore
+    EXPIRY = 7 * 24 * 3600
+
+    def self.upload(content:, filename:, content_type:)
+      key = "attachments/#{SecureRandom.uuid}/#{filename}"
+      bucket = ENV.fetch("AWS_S3_BUCKET")
+
+      s3.put_object(
+        bucket: bucket,
+        key: key,
+        body: content,
+        content_type: content_type
+      )
+
+      presigner.presigned_url(:get_object, bucket: bucket, key: key, expires_in: EXPIRY)
+    end
+
+    def self.s3
+      Aws::S3::Client.new
+    end
+    private_class_method :s3
+
+    def self.presigner
+      Aws::S3::Presigner.new(client: s3)
+    end
+    private_class_method :presigner
+  end
+end

data/lib/mail_mcp/credential_context.rb

@@ -0,0 +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)
+end