hypermail-mcp 0.7.4 → 0.7.5

package/README.md

@@ -3,6 +3,13 @@
 A **Model Context Protocol** server that lets an agent operate any of the user's
 inboxes through a single, unified tool surface.
 
+> **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,11 +20,7 @@ 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
+> **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
 > [Environment Variables](#environment-variables) for the full reference.
@@ -213,6 +216,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 +244,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 +258,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 +270,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 +287,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.