hypermail-mcp 0.7.0 → 0.7.1

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.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.
@@ -170,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

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.7.0",
+  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: {
@@ -3817,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) => {
@@ -3835,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);
@@ -3858,38 +3894,68 @@ 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 || process.env.HYPERMAIL_WATCH_ENABLED === "true") {
+  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: process.env.HYPERMAIL_WATCH_ENABLED === "true" || Boolean(parsed.watch?.enabled),
-      pollIntervalSeconds: parsed.watch?.pollIntervalSeconds ?? 10,
-      webhook: parsed.watch?.webhook
+      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
   };
 }
@@ -4031,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.
+
+  Environment variables:
 
-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}" }
+  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);
 }