apple-mail-mcp 2.1.0 → 2.1.1

package/README.md

@@ -348,6 +348,29 @@ config. Gmail label semantics: common names (`All Mail`, `Sent`, `Trash`,
 > (e.g. `iCloud`), and use an **app-specific password** (from appleid.apple.com)
 > stored in the Keychain.
 
+##### Configuration file (when the host strips `env`)
+
+Some host apps (e.g. Claude Desktop) launch the MCP server with a scrubbed
+environment and ignore the `env` block in their server config, so there's no way
+to pass `APPLE_MAIL_MCP_*` settings through it. In that case, put them in a JSON
+file the host doesn't manage — `APPLE_MAIL_MCP_CONFIG_FILE`, or by default
+`~/Library/Application Support/apple-mail-mcp/config.json`:
+
+```json
+{
+  "APPLE_MAIL_MCP_IMAP_USER": "you@gmail.com",
+  "APPLE_MAIL_MCP_IMAP_HOST": "imap.gmail.com",
+  "APPLE_MAIL_MCP_IMAP_KEYCHAIN_SERVICE": "imap.gmail.com",
+  "APPLE_MAIL_MCP_IMAP_KEYCHAIN_ACCOUNT": "you@gmail.com",
+  "APPLE_MAIL_MCP_IMAP_IDLE": "1"
+}
+```
+
+The server reads it at startup and merges values into the environment **without
+overriding** anything already set there (so an explicit `env` still wins). Store
+only non-secret config here — **passwords belong in the Keychain**, never in this
+file.
+
 ##### Push notifications (IMAP IDLE) — opt-in
 
 When `APPLE_MAIL_MCP_IMAP_IDLE=1`, the server opens a dedicated, long-lived

package/build/index.js

@@ -34,6 +34,10 @@ import { runDoctor, formatDoctorReport } from "./tools/doctor.js";
 import { registerResourcesAndPrompts } from "./tools/resourcesAndPrompts.js";
 import { normalizeSubject, subjectFromGetMessage } from "./tools/thread.js";
 import { ImapIdleWatcher } from "./services/imapIdle.js";
+import { loadFileConfig } from "./services/fileConfig.js";
+// Load file-based config FIRST (2.1.1) — before anything reads APPLE_MAIL_MCP_*.
+// Lets users configure the server when the host app strips the MCP env block.
+loadFileConfig();
 // =============================================================================
 // Shared Validation Schemas
 // =============================================================================

package/build/services/fileConfig.d.ts

@@ -0,0 +1,7 @@
+export declare function fileConfigPath(env?: NodeJS.ProcessEnv): string;
+/**
+ * Merge a JSON config file's string values into `env` for keys not already set.
+ * Returns the list of keys actually applied. Tolerates a missing/corrupt file.
+ */
+export declare function loadFileConfig(env?: NodeJS.ProcessEnv, path?: string): string[];
+//# sourceMappingURL=fileConfig.d.ts.map

package/build/services/fileConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileConfig.d.ts","sourceRoot":"","sources":["../../src/services/fileConfig.ts"],"names":[],"mappings":"AAqBA,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAI3E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,IAAI,GAAE,MAA4B,GACjC,MAAM,EAAE,CAiBV"}

package/build/services/fileConfig.js

@@ -0,0 +1,52 @@
+/**
+ * File-based configuration loader (2.1.1).
+ *
+ * Some host apps (e.g. Claude Desktop) spawn the MCP server with a scrubbed
+ * environment and ignore/strip the `env` block in their server config, so
+ * there's no way to pass `APPLE_MAIL_MCP_*` settings in. This loads them from a
+ * JSON file the host doesn't manage, merging into `process.env` WITHOUT
+ * overriding anything already set (so an explicit env still wins).
+ *
+ * The file holds only non-secret config — account/host/Keychain-service names
+ * and flags. Passwords are NEVER stored here; they stay in the macOS Keychain.
+ *
+ * Path: `APPLE_MAIL_MCP_CONFIG_FILE`, else
+ * `~/Library/Application Support/apple-mail-mcp/config.json`.
+ *
+ * @module services/fileConfig
+ */
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+export function fileConfigPath(env = process.env) {
+    const override = env.APPLE_MAIL_MCP_CONFIG_FILE;
+    if (override && override.trim())
+        return override.trim();
+    return join(homedir(), "Library", "Application Support", "apple-mail-mcp", "config.json");
+}
+/**
+ * Merge a JSON config file's string values into `env` for keys not already set.
+ * Returns the list of keys actually applied. Tolerates a missing/corrupt file.
+ */
+export function loadFileConfig(env = process.env, path = fileConfigPath(env)) {
+    const applied = [];
+    try {
+        if (!existsSync(path))
+            return applied;
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (!parsed || typeof parsed !== "object")
+            return applied;
+        for (const [k, v] of Object.entries(parsed)) {
+            if (typeof v !== "string")
+                continue;
+            if (env[k] === undefined || env[k] === "") {
+                env[k] = v;
+                applied.push(k);
+            }
+        }
+    }
+    catch (e) {
+        console.error(`Failed to load apple-mail-mcp config file ${path}: ${String(e)}`);
+    }
+    return applied;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-mail-mcp",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "MCP server for Apple Mail - read, search, send, and manage emails via Claude",
   "type": "module",
   "main": "build/index.js",