apple-tools-mcp 3.0.2 → 3.0.4

package/lib/mailWrite.js

@@ -31,6 +31,7 @@ import {
   isHardTccDenial
 } from "./appleScript.js";
 import { isIndexerMode } from "./processMode.js";
+import { safeSpawnDetached } from "./shell.js";
 import {
   planWrite,
   plannedWriteResult,
@@ -160,6 +161,30 @@ export const BODY_PASTE_MISDIRECTED_SENTINEL = "BODY_PASTE_MISDIRECTED";
 export const BODY_FOCUS_FAILED_SENTINEL = "BODY_FOCUS_FAILED";
 /** Focus request ran, but the re-read AXFocusedUIElement was not the chosen body. */
 export const BODY_FOCUS_UNPROVEN_SENTINEL = "BODY_FOCUS_UNPROVEN";
+/**
+ * System Events sees 0 Mail windows while Mail AppleScript still lists the compose:
+ * the screen saver is up (loginwindow owns the screen) or the display is asleep.
+ */
+export const DISPLAY_ASLEEP_GUI_UNAVAILABLE_SENTINEL = "DISPLAY_ASLEEP_GUI_UNAVAILABLE";
+/** Outlasts the whole compose osascript (MAIL_COMPOSE_TIMEOUT_MS) so the assertion is live while it runs. */
+export const DISPLAY_WAKE_SECONDS = 30;
+export const DISPLAY_WAKE_POLL_ATTEMPTS = 20;
+
+/**
+ * Declare user activity so a sleeping display wakes before GUI scripting. caffeinate runs
+ * detached for its own -t: a blocking spawn would either SIGKILL it early (3.0.3's 5s timeout
+ * cut the 15s assertion at ~4s) or release it before compose starts. This does not dismiss a
+ * running screen saver; the compose script stops that itself. Best-effort; never throws.
+ */
+export function wakeDisplay({ spawnDetached = safeSpawnDetached, platform = process.platform } = {}) {
+  if (platform !== "darwin" || (process.env.VITEST && spawnDetached === safeSpawnDetached)) return false;
+  try {
+    return spawnDetached("/usr/bin/caffeinate", ["-u", "-t", String(DISPLAY_WAKE_SECONDS)]) != null;
+  } catch {
+    return false;
+  }
+}
+
 /** Mail To: recipient chips surface as U+FFFC (object replacement), not body text. */
 export const MAIL_RECIPIENT_TOKEN_CHAR_ID = 65532;
 export const GUI_SCRIPTING_UNAVAILABLE_SENTINEL = "GUI_SCRIPTING_UNAVAILABLE";
@@ -618,6 +643,16 @@ on atmAxValueIsRecipientToken(atmVal)
   return false
 end atmAxValueIsRecipientToken
 
+-- A running screen saver keeps loginwindow in front and hides every Mail window from
+-- System Events; caffeinate's user-activity assertion does not dismiss it.
+on atmStopScreenSaver()
+  try
+    tell application "System Events"
+      if running of screen saver preferences then stop current screen saver
+    end tell
+  end try
+end atmStopScreenSaver
+
 on atmFillMailBody(bodyText, needle, titleMarker, msg)
   try
     tell application "Mail" to activate
@@ -628,8 +663,15 @@ on atmFillMailBody(bodyText, needle, titleMarker, msg)
     set atmSaveBh to -1
     with timeout of ${seSecs} seconds
       tell application "System Events"
+        my atmStopScreenSaver()
         tell process "Mail"
           set frontmost to true
+          repeat ${DISPLAY_WAKE_POLL_ATTEMPTS} times
+            if (count of (every window)) > 0 then exit repeat
+            my atmStopScreenSaver()
+            delay 0.5
+          end repeat
+          set atmSeWindowCount to count of (every window)
           delay 0.3
           set atmWin to missing value
           repeat with atmCand in windows
@@ -658,6 +700,7 @@ on atmFillMailBody(bodyText, needle, titleMarker, msg)
               end if
             end repeat
           end if
+          if atmWin is missing value and atmSeWindowCount is 0 then error "${DISPLAY_ASLEEP_GUI_UNAVAILABLE_SENTINEL}"
           if atmWin is missing value then error "${BODY_FOCUS_FAILED_SENTINEL}"
           try
             perform action "AXRaise" of atmWin
@@ -744,6 +787,7 @@ on atmFillMailBody(bodyText, needle, titleMarker, msg)
   on error errMsg number errNum
     if errMsg contains "assistive access" or errNum is -25211 then error "${ACCESSIBILITY_DENIED_SENTINEL}"
     if errMsg contains "${GUI_SCRIPTING_UNAVAILABLE_SENTINEL}" then error "${GUI_SCRIPTING_UNAVAILABLE_SENTINEL}"
+    if errMsg contains "${DISPLAY_ASLEEP_GUI_UNAVAILABLE_SENTINEL}" then error "${DISPLAY_ASLEEP_GUI_UNAVAILABLE_SENTINEL}"
     error errMsg number errNum
   end try
 end atmFillMailBody`;
@@ -1292,6 +1336,9 @@ function failure(action, summary, result, secrets) {
   if (err.includes("gui_scripting_unavailable")) {
     return `${action} failed — attempted to ${summary}. ${MAIL_GUI_SCRIPTING_GUIDANCE}`;
   }
+  if (err.includes("display_asleep_gui_unavailable")) {
+    return `${action} failed — attempted to ${summary}. The display is asleep or the screen is locked, so System Events cannot see Mail's compose window (GUI unavailable even after waking the display and stopping the screen saver); nothing was sent. Wake or unlock the Mac and retry.`;
+  }
   if (err.includes("body_focus_unproven")) {
     return `${action} failed — attempted to ${summary}. Keyboard focus was not on the message body (focus proof failed); the draft was discarded and nothing was sent.`;
   }
@@ -1480,6 +1527,7 @@ export function mailCompose(args = {}, { draft = false, indexerMode = isIndexerM
   });
 
   const deadlineMs = sentVerifyClock.now() + MCP_CALL_DEADLINE_MS;
+  wakeDisplay();
   const result = runAppleScript(script, { timeout: MAIL_COMPOSE_TIMEOUT_MS, appName: "Mail" });
   if (
     !result.ok &&

package/lib/shell.js

@@ -8,7 +8,7 @@
  * - Validating inputs before execution
  */
 
-import { spawnSync } from "child_process";
+import { spawn, spawnSync } from "child_process";
 import path from "path";
 import { escapeSQL } from "./validators.js";
 
@@ -340,6 +340,28 @@ export function safeOpenApp(appName, options = {}) {
   return String(result.stdout || "").trim();
 }
 
+/**
+ * Start a command in the background and return immediately (no shell, no
+ * timeout, stdio ignored). The child is detached and unref'd, so it is never
+ * killed mid-run by a spawnSync timeout and never holds the caller open — for
+ * self-terminating helpers like `caffeinate -t N`. Returns the pid, or null if
+ * the spawn failed.
+ */
+export function safeSpawnDetached(command, args = []) {
+  if (!command || typeof command !== 'string') {
+    throw new Error('Command is required');
+  }
+
+  if (!Array.isArray(args)) {
+    throw new Error('Args must be an array');
+  }
+
+  const child = spawn(command, args, { detached: true, stdio: 'ignore', shell: false });
+  child.on('error', () => {});
+  child.unref();
+  return child.pid ?? null;
+}
+
 export function safeSpawn(command, args = [], options = {}) {
   const {
     timeout = 30000,

package/package.json

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