hypermail-mcp 0.6.3 → 0.7.0

package/README.md

@@ -3,6 +3,11 @@
 A **Model Context Protocol** server that lets an agent operate any of the user's
 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.
+> Works in both stdio and HTTP transport modes.
+>
 > **v0.6.3** — Unify stdio and HTTP modes into a single feature set. Removed
 > email watch (inbox polling, SSE push, notification buffer), agent
 > multi-tenancy (`agents.yaml`, `x-api-key` auth, per-agent allowlists), and
@@ -149,6 +154,14 @@ looks for it in the same directory as `cli.js`.
   },
   "providers": {
     "outlook": { "clientId": "...", "tenantId": "..." }
+  },
+  "watch": {
+    "enabled": true,
+    "pollIntervalSeconds": 10,
+    "webhook": {
+      "url": "http://your-agent:3000/api/email-webhook",
+      "retry": { "maxAttempts": 5, "baseDelayMs": 1000 }
+    }
   }
 }
 ```
@@ -190,6 +203,49 @@ account store.
 | `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`. |
 
+## 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.
+
+```jsonc
+{
+  "watch": {
+    "enabled": true,
+    "pollIntervalSeconds": 10,
+    "webhook": {
+      "url": "http://localhost:3000/api/email-webhook",
+      "retry": { "maxAttempts": 5, "baseDelayMs": 1000 }
+    }
+  }
+}
+```
+
+| 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) |
+
+**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.
+- 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)
 
 1. Agent calls `add_account({ provider: "outlook" })`.
@@ -240,6 +296,10 @@ src/
       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
+    index.ts                   # barrel export
   tools/
     index.ts                   # MCP tool registrations
     accounts.ts                # list/add/remove/complete-add account tools

package/dist/cli.js

@@ -3568,7 +3568,7 @@ function registerTools(server, opts) {
 // package.json
 var package_default = {
   name: "hypermail-mcp",
-  version: "0.6.3",
+  version: "0.7.0",
   description: "Unified email MCP server \u2014 operate any inbox (Outlook now, IMAP/Gmail later) by passing an email address.",
   type: "module",
   bin: {
@@ -3638,6 +3638,116 @@ var package_default = {
 // src/version.ts
 var VERSION = package_default.version;
 
+// src/watcher/webhook.ts
+async function postWebhook(email, config) {
+  if (!config.webhook) return false;
+  const { url, retry } = config.webhook;
+  const maxAttempts = retry.maxAttempts;
+  const baseDelayMs = retry.baseDelayMs;
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    if (attempt > 0) {
+      const delay = baseDelayMs * 2 ** (attempt - 1);
+      await sleep(delay);
+    }
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(email)
+      });
+      if (res.ok) return true;
+      console.error(
+        `[hypermail-watch] webhook POST ${email.id} attempt ${attempt + 1}/${maxAttempts}: HTTP ${res.status}`
+      );
+    } catch (err) {
+      const code = err.code ?? "";
+      console.error(
+        `[hypermail-watch] webhook POST ${email.id} attempt ${attempt + 1}/${maxAttempts}: ${code || String(err)}`
+      );
+    }
+  }
+  console.error(
+    `[hypermail-watch] webhook delivery failed after ${maxAttempts} retries for ${email.id}`
+  );
+  return false;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/watcher/manager.ts
+var WatcherManager = class {
+  constructor(store, registry, config) {
+    this.store = store;
+    this.registry = registry;
+    this.config = config;
+  }
+  store;
+  registry;
+  config;
+  intervalId = null;
+  /** Start the poll loop. Fires immediately on the first tick, then every
+   *  `pollIntervalSeconds`. Safe to call multiple times — subsequent calls
+   *  are no-ops. */
+  start() {
+    if (this.intervalId !== null) return;
+    this.poll();
+    this.intervalId = setInterval(
+      () => this.poll(),
+      this.config.pollIntervalSeconds * 1e3
+    );
+  }
+  /** Stop the poll loop and release the interval. Safe to call when already
+   *  stopped. */
+  stop() {
+    if (this.intervalId !== null) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+  }
+  // ── private ──
+  async poll() {
+    const accounts = this.store.listAccounts();
+    for (const acct of accounts) {
+      try {
+        await this.pollAccount(acct.email);
+      } catch (err) {
+        console.error(
+          `[hypermail-watch] poll failed for ${acct.email}:`,
+          err
+        );
+      }
+    }
+  }
+  async pollAccount(email) {
+    const { provider, account } = this.registry.resolveByEmail(email);
+    const result = await provider.listEmails(account, {
+      folder: "inbox",
+      limit: 50
+    });
+    const knownIds = [...account.lastSeenIds ?? []];
+    const newEmails = result.items.filter((e) => !knownIds.includes(e.id));
+    if (newEmails.length === 0) return;
+    for (const summary of newEmails) {
+      try {
+        const full = await provider.readEmail(account, summary.id);
+        await this.emit(full);
+        knownIds.unshift(summary.id);
+      } catch (err) {
+        console.error(
+          `[hypermail-watch] emission failed for ${email}/${summary.id}:`,
+          err
+        );
+      }
+    }
+    const capped = knownIds.slice(0, 200);
+    await this.store.upsertAccount({ ...account, lastSeenIds: capped });
+  }
+  async emit(full) {
+    await postWebhook(full, this.config);
+  }
+};
+
 // src/config.ts
 import { readFileSync } from "fs";
 import { z as z7 } from "zod";
@@ -3663,8 +3773,15 @@ var providersConfigSchema = z7.object({
   gmail: gmailProviderSchema.optional()
 });
 var watchConfigSchema = z7.object({
-  enabled: z7.boolean().default(true),
-  pollIntervalSeconds: z7.number().int().min(10).max(3600).default(60)
+  enabled: z7.boolean().default(false),
+  pollIntervalSeconds: z7.number().int().min(10).max(3600).default(10),
+  webhook: z7.object({
+    url: z7.string(),
+    retry: z7.object({
+      maxAttempts: z7.number().int().min(1).max(10).default(5),
+      baseDelayMs: z7.number().int().min(100).default(1e3)
+    }).optional()
+  }).optional()
 });
 var rawConfigSchema = z7.object({
   dataDir: z7.string().optional(),
@@ -3760,11 +3877,20 @@ function loadConfig(configPath, cliOverrides = {}) {
     port: cliOverrides.port ?? parsed.http?.port ?? 3e3,
     host: cliOverrides.host ?? parsed.http?.host ?? "127.0.0.1"
   };
+  let watch;
+  if (parsed.watch || process.env.HYPERMAIL_WATCH_ENABLED === "true") {
+    watch = {
+      enabled: process.env.HYPERMAIL_WATCH_ENABLED === "true" || Boolean(parsed.watch?.enabled),
+      pollIntervalSeconds: parsed.watch?.pollIntervalSeconds ?? 10,
+      webhook: parsed.watch?.webhook
+    };
+  }
   return {
     dataDir: cliOverrides.dataDir ?? parsed.dataDir ?? process.env.HYPERMAIL_MCP_DATA_DIR,
     http,
     tools: parsed.tools ? { disabled: parsed.tools.disabled, enabled: parsed.tools.enabled } : void 0,
-    providers: parsed.providers
+    providers: parsed.providers,
+    watch
   };
 }
 function resolveTools(config) {
@@ -3783,6 +3909,14 @@ async function startServer(opts) {
   const store = await AccountStore.open({ dataDir: config.dataDir });
   const registry = buildRegistry({ store, providers: config.providers });
   const tools = resolveTools(config);
+  let watcher;
+  if (config.watch?.enabled) {
+    watcher = new WatcherManager(store, registry, config.watch);
+    watcher.start();
+    const stop = () => watcher?.stop();
+    process.on("SIGTERM", stop);
+    process.on("SIGINT", stop);
+  }
   const createServer = () => {
     const s = new McpServer(
       { name: "hypermail-mcp", version: VERSION },