@marlinjai/email-mcp 1.4.4 → 1.7.0

package/README.md

@@ -62,11 +62,19 @@ No configuration needed — the setup wizard handles everything using built-in O
 ```bash
 npx -y -p @marlinjai/email-mcp@latest email-mcp-setup
 # Select "Gmail" when prompted
+# Choose "Full" or "Restricted" permission scope when asked
 # A browser window opens for Google authorization
 # Grant the requested permissions and return to the terminal
 ```
 
-> **Note:** If you prefer to use your own OAuth app, create a Desktop OAuth 2.0 Client in the [Google Cloud Console](https://console.cloud.google.com/) with the Gmail API enabled.
+The wizard asks which Gmail permission scope to authorize:
+
+- **Full** (default) — everything below, plus immediate, Trash-bypassing permanent deletion (`https://mail.google.com/`, Gmail's maximum-permission scope).
+- **Restricted** — read, send, label, archive, and move-to-trash (`gmail.modify` + `gmail.settings.basic`), but no permanent deletion. Every tool in this server works identically under Restricted except an explicit `permanent: true` delete, which fails with a Gmail API error instead of succeeding.
+
+Pass `--scope full` or `--scope restricted` to skip the prompt, or set `EMAIL_MCP_GMAIL_SCOPE=restricted` in the environment the wizard runs in.
+
+> **Note:** If you prefer to use your own OAuth app instead of the shared one this package ships with, create a Desktop OAuth 2.0 Client in the [Google Cloud Console](https://console.cloud.google.com/) with the Gmail API enabled, then set `EMAIL_MCP_GMAIL_CLIENT_ID` and `EMAIL_MCP_GMAIL_CLIENT_SECRET` in the environment before running the setup wizard (and in the MCP server's environment, since re-authentication uses the same variables). This gives you your own token lifecycle, independent of the publisher's Cloud project, and sidesteps Google's unverified-app warning and 100-test-user cap for your own account(s) once you add yourself as a test user on your own app.
 
 ### Outlook
 
@@ -79,7 +87,7 @@ npx -y -p @marlinjai/email-mcp@latest email-mcp-setup
 # Sign in and grant the requested permissions
 ```
 
-> **Note:** If you prefer to use your own OAuth app, register one in the [Azure Portal](https://portal.azure.com/) with `Mail.ReadWrite`, `Mail.Send`, `MailboxSettings.ReadWrite` (needed for `email_create_block_rule`), and `offline_access` permissions.
+> **Note:** If you prefer to use your own OAuth app, register one in the [Azure Portal](https://portal.azure.com/) with `Mail.ReadWrite`, `Mail.Send`, `MailboxSettings.ReadWrite` (needed for `email_create_block_rule`), and `offline_access` permissions, then set `EMAIL_MCP_OUTLOOK_CLIENT_ID` in the environment before running the setup wizard.
 
 ### iCloud
 
@@ -105,7 +113,7 @@ npx -y -p @marlinjai/email-mcp@latest email-mcp-setup
 # Optionally enter SMTP host and port for sending
 ```
 
-## Available Tools (30)
+## Available Tools (32)
 
 ### Account Management (4)
 
@@ -116,7 +124,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,8 +133,9 @@ 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)
+### Sending & Drafts (6)
 
 | Tool | Description |
 |------|-------------|
@@ -134,6 +143,7 @@ npx -y -p @marlinjai/email-mcp@latest email-mcp-setup
 | `email_reply` | Reply to an email (supports reply-all, preserves threading) |
 | `email_forward` | Forward an email to new recipients |
 | `email_draft_create` | Save a draft without sending |
+| `email_draft_update` | Update an existing draft in place. On Gmail/Outlook the draft id is unchanged; on iCloud/generic IMAP there's no in-place update (IMAP messages are immutable), so the old draft is deleted and a new one appended — the returned id is a **new** id, always use it going forward |
 | `email_draft_list` | List all drafts |
 
 ### Organization (8)
@@ -217,6 +227,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: