apple-mail-mcp 2.2.0 → 2.4.0

package/README.md

@@ -6,6 +6,7 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that e
 [![npm downloads](https://img.shields.io/npm/dm/apple-mail-mcp)](https://www.npmjs.com/package/apple-mail-mcp)
 [![node](https://img.shields.io/node/v/apple-mail-mcp)](https://www.npmjs.com/package/apple-mail-mcp)
 [![CI](https://github.com/sweetrb/apple-mail-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sweetrb/apple-mail-mcp/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/sweetrb/apple-mail-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/sweetrb/apple-mail-mcp)
 [![platform: macOS](https://img.shields.io/badge/platform-macOS-111?logo=apple&logoColor=white)](https://www.apple.com/macos/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![MCP](https://img.shields.io/badge/MCP-server-blue)](https://modelcontextprotocol.io)
@@ -255,7 +256,7 @@ Send a new email immediately.
 | `bcc` | string[] | No | BCC recipients |
 | `account` | string | No | Send from specific account (with `transport: "smtp"`, overrides the From address) |
 | `attachments` | (string \| {filename, contentBase64})[] | No | Up to 20 attachments: absolute file paths (e.g., `"/Users/me/report.pdf"`) and/or inline `{filename, contentBase64}` objects for content not on disk |
-| `transport` | `"applescript"` \| `"smtp"` | No | Send transport (default `"applescript"`). Use `"smtp"` to send clean MIME directly, avoiding the macOS 15+ Mail.app `<blockquote>` wrapping — see [SMTP transport](#smtp-transport) |
+| `transport` | `"applescript"` \| `"smtp"` | No | Send transport. If omitted, **SMTP is used automatically when configured** (otherwise AppleScript). Pass `"smtp"` to require clean MIME, or `"applescript"` to force the Mail.app path — see [SMTP transport](#smtp-transport) |
 
 **Example:**
 ```json
@@ -274,8 +275,25 @@ On macOS 15+ (Sequoia/Tahoe), Mail.app wraps any AppleScript-injected body in
 `<blockquote type="cite">` under the `Apple-Mail-URLShareWrapperClass` template,
 so emails sent through the default `applescript` transport render to recipients
 as if they were quoted/forwarded (Apple radar **FB11734014**, open since
-Ventura). Passing `transport: "smtp"` bypasses Mail.app entirely and submits
-clean MIME via SMTP.
+Ventura). The SMTP transport bypasses Mail.app entirely and submits clean MIME
+directly. **Once SMTP is configured, `send-email` uses it automatically** (no
+need to pass `transport` per call); pass `transport: "applescript"` to force the
+Mail.app path.
+
+Two differences to know when SMTP is auto-preferred:
+
+- **No Sent-folder copy.** SMTP submission does not file the message in Mail.app's
+  Sent mailbox (the server's own "save to Sent" may, depending on provider). Use
+  `transport: "applescript"` if you need the local Sent copy.
+- **`account` is a From override, not account selection.** Over SMTP, `account`
+  is used as the From address only when it is an email address; a Mail.app
+  account *label* (e.g. `"Work"`) can't select an account over SMTP, so a call
+  that passes one is left on the AppleScript path automatically. To force
+  account selection, pass `transport: "applescript"` explicitly.
+
+Both plain-text and HTML bodies are supported — over SMTP an HTML body (CLI
+`--html-body-file`) is sent as `multipart/alternative` with the plain-text
+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:
@@ -292,23 +310,48 @@ read from the macOS **Keychain** by default, so no secret goes in config:
 | `APPLE_MAIL_MCP_SMTP_KEYCHAIN_ACCOUNT` | No | = user | Keychain item account |
 
 Store the password in the Keychain once (an app-specific password for Gmail/
-iCloud), e.g.:
+iCloud). A generic-password item with an explicit service name keeps it from
+colliding with the system mail account password, and matches
+`APPLE_MAIL_MCP_SMTP_KEYCHAIN_SERVICE`:
 
 ```bash
+# Fastmail (Keychain service defaults to the host)
 security add-internet-password -s smtp.fastmail.com -a you@example.com -w
+
+# Gmail / Google Workspace, using a dedicated Keychain service name:
+#   APPLE_MAIL_MCP_SMTP_HOST=smtp.gmail.com
+#   APPLE_MAIL_MCP_SMTP_USER=you@gmail.com
+#   APPLE_MAIL_MCP_SMTP_KEYCHAIN_SERVICE=apple-mail-mcp-smtp
+security add-generic-password -s apple-mail-mcp-smtp -a you@gmail.com -w
 ```
 
-Then send:
+Once the env vars are set, a plain `send-email` (no `transport`) already goes
+out clean:
 ```json
 {
   "to": ["colleague@company.com"],
   "subject": "Standings",
-  "body": "Plain body — no blockquote wrapping.",
-  "transport": "smtp"
+  "body": "Plain body — no blockquote wrapping."
 }
 ```
 
-The default `applescript` transport is unchanged; SMTP is opt-in per call.
+###### `apple-mail-send` CLI (no MCP server required)
+
+The package also installs an `apple-mail-send` binary — a standalone CLI over the
+same SMTP path, for cron jobs, scheduled tasks, and scripts that can't run an MCP
+session. It reads the identical `APPLE_MAIL_MCP_SMTP_*` env + Keychain config:
+
+```bash
+apple-mail-send \
+  --from you@example.com --to colleague@company.com \
+  --subject "Standings" --body-file /tmp/body.txt \
+  [--html-body-file /tmp/body.html] [--attach /tmp/report.pdf]
+```
+
+Repeatable `--to`/`--cc`/`--bcc`/`--attach`; an `--html-body-file` is sent as a
+`multipart/alternative` alongside the plain `--body-file`. Exit codes follow
+`sysexits.h`: `0` success, `64` usage error, `66` unreadable body file, `78`
+SMTP not configured.
 
 ##### IMAP backend — opt-in
 

package/build/cli.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { sendViaSmtp, resolveSmtpConfig } from "./services/smtpMailer.js";
+/** sysexits.h codes used so callers can distinguish failure modes. */
+export declare const EX_USAGE = 64;
+export declare const EX_NOINPUT = 66;
+export declare const EX_CONFIG = 78;
+/** Injectable dependencies, defaulted to the real implementations. */
+export interface CliDeps {
+    send?: typeof sendViaSmtp;
+    resolveConfig?: typeof resolveSmtpConfig;
+    readTextFile?: (path: string) => string;
+    stdout?: (line: string) => void;
+    stderr?: (line: string) => void;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Parses argv, sends the email, and returns a process exit code. Pure with
+ * respect to its deps (no direct process/console access) so it can be unit
+ * tested without the network or Keychain.
+ *
+ * @param argv - arguments AFTER `node cli.js` (i.e. `process.argv.slice(2)`)
+ */
+export declare function runCli(argv: string[], deps?: CliDeps): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/build/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAyBA,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAY,MAAM,0BAA0B,CAAC;AAGpF,sEAAsE;AACtE,eAAO,MAAM,QAAQ,KAAK,CAAC;AAC3B,eAAO,MAAM,UAAU,KAAK,CAAC;AAC7B,eAAO,MAAM,SAAS,KAAK,CAAC;AAqB5B,sEAAsE;AACtE,MAAM,WAAW,OAAO;IACtB,IAAI,CAAC,EAAE,OAAO,WAAW,CAAC;IAC1B,aAAa,CAAC,EAAE,OAAO,iBAAiB,CAAC;IACzC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACxC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,OAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAwGhF"}

package/build/cli.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/**
+ * `apple-mail-send` — standalone clean-SMTP email CLI.
+ *
+ * A thin command-line front end over {@link sendViaSmtp} so scheduled tasks,
+ * cron jobs, and other scripts can send clean MIME (no Mail.app blockquote
+ * wrapping, issue #12) WITHOUT a running MCP server. It reuses the exact same
+ * SMTP config resolution as the MCP `send-email` tool — env vars first, then the
+ * macOS Keychain (see the README "SMTP transport" section).
+ *
+ * The flag surface intentionally mirrors the legacy nhl-bracket-tracker
+ * `send_email.py` (--from/--to/--cc/--bcc/--subject/--body-file/
+ * --html-body-file/--attach) and its exit codes (78 = EX_CONFIG when SMTP is
+ * not configured) so callers can drop this in as a replacement.
+ *
+ * Usage:
+ *   apple-mail-send --from me@example.com --to you@example.com \
+ *     --subject "Hi" --body-file /tmp/body.txt \
+ *     [--html-body-file /tmp/body.html] [--attach /tmp/report.pdf]
+ *
+ * @module cli
+ */
+import { readFileSync, realpathSync } from "fs";
+import { fileURLToPath } from "url";
+import { parseArgs } from "util";
+import { sendViaSmtp, resolveSmtpConfig, SMTP_ENV } from "./services/smtpMailer.js";
+/** sysexits.h codes used so callers can distinguish failure modes. */
+export const EX_USAGE = 64;
+export const EX_NOINPUT = 66;
+export const EX_CONFIG = 78;
+const USAGE = `apple-mail-send — send a clean email via SMTP (no Mail.app blockquote wrapping).
+
+Required:
+  --from <addr>         Sender address (must be allowed by the SMTP server)
+  --to <addr>           Recipient (repeatable)
+  --subject <text>      Subject line
+  --body-file <path>    UTF-8 file with the plain-text body
+
+Optional:
+  --cc <addr>           CC recipient (repeatable)
+  --bcc <addr>          BCC recipient (repeatable)
+  --html-body-file <p>  UTF-8 file with an HTML alternative body (sends
+                        multipart/alternative)
+  --attach <path>       Absolute path to a file to attach (repeatable)
+  --help                Show this help
+
+SMTP connection comes from ${SMTP_ENV.host} / ${SMTP_ENV.user} (+ password via
+${SMTP_ENV.password} or the macOS Keychain). See the README "SMTP transport".`;
+/**
+ * Parses argv, sends the email, and returns a process exit code. Pure with
+ * respect to its deps (no direct process/console access) so it can be unit
+ * tested without the network or Keychain.
+ *
+ * @param argv - arguments AFTER `node cli.js` (i.e. `process.argv.slice(2)`)
+ */
+export async function runCli(argv, deps = {}) {
+    const send = deps.send ?? sendViaSmtp;
+    const resolveConfig = deps.resolveConfig ?? resolveSmtpConfig;
+    const readTextFile = deps.readTextFile ?? ((p) => readFileSync(p, "utf8"));
+    const out = deps.stdout ?? ((l) => console.log(l));
+    const err = deps.stderr ?? ((l) => console.error(l));
+    const env = deps.env ?? process.env;
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: argv,
+            options: {
+                from: { type: "string" },
+                to: { type: "string", multiple: true },
+                cc: { type: "string", multiple: true },
+                bcc: { type: "string", multiple: true },
+                subject: { type: "string" },
+                "body-file": { type: "string" },
+                "html-body-file": { type: "string" },
+                attach: { type: "string", multiple: true },
+                help: { type: "boolean" },
+            },
+            allowPositionals: false,
+        }));
+    }
+    catch (e) {
+        err(e instanceof Error ? e.message : String(e));
+        err(USAGE);
+        return EX_USAGE;
+    }
+    if (values.help) {
+        out(USAGE);
+        return 0;
+    }
+    const missing = [];
+    if (!values.from)
+        missing.push("--from");
+    if (!values.to || values.to.length === 0)
+        missing.push("--to");
+    if (!values.subject)
+        missing.push("--subject");
+    if (!values["body-file"])
+        missing.push("--body-file");
+    if (missing.length > 0) {
+        err(`Missing required argument(s): ${missing.join(", ")}`);
+        err(USAGE);
+        return EX_USAGE;
+    }
+    // Resolve the full SMTP config up front (host/user/port + Keychain password)
+    // so a missing password counts as EX_CONFIG (78) — the same actionable
+    // "needs setup" signal as a missing host/user — rather than a generic failure.
+    let config;
+    try {
+        config = resolveConfig(env);
+    }
+    catch (e) {
+        err(e instanceof Error ? e.message : String(e));
+        err(`See the README "SMTP transport" section.`);
+        return EX_CONFIG;
+    }
+    let body;
+    let htmlBody;
+    try {
+        body = readTextFile(values["body-file"]);
+        if (values["html-body-file"])
+            htmlBody = readTextFile(values["html-body-file"]);
+    }
+    catch (e) {
+        err(`Could not read body file: ${e instanceof Error ? e.message : String(e)}`);
+        return EX_NOINPUT;
+    }
+    const attachments = values.attach?.length
+        ? values.attach
+        : undefined;
+    const result = await send({
+        from: values.from,
+        to: values.to,
+        cc: values.cc,
+        bcc: values.bcc,
+        subject: values.subject,
+        body,
+        htmlBody,
+        attachments,
+    }, config);
+    if (!result.success) {
+        err(result.error ?? "SMTP send failed.");
+        return 1;
+    }
+    out(`sent to ${values.to.join(", ")} from ${values.from}`);
+    return 0;
+}
+// Entry point when invoked directly (not when imported by tests). Resolve both
+// sides through the filesystem so it still matches when launched via the npm
+// `bin` symlink (argv[1] is the symlink; import.meta.url is the real build file).
+function isInvokedDirectly() {
+    if (typeof process === "undefined" || !process.argv?.[1])
+        return false;
+    try {
+        return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    }
+}
+if (isInvokedDirectly()) {
+    runCli(process.argv.slice(2)).then((code) => process.exit(code), (e) => {
+        console.error(e instanceof Error ? (e.stack ?? e.message) : String(e));
+        process.exit(1);
+    });
+}