hypermail-mcp 0.7.4 → 0.7.6

package/README.md

@@ -3,6 +3,18 @@
 A **Model Context Protocol** server that lets an agent operate any of the user's
 inboxes through a single, unified tool surface.
 
+> **v0.7.6** — Strict provider env var enforcement. Legacy env vars
+> (`MS_CLIENT_ID`, `MS_TENANT_ID`, `GOOGLE_CLIENT_ID`,
+> `GOOGLE_CLIENT_SECRET`) are unconditionally ignored; only the dedicated
+> `HYPERMAIL_PROVIDERS_*` names are resolved.
+>
+> **v0.7.5** — Attachments via file path on `send_email`/`draft_email`
+> (`attachments` param). `edit_draft` gains `new_attachments` and
+> `remove_attachments` — `add_attachment_to_draft` is removed (23 tools now).
+> Draft editing uses multi-strategy thread boundary detection for more reliable
+> quoted-thread preservation. Watcher now supports script emission (`runScript`)
+> alongside webhook delivery.
+>
 > **v0.7.4** — `inReplyTo` is now a required parameter on `send_email` and
 > `draft_email` (was optional). Set it to `false` for a new email, or pass a
 > message ID to thread a reply. This forces the agent to make an explicit choice
@@ -13,13 +25,8 @@ inboxes through a single, unified tool surface.
 > the entire content — including the quoted thread. Now only the answer part
 > (above the spacer delimiter) is replaced.
 >
-> **v0.7.2** — `add_attachment_to_draft` now accepts `filePath` (absolute path to
-a local file) as an alternative to `contentBytes`. The file is read from disk and
-base64-encoded automatically, the MIME type is inferred from the extension, and
-`name` defaults to the file's basename.
->> **v0.7.1** — Every config field is now settable via a dedicated
-> `HYPERMAIL_*` env var. Legacy env vars (`MS_CLIENT_ID`, `MS_TENANT_ID`,
-> `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`) still work as fallbacks. See
+> **v0.7.1** — Every config field is now settable via a dedicated
+> `HYPERMAIL_*` env var. Legacy provider env vars are no longer accepted. See
 > [Environment Variables](#environment-variables) for the full reference.
 >
 > **v0.7.0** — Email watch mode: background poll loop detects new inbox
@@ -117,8 +124,8 @@ docker run -d \
   --name hypermail-mcp \
   -p 3000:3000 \
   -e HYPERMAIL_MCP_KEY=<32-byte-key> \
-  -e MS_CLIENT_ID=<your-client-id> \
-  -e MS_TENANT_ID=<your-tenant-id> \
+  -e HYPERMAIL_PROVIDERS_OUTLOOK_CLIENT_ID=<your-client-id> \
+  -e HYPERMAIL_PROVIDERS_OUTLOOK_TENANT_ID=<your-tenant-id> \
   -v hypermail-data:/data \
   hypermail-mcp
 ```
@@ -148,8 +155,8 @@ The server listens on `http://127.0.0.1:3000/mcp`. Pi connects via the
 | --- | --- | --- |
 | `HYPERMAIL_MCP_DATA_DIR` | Where to keep the encrypted accounts blob | `~/.hypermail-mcp` |
 | `HYPERMAIL_MCP_KEY` | 32-byte AES-256-GCM key (hex, base64, or any passphrase — derived via SHA-256). Required for hosted deployments. Auto-generated for stdio. | auto-generated, stored via OS keychain (`keytar`) or a local `master.key` file |
-| `MS_CLIENT_ID` | Azure Entra public client (application) id used for device-code login | placeholder — **set your own for production** |
-| `MS_TENANT_ID` | Tenant for the authority URL | `common` |
+| `HYPERMAIL_PROVIDERS_OUTLOOK_CLIENT_ID` | Azure Entra public client (application) id used for device-code login | placeholder — **set your own for production** |
+| `HYPERMAIL_PROVIDERS_OUTLOOK_TENANT_ID` | Tenant for the authority URL | `common` |
 
 CLI flags: `--http`, `--port`, `--host`, `--data-dir`, `--read-only`, `--help`.
 
@@ -193,9 +200,10 @@ and read emails.
 
 Every config field can be set via a dedicated `HYPERMAIL_*` env var, following
 a dotted-path naming convention (`HYPERMAIL_HTTP_PORT`,
-`HYPERMAIL_PROVIDERS_OUTLOOK_CLIENT_ID`, etc.). Legacy env vars
-(`MS_CLIENT_ID`, `MS_TENANT_ID`, `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`)
-still work as fallbacks for backward compatibility.
+`HYPERMAIL_PROVIDERS_OUTLOOK_CLIENT_ID`, etc.). Legacy provider env vars such
+as `MS_CLIENT_ID`, `MS_TENANT_ID`, `GOOGLE_CLIENT_ID`, and
+`GOOGLE_CLIENT_SECRET` are ignored; use the `HYPERMAIL_PROVIDERS_*` names
+below.
 
 | Env var | Config path | Type |
 | --- | --- | --- |
@@ -213,6 +221,10 @@ still work as fallbacks for backward compatibility.
 | `HYPERMAIL_WATCH_WEBHOOK_URL` | `watch.webhook.url` | `string` |
 | `HYPERMAIL_WATCH_WEBHOOK_RETRY_MAX_ATTEMPTS` | `watch.webhook.retry.maxAttempts` | `int` |
 | `HYPERMAIL_WATCH_WEBHOOK_RETRY_BASE_DELAY_MS` | `watch.webhook.retry.baseDelayMs` | `int` |
+| `HYPERMAIL_WATCH_SCRIPT_COMMAND` | `watch.script.command` | `string` |
+| `HYPERMAIL_WATCH_SCRIPT_TIMEOUT_MS` | `watch.script.timeoutMs` | `int` |
+| `HYPERMAIL_WATCH_SCRIPT_RETRY_MAX_ATTEMPTS` | `watch.script.retry.maxAttempts` | `int` |
+| `HYPERMAIL_WATCH_SCRIPT_RETRY_BASE_DELAY_MS` | `watch.script.retry.baseDelayMs` | `int` |
 
 **Priority order:** CLI flags > config file > `HYPERMAIL_*` env var > hardcoded default.
 
@@ -237,11 +249,10 @@ account store.
 | `archive_email` | `account`, `id` | Move a message to the Archive folder. Disabled under `--read-only`. |
 | `trash_email` | `account`, `id` | Move a message to Deleted Items (trash). Disabled under `--read-only`. |
 | `move_email` | `account`, `id`, `destination` | Move to any folder by well-known name (`inbox`, `drafts`, etc.) or custom folder ID. Disabled under `--read-only`. |
-| `send_email` | `account`, `to[]`, `cc?`, `bcc?`, `subject`, `body`, `format`, `include_signature`, `inReplyTo`, `replyAll?`, `forwardMessageId?` | Send an email. `format` (`"html"` or `"markdown"`) controls body format — Markdown is converted to HTML via `marked`. Appends signature when `include_signature` is true. `inReplyTo` sends as threaded reply; `forwardMessageId` sends as forward. `inReplyTo` is required — set to `false` for new emails. Disabled under `--read-only`. |
-| `draft_email` | `account`, `to[]`, `cc?`, `bcc?`, `subject`, `body`, `format`, `include_signature`, `inReplyTo`, `replyAll?`, `forwardMessageId?` | Save as draft instead of sending. `format` (`"html"` or `"markdown"`) controls body format — Markdown is converted to HTML via `marked`. Returns the draft message ID and HTML body (`draftHtml`). `inReplyTo` is required — set to `false` for new emails. Disabled under `--read-only`. |
-| `edit_draft` | `account`, `id`, `to?`, `cc?`, `bcc?`, `subject?`, `body?`, `format?`, `include_signature?` | Edit an existing draft by ID. Only provided fields are updated. `format` only meaningful when `body` is provided. Returns the updated draft ID and HTML body (`draftHtml`). Disabled under `--read-only`. |
+| `send_email` | `account`, `to[]`, `cc?`, `bcc?`, `subject`, `body`, `format`, `include_signature`, `inReplyTo`, `replyAll?`, `forwardMessageId?`, `attachments?` | Send an email. `format` (`"html"` or `"markdown"`) controls body format — Markdown is converted to HTML via `marked`. Appends signature when `include_signature` is true. `inReplyTo` sends as threaded reply; `forwardMessageId` sends as forward. `inReplyTo` is required — set to `false` for new emails. `attachments` is an optional array of `{filePath, name?}` — files are read from disk and encoded automatically. Disabled under `--read-only`. |
+| `draft_email` | `account`, `to[]`, `cc?`, `bcc?`, `subject`, `body`, `format`, `include_signature`, `inReplyTo`, `replyAll?`, `forwardMessageId?`, `attachments?` | Save as draft instead of sending. Same params as `send_email` including `attachments`. Returns the draft message ID and HTML body (`draftHtml`). `inReplyTo` is required — set to `false` for new emails. Disabled under `--read-only`. |
+| `edit_draft` | `account`, `id`, `to?`, `cc?`, `bcc?`, `subject?`, `body?`, `format?`, `include_signature?`, `new_attachments?`, `remove_attachments?` | Edit an existing draft by ID. Only provided fields are updated. `new_attachments` adds files (`{filePath, name?}[]`); `remove_attachments` removes by attachment ID (`string[]`). Returns the updated draft ID, HTML body (`draftHtml`), and attachment metadata. Disabled under `--read-only`. |
 | `send_draft` | `account`, `id` | Send an existing draft email by ID. Use with draft IDs returned by `draft_email` or `edit_draft`. Disabled under `--read-only`. |
-| `add_attachment_to_draft` | `account`, `id`, `name?`, `contentBytes?`, `filePath?`, `contentType?` | Attach a file to an existing draft by ID. Provide `contentBytes` (base64) or `filePath` (absolute path — auto-encodes). Disabled under `--read-only`. |
 | `list_folders` | `account`, `parentFolderId?` | List available mail folders. Returns top-level folders by default, or children of `parentFolderId`. |
 | `create_folder` | `account`, `displayName`, `parentFolderId?` | Create a new mail folder under root (default) or the given parent. Disabled under `--read-only`. |
 | `delete_folder` | `account`, `folderId` | Delete a mail folder by ID. Disabled under `--read-only`. |
@@ -252,9 +263,9 @@ account store.
 ## Email Watch
 
 When enabled, hypermail-mcp runs a background poll loop that scans inboxes for
-new messages and POSTs each one to a configurable webhook URL. Intended for
-push-based email triage — downstream agents (e.g. Mastra) receive full email
-content without polling.
+new messages and delivers each one via webhook POST and/or script execution.
+Intended for push-based email triage — downstream agents (e.g. Mastra) receive
+full email content without polling.
 
 ```jsonc
 {
@@ -264,6 +275,11 @@ content without polling.
     "webhook": {
       "url": "http://localhost:3000/api/email-webhook",
       "retry": { "maxAttempts": 5, "baseDelayMs": 1000 }
+    },
+    "script": {
+      "command": "node /path/to/email-handler.js",
+      "timeoutMs": 30000,
+      "retry": { "maxAttempts": 3, "baseDelayMs": 1000 }
     }
   }
 }
@@ -276,16 +292,25 @@ content without polling.
 | `watch.webhook.url` | — | Endpoint that receives `POST` with `EmailFull` JSON |
 | `watch.webhook.retry.maxAttempts` | `5` | Max delivery attempts (1–10) |
 | `watch.webhook.retry.baseDelayMs` | `1000` | Base backoff delay (× 2^attempt) |
+| `watch.script.command` | — | Shell command spawned with email JSON on stdin |
+| `watch.script.timeoutMs` | `30000` | Max script runtime before SIGKILL |
+| `watch.script.retry.maxAttempts` | `3` | Max script delivery attempts |
+| `watch.script.retry.baseDelayMs` | `1000` | Base backoff delay (× 2^attempt) |
 
 **Behavior:**
 - Polls **all accounts** in the store, **inbox only**.
 - Detects new emails via `lastSeenIds` (capped at 200) stored in the encrypted
   account file — no duplicate emits across restarts.
-- One `POST` per email (full body: subject, sender, text, HTML, attachments
-  metadata, thread ID via `EmailFull`).
-- Delivery uses exponential backoff (`baseDelay × 2^attempt`). Retries on
-  non-2xx responses and connection errors. Logs and moves on after
-  `maxAttempts` exhausted — never blocks the poll loop.
+- Two delivery modes (can be used together):
+  - **Webhook:** One `POST` per email (full body as `EmailFull` JSON).
+  - **Script:** Spawns a shell command with the `EmailFull` JSON piped to
+    stdin. The script receives `conversationId`, `subject`, `from`, `toRecipients`,
+    `body`, `isRead`, `sentDateTime`, `attachments`, plus an `account` field.
+- Both modes use exponential backoff (`baseDelay × 2^attempt`). Retries on
+  failures (non-2xx for webhook, non-zero exit for script). Logs and moves on
+  after `maxAttempts` exhausted — never blocks the poll loop.
+- Each delivery mode is fire-and-forget — the poll loop continues while
+  delivery runs in the background.
 - Works in both **stdio** and **HTTP** transport modes — the poll interval
   fires normally alongside MCP message handling.