apple-mail-mcp 2.2.0 → 2.4.0

package/build/services/smtpMailer.d.ts

@@ -9,8 +9,9 @@
  *
  * Connection settings come from environment variables; the password is read
  * from the macOS Keychain via the `security` CLI by default so no secret is
- * ever placed in config. AppleScript remains the default transport — SMTP is
- * opt-in per call (`transport: "smtp"`).
+ * ever placed in config. When SMTP is configured, `send-email` auto-prefers it
+ * over AppleScript (opt out per call with `transport: "applescript"`); see
+ * {@link shouldUseSmtp}.
  *
  * @module services/smtpMailer
  */
@@ -20,6 +21,7 @@ import type { AttachmentInput } from "../types.js";
 export interface SmtpSendOptions {
     to: string[];
     subject: string;
+    /** Plain-text body. Always sent as the text/plain part. */
     body: string;
     cc?: string[];
     bcc?: string[];
@@ -27,6 +29,13 @@ export interface SmtpSendOptions {
     from?: string;
     /** Files to attach: absolute paths and/or inline base64 content (B4). */
     attachments?: AttachmentInput[];
+    /**
+     * Optional HTML body. When provided, the message is sent as
+     * multipart/alternative ({@link SmtpSendOptions.body} as the text/plain part,
+     * this as the text/html part) so clients pick the richer rendering while
+     * plain-text clients still get a clean fallback.
+     */
+    htmlBody?: string;
 }
 /** Resolved SMTP connection configuration. */
 export interface SmtpConfig {
@@ -57,6 +66,28 @@ export declare const SMTP_ENV: {
     readonly keychainService: "APPLE_MAIL_MCP_SMTP_KEYCHAIN_SERVICE";
     readonly keychainAccount: "APPLE_MAIL_MCP_SMTP_KEYCHAIN_ACCOUNT";
 };
+/**
+ * Cheap check for whether the SMTP transport is configured at all, i.e. the two
+ * required settings ({@link SMTP_ENV.host} and {@link SMTP_ENV.user}) are
+ * present. Used to auto-prefer SMTP over AppleScript when no transport is
+ * explicitly requested, and by `doctor`. Does NOT touch the Keychain or verify
+ * the password — a misconfigured password still surfaces a clear error at send
+ * time via {@link resolveSmtpConfig}.
+ */
+export declare function isSmtpConfigured(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Decides whether `send-email` should use the SMTP transport for this call.
+ *
+ * - explicit `"smtp"` → always SMTP (config errors surface, no fallback);
+ * - explicit `"applescript"` → always the Mail.app path;
+ * - omitted → SMTP when configured, **except** when a non-email `account` label
+ *   (a Mail.app account name such as `"Work"`) is supplied. That requests
+ *   account-based sending, which only the AppleScript path can do, so we honor
+ *   the caller's intent instead of silently switching their account. An
+ *   `account` that is an email address is treated as a From override and does
+ *   not block SMTP.
+ */
+export declare function shouldUseSmtp(transport: "applescript" | "smtp" | undefined, account: string | undefined, configured?: boolean): boolean;
 /**
  * Reads a password from the macOS login Keychain via the `security` CLI.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"smtpMailer.d.ts","sourceRoot":"","sources":["../../src/services/smtpMailer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,UAAU,MAAM,YAAY,CAAC;AAIpC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,EAAE,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;CACjC;AAED,8CAA8C;AAC9C,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,8BAA8B;AAC9B,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;CASX,CAAC;AAEX;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAcpF;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,UAAU,CA8ClF;AAqBD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,eAAe,EACrB,MAAM,CAAC,EAAE,UAAU,EACnB,eAAe,GAAE,OAAO,UAAU,CAAC,eAA4C,GAC9E,OAAO,CAAC,cAAc,CAAC,CAyCzB"}
+{"version":3,"file":"smtpMailer.d.ts","sourceRoot":"","sources":["../../src/services/smtpMailer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,UAAU,MAAM,YAAY,CAAC;AAIpC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,EAAE,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,8CAA8C;AAC9C,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,8BAA8B;AAC9B,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;CASX,CAAC;AAEX;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAE9E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,EAC7C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,UAAU,GAAE,OAA4B,GACvC,OAAO,CAMT;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAcpF;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,UAAU,CA8ClF;AAqBD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,eAAe,EACrB,MAAM,CAAC,EAAE,UAAU,EACnB,eAAe,GAAE,OAAO,UAAU,CAAC,eAA4C,GAC9E,OAAO,CAAC,cAAc,CAAC,CA6CzB"}

package/build/services/smtpMailer.js

@@ -9,8 +9,9 @@
  *
  * Connection settings come from environment variables; the password is read
  * from the macOS Keychain via the `security` CLI by default so no secret is
- * ever placed in config. AppleScript remains the default transport — SMTP is
- * opt-in per call (`transport: "smtp"`).
+ * ever placed in config. When SMTP is configured, `send-email` auto-prefers it
+ * over AppleScript (opt out per call with `transport: "applescript"`); see
+ * {@link shouldUseSmtp}.
  *
  * @module services/smtpMailer
  */
@@ -32,6 +33,39 @@ export const SMTP_ENV = {
     keychainService: "APPLE_MAIL_MCP_SMTP_KEYCHAIN_SERVICE",
     keychainAccount: "APPLE_MAIL_MCP_SMTP_KEYCHAIN_ACCOUNT",
 };
+/**
+ * Cheap check for whether the SMTP transport is configured at all, i.e. the two
+ * required settings ({@link SMTP_ENV.host} and {@link SMTP_ENV.user}) are
+ * present. Used to auto-prefer SMTP over AppleScript when no transport is
+ * explicitly requested, and by `doctor`. Does NOT touch the Keychain or verify
+ * the password — a misconfigured password still surfaces a clear error at send
+ * time via {@link resolveSmtpConfig}.
+ */
+export function isSmtpConfigured(env = process.env) {
+    return Boolean(env[SMTP_ENV.host]?.trim() && env[SMTP_ENV.user]?.trim());
+}
+/**
+ * Decides whether `send-email` should use the SMTP transport for this call.
+ *
+ * - explicit `"smtp"` → always SMTP (config errors surface, no fallback);
+ * - explicit `"applescript"` → always the Mail.app path;
+ * - omitted → SMTP when configured, **except** when a non-email `account` label
+ *   (a Mail.app account name such as `"Work"`) is supplied. That requests
+ *   account-based sending, which only the AppleScript path can do, so we honor
+ *   the caller's intent instead of silently switching their account. An
+ *   `account` that is an email address is treated as a From override and does
+ *   not block SMTP.
+ */
+export function shouldUseSmtp(transport, account, configured = isSmtpConfigured()) {
+    if (transport === "smtp")
+        return true;
+    if (transport === "applescript")
+        return false;
+    if (!configured)
+        return false;
+    const isAccountLabel = Boolean(account && !account.includes("@"));
+    return !isAccountLabel;
+}
 /**
  * Reads a password from the macOS login Keychain via the `security` CLI.
  *
@@ -152,6 +186,7 @@ export async function sendViaSmtp(opts, config, createTransport = nodemailer.cre
         secure: cfg.secure,
         auth: { user: cfg.user, pass: cfg.pass },
     });
+    const html = opts.htmlBody?.trim() ? opts.htmlBody : undefined;
     try {
         const info = await transporter.sendMail({
             from: opts.from?.trim() || cfg.from,
@@ -160,6 +195,8 @@ export async function sendViaSmtp(opts, config, createTransport = nodemailer.cre
             bcc: opts.bcc,
             subject: opts.subject,
             text: opts.body,
+            // When present, nodemailer emits multipart/alternative (text + html).
+            html,
             attachments,
         });
         return { success: true, messageId: info.messageId };

package/build/tools/doctor.js

@@ -1,5 +1,5 @@
 import { imapHealthCheck, IMAP_ENV, listImapAccountLabels } from "../services/imapClient.js";
-import { SMTP_ENV } from "../services/smtpMailer.js";
+import { SMTP_ENV, isSmtpConfigured } from "../services/smtpMailer.js";
 export async function runDoctor(mailManager) {
     const checks = [];
     // 1. Mail.app reachability + Automation permission (existing health check).
@@ -56,10 +56,10 @@ export async function runDoctor(mailManager) {
     const smtpHost = process.env[SMTP_ENV.host]?.trim();
     checks.push({
         name: "SMTP transport",
-        status: smtpHost ? "ok" : "warn",
-        detail: smtpHost
-            ? `configured (${smtpHost}); send-email transport:"smtp" is available`
-            : `not configured — send-email uses AppleScript (subject to macOS 15+ blockquote wrapping). Set ${SMTP_ENV.host} to enable.`,
+        status: isSmtpConfigured() ? "ok" : "warn",
+        detail: isSmtpConfigured()
+            ? `configured (${smtpHost}); send-email auto-prefers clean SMTP (no Mail.app Sent-folder copy; a non-email "account" label still routes to AppleScript). Pass transport:"applescript" to force Mail.app. The apple-mail-send CLI is also available.`
+            : `not configured — send-email uses AppleScript (subject to macOS 15+ blockquote wrapping). Set ${SMTP_ENV.host} and ${SMTP_ENV.user} (+ password via Keychain) to enable.`,
     });
     const healthy = !checks.some((c) => c.status === "fail");
     return { healthy, checks };

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "apple-mail-mcp",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "MCP server for Apple Mail - read, search, send, and manage emails via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",
   "types": "build/index.d.ts",
   "bin": {
-    "apple-mail-mcp": "build/index.js"
+    "apple-mail-mcp": "build/index.js",
+    "apple-mail-send": "build/cli.js"
   },
   "files": [
     "build",