apple-tools-mcp 3.0.0 → 3.0.2

package/lib/calendarWrite.js

@@ -44,6 +44,17 @@ export const RECURRENCE_FREQUENCIES = ["daily", "weekly", "monthly", "yearly"];
 export const RECURRENCE_DAYS = ["MO", "TU", "WE", "TH", "FR", "SA", "SU"];
 export const RSVP_RESPONSES = ["accept", "decline", "tentative"];
 
+// Regression (2026-09-23): calendar_edit's classic-AppleScript fallback and
+// calendar_rsvp both ran atmFindEvent (see findEventHandler below) under a
+// flat 60000ms runAppleScript timeout -- exactly matching the MCP client
+// SDK's own default 60s CallTool timeout, so the client could give up with
+// a raw "Request timed out" before the server ever got to answer, even
+// though the underlying operation kept running and generally succeeded
+// (same class of bug already fixed for mail_send/reply/forward). Trimmed
+// under that ceiling to leave real margin, including for atmFindEvent's own
+// retry loop (~8s worst case).
+export const CALENDAR_FIND_TIMEOUT_MS = 45000;
+
 const RSVP_STATUS = {
   accept: "accepted",
   decline: "declined",
@@ -163,16 +174,36 @@ export function defaultEndParts(start, allDay) {
   };
 }
 
+/**
+ * calendar_edit / calendar_rsvp's classic-AppleScript fallback both resolve
+ * an event by uid through this handler. Regression (2026-09-23): RSVPing to
+ * an event created moments earlier through the daemon's separate EventKit
+ * session ("no event with that id was found") failed on the first lookup
+ * even though the event genuinely existed -- Calendar.app's classic
+ * AppleScript object model can lag behind a write made through EventKit.
+ * An EventKit-based fix isn't available here: writeOnly EventKit can only
+ * re-query an event via the exact in-memory EKEvent object from the
+ * session that created it (see describeEventKitWriteFailure below), which
+ * doesn't exist for a real invitation synced in from elsewhere. Retrying
+ * the classic lookup a few times gives Calendar.app's own model a chance
+ * to catch up, well inside callers' existing 60s budget.
+ */
 function findEventHandler() {
   return `on atmFindEvent(theUid)
-  tell application "Calendar"
-    repeat with cal in calendars
-      try
-        set hits to (every event of cal whose uid is theUid)
-        if (count of hits) > 0 then return item 1 of hits
-      end try
-    end repeat
-  end tell
+  set attemptsLeft to 5
+  repeat
+    tell application "Calendar"
+      repeat with cal in calendars
+        try
+          set hits to (every event of cal whose uid is theUid)
+          if (count of hits) > 0 then return item 1 of hits
+        end try
+      end repeat
+    end tell
+    set attemptsLeft to attemptsLeft - 1
+    if attemptsLeft is 0 then exit repeat
+    delay 2
+  end repeat
   error "EVENT_NOT_FOUND"
 end atmFindEvent`;
 }
@@ -503,11 +534,19 @@ function addRow(c) {
   var local = type === 0 ? "yes" : "no";
   rows.push(name + "<<>>" + writable + "<<>>" + local + "<<>>" + type + "<<>>" + srcName);
 }
+var listError = "";
 try {
   var cals = store.calendarsForEntityType($.EKEntityTypeEvent);
   for (var i = 0; i < cals.count; i++) addRow(cals.objectAtIndex(i));
-} catch (e) {}
-try { addRow(store.defaultCalendarForNewEvents); } catch (e) {}
+} catch (e) {
+  listError = String(e);
+}
+try { addRow(store.defaultCalendarForNewEvents); } catch (e) {
+  if (!listError) listError = String(e);
+}
+if (rows.length === 0 && listError) {
+  throw new Error("EVENTKIT_LIST_FAILED: " + listError);
+}
 rows.join("|||");`;
 }
 
@@ -659,26 +698,37 @@ set AppleScript's text item delimiters to "|||"
 return outputList as string`;
 
   const result = runAppleScript(script, { timeout: 30000, appName: "Calendar" });
-  if (!result.ok) {
-    return { ok: false, message: failure(action, "list calendars", result) };
-  }
-
-  let calendars = result.output
-    .split("|||")
-    .map((entry) => entry.trim())
-    .filter((entry) => entry.length > 0)
-    .map((entry) => {
-      const [name, writable] = entry.split("<<>>");
-      return { name: name || "", writable: writable !== "no" };
-    });
 
+  // EventKit does not require Calendar.app to be running, so a real EventKit
+  // list can stand in when the classic AppleScript path fails (app closed).
+  // An empty EventKit string is not that list: the JXA helper used to swallow
+  // every error and still exit 0, which hid TCC / timeout / not-running.
   const ekList = runAppleScript(buildEventKitListCalendarsScript(), {
     timeout: 15000,
     appName: "Calendar",
     language: "JavaScript"
   });
-  if (ekList.ok) {
-    calendars = mergeCalendarSources(calendars, parseEventKitCalendarList(ekList.output));
+  const ekCalendars = ekList.ok ? parseEventKitCalendarList(ekList.output) : [];
+
+  if (!result.ok && ekCalendars.length === 0) {
+    return { ok: false, message: failure(action, "list calendars", result) };
+  }
+
+  let calendars = result.ok
+    ? result.output
+        .split("|||")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0)
+        .map((entry) => {
+          const [name, writable] = entry.split("<<>>");
+          return { name: name || "", writable: writable !== "no" };
+        })
+    : [];
+
+  if (ekCalendars.length > 0) {
+    calendars = result.ok
+      ? mergeCalendarSources(calendars, ekCalendars)
+      : ekCalendars;
   }
 
   if (calendars.length === 0) {
@@ -1115,7 +1165,7 @@ export function calendarEdit(args = {}) {
     return { ok: false, message: `${action} refused: ${e.message}` };
   }
 
-  const result = runAppleScript(script, { timeout: 60000, appName: "Calendar" });
+  const result = runAppleScript(script, { timeout: CALENDAR_FIND_TIMEOUT_MS, appName: "Calendar" });
   if (!result.ok) return { ok: false, message: failure(action, summary, result, [updates.description || ""]) };
 
   return {
@@ -1284,10 +1334,16 @@ export function calendarRemove(args = {}) {
 }
 
 export function buildRsvpScript({ eventId, status, attendeeEmail }) {
+  // Calendar.app's AppleScript dictionary defines `participation status` as
+  // one of unknown/accepted/declined/tentative (confirmed via `sdef`/aete
+  // dump) -- there is no "needs action" term, so that bare two-word phrase
+  // was a syntax error (AppleScript parsed "needs" as an identifier and
+  // choked on "action" where it expected "then"). `unknown` is the correct
+  // term for "no answer yet".
   const match = attendeeEmail
     ? `    if (email of att) is ${asString(attendeeEmail)} then set theAttendee to att`
     : `    try
-      if (participation status of att) is needs action then set theAttendee to att
+      if (participation status of att) is unknown then set theAttendee to att
     end try`;
 
   return `${findEventHandler()}
@@ -1344,7 +1400,7 @@ export function calendarRsvp(args = {}) {
 
   const result = runAppleScript(
     buildRsvpScript({ eventId, status: RSVP_STATUS[responseRaw], attendeeEmail }),
-    { timeout: 60000, appName: "Calendar" }
+    { timeout: CALENDAR_FIND_TIMEOUT_MS, appName: "Calendar" }
   );
 
   if (!result.ok) {

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;
@@ -504,17 +525,27 @@ on atmTopElemBits(atmEl)
   return atmBits
 end atmTopElemBits
 
+-- Mail titles a compose window with the full subject, while the marker is
+-- cut to ${MAIL_COMPOSE_TITLE_MARKER_MAX} characters for long subjects. A marker that length is a
+-- prefix; a shorter one is the whole subject and must match exactly.
+on atmTitleMatches(atmTitle, atmMarker)
+  if atmTitle is atmMarker then return true
+  if (length of atmMarker) >= ${MAIL_COMPOSE_TITLE_MARKER_MAX} and atmTitle starts with atmMarker then return true
+  return false
+end atmTitleMatches
+
 on atmTopElemExactTitle(atmEl, atmMarker)
   try
-    if (name of atmEl as string) is atmMarker then return true
+    if my atmTitleMatches(name of atmEl as string, atmMarker) then return true
   end try
   try
-    if (title of atmEl as string) is atmMarker then return true
+    if my atmTitleMatches(title of atmEl as string, atmMarker) then return true
   end try
   try
     tell application "System Events"
-      if (value of attribute "AXTitle" of atmEl as string) is atmMarker then return true
+      set atmAxTitle to (value of attribute "AXTitle" of atmEl as string)
     end tell
+    if my atmTitleMatches(atmAxTitle, atmMarker) then return true
   end try
   return false
 end atmTopElemExactTitle
@@ -603,7 +634,7 @@ on atmFillMailBody(bodyText, needle, titleMarker, msg)
           set atmWin to missing value
           repeat with atmCand in windows
             try
-              if (name of atmCand as string) is titleMarker then
+              if my atmTitleMatches(name of atmCand as string, titleMarker) then
                 set atmWin to atmCand
                 exit repeat
               end if
@@ -840,11 +871,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 +914,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 +1221,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 +1234,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 +1359,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 +1374,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 +1395,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 +1479,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 +1503,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 +1559,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 +1575,8 @@ export function mailReply(args = {}) {
     details: {
       message_id: resolved.messageId,
       reply_all: String(replyAll)
-    }
+    },
+    deadlineMs
   });
 }
 
@@ -1538,9 +1624,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 +1641,8 @@ export function mailForward(args = {}) {
     details: {
       message_id: resolved.messageId,
       to: to.addresses.join(", ")
-    }
+    },
+    deadlineMs
   });
 }
 
@@ -1586,7 +1674,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 +1725,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 +1758,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-tools-mcp",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "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",