hypermail-mcp 0.7.0 → 0.7.2

package/README.md

@@ -3,6 +3,15 @@
 A **Model Context Protocol** server that lets an agent operate any of the user's
 inboxes through a single, unified tool surface.
 
+> **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
+> `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 +179,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(
@@ -3303,6 +3301,8 @@ function registerOrganizeTools(server, ctx) {
 
 // src/tools/compose.ts
 import { z as z6 } from "zod";
+import { readFileSync } from "fs";
+import { basename, extname } from "path";
 function registerComposeTools(server, ctx) {
   const { store, registry, tools } = ctx;
   const sendEmailSchema = z6.object({
@@ -3508,6 +3508,31 @@ function registerComposeTools(server, ctx) {
       }
     );
   }
+  const MIME_TYPES = {
+    ".pdf": "application/pdf",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".svg": "image/svg+xml",
+    ".webp": "image/webp",
+    ".txt": "text/plain",
+    ".html": "text/html",
+    ".css": "text/css",
+    ".csv": "text/csv",
+    ".json": "application/json",
+    ".xml": "application/xml",
+    ".zip": "application/zip",
+    ".gz": "application/gzip",
+    ".tar": "application/x-tar",
+    ".doc": "application/msword",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".xls": "application/vnd.ms-excel",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    ".mp3": "audio/mpeg",
+    ".mp4": "video/mp4"
+  };
   const addAttachmentOutputSchema = {
     attached: z6.literal(true),
     id: z6.string(),
@@ -3521,25 +3546,48 @@ function registerComposeTools(server, ctx) {
     server.registerTool(
       "add_attachment_to_draft",
       {
-        description: "Add a file attachment to an existing draft email by ID. `contentBytes` must be base64-encoded file content. `contentType` is the MIME type (e.g. 'application/pdf'); defaults to 'application/octet-stream' if omitted. Disabled in --read-only mode.",
-        inputSchema: {
+        description: "Add a file attachment to an existing draft email by ID. Provide exactly one of `contentBytes` (base64-encoded content) or `filePath` (absolute path to a local file). When using `filePath`, the file is read from disk and base64-encoded automatically, and `name` defaults to the file's basename if not provided. `contentType` is the MIME type (e.g. 'application/pdf'); when using `filePath` it is inferred from the extension if omitted. Disabled in --read-only mode.",
+        inputSchema: z6.object({
           account: z6.string().email(),
           id: z6.string().min(1).describe("Draft message ID"),
-          name: z6.string().min(1).describe("Attachment filename (e.g. 'report.pdf')"),
-          contentBytes: z6.string().min(1).describe("Base64-encoded file content"),
-          contentType: z6.string().optional().describe("MIME type (e.g. 'application/pdf')")
-        },
+          name: z6.string().min(1).optional().describe(
+            "Attachment filename (e.g. 'report.pdf'). Defaults to the file's basename when `filePath` is used."
+          ),
+          contentBytes: z6.string().min(1).optional().describe("Base64-encoded file content. Mutually exclusive with `filePath`."),
+          filePath: z6.string().min(1).optional().describe(
+            "Absolute path to a local file. The file is read and base64-encoded automatically. Mutually exclusive with `contentBytes`."
+          ),
+          contentType: z6.string().optional().describe("MIME type (e.g. 'application/pdf'). Inferred from `filePath` extension if omitted.")
+        }).refine(
+          (v) => Boolean(v.contentBytes) !== Boolean(v.filePath),
+          { message: "Provide exactly one of `contentBytes` or `filePath`." }
+        ),
         outputSchema: addAttachmentOutputSchema
       },
       async (args) => {
         try {
           const { provider, account } = registry.resolveByEmail(args.account);
+          let contentBytes;
+          let name;
+          let contentType = args.contentType;
+          if (args.filePath) {
+            const fileData = readFileSync(args.filePath);
+            contentBytes = fileData.toString("base64");
+            name = args.name ?? basename(args.filePath);
+            if (!contentType) {
+              const ext = extname(args.filePath).toLowerCase();
+              contentType = MIME_TYPES[ext] ?? "application/octet-stream";
+            }
+          } else {
+            contentBytes = args.contentBytes;
+            name = args.name;
+          }
           const res = await provider.addAttachmentToDraft(
             account,
             args.id,
-            args.name,
-            args.contentBytes,
-            args.contentType
+            name,
+            contentBytes,
+            contentType
           );
           const data = {
             attached: true,
@@ -3568,7 +3616,7 @@ function registerTools(server, opts) {
 // package.json
 var package_default = {
   name: "hypermail-mcp",
-  version: "0.7.0",
+  version: "0.7.2",
   description: "Unified email MCP server \u2014 operate any inbox (Outlook now, IMAP/Gmail later) by passing an email address.",
   type: "module",
   bin: {
@@ -3749,7 +3797,7 @@ var WatcherManager = class {
 };
 
 // src/config.ts
-import { readFileSync } from "fs";
+import { readFileSync as readFileSync2 } from "fs";
 import { z as z7 } from "zod";
 var httpConfigSchema = z7.object({
   enabled: z7.boolean().default(false),
@@ -3817,6 +3865,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 +3901,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);
@@ -3850,7 +3936,7 @@ function loadConfig(configPath, cliOverrides = {}) {
   let raw = {};
   if (configPath) {
     try {
-      raw = JSON.parse(readFileSync(configPath, "utf-8"));
+      raw = JSON.parse(readFileSync2(configPath, "utf-8"));
     } catch (err) {
       const detail = err instanceof SyntaxError ? "Invalid JSON" : err instanceof Error ? err.message : String(err);
       throw new Error(`Failed to read config file "${configPath}": ${detail}`);
@@ -3858,38 +3944,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 +4147,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:
+
+  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 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}" }
+  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);
 }