apple-tools-mcp 2.1.5 → 3.0.1

package/lib/mailWrite.js

@@ -182,6 +182,27 @@ export const MAIL_SE_PROBE_TIMEOUT_MS = 4000;
 export const SYSTEM_EVENTS_AUTOMATION_PROBE_TIMEOUT_MS = 30000;
 /** Compose osascript budget (make + keystroke + send). Far below the ~60s SE wedge. */
 export const MAIL_COMPOSE_TIMEOUT_MS = 25000;
+// Regression (2026-09-23): atmFindMessage's `messages of <box> whose message
+// id is X` scan is genuinely slow on a large mailbox (observed 30-38s on a
+// ~68,500-message account, even matching in the first/fastest box checked --
+// this is a known AppleScript `whose`-filter characteristic, not specific to
+// one mailbox choice). mail_mark / mail_archive / mail_trash had no explicit
+// timeout at all (defaulting to the shared 30s DEFAULT_SCRIPT_TIMEOUT_MS),
+// so they timed out before that scan could finish on this account. Widened
+// with real margin over the observed worst case, while staying under the
+// MCP client SDK's 60s default CallTool timeout (mail_send's fix comment
+// above SENT_VERIFY_ATTEMPTS has the full story on why that ceiling matters).
+export const MAIL_FIND_TIMEOUT_MS = 50000;
+// Whole tool call must answer before the MCP client's default 60s CallTool
+// timeout. 55s leaves the process time to format that answer.
+export const MCP_CALL_DEADLINE_MS = 55000;
+// mail_reply / mail_forward run atmFindMessage and then the send inside one
+// osascript. The find alone has been observed at 30-38s, so a combined
+// budget at that observed ceiling kills the script after the lookup and
+// before send. Match the find-only budget (50s): a 38s lookup still has
+// ~12s left for send. Verification after the script returns is capped to
+// whatever remains under MCP_CALL_DEADLINE_MS, not a second full window.
+export const MAIL_FIND_AND_SEND_TIMEOUT_MS = MAIL_FIND_TIMEOUT_MS;
 export const MAIL_SE_APPLEEVENT_TIMEOUT_SEC = 8;
 export const MAIL_APPLEEVENT_TIMEOUT_SEC = 15;
 export const MAIL_SE_PROBE_APPLEEVENT_TIMEOUT_SEC = 3;
@@ -840,11 +861,41 @@ export const SENT_VERIFY_NOT_FOUND = "NOT_FOUND";
 /** Older hang-recovery scripts returned FOUND to mean Sent. Still accepted. */
 export const SENT_VERIFY_FOUND = "FOUND";
 export const SENT_VERIFY_TIMEOUT_MS = 15000;
-export const SENT_VERIFY_ATTEMPTS = 3;
-export const SENT_VERIFY_RETRY_MS = 400;
+/** Skip a poll that could not return before the call deadline. */
+export const SENT_VERIFY_MIN_POLL_MS = 1000;
+// Regression (2026-09-23): 6 consecutive real sends on an iCloud/IMAP
+// account all delivered successfully, but each took a different, unbounded
+// amount of time before Mail made the message queryable in Sent via
+// AppleScript (observed: 20s, 20s, 30s, 65s, 47s, ~64s), even though Mail's
+// `send` call itself returned in a few seconds. The old budget (3 attempts
+// x 400ms = ~1.2s) gave up long before that and reported a false-negative
+// failure on messages that really were delivered.
+//
+// A larger budget alone cannot fully fix this: the MCP client SDK's own
+// default CallTool timeout is 60s (McpError -32001 "Request timed out"),
+// confirmed by testing an attempts=30/retryMs=4000 (~120s worst case)
+// budget against a real client -- the client gave up and errored while the
+// server was still polling and about to find the (already-delivered)
+// message. Any purely-synchronous verification longer than that ceiling is
+// self-defeating: it cannot outrun the client's own timeout, and going past
+// it only means the client sees a raw protocol timeout instead of a useful
+// answer. So the budget below stays safely under that ceiling (well under
+// 60s total including the initial send), and a miss within budget is
+// reported as *unconfirmed*, not failed -- honesty over false confidence,
+// since 9/9 real sends observed here eventually succeeded.
+//
+// Attempt count and sleep are a ceiling, not a guaranteed wait. Each poll
+// also runs under SENT_VERIFY_TIMEOUT_MS (15s), so 6 x 15s plus the sleeps
+// can blow past the 60s client timeout if a poll hangs. verifyQueuedMessage
+// stops at MCP_CALL_DEADLINE_MS and shrinks each poll to the time left.
+export const SENT_VERIFY_ATTEMPTS = 6;
+export const SENT_VERIFY_RETRY_MS = 2000;
 
 export const MAIL_VERIFY_MISS_GUIDANCE =
-  "Mail reported the send call succeeded, but the message was not found in Sent or Outbox. Do not assume it was delivered.";
+  "Mail reported the send call succeeded, and this account's Sent folder has been observed to take up to a minute or more to " +
+  "reflect a new message (iCloud/IMAP sync lag), longer than it is safe to block a single tool call for. This is not a known " +
+  "failure -- treat it as unconfirmed. Check Sent (and Outbox) before deciding whether to retry; retrying a message that " +
+  "already landed sends a second copy.";
 
 function defaultSentVerifySleep(ms) {
   if (!ms || ms <= 0) return;
@@ -853,11 +904,13 @@ function defaultSentVerifySleep(ms) {
 
 /** Test hook: skip the retry delay without changing attempt count. */
 export const sentVerifyClock = {
-  sleep: defaultSentVerifySleep
+  sleep: defaultSentVerifySleep,
+  now: () => Date.now()
 };
 
 export function resetSentVerifyClock() {
   sentVerifyClock.sleep = defaultSentVerifySleep;
+  sentVerifyClock.now = () => Date.now();
 }
 
 /**
@@ -1158,10 +1211,12 @@ function pickSentVerifyScript({
  * Compose matches require To + subject (Message-ID when available) — never
  * subject alone. Returns a hit object or null. Verify failure is not success.
  */
-export function recoverIfInSent(match = {}) {
+export function recoverIfInSent(match = {}, { timeout = SENT_VERIFY_TIMEOUT_MS } = {}) {
   const script = pickSentVerifyScript(match);
   if (!script) return null;
-  const result = runAppleScript(script, { timeout: SENT_VERIFY_TIMEOUT_MS, appName: "Mail" });
+  const pollTimeout = Math.min(SENT_VERIFY_TIMEOUT_MS, Math.max(0, timeout));
+  if (pollTimeout < SENT_VERIFY_MIN_POLL_MS) return null;
+  const result = runAppleScript(script, { timeout: pollTimeout, appName: "Mail" });
   if (!result.ok) return null;
   return parseSentVerifyOutput(result.output);
 }
@@ -1169,13 +1224,25 @@ export function recoverIfInSent(match = {}) {
 /**
  * Poll Sent/Outbox after a send that returned without throw.
  */
-export function verifyQueuedMessage(match = {}, { attempts = SENT_VERIFY_ATTEMPTS, retryMs = SENT_VERIFY_RETRY_MS } = {}) {
+export function verifyQueuedMessage(match = {}, {
+  attempts = SENT_VERIFY_ATTEMPTS,
+  retryMs = SENT_VERIFY_RETRY_MS,
+  deadlineMs = null
+} = {}) {
+  const deadline = Number.isFinite(deadlineMs)
+    ? deadlineMs
+    : sentVerifyClock.now() + MCP_CALL_DEADLINE_MS;
   let last = null;
   const n = Math.max(1, attempts);
   for (let i = 0; i < n; i++) {
-    last = recoverIfInSent(match);
+    const remaining = deadline - sentVerifyClock.now();
+    if (remaining < SENT_VERIFY_MIN_POLL_MS) break;
+    last = recoverIfInSent(match, { timeout: Math.min(SENT_VERIFY_TIMEOUT_MS, remaining) });
     if (last) return last;
-    if (i < n - 1) sentVerifyClock.sleep(retryMs);
+    if (i >= n - 1) break;
+    const sleepFor = Math.min(retryMs, deadline - sentVerifyClock.now() - SENT_VERIFY_MIN_POLL_MS);
+    if (sleepFor <= 0) break;
+    sentVerifyClock.sleep(sleepFor);
   }
   return last;
 }
@@ -1282,7 +1349,7 @@ function sendVerifiedSuccess({ action, successSummary, details, verified, recove
 }
 
 function verifyMissMessage(action, summary) {
-  return `${action} failed — attempted to ${summary}. ${MAIL_VERIFY_MISS_GUIDANCE}`;
+  return `${action}: unconfirmed — attempted to ${summary}. ${MAIL_VERIFY_MISS_GUIDANCE}`;
 }
 
 function finalizeMailWrite({
@@ -1297,15 +1364,20 @@ function finalizeMailWrite({
   to = null,
   messageId = null,
   successSummary,
-  details
+  details,
+  deadlineMs = null
 }) {
   const match = { inReplyTo, subject, forwardTo, to, messageId };
+  const deadline = Number.isFinite(deadlineMs)
+    ? deadlineMs
+    : sentVerifyClock.now() + MCP_CALL_DEADLINE_MS;
+  const remaining = () => deadline - sentVerifyClock.now();
 
   if (result.ok) {
     if (!sendNow) {
       return { ok: true, delivered: false, mailbox: null, message: writeSuccessMessage(action, successSummary, details) };
     }
-    const verified = verifyQueuedMessage(match);
+    const verified = verifyQueuedMessage(match, { deadlineMs: deadline });
     if (!verified) {
       return { ok: false, delivered: false, mailbox: null, message: verifyMissMessage(action, summary) };
     }
@@ -1313,7 +1385,7 @@ function finalizeMailWrite({
   }
 
   if (sendNow && isMailSendTimeout(result)) {
-    const recovered = recoverIfInSent(match);
+    const recovered = recoverIfInSent(match, { timeout: remaining() });
     if (recovered) {
       return sendVerifiedSuccess({ action, successSummary, details, verified: recovered, recovered: true });
     }
@@ -1397,6 +1469,7 @@ export function mailCompose(args = {}, { draft = false, indexerMode = isIndexerM
     html: bodyFormat === "html"
   });
 
+  const deadlineMs = sentVerifyClock.now() + MCP_CALL_DEADLINE_MS;
   const result = runAppleScript(script, { timeout: MAIL_COMPOSE_TIMEOUT_MS, appName: "Mail" });
   if (
     !result.ok &&
@@ -1420,7 +1493,8 @@ export function mailCompose(args = {}, { draft = false, indexerMode = isIndexerM
       cc: cc.addresses.join(", ") || undefined,
       bcc: bcc.addresses.length ? `${bcc.addresses.length} recipient(s)` : undefined,
       subject: truncate(subject.text, 150)
-    }
+    },
+    deadlineMs
   });
 }
 
@@ -1475,9 +1549,10 @@ export function mailReply(args = {}) {
   });
   if (!plan.proceed) return plannedWriteResult(plan);
 
+  const deadlineMs = sentVerifyClock.now() + MCP_CALL_DEADLINE_MS;
   const result = runAppleScript(
     buildReplyScript({ messageId: resolved.messageId, body: body.text, replyAll, sendNow }),
-    { timeout: 60000, appName: "Mail" }
+    { timeout: MAIL_FIND_AND_SEND_TIMEOUT_MS, appName: "Mail" }
   );
   return finalizeMailWrite({
     action,
@@ -1490,7 +1565,8 @@ export function mailReply(args = {}) {
     details: {
       message_id: resolved.messageId,
       reply_all: String(replyAll)
-    }
+    },
+    deadlineMs
   });
 }
 
@@ -1538,9 +1614,10 @@ export function mailForward(args = {}) {
   });
   if (!plan.proceed) return plannedWriteResult(plan);
 
+  const deadlineMs = sentVerifyClock.now() + MCP_CALL_DEADLINE_MS;
   const result = runAppleScript(
     buildForwardScript({ messageId: resolved.messageId, to: to.addresses, body: body.text, sendNow }),
-    { timeout: 60000, appName: "Mail" }
+    { timeout: MAIL_FIND_AND_SEND_TIMEOUT_MS, appName: "Mail" }
   );
   return finalizeMailWrite({
     action,
@@ -1554,7 +1631,8 @@ export function mailForward(args = {}) {
     details: {
       message_id: resolved.messageId,
       to: to.addresses.join(", ")
-    }
+    },
+    deadlineMs
   });
 }
 
@@ -1586,7 +1664,7 @@ export function mailMark(args = {}) {
   });
   if (!plan.proceed) return plannedWriteResult(plan);
 
-  const result = runAppleScript(buildMarkScript({ messageId: resolved.messageId, read: status === "read" }), { appName: "Mail" });
+  const result = runAppleScript(buildMarkScript({ messageId: resolved.messageId, read: status === "read" }), { timeout: MAIL_FIND_TIMEOUT_MS, appName: "Mail" });
   if (!result.ok) return { ok: false, message: failure(action, summary, result, []) };
 
   return { ok: true, message: writeSuccessMessage(action, `marked as ${status}`, { message_id: resolved.messageId }) };
@@ -1637,7 +1715,7 @@ export function mailArchive(args = {}) {
       mailboxNames: ["Archive", "All Mail", "Archived"],
       allowDeleteFallback: false
     }),
-    { appName: "Mail" }
+    { timeout: MAIL_FIND_TIMEOUT_MS, appName: "Mail" }
   );
   if (!result.ok) {
     if (result.kind === "not_found" && String(result.error).includes("ARCHIVE_MAILBOX_NOT_FOUND")) {
@@ -1670,7 +1748,7 @@ export function mailTrash(args = {}) {
       mailboxNames: ["Trash", "Deleted Messages", "Bin"],
       allowDeleteFallback: true
     }),
-    { appName: "Mail" }
+    { timeout: MAIL_FIND_TIMEOUT_MS, appName: "Mail" }
   );
   if (!result.ok) return { ok: false, message: failure(action, summary, result, []) };
 

package/lib/processMode.js

@@ -5,7 +5,12 @@
  * Convenience bin: `apple-tools-indexer` (`bin/apple-tools-indexer.js`;
  * detected via argv[1] or `--mode=indexer`).
  * Permissions CLI: `apple-tools-mcp permissions` / `--mode=permissions`.
- * MCP stdio remains the default when neither is present.
+ * HTTP transport: `node index.js --transport=http` or `apple-tools-http`
+ * (`bin/apple-tools-http.js`) — read-only-vs-write is unchanged, but every
+ * request needs a bearer token; see lib/httpAuth.js.
+ * Token CLI: `apple-tools-mcp http-token` prints (generating if needed) the
+ * Keychain-stored HTTP auth token, then exits.
+ * MCP stdio remains the default when none of the above is present.
  */
 
 import path from "path";
@@ -74,3 +79,39 @@ export function isIndexerMode(argv = process.argv) {
   const entry = argv[1] ? path.basename(argv[1]) : "";
   return entry === "apple-tools-indexer" || entry === "apple-tools-indexer.js";
 }
+
+/**
+ * @param {string[]} [argv=process.argv]
+ * @returns {boolean}
+ */
+export function isHttpTokenMode(argv = process.argv) {
+  if (!Array.isArray(argv) || argv.length === 0) {
+    return false;
+  }
+  if (argv.includes("--mode=http-token")) {
+    return true;
+  }
+  return firstPositionalArg(argv) === "http-token";
+}
+
+/**
+ * @param {string[]} [argv=process.argv]
+ * @returns {boolean}
+ */
+export function isHttpMode(argv = process.argv) {
+  if (!Array.isArray(argv) || argv.length === 0) {
+    return false;
+  }
+  if (isPermissionsMode(argv) || isHttpTokenMode(argv)) {
+    return false;
+  }
+  if (argv.includes("--transport=http") || argv.includes("--mode=http")) {
+    return true;
+  }
+  const transportIdx = argv.indexOf("--transport");
+  if (transportIdx !== -1 && argv[transportIdx + 1] === "http") {
+    return true;
+  }
+  const entry = argv[1] ? path.basename(argv[1]) : "";
+  return entry === "apple-tools-http" || entry === "apple-tools-http.js";
+}

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "apple-tools-mcp",
-  "version": "2.1.5",
-  "description": "MCP server for semantic search and write actions across Apple Mail, Messages, Calendar, and Contacts",
+  "version": "3.0.1",
+  "description": "MCP server for semantic search and write actions across Apple Mail, Messages, Calendar, and Contacts. Speaks stdio (local) or bearer-token-authenticated Streamable HTTP (LAN / Tailscale).",
   "type": "module",
   "main": "index.js",
   "bin": {
     "apple-tools-mcp": "bin/apple-tools-mcp.js",
-    "apple-tools-indexer": "bin/apple-tools-indexer.js"
+    "apple-tools-indexer": "bin/apple-tools-indexer.js",
+    "apple-tools-http": "bin/apple-tools-http.js",
+    "apple-tools-http-proxy": "bin/apple-tools-http-proxy.js"
   },
   "author": "Peter Coates",
   "license": "MIT",
@@ -28,7 +30,10 @@
     "messages",
     "imessage",
     "semantic-search",
-    "macos"
+    "macos",
+    "streamable-http",
+    "remote-mcp",
+    "tailscale"
   ],
   "engines": {
     "node": ">=18.0.0"
@@ -46,6 +51,7 @@
     "contacts.js",
     "lib/",
     "bin/",
+    "examples/",
     "scripts/audit-index.js",
     "scripts/smoke-writes.js",
     "scripts/postinstall.js",
@@ -56,6 +62,8 @@
     "start": "node index.js",
     "indexer": "node index.js --mode=indexer",
     "permissions": "node index.js permissions",
+    "http": "node index.js --transport=http",
+    "http-token": "node index.js http-token",
     "postinstall": "node scripts/postinstall.js",
     "build-index": "node -e \"import('./indexer.js').then(i=>i.rebuildIndex()).catch(e=>{console.error(e.message);process.exit(1)})\"",
     "audit": "node scripts/audit-index.js",
@@ -82,14 +90,14 @@
     "perf:dates": "vitest run tests/perf/date-parsing.perf.test.js"
   },
   "dependencies": {
+    "@huggingface/transformers": "^4.3.0",
     "@lancedb/lancedb": "^0.22.3",
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "@xenova/transformers": "^2.17.2",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "chrono-node": "^2.9.0"
   },
   "devDependencies": {
-    "vitest": "^2.1.0",
     "@vitest/coverage-v8": "^2.1.0",
-    "fast-check": "^3.22.0"
+    "fast-check": "^3.22.0",
+    "vitest": "^2.1.0"
   }
 }