@marlinjai/email-mcp 1.4.3 → 1.5.0

package/README.md

@@ -105,7 +105,7 @@ npx -y -p @marlinjai/email-mcp@latest email-mcp-setup
 # Optionally enter SMTP host and port for sending
 ```
 
-## Available Tools (30)
+## Available Tools (31)
 
 ### Account Management (4)
 
@@ -116,7 +116,7 @@ npx -y -p @marlinjai/email-mcp@latest email-mcp-setup
 | `email_remove_account` | Remove an account and its stored credentials |
 | `email_test_account` | Test connection to an account |
 
-### Reading & Searching (5)
+### Reading & Searching (6)
 
 | Tool | Description |
 |------|-------------|
@@ -125,6 +125,7 @@ npx -y -p @marlinjai/email-mcp@latest email-mcp-setup
 | `email_get` | Get full email content by ID (headers, body, attachment metadata) |
 | `email_get_thread` | Get an entire email thread/conversation |
 | `email_get_attachment` | Download a specific attachment by ID (returns base64 data) |
+| `email_save_attachment` | Download an attachment directly to disk, returning metadata only — avoids the token cost of round-tripping large files as base64. `outputPath` is relative to a fixed downloads directory (`~/.email-mcp/downloads`, override with `EMAIL_MCP_DOWNLOADS_DIR`) and cannot escape it |
 
 ### Sending & Drafts (5)
 
@@ -165,7 +166,7 @@ All batch tools accept a `sourceFolder` parameter for IMAP/iCloud and include a
 |------|-------------|
 | `email_report_spam` | Report an email as spam/junk, training the provider's own filter — the same signal the "Report Junk" button sends in Gmail/Outlook. This is different from `email_delete`, which removes the message but teaches the filter nothing. **Not** an abuse report to the provider's security team; it only trains this account's filter |
 | `email_batch_report_spam` | Report multiple emails as spam/junk at once |
-| `email_create_block_rule` | Create a standing rule that intercepts future mail matching a pattern (sender domain/address, subject, or arbitrary header content) and either deletes it or files it straight to Junk. Use `headerContains` (e.g. a Reply-To domain) to block a spam template family whose visible "From" domain rotates — matching the rotating domain directly stops working within days. **Not supported on iCloud/generic IMAP** (no standard server-side rule mechanism exists across IMAP servers). On Outlook, requires the `MailboxSettings.ReadWrite` scope — accounts authenticated before this tool existed need to re-run the setup wizard once to re-consent |
+| `email_create_block_rule` | Create a standing rule that intercepts future mail matching a pattern (sender domain/address, subject, or arbitrary header content) and either deletes it or moves it. Use `headerContains` (e.g. a Reply-To domain) to block a spam template family whose visible "From" domain rotates — matching the rotating domain directly stops working within days. **Not supported on iCloud/generic IMAP** (no standard server-side rule mechanism exists across IMAP servers). On Outlook, `moveToJunk` files straight to the Junk Email folder and requires the `MailboxSettings.ReadWrite` scope. On Gmail, `moveToJunk` skips the inbox (archives) rather than literally filing to Spam — Gmail's filter API rejects the SPAM label on standing rules (only Gmail's own classifier can apply it; `email_report_spam` still can, since that's a direct per-message action, not a filter) — and requires the `gmail.settings.basic` scope. Accounts authenticated before these scopes existed need to re-run the setup wizard once to re-consent |
 | `email_list_block_rules` | List the standing block rules on an account, for auditing or before deleting one |
 | `email_delete_block_rule` | Delete a standing block rule — use to undo a rule that turned out too broad |
 
@@ -217,6 +218,25 @@ pnpm test:watch
 pnpm test:integration
 ```
 
+## Credential Storage
+
+Account credentials are encrypted at rest with AES-256-GCM in `~/.email-mcp/credentials.enc`.
+
+By default the encryption key is derived from a stable, machine-specific identifier
+(the hardware UUID on macOS, `/etc/machine-id` on Linux, or the `MachineGuid` on
+Windows), falling back to the hostname when none is available.
+
+Set the `EMAIL_MCP_KEY` environment variable to supply your own passphrase instead.
+This is recommended when the machine identifier may change (for example in
+containers or CI), or when you want to move `credentials.enc` between machines:
+
+```bash
+export EMAIL_MCP_KEY="your-strong-passphrase"
+```
+
+When `EMAIL_MCP_KEY` is set, existing credential files are transparently
+re-encrypted with the passphrase the next time they are read.
+
 ## Support
 
 If this project is useful to you, consider supporting its development: