apple-mail-mcp 2.1.0 → 2.1.2

package/README.md

@@ -284,6 +284,8 @@ The default `applescript` transport is unchanged; SMTP is opt-in per call.
 
 ##### IMAP backend — opt-in
 
+> 📘 **For step-by-step setup (app passwords, Keychain, config methods, multi-account, upgrading, troubleshooting), see the [IMAP / SMTP Setup Guide](docs/IMAP-SETUP.md).** The summary below is the reference; the guide is the walkthrough.
+
 AppleScript runs `search`/`list` predicates client-side over the Apple Event
 bridge, which is slow and can time out (false-empty) on large Gmail/IMAP
 mailboxes (see [#24](https://github.com/sweetrb/apple-mail-mcp/issues/24)), and
@@ -348,6 +350,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
@@ -1117,6 +1142,8 @@ Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for gui
 
 ## Related Projects
 
-- [apple-notes-mcp](https://github.com/sweetrb/apple-notes-mcp) — MCP server for Apple Notes
-- [apple-numbers-mcp](https://github.com/sweetrb/apple-numbers-mcp) — MCP server for Apple Numbers spreadsheets
-- [apple-photos-mcp](https://github.com/sweetrb/apple-photos-mcp) — MCP server for Apple Photos
+Part of a family of macOS MCP servers:
+
+- [apple-notes-mcp](https://github.com/sweetrb/apple-notes-mcp) — MCP server for Apple Notes (create, search, update, and export notes)
+- [apple-numbers-mcp](https://github.com/sweetrb/apple-numbers-mcp) — MCP server for Apple Numbers (read and write .numbers spreadsheets)
+- [apple-photos-mcp](https://github.com/sweetrb/apple-photos-mcp) — MCP server for Apple Photos (query metadata and export originals)

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.2",
   "description": "MCP server for Apple Mail - read, search, send, and manage emails via Claude",
   "type": "module",
   "main": "build/index.js",
@@ -30,7 +30,7 @@
     "typecheck": "tsc --noEmit",
     "version": "node -e \"const p=require('./package.json'); const f='.claude-plugin/plugin.json'; const c=JSON.parse(require('fs').readFileSync(f,'utf8')); c.version=p.version; require('fs').writeFileSync(f,JSON.stringify(c,null,2)+'\\n')\" && git add .claude-plugin/plugin.json",
     "prepublishOnly": "npm run lint && npm run test && npm run build",
-    "prepare": "husky"
+    "prepare": "husky; npm run build"
   },
   "keywords": [
     "mcp",