hypermail-mcp 0.7.6 → 0.7.8

package/README.md

@@ -3,17 +3,29 @@
 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.8** — Default Gmail loopback redirect URI changed from random-port
+> `/oauth2callback` to fixed `http://127.0.0.1:33333/callback` (still overridable via
+> `HYPERMAIL_GMAIL_REDIRECT_URI`). `.data/` encryption key directory added to
+> `.gitignore`.
+>
+> **v0.7.7** — Env-only configuration. Runtime config now comes from flat
+> `HYPERMAIL_*` environment variables plus selected CLI overrides. Config files
+> and legacy provider env names are no longer read. Hosted Gmail OAuth callbacks
+> are supported via `HYPERMAIL_GMAIL_REDIRECT_URI`; local loopback and manual
+> completion still work.
+>
+> **v0.7.6** — Gmail setup uses OAuth authorization URLs instead of Google's
+> rejected device-code flow for Gmail API scopes. `complete_add_account` accepts
+> a final redirected URL or raw `code`/`state`, and provider credentials use
+> dedicated `HYPERMAIL_GMAIL_*` / `HYPERMAIL_OUTLOOK_*` env vars.
 >
 > **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.
+> quoted-thread preservation. Watcher now supports shell-command notification
+> alongside webhook delivery. Published CLI installs the MCP SDK dependency so
+> global/npx runs do not fail on a missing SDK module.
 >
 > **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
@@ -31,7 +43,7 @@ inboxes through a single, unified tool surface.
 >
 > **v0.7.0** — Email watch mode: background poll loop detects new inbox
 > messages and POSTs them to a configurable webhook URL (e.g. Mastra). Opt-in —
-> disabled by default, enabled via `HYPERMAIL_WATCH_ENABLED=true` or config.
+> disabled by default, enabled via `HYPERMAIL_WATCH_ENABLED=true`.
 > Works in both stdio and HTTP transport modes.
 >
 > **v0.6.3** — Unify stdio and HTTP modes into a single feature set. Removed
@@ -58,13 +70,14 @@ inboxes through a single, unified tool surface.
 > union output schemas that caused `validateToolOutput` crashes.
 
 The agent doesn't care whether an address is a work Outlook account, a personal
-Microsoft account, or (soon) a personal IMAP mailbox — it just calls
+Microsoft account, a personal IMAP mailbox, or Gmail — it just calls
 `list_emails`, `search_emails`, `read_email`, `send_email` and passes the email
 address as the `account` argument. The server routes to the right backend.
 
 **v1 status:** Outlook / Microsoft 365 (personal + work) fully supported via
 Microsoft Graph. IMAP (any IMAP server) supported via `imapflow` + `nodemailer`.
-Gmail supported via Google OAuth device-code flow.
+Gmail supported via Google OAuth authorization-code flow with local loopback or
+hosted callbacks plus remote-safe manual completion.
 
 ## Why
 
@@ -110,8 +123,8 @@ hypermail-mcp --http --port 3000 --host 0.0.0.0
 # endpoint: http://<host>:3000/mcp  (Streamable HTTP transport, session-aware)
 ```
 
-When hosted you **must** set `HYPERMAIL_MCP_KEY` so the account file is
-reproducibly decryptable.
+When hosted, set `HYPERMAIL_KEY` so the account file is reproducibly
+decryptable across restarts and redeploys.
 
 ### Docker
 
@@ -120,18 +133,20 @@ reproducibly decryptable.
 docker build -t hypermail-mcp .
 
 # Run
+# Pass secret values from your shell or deployment environment; do not commit them.
 docker run -d \
   --name hypermail-mcp \
   -p 3000:3000 \
-  -e HYPERMAIL_MCP_KEY=<32-byte-key> \
-  -e HYPERMAIL_PROVIDERS_OUTLOOK_CLIENT_ID=<your-client-id> \
-  -e HYPERMAIL_PROVIDERS_OUTLOOK_TENANT_ID=<your-tenant-id> \
-  -v hypermail-data:/data \
+  -e HYPERMAIL_KEY \
+  -e HYPERMAIL_OUTLOOK_CLIENT_ID \
+  -e HYPERMAIL_OUTLOOK_TENANT_ID \
+  -v hypermail-data:/var/lib/mcp \
   hypermail-mcp
 ```
 
 The image runs the server in HTTP mode on port 3000 with a 30-second
-HEALTHCHECK against `/mcp`. Data is persisted via a Docker volume at `/data`.
+HEALTHCHECK against `/mcp`. Data is persisted via a Docker volume at
+`/var/lib/mcp`.
 
 ### Development
 
@@ -141,92 +156,81 @@ To test the HTTP server locally:
 # Terminal 1: auto-rebuild TypeScript on save
 pnpm dev
 
-# Terminal 2: start HTTP server with dev config
+# Terminal 2: start HTTP server with env/CLI config
 pnpm dev:http
 ```
 
-The server listens on `http://127.0.0.1:3000/mcp`. Pi connects via the
-`.pi/mcp.json` config (read by `pi-mcp-adapter`). Tools appear as
-`hypermail_http_*`.
+The server listens on `http://127.0.0.1:3000/mcp`.
 
-## Add-account flow (Outlook)
+## Runtime and provider configuration
 
-| Env var | Purpose | Default |
-| --- | --- | --- |
-| `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 |
-| `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` |
+Hypermail uses flat `HYPERMAIL_*` environment variables as the source of truth.
+There is no runtime config file. CLI flags only override transport, host, port,
+and data directory for a single invocation.
 
-CLI flags: `--http`, `--port`, `--host`, `--data-dir`, `--read-only`, `--help`.
+CLI flags: `--http`, `--port`, `--host`, `--data-dir`, `--help`.
 
-Subcommands: `hypermail-mcp generate-key` — generate an `hm_sk_` API key.
+Subcommands: `hypermail-mcp generate-key` — generate a base64 32-byte key for
+`HYPERMAIL_KEY`.
 
-### Configuration
+### Local CLI / env example
+
+```bash
+export HYPERMAIL_KEY="$(hypermail-mcp generate-key)"
+export HYPERMAIL_DATA_DIR="$HOME/.local/share/hypermail-mcp"
+export HYPERMAIL_OUTLOOK_CLIENT_ID="<your-client-id>"
+hypermail-mcp
+```
 
-Instead of (or in addition to) CLI flags and env vars, you can configure the
-server with a `hypermail-config.json` file next to the server binary. The server
-looks for it in the same directory as `cli.js`.
+### Generic MCP client JSON example
 
 ```jsonc
 {
-  "http": { "enabled": true, "port": 3000, "host": "0.0.0.0" },
-  "dataDir": "/path/to/data",
-  "tools": {
-    // allowlist: only these tools are registered
-    "enabled": ["list_emails", "search_emails", "read_email", "send_email"],
-    // blocklist: these tools are NOT registered
-    // "disabled": ["add_account", "remove_account"]
-  },
-  "providers": {
-    "outlook": { "clientId": "...", "tenantId": "..." }
-  },
-  "watch": {
-    "enabled": true,
-    "pollIntervalSeconds": 10,
-    "webhook": {
-      "url": "http://your-agent:3000/api/email-webhook",
-      "retry": { "maxAttempts": 5, "baseDelayMs": 1000 }
+  "mcpServers": {
+    "hypermail": {
+      "command": "npx",
+      "args": ["-y", "hypermail-mcp"],
+      "env": {
+        "HYPERMAIL_KEY": "${HYPERMAIL_KEY}",
+        "HYPERMAIL_DATA_DIR": "${HYPERMAIL_DATA_DIR}",
+        "HYPERMAIL_OUTLOOK_CLIENT_ID": "${HYPERMAIL_OUTLOOK_CLIENT_ID}"
+      }
     }
   }
 }
 ```
 
-Per-tool filtering (`tools.enabled` / `tools.disabled`) lets operators ship
-minimal agent-facing surfaces — e.g. a read-only assistant that can only list
-and read emails.
-
-## Environment Variables
-
-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 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.
+### Environment Variables
 
-| Env var | Config path | Type |
+| Env var | Purpose | Default / behavior |
 | --- | --- | --- |
-| `HYPERMAIL_HTTP_ENABLED` | `http.enabled` | `bool` |
-| `HYPERMAIL_HTTP_PORT` | `http.port` | `int` |
-| `HYPERMAIL_HTTP_HOST` | `http.host` | `string` |
-| `HYPERMAIL_TOOLS_ENABLED` | `tools.enabled` | comma-sep strings |
-| `HYPERMAIL_TOOLS_DISABLED` | `tools.disabled` | comma-sep strings |
-| `HYPERMAIL_PROVIDERS_OUTLOOK_CLIENT_ID` | `providers.outlook.clientId` | `string` |
-| `HYPERMAIL_PROVIDERS_OUTLOOK_TENANT_ID` | `providers.outlook.tenantId` | `string` |
-| `HYPERMAIL_PROVIDERS_GMAIL_CLIENT_ID` | `providers.gmail.clientId` | `string` |
-| `HYPERMAIL_PROVIDERS_GMAIL_CLIENT_SECRET` | `providers.gmail.clientSecret` | `string` |
-| `HYPERMAIL_WATCH_ENABLED` | `watch.enabled` | `bool` |
-| `HYPERMAIL_WATCH_POLL_INTERVAL` | `watch.pollIntervalSeconds` | `int` |
-| `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.
+| `HYPERMAIL_DATA_DIR` | Account/token store location | `${XDG_DATA_HOME:-~/.local/share}/hypermail-mcp` |
+| `HYPERMAIL_KEY` | 32-byte AES-256-GCM key as hex/base64, or any passphrase derived via SHA-256 | If unset, generates and persists a local key and prints a startup warning |
+| `HYPERMAIL_TRANSPORT` | Runtime transport: `stdio` or `http` | `stdio`; `--http` overrides to `http` |
+| `HYPERMAIL_HTTP_PORT` | HTTP bind port | `3000`; invalid HTTP-mode values warn and fall back |
+| `HYPERMAIL_HTTP_HOST` | HTTP bind host | `127.0.0.1`; invalid HTTP-mode values warn and fall back |
+| `HYPERMAIL_OUTLOOK_CLIENT_ID` | Optional custom Azure/Entra public client ID | Built-in public client |
+| `HYPERMAIL_OUTLOOK_TENANT_ID` | Optional Outlook tenant/authority selector | `common` |
+| `HYPERMAIL_GMAIL_CLIENT_ID` | Google OAuth client ID | Required when adding a Gmail account |
+| `HYPERMAIL_GMAIL_CLIENT_SECRET` | Google OAuth client secret, when issued by the client type | unset |
+| `HYPERMAIL_GMAIL_REDIRECT_URI` | Hosted Gmail OAuth callback URI | Local loopback callback when unset |
+| `HYPERMAIL_TOOLS_ENABLED` | Comma-separated tool allowlist | Empty/unset means no filtering |
+| `HYPERMAIL_TOOLS_DISABLED` | Comma-separated tool blocklist | Empty/unset means no filtering |
+| `HYPERMAIL_WATCH_ENABLED` | Enable inbox polling: `true` or `false` | `false` |
+| `HYPERMAIL_WATCH_POLL_SECONDS` | Watcher polling cadence | `10` |
+| `HYPERMAIL_WATCH_WEBHOOK_URL` | Webhook delivery target | Required if watch is enabled and no notify command is set |
+| `HYPERMAIL_WATCH_WEBHOOK_RETRY_ATTEMPTS` | Webhook retry attempts | `5` |
+| `HYPERMAIL_WATCH_WEBHOOK_RETRY_DELAY_MS` | Webhook exponential-backoff base delay | `1000` |
+| `HYPERMAIL_WATCH_NOTIFY_COMMAND` | Shell command run with `EmailFull` JSON on stdin | Required if watch is enabled and no webhook is set |
+| `HYPERMAIL_WATCH_NOTIFY_TIMEOUT_MS` | Notify-command execution timeout | `30000` |
+| `HYPERMAIL_WATCH_NOTIFY_RETRY_ATTEMPTS` | Notify-command retry attempts | `5` |
+| `HYPERMAIL_WATCH_NOTIFY_RETRY_DELAY_MS` | Notify-command exponential-backoff base delay | `1000` |
+
+**Priority order:** selected CLI flags > `HYPERMAIL_*` env vars > hardcoded defaults.
+
+Per-tool filtering (`HYPERMAIL_TOOLS_ENABLED` / `HYPERMAIL_TOOLS_DISABLED`) lets
+operators ship minimal agent-facing surfaces. If both non-empty lists are set,
+or either list contains an unknown tool name, startup fails.
 
 ## Tools
 
@@ -237,65 +241,48 @@ account store.
 | Tool | Inputs | Notes |
 | --- | --- | --- |
 | `list_accounts` | — | Returns registered emails + provider, no secrets. |
-| `add_account` | `provider`, `email?`, `config?` | Starts device-code (Outlook). Returns `{handle, verification:{userCode, verificationUri, expiresAt}}`. |
-| `complete_add_account` | `provider`, `handle` | Returns `pending` / `ready` / `expired` / `error`. |
+| `add_account` | `provider`, `email?`, `config?` | Starts the provider add flow. Outlook returns a device code; Gmail returns an OAuth URL. Returns `{handle, verification:{type, userCode, verificationUri, expiresAt, message}}`. |
+| `complete_add_account` | `provider`, `handle`, `authorizationResponse?`, `code?`, `state?` | Returns `pending` / `ready` / `expired` / `error`. Gmail accepts a pasted final redirected URL or raw code/state for remote-safe completion. |
 | `get_account_settings` | `account` | Get signature (HTML) and style preferences for an account. |
-| `set_account_settings` | `account`, `signature?`, `signaturePath?`, `style?` | Set signature HTML (inline or via file path) and font preferences. Disabled under `--read-only`. |
+| `set_account_settings` | `account`, `signature?`, `signaturePath?`, `style?` | Set signature HTML (inline or via file path) and font preferences. |
 | `remove_account` | `email` | Deletes tokens for the account. |
 | `list_emails` | `account`, `folder?`, `limit?`, `unreadOnly?`, `skip?` | Defaults: folder=`inbox`, limit=25. Supports pagination via `skip` — response includes `hasMore`. |
 | `search_emails` | `account`, `query`, `limit?` | KQL on Outlook. |
 | `read_email` | `account`, `id`, `format?` | Returns full body + recipients + attachment metadata. `format`: `markdown` (default), `html`, or `text`. |
 | `read_attachment` | `account`, `messageId`, `attachmentId` | Download an attachment to a temporary file and return its path. |
-| `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?`, `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`. |
+| `archive_email` | `account`, `id` | Move a message to the Archive folder. |
+| `trash_email` | `account`, `id` | Move a message to Deleted Items (trash). |
+| `move_email` | `account`, `id`, `destination` | Move to any folder by well-known name (`inbox`, `drafts`, etc.) or custom folder ID. |
+| `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. |
+| `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. |
+| `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. |
+| `send_draft` | `account`, `id` | Send an existing draft email by ID. Use with draft IDs returned by `draft_email` or `edit_draft`. |
 | `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`. |
-| `rename_folder` | `account`, `folderId`, `newName` | Rename an existing mail folder. Disabled under `--read-only`. |
-| `mark_read` | `account`, `id` | Mark a message as read. Disabled under `--read-only`. |
-| `mark_unread` | `account`, `id` | Mark a message as unread. Disabled under `--read-only`. |
+| `create_folder` | `account`, `displayName`, `parentFolderId?` | Create a new mail folder under root (default) or the given parent. |
+| `delete_folder` | `account`, `folderId` | Delete a mail folder by ID. |
+| `rename_folder` | `account`, `folderId`, `newName` | Rename an existing mail folder. |
+| `mark_read` | `account`, `id` | Mark a message as read. |
+| `mark_unread` | `account`, `id` | Mark a message as unread. |
 
 ## Email Watch
 
 When enabled, hypermail-mcp runs a background poll loop that scans inboxes for
-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.
+new messages and delivers each one via webhook POST and/or shell command.
+Intended for push-based email triage — downstream agents receive full email
+content without polling.
 
-```jsonc
-{
-  "watch": {
-    "enabled": true,
-    "pollIntervalSeconds": 10,
-    "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 }
-    }
-  }
-}
+```bash
+HYPERMAIL_WATCH_ENABLED=true \
+HYPERMAIL_WATCH_POLL_SECONDS=10 \
+HYPERMAIL_WATCH_WEBHOOK_URL=http://localhost:3000/api/email-webhook \
+HYPERMAIL_WATCH_NOTIFY_COMMAND='node /path/to/email-handler.js' \
+hypermail-mcp
 ```
 
-| Setting | Default | Notes |
-| --- | --- | --- |
-| `watch.enabled` | `false` | Toggle via config or `HYPERMAIL_WATCH_ENABLED=true` env var |
-| `watch.pollIntervalSeconds` | `10` | Min 10s, max 3600s |
-| `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) |
+**Validation:** If `HYPERMAIL_WATCH_ENABLED=true`, startup requires at least one
+of `HYPERMAIL_WATCH_WEBHOOK_URL` or `HYPERMAIL_WATCH_NOTIFY_COMMAND`. Webhook
+URLs are syntax-validated, and notify commands must be non-empty. Startup does
+not test network reachability or execute the command.
 
 **Behavior:**
 - Polls **all accounts** in the store, **inbox only**.
@@ -303,21 +290,22 @@ full email content without polling.
   account file — no duplicate emits across restarts.
 - 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.
+  - **Notify command:** Executes `HYPERMAIL_WATCH_NOTIFY_COMMAND` through the
+    platform shell with the `EmailFull` JSON piped to stdin.
 - Both modes use exponential backoff (`baseDelay × 2^attempt`). Retries on
-  failures (non-2xx for webhook, non-zero exit for script). Logs and moves on
+  failures (non-2xx for webhook, non-zero exit for command). 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.
+- Command delivery 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.
 
 **Rate limits:** Polling every 10s on a single inbox = 6 req/min = 0.6% of
 Microsoft Graph's 10,000 req/10min per-user limit. Safe for personal inboxes.
 
-## Add-account flow (Outlook)
+## Add-account flows
+
+### Outlook
 
 1. Agent calls `add_account({ provider: "outlook" })`.
 2. Server returns:
@@ -326,6 +314,7 @@ Microsoft Graph's 10,000 req/10min per-user limit. Safe for personal inboxes.
      "status": "pending",
      "handle": "…uuid…",
      "verification": {
+       "type": "device_code",
        "userCode": "ABCD-EFGH",
        "verificationUri": "https://microsoft.com/devicelogin",
        "expiresAt": "2025-…",
@@ -338,6 +327,57 @@ Microsoft Graph's 10,000 req/10min per-user limit. Safe for personal inboxes.
    it returns `{ "status": "ready", "account": {...} }`.
 5. From then on, any tool can be called with `account: "<that-email>"`.
 
+### Gmail
+
+Gmail uses Google OAuth 2.0, matching the official Gmail MCP model. Google's
+device-code endpoint rejects Gmail API scopes, so Hypermail uses an authorization
+URL with a real callback. Service accounts are only suitable for Google
+Workspace domain-wide delegation; they don't grant server-to-server access to
+consumer `@gmail.com` inboxes.
+
+For local stdio/Desktop OAuth clients, Hypermail starts a temporary
+`127.0.0.1` loopback callback server automatically. For hosted HTTP deployments,
+set `HYPERMAIL_GMAIL_REDIRECT_URI` and register the exact URI in Google Auth
+Platform, for example:
+
+```bash
+HYPERMAIL_TRANSPORT=http
+HYPERMAIL_GMAIL_REDIRECT_URI=https://mail.example.com/oauth/gmail/callback
+```
+
+1. Configure `HYPERMAIL_GMAIL_CLIENT_ID` and, when issued by your Google client
+   type, `HYPERMAIL_GMAIL_CLIENT_SECRET`. Use a Desktop client for local
+   loopback, or a Web client for hosted HTTP callbacks.
+2. Agent calls `add_account({ provider: "gmail" })`.
+3. Server returns an OAuth URL:
+   ```json
+   {
+     "status": "pending",
+     "handle": "…uuid…",
+     "verification": {
+       "type": "oauth_url",
+       "userCode": "",
+       "verificationUri": "https://accounts.google.com/o/oauth2/v2/auth?...",
+       "expiresAt": "2025-…",
+       "message": "Open this URL in a browser to authorize Gmail access..."
+     }
+   }
+   ```
+4. The user opens `verificationUri` and grants access. If the configured
+   callback is reachable, the browser shows a small success page and the agent
+   can poll `complete_add_account({ provider: "gmail", handle })` until ready.
+5. If the browser cannot reach the callback, the manual fallback still works:
+   copy the final redirected URL from the browser address bar and call:
+   ```json
+   {
+     "provider": "gmail",
+     "handle": "…uuid…",
+     "authorizationResponse": "http://127.0.0.1:54321/oauth2callback?code=...&state=..."
+   }
+   ```
+6. `complete_add_account` validates state, exchanges the code for tokens, stores
+   the account, and returns `{ "status": "ready", "account": {...} }`.
+
 ## Roadmap
 
 - Threading / conversations.
@@ -350,7 +390,7 @@ src/
   cli.ts                       # arg parsing + entry
   server.ts                    # MCP server, stdio + HTTP transports, session management
   version.ts                   # version constant
-  config.ts                    # hypermail-config.json schema + resolution
+  config.ts                    # env-only config types + resolution
   store/
     account-store.ts           # encrypted multi-account store (AES-256-GCM)
     crypto.ts                  # AES-256-GCM encrypt/decrypt, key resolution, atomic writes
@@ -363,19 +403,20 @@ src/
       index.ts                 # OutlookProvider implementation
     imap/index.ts              # IMAP provider (imapflow + nodemailer)
     gmail/
-      auth.ts                  # Google OAuth device-code flow
+      auth.ts                  # Google OAuth authorization-code flow
       client.ts                # Gmail API (googleapis)
       index.ts                 # GmailProvider implementation
     shared/                    # shared utilities across providers
   watcher/
     manager.ts                 # WatcherManager — inbox poll loop + dedup
     webhook.ts                 # HTTP POST with exponential backoff retry
+    script.ts                  # shell-command delivery with retry/timeout
     index.ts                   # barrel export
   tools/
     index.ts                   # MCP tool registrations
     accounts.ts                # list/add/remove/complete-add account tools
     browse.ts                  # list/search/read email tools
-    compose.ts                 # send/draft/edit/send-draft/add-attachment tools
+    compose.ts                 # send/draft/edit/send-draft tools
     folders.ts                 # list/create/delete/rename folder tools
     organize.ts                # archive/trash/move/mark-read/mark-unread tools
     shared.ts                  # shared tool helpers