hypermail-mcp 0.6.3 → 0.7.1

package/README.md

@@ -3,6 +3,16 @@
 A **Model Context Protocol** server that lets an agent operate any of the user's
 inboxes through a single, unified tool surface.
 
+> **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.
+>
+> **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 +159,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 }
+    }
   }
 }
 ```
@@ -157,6 +175,33 @@ 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 env vars
+(`MS_CLIENT_ID`, `MS_TENANT_ID`, `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`)
+still work as fallbacks for backward compatibility.
+
+| Env var | Config path | Type |
+| --- | --- | --- |
+| `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` |
+
+**Priority order:** CLI flags > config file > `HYPERMAIL_*` env var > hardcoded default.
+
 ## Tools
 
 All "email" tools take an `account` argument — the email address of the inbox
@@ -190,6 +235,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 +328,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

@@ -52,8 +52,6 @@ function decrypt(buf, key) {
 }
 function resolveDataDir(explicit) {
   if (explicit && explicit.length > 0) return path.resolve(explicit);
-  const env = process.env.HYPERMAIL_MCP_DATA_DIR;
-  if (env && env.length > 0) return path.resolve(env);
   return path.join(homedir(), ".hypermail-mcp");
 }
 function parseEnvKey(raw) {
@@ -219,8 +217,8 @@ function isSerializedTokens(obj) {
   return typeof o.msalCache === "string" && typeof o.homeAccountId === "string" && typeof o.tenantId === "string" && typeof o.username === "string" && Array.isArray(o.scopes);
 }
 function makeConfig(prevCacheJson, clientIdOverride, tenantOverride) {
-  const clientId = clientIdOverride || process.env.MS_CLIENT_ID || DEFAULT_CLIENT_ID;
-  const tenant = tenantOverride || process.env.MS_TENANT_ID || "common";
+  const clientId = clientIdOverride || DEFAULT_CLIENT_ID;
+  const tenant = tenantOverride || "common";
   return {
     auth: {
       clientId,
@@ -1602,13 +1600,13 @@ async function getEmailFromToken(accessToken) {
   return data.emailAddress;
 }
 function beginDeviceCode2(scopes = DEFAULT_SCOPES2, clientIdOverride, clientSecretOverride) {
-  const clientId = clientIdOverride || process.env.GOOGLE_CLIENT_ID;
+  const clientId = clientIdOverride;
   if (!clientId) {
     throw new Error(
-      "GOOGLE_CLIENT_ID is required for Gmail OAuth \u2014 set it in env or provider config"
+      "GOOGLE_CLIENT_ID is required for Gmail OAuth \u2014 set it via HYPERMAIL_PROVIDERS_GMAIL_CLIENT_ID, GOOGLE_CLIENT_ID, or provider config"
     );
   }
-  const clientSecret = clientSecretOverride || process.env.GOOGLE_CLIENT_SECRET || void 0;
+  const clientSecret = clientSecretOverride || void 0;
   let resolve;
   let reject;
   const result = new Promise(
@@ -3568,7 +3566,7 @@ function registerTools(server, opts) {
 // package.json
 var package_default = {
   name: "hypermail-mcp",
-  version: "0.6.3",
+  version: "0.7.1",
   description: "Unified email MCP server \u2014 operate any inbox (Outlook now, IMAP/Gmail later) by passing an email address.",
   type: "module",
   bin: {
@@ -3638,6 +3636,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 +3771,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(),
@@ -3700,6 +3815,24 @@ var KNOWN_TOOLS = [
   "add_attachment_to_draft",
   "check_notifications"
 ];
+var ENV_HTTP_ENABLED = "HYPERMAIL_HTTP_ENABLED";
+var ENV_HTTP_PORT = "HYPERMAIL_HTTP_PORT";
+var ENV_HTTP_HOST = "HYPERMAIL_HTTP_HOST";
+var ENV_TOOLS_DISABLED = "HYPERMAIL_TOOLS_DISABLED";
+var ENV_TOOLS_ENABLED = "HYPERMAIL_TOOLS_ENABLED";
+var ENV_OUTLOOK_CLIENT_ID = "HYPERMAIL_PROVIDERS_OUTLOOK_CLIENT_ID";
+var ENV_OUTLOOK_TENANT_ID = "HYPERMAIL_PROVIDERS_OUTLOOK_TENANT_ID";
+var ENV_GMAIL_CLIENT_ID = "HYPERMAIL_PROVIDERS_GMAIL_CLIENT_ID";
+var ENV_GMAIL_CLIENT_SECRET = "HYPERMAIL_PROVIDERS_GMAIL_CLIENT_SECRET";
+var ENV_WATCH_ENABLED = "HYPERMAIL_WATCH_ENABLED";
+var ENV_WATCH_POLL_INTERVAL = "HYPERMAIL_WATCH_POLL_INTERVAL";
+var ENV_WATCH_WEBHOOK_URL = "HYPERMAIL_WATCH_WEBHOOK_URL";
+var ENV_WATCH_WEBHOOK_RETRY_MAX_ATTEMPTS = "HYPERMAIL_WATCH_WEBHOOK_RETRY_MAX_ATTEMPTS";
+var ENV_WATCH_WEBHOOK_RETRY_BASE_DELAY = "HYPERMAIL_WATCH_WEBHOOK_RETRY_BASE_DELAY_MS";
+var LEGACY_MS_CLIENT_ID = "MS_CLIENT_ID";
+var LEGACY_MS_TENANT_ID = "MS_TENANT_ID";
+var LEGACY_GOOGLE_CLIENT_ID = "GOOGLE_CLIENT_ID";
+var LEGACY_GOOGLE_CLIENT_SECRET = "GOOGLE_CLIENT_SECRET";
 var ENV_VAR_RE = /\$\{([A-Z_][A-Z0-9_]*)\}/g;
 function resolveEnvVars(value) {
   return value.replace(ENV_VAR_RE, (_match, name) => {
@@ -3718,6 +3851,26 @@ function deepResolve(obj) {
   }
   return obj;
 }
+function parseBool(value) {
+  if (value === void 0) return void 0;
+  const lower = value.trim().toLowerCase();
+  if (lower === "true" || lower === "1" || lower === "yes") return true;
+  if (lower === "false" || lower === "0" || lower === "no" || lower === "") return false;
+  return void 0;
+}
+function parseIntSafe(value) {
+  if (value === void 0) return void 0;
+  const trimmed = value.trim();
+  if (trimmed === "") return void 0;
+  const n = Number.parseInt(trimmed, 10);
+  return Number.isNaN(n) ? void 0 : n;
+}
+function parseStringArray(value) {
+  if (value === void 0) return void 0;
+  const trimmed = value.trim();
+  if (trimmed === "") return [];
+  return trimmed.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+}
 function validateToolNames(toolNames, listName) {
   if (!toolNames || toolNames.length === 0) return;
   const known = new Set(KNOWN_TOOLS);
@@ -3741,30 +3894,69 @@ function loadConfig(configPath, cliOverrides = {}) {
   }
   raw = deepResolve(raw);
   const parsed = rawConfigSchema.parse(raw);
-  if (parsed.tools) {
-    if (parsed.tools.disabled && parsed.tools.enabled) {
-      throw new Error(
-        "tools.disabled and tools.enabled are mutually exclusive \u2014 use one or the other"
-      );
+  const http = {
+    enabled: cliOverrides.http ?? parsed.http?.enabled ?? parseBool(process.env[ENV_HTTP_ENABLED]) ?? false,
+    port: cliOverrides.port ?? parsed.http?.port ?? parseIntSafe(process.env[ENV_HTTP_PORT]) ?? 3e3,
+    host: cliOverrides.host ?? parsed.http?.host ?? process.env[ENV_HTTP_HOST] ?? "127.0.0.1"
+  };
+  const toolsDisabled = parsed.tools?.disabled ?? parseStringArray(process.env[ENV_TOOLS_DISABLED]);
+  const toolsEnabled = parsed.tools?.enabled ?? parseStringArray(process.env[ENV_TOOLS_ENABLED]);
+  if (toolsDisabled && toolsEnabled) {
+    throw new Error(
+      "tools.disabled and tools.enabled are mutually exclusive \u2014 use one or the other"
+    );
+  }
+  if (toolsEnabled !== void 0 && toolsEnabled.length === 0) {
+    throw new Error(
+      "tools.enabled is empty \u2014 at least one tool must be listed. To enable all tools, omit the tools section entirely."
+    );
+  }
+  validateToolNames(toolsDisabled, "tools.disabled");
+  validateToolNames(toolsEnabled, "tools.enabled");
+  const tools = toolsDisabled || toolsEnabled ? { disabled: toolsDisabled, enabled: toolsEnabled } : void 0;
+  const outlookClientId = parsed.providers?.outlook?.clientId ?? process.env[ENV_OUTLOOK_CLIENT_ID] ?? process.env[LEGACY_MS_CLIENT_ID];
+  const outlookTenantId = parsed.providers?.outlook?.tenantId ?? process.env[ENV_OUTLOOK_TENANT_ID] ?? process.env[LEGACY_MS_TENANT_ID];
+  const gmailClientId = parsed.providers?.gmail?.clientId ?? process.env[ENV_GMAIL_CLIENT_ID] ?? process.env[LEGACY_GOOGLE_CLIENT_ID];
+  const gmailClientSecret = parsed.providers?.gmail?.clientSecret ?? process.env[ENV_GMAIL_CLIENT_SECRET] ?? process.env[LEGACY_GOOGLE_CLIENT_SECRET];
+  let providers;
+  if (outlookClientId || outlookTenantId || gmailClientId || gmailClientSecret) {
+    providers = {};
+    if (outlookClientId || outlookTenantId) {
+      providers.outlook = {};
+      if (outlookClientId) providers.outlook.clientId = outlookClientId;
+      if (outlookTenantId) providers.outlook.tenantId = outlookTenantId;
     }
-    if (parsed.tools.enabled !== void 0 && parsed.tools.enabled.length === 0) {
-      throw new Error(
-        "tools.enabled is empty \u2014 at least one tool must be listed. To enable all tools, omit the tools section entirely."
-      );
+    if (gmailClientId || gmailClientSecret) {
+      providers.gmail = {};
+      if (gmailClientId) providers.gmail.clientId = gmailClientId;
+      if (gmailClientSecret) providers.gmail.clientSecret = gmailClientSecret;
     }
-    validateToolNames(parsed.tools.disabled, "tools.disabled");
-    validateToolNames(parsed.tools.enabled, "tools.enabled");
   }
-  const http = {
-    enabled: cliOverrides.http ?? parsed.http?.enabled ?? false,
-    port: cliOverrides.port ?? parsed.http?.port ?? 3e3,
-    host: cliOverrides.host ?? parsed.http?.host ?? "127.0.0.1"
-  };
+  const watchEnabledEnv = parseBool(process.env[ENV_WATCH_ENABLED]);
+  let watch;
+  if (parsed.watch || watchEnabledEnv !== void 0) {
+    const webhookUrl = parsed.watch?.webhook?.url ?? process.env[ENV_WATCH_WEBHOOK_URL];
+    let webhook;
+    if (webhookUrl) {
+      const retryMaxAttempts = parsed.watch?.webhook?.retry?.maxAttempts ?? parseIntSafe(process.env[ENV_WATCH_WEBHOOK_RETRY_MAX_ATTEMPTS]) ?? 5;
+      const retryBaseDelayMs = parsed.watch?.webhook?.retry?.baseDelayMs ?? parseIntSafe(process.env[ENV_WATCH_WEBHOOK_RETRY_BASE_DELAY]) ?? 1e3;
+      webhook = {
+        url: webhookUrl,
+        retry: { maxAttempts: retryMaxAttempts, baseDelayMs: retryBaseDelayMs }
+      };
+    }
+    watch = {
+      enabled: watchEnabledEnv ?? parsed.watch?.enabled ?? false,
+      pollIntervalSeconds: parsed.watch?.pollIntervalSeconds ?? parseIntSafe(process.env[ENV_WATCH_POLL_INTERVAL]) ?? 10,
+      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
+    tools,
+    providers,
+    watch
   };
 }
 function resolveTools(config) {
@@ -3783,6 +3975,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 },
@@ -3897,19 +4097,51 @@ Options:
   -h, --help          Show this help
 
 Configuration:
-  All server settings (data dir, HTTP, tool filtering, provider credentials)
-  live in hypermail-config.json. Pass it via --config.
+  All settings can be provided via environment variables \u2014 no config file
+  required. Use hypermail-config.json for advanced scenarios.
 
-Example hypermail-config.json:
-  {
-    "dataDir": "/path/to/data",
-    "http": { "enabled": false },
-    "tools": { "disabled": ["send_email"] },
-    "providers": {
-      "outlook": { "clientId": "\${MS_CLIENT_ID}", "tenantId": "\${MS_TENANT_ID}" },
-      "gmail": { "clientId": "\${GOOGLE_CLIENT_ID}", "clientSecret": "\${GOOGLE_CLIENT_SECRET}" }
+  Environment variables:
+
+  HYPERMAIL_MCP_DATA_DIR              Data directory (string)
+  HYPERMAIL_HTTP_ENABLED              Enable HTTP mode (bool: true/false/1/0)
+  HYPERMAIL_HTTP_PORT                 HTTP port (number)
+  HYPERMAIL_HTTP_HOST                 HTTP bind address (string)
+  HYPERMAIL_TOOLS_DISABLED            Comma-separated tool names to disable
+  HYPERMAIL_TOOLS_ENABLED             Comma-separated tool names to enable
+  HYPERMAIL_PROVIDERS_OUTLOOK_CLIENT_ID   Outlook OAuth client ID (string)
+  HYPERMAIL_PROVIDERS_OUTLOOK_TENANT_ID   Outlook tenant ID (string)
+  HYPERMAIL_PROVIDERS_GMAIL_CLIENT_ID     Gmail OAuth client ID (string)
+  HYPERMAIL_PROVIDERS_GMAIL_CLIENT_SECRET Gmail OAuth client secret (string)
+  HYPERMAIL_WATCH_ENABLED             Enable inbox polling (bool)
+  HYPERMAIL_WATCH_POLL_INTERVAL       Poll interval in seconds (number)
+  HYPERMAIL_WATCH_WEBHOOK_URL         Webhook URL for new-email events (string)
+  HYPERMAIL_WATCH_WEBHOOK_RETRY_MAX_ATTEMPTS  Retry max attempts (number)
+  HYPERMAIL_WATCH_WEBHOOK_RETRY_BASE_DELAY_MS Retry base delay ms (number)
+  HYPERMAIL_MCP_KEY                   Encryption master key (hex or base64)
+
+  Legacy env vars (still supported):
+  MS_CLIENT_ID, MS_TENANT_ID, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
+
+  Priority: CLI flags > config file > env vars > defaults.
+
+  Example (env-only, no config file):
+    HYPERMAIL_HTTP_ENABLED=true \\
+    HYPERMAIL_HTTP_PORT=8080 \\
+    HYPERMAIL_PROVIDERS_OUTLOOK_CLIENT_ID=abc123 \\
+    HYPERMAIL_PROVIDERS_OUTLOOK_TENANT_ID=common \\
+    HYPERMAIL_MCP_DATA_DIR=/data/hypermail \\
+    hypermail-mcp --http
+
+  Example hypermail-config.json:
+    {
+      "dataDir": "/path/to/data",
+      "http": { "enabled": false },
+      "tools": { "disabled": ["send_email"] },
+      "providers": {
+        "outlook": { "clientId": "\${MS_CLIENT_ID}", "tenantId": "\${MS_TENANT_ID}" },
+        "gmail": { "clientId": "\${GOOGLE_CLIENT_ID}", "clientSecret": "\${GOOGLE_CLIENT_SECRET}" }
+      }
     }
-  }
 `;
   process.stdout.write(msg);
 }