apple-mail-mcp 2.10.26 → 2.10.28

package/README.md

@@ -358,12 +358,19 @@ fallback.
 Configure SMTP via environment variables on the MCP server. The password is
 read from the macOS **Keychain** by default, so no secret goes in config:
 
+Non-implicit-TLS SMTP connections fail closed if STARTTLS is unavailable.
+`APPLE_MAIL_MCP_SMTP_ALLOW_PLAINTEXT=1` is a deliberate escape hatch for a
+trusted isolated server or test fixture; it disables the upgrade requirement and
+can expose credentials and message content. The server emits a warning when it
+is used. Keep the default unset.
+
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
 | `APPLE_MAIL_MCP_SMTP_HOST` | Yes | — | SMTP server hostname (e.g. `smtp.fastmail.com`) |
 | `APPLE_MAIL_MCP_SMTP_USER` | Yes | — | SMTP username |
 | `APPLE_MAIL_MCP_SMTP_PORT` | No | `465` if secure, else `587` | SMTP port |
 | `APPLE_MAIL_MCP_SMTP_SECURE` | No | `false` | `true` for implicit TLS (port 465); otherwise STARTTLS |
+| `APPLE_MAIL_MCP_SMTP_ALLOW_PLAINTEXT` | No | `0` | Set `1` only for an explicitly trusted plaintext test/server; otherwise STARTTLS is required |
 | `APPLE_MAIL_MCP_SMTP_FROM` | No | = user | From address |
 | `APPLE_MAIL_MCP_SMTP_ALLOWED_FROM` | No | — | Comma-separated sender aliases permitted as per-message From overrides |
 | `APPLE_MAIL_MCP_SMTP_PASSWORD` | No | — | Password (if set, used instead of the Keychain) |
@@ -480,6 +487,7 @@ for an explicitly-named IMAP account, never on an omitted account.
 | `APPLE_MAIL_MCP_IMAP_ACCOUNT` | No | = user | Mail account name to match for routing |
 | `APPLE_MAIL_MCP_IMAP_HOST` | No | `imap.gmail.com` | IMAP server hostname |
 | `APPLE_MAIL_MCP_IMAP_PORT` | No | `993` | IMAP port (993 = implicit TLS) |
+| `APPLE_MAIL_MCP_IMAP_ALLOW_PLAINTEXT` | No | `0` | Set `1` only for an explicitly trusted plaintext test/server; otherwise STARTTLS is required |
 | `APPLE_MAIL_MCP_IMAP_PASSWORD` | No | — | Password (if set, used instead of the Keychain) |
 | `APPLE_MAIL_MCP_IMAP_KEYCHAIN_SERVICE` | No | — | Keychain item service/server name |
 | `APPLE_MAIL_MCP_IMAP_KEYCHAIN_ACCOUNT` | No | = user | Keychain item account |
@@ -495,6 +503,12 @@ Each entry accepts `account`, `user`, `host`, `port`, `password`, `keychainServi
 `keychainAccount`. Calls route to the account matching their `account` argument (or the
 decoded `imap:` id), and each account keeps its own pooled connection.
 
+Non-implicit-TLS IMAP connections require STARTTLS and fail closed when the server
+does not offer a usable upgrade. `APPLE_MAIL_MCP_IMAP_ALLOW_PLAINTEXT=1` is a
+deliberate escape hatch for a trusted isolated server or test fixture; it disables
+the upgrade requirement and can expose credentials and message content. Keep the
+default unset.
+
 As with SMTP, the password is read from the macOS **Keychain** by default (use
 an app-specific password for Gmail/Workspace/iCloud), so no secret goes in
 config. Gmail label semantics: common names (`All Mail`, `Sent`, `Trash`,
@@ -1085,10 +1099,15 @@ Create a Mail rule with one or more conditions and actions.
 | `conditions` | object[] | Yes | One or more `{field, operator, value}` (see below) |
 | `actions` | object | Yes | At least one of `markRead`, `markFlagged`, `delete`, `moveTo` |
 | `matchAll` | boolean | No | `true` (default) = all conditions must match; `false` = any |
-| `enabled` | boolean | No | Whether the rule is enabled on creation (default `true`) |
+| `enabled` | boolean | No | Whether the rule is enabled on creation (default `false`) |
 
 Each condition is `{ field, operator, value }` where `field` is one of `from`, `to`, `cc`, `subject`, `content` and `operator` is one of `contains`, `notContains`, `equals`, `beginsWith`, `endsWith`. Actions: `markRead` / `markFlagged` / `delete` (booleans), `moveTo` (mailbox name) with optional `moveToAccount`.
 
+New rules are created **disabled by default**, including rules that delete or move
+messages. Review the conditions and actions with `list-rules` and in Mail.app,
+then call `enable-rule` explicitly when the rule is approved. Set
+`enabled: true` only when immediate activation is deliberate.
+
 **Example:**
 ```json
 {

package/build/cli.js

@@ -11919,6 +11919,7 @@ var SMTP_ENV = {
   host: "APPLE_MAIL_MCP_SMTP_HOST",
   port: "APPLE_MAIL_MCP_SMTP_PORT",
   secure: "APPLE_MAIL_MCP_SMTP_SECURE",
+  allowPlaintext: "APPLE_MAIL_MCP_SMTP_ALLOW_PLAINTEXT",
   user: "APPLE_MAIL_MCP_SMTP_USER",
   from: "APPLE_MAIL_MCP_SMTP_FROM",
   allowedFrom: "APPLE_MAIL_MCP_SMTP_ALLOWED_FROM",
@@ -11969,7 +11970,17 @@ function resolveSmtpConfig(env = process.env) {
       `No SMTP password found. Set ${SMTP_ENV.password}, or store an internet password in the Keychain for service "${env[SMTP_ENV.keychainService]?.trim() || host}" / account "${env[SMTP_ENV.keychainAccount]?.trim() || user}". ` + SETUP_HINT
     );
   }
-  return { host, port, secure, user, pass, from, allowedFrom };
+  const allowPlaintext = /^(1|true|yes|on)$/i.test(env[SMTP_ENV.allowPlaintext]?.trim() ?? "");
+  return {
+    host,
+    port,
+    secure,
+    allowPlaintext,
+    user,
+    pass,
+    from,
+    allowedFrom
+  };
 }
 function buildAttachments(attachments) {
   if (!attachments || attachments.length === 0) return void 0;
@@ -12008,10 +12019,19 @@ async function sendViaSmtp(opts, config, createTransport = import_nodemailer.def
   } catch (error) {
     return { success: false, error: error instanceof Error ? error.message : String(error) };
   }
+  const requireTLS = !cfg.secure && !cfg.allowPlaintext;
+  if (!cfg.secure && cfg.allowPlaintext) {
+    console.warn(
+      `SMTP plaintext explicitly enabled via ${SMTP_ENV.allowPlaintext}; credentials and message content may be exposed.`
+    );
+  }
   const transporter = createTransport({
     host: cfg.host,
     port: cfg.port,
     secure: cfg.secure,
+    // Port 587/143-style configurations must not silently downgrade to
+    // plaintext when the server advertises no usable TLS upgrade.
+    requireTLS,
     auth: { user: cfg.user, pass: cfg.pass }
   });
   const html = opts.htmlBody?.trim() ? opts.htmlBody : void 0;
@@ -12032,9 +12052,11 @@ async function sendViaSmtp(opts, config, createTransport = import_nodemailer.def
     });
     return { success: true, messageId: info.messageId };
   } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    const tlsHint = requireTLS ? ` STARTTLS is required for non-implicit TLS; to explicitly allow plaintext (not recommended), set ${SMTP_ENV.allowPlaintext}=1.` : "";
     return {
       success: false,
-      error: `SMTP send failed: ${error instanceof Error ? error.message : String(error)}`
+      error: `SMTP send failed: ${detail}.${tlsHint}`
     };
   } finally {
     transporter.close();

package/build/index.js

@@ -82068,7 +82068,7 @@ end tell`;
     if (!actionStmts.length) {
       return { success: false, error: "A rule needs at least one action." };
     }
-    const enabled = opts.enabled !== false;
+    const enabled = opts.enabled === true;
     const matchAll = opts.matchAll !== false;
     const script = buildAppLevelScript(`
       try
@@ -82446,6 +82446,7 @@ var SMTP_ENV = {
   host: "APPLE_MAIL_MCP_SMTP_HOST",
   port: "APPLE_MAIL_MCP_SMTP_PORT",
   secure: "APPLE_MAIL_MCP_SMTP_SECURE",
+  allowPlaintext: "APPLE_MAIL_MCP_SMTP_ALLOW_PLAINTEXT",
   user: "APPLE_MAIL_MCP_SMTP_USER",
   from: "APPLE_MAIL_MCP_SMTP_FROM",
   allowedFrom: "APPLE_MAIL_MCP_SMTP_ALLOWED_FROM",
@@ -82506,7 +82507,17 @@ function resolveSmtpConfig(env = process.env) {
       `No SMTP password found. Set ${SMTP_ENV.password}, or store an internet password in the Keychain for service "${env[SMTP_ENV.keychainService]?.trim() || host}" / account "${env[SMTP_ENV.keychainAccount]?.trim() || user}". ` + SETUP_HINT
     );
   }
-  return { host, port, secure, user, pass, from, allowedFrom };
+  const allowPlaintext = /^(1|true|yes|on)$/i.test(env[SMTP_ENV.allowPlaintext]?.trim() ?? "");
+  return {
+    host,
+    port,
+    secure,
+    allowPlaintext,
+    user,
+    pass,
+    from,
+    allowedFrom
+  };
 }
 function buildAttachments(attachments) {
   if (!attachments || attachments.length === 0) return void 0;
@@ -82545,10 +82556,19 @@ async function sendViaSmtp(opts, config2, createTransport = import_nodemailer.de
   } catch (error2) {
     return { success: false, error: error2 instanceof Error ? error2.message : String(error2) };
   }
+  const requireTLS = !cfg.secure && !cfg.allowPlaintext;
+  if (!cfg.secure && cfg.allowPlaintext) {
+    console.warn(
+      `SMTP plaintext explicitly enabled via ${SMTP_ENV.allowPlaintext}; credentials and message content may be exposed.`
+    );
+  }
   const transporter = createTransport({
     host: cfg.host,
     port: cfg.port,
     secure: cfg.secure,
+    // Port 587/143-style configurations must not silently downgrade to
+    // plaintext when the server advertises no usable TLS upgrade.
+    requireTLS,
     auth: { user: cfg.user, pass: cfg.pass }
   });
   const html = opts.htmlBody?.trim() ? opts.htmlBody : void 0;
@@ -82569,9 +82589,11 @@ async function sendViaSmtp(opts, config2, createTransport = import_nodemailer.de
     });
     return { success: true, messageId: info.messageId };
   } catch (error2) {
+    const detail = error2 instanceof Error ? error2.message : String(error2);
+    const tlsHint = requireTLS ? ` STARTTLS is required for non-implicit TLS; to explicitly allow plaintext (not recommended), set ${SMTP_ENV.allowPlaintext}=1.` : "";
     return {
       success: false,
-      error: `SMTP send failed: ${error2 instanceof Error ? error2.message : String(error2)}`
+      error: `SMTP send failed: ${detail}.${tlsHint}`
     };
   } finally {
     transporter.close();
@@ -82744,6 +82766,7 @@ var IMAP_ENV = {
   password: "APPLE_MAIL_MCP_IMAP_PASSWORD",
   keychainService: "APPLE_MAIL_MCP_IMAP_KEYCHAIN_SERVICE",
   keychainAccount: "APPLE_MAIL_MCP_IMAP_KEYCHAIN_ACCOUNT",
+  allowPlaintext: "APPLE_MAIL_MCP_IMAP_ALLOW_PLAINTEXT",
   // C2 multi-account: JSON array of additional accounts, e.g.
   // [{"account":"Work","user":"me@co.com","host":"imap.co.com","keychainService":"imap.co.com"}]
   accounts: "APPLE_MAIL_MCP_IMAP_ACCOUNTS"
@@ -82784,6 +82807,9 @@ function depsForAccount(account, deps) {
 function depsForMessageRef(ref, deps) {
   return depsForAccount(ref.account, deps);
 }
+function isTruthySetting(value) {
+  return /^(1|true|yes|on)$/i.test(value?.trim() ?? "");
+}
 function specMatchesSelector(spec, selector) {
   return spec.accountLabel === selector || spec.user === selector || (spec.aliases?.includes(selector) ?? false);
 }
@@ -82849,7 +82875,7 @@ function listImapAccountSpecs(env = process.env) {
   }
   return specs;
 }
-function specToConfig(spec) {
+function specToConfig(spec, allowPlaintext = false) {
   if (!Number.isInteger(spec.port) || spec.port <= 0) {
     throw new Error(`Invalid IMAP port for account "${spec.accountLabel}": "${spec.port}".`);
   }
@@ -82866,6 +82892,7 @@ function specToConfig(spec) {
     host: spec.host,
     port: spec.port,
     secure: spec.port === 993,
+    allowPlaintext,
     user: spec.user,
     pass,
     accountLabel: spec.accountLabel
@@ -82883,9 +82910,10 @@ function listImapAccountLabels(env = process.env) {
 }
 function resolveImapConfigs(env = process.env) {
   const out = [];
+  const allowPlaintext = isTruthySetting(env[IMAP_ENV.allowPlaintext]);
   for (const spec of listImapAccountSpecs(env)) {
     try {
-      out.push(specToConfig(spec));
+      out.push(specToConfig(spec, allowPlaintext));
     } catch (e) {
       console.error(`Skipping IMAP account "${spec.accountLabel}": ${String(e)}`);
     }
@@ -82910,19 +82938,45 @@ function resolveImapConfig(env = process.env, account) {
   } else {
     spec = specs[0];
   }
-  return specToConfig(spec);
+  return specToConfig(spec, isTruthySetting(env[IMAP_ENV.allowPlaintext]));
 }
-var defaultConnect = async (cfg) => {
-  const client = new import_imapflow.ImapFlow({
+function buildImapConnectionOptions(cfg) {
+  return {
     host: cfg.host,
     port: cfg.port,
     secure: cfg.secure,
+    // ImapFlow reads this as a tri-state, and the distinction matters:
+    //   true      -> require STARTTLS; fail if the server does not offer it
+    //   false     -> NEVER STARTTLS, even if the server advertises it
+    //   undefined -> opportunistic upgrade (ImapFlow's documented default)
+    //
+    // secure=true already has implicit TLS, so there is no upgrade to negotiate.
+    // Without the escape hatch the upgrade is required. WITH it we must fall back
+    // to `undefined`, not `false`: the escape hatch means "let me reach a server
+    // that cannot do TLS", not "never encrypt". Sending `false` suppressed the
+    // upgrade even against servers still offering it, so enabling the opt-out for
+    // one broken account silently downgraded every other plaintext-port account
+    // below what it already negotiated before this option existed.
+    doSTARTTLS: cfg.secure || cfg.allowPlaintext ? void 0 : true,
     auth: { user: cfg.user, pass: cfg.pass },
     logger: false
-  });
+  };
+}
+var defaultConnect = async (cfg) => {
+  const client = new import_imapflow.ImapFlow(buildImapConnectionOptions(cfg));
   client.on("error", () => {
   });
-  await client.connect();
+  try {
+    await client.connect();
+  } catch (error2) {
+    if (!cfg.secure && !cfg.allowPlaintext) {
+      const detail = error2 instanceof Error ? error2.message : String(error2);
+      throw new Error(
+        `IMAP connection failed: ${detail}. STARTTLS is required for non-implicit TLS; to explicitly allow plaintext (not recommended), set ${IMAP_ENV.allowPlaintext}=1.`
+      );
+    }
+    throw error2;
+  }
   return client;
 };
 function resolveMailboxPath(mailbox, mode) {
@@ -84214,16 +84268,20 @@ function subjectFromGetMessage(info) {
 // src/services/imapIdle.ts
 var import_imapflow2 = __toESM(require_imap_flow(), 1);
 var defaultIdleConnect = async (cfg) => {
-  const client = new import_imapflow2.ImapFlow({
-    host: cfg.host,
-    port: cfg.port,
-    secure: cfg.secure,
-    auth: { user: cfg.user, pass: cfg.pass },
-    logger: false
-  });
+  const client = new import_imapflow2.ImapFlow(buildImapConnectionOptions(cfg));
   client.on("error", () => {
   });
-  await client.connect();
+  try {
+    await client.connect();
+  } catch (error2) {
+    if (!cfg.secure && !cfg.allowPlaintext) {
+      const detail = error2 instanceof Error ? error2.message : String(error2);
+      throw new Error(
+        `IMAP IDLE connection failed: ${detail}. STARTTLS is required for non-implicit TLS; to explicitly allow plaintext (not recommended), set ${IMAP_ENV.allowPlaintext}=1.`
+      );
+    }
+    throw error2;
+  }
   return client;
 };
 var ImapIdleWatcher = class {
@@ -86249,7 +86307,7 @@ registerTool(
         "At least one action is required (markRead, markFlagged, delete, or moveTo)"
       ),
       matchAll: external_exports.boolean().default(true),
-      enabled: external_exports.boolean().default(true)
+      enabled: external_exports.boolean().default(false).describe("Enable immediately; defaults to false so the rule must be reviewed first")
     },
     outputSchema: {
       name: external_exports.string().optional(),

package/package.json

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