apple-tools-mcp 3.0.3 → 3.0.5

package/index.js

@@ -32,6 +32,7 @@ import {
   isWriteTool,
   dispatchWriteTool,
   executeWriteToolLocally,
+  loggedBridgeHandler,
   mcpWriteResult
 } from "./lib/writeTools.js";
 import { startWriteBridgeServer, defaultSocketPath } from "./lib/writeBridge.js";
@@ -112,7 +113,7 @@ async function startWriteBridge() {
   try {
     writeBridge = await startWriteBridgeServer({
       socketPath: WRITE_SOCKET_PATH,
-      handler: (tool, args) => executeWriteToolLocally(tool, args),
+      handler: loggedBridgeHandler((tool, args) => executeWriteToolLocally(tool, args), (msg) => console.error(msg)),
       log: (msg) => console.error(msg)
     });
     ensureEventKitSession({ helpers: EVENTKIT_JXA_HELPERS });

package/lib/mailWrite.js

@@ -31,7 +31,7 @@ import {
   isHardTccDenial
 } from "./appleScript.js";
 import { isIndexerMode } from "./processMode.js";
-import { safeSpawn } from "./shell.js";
+import { safeSpawnDetached } from "./shell.js";
 import {
   planWrite,
   plannedWriteResult,
@@ -161,16 +161,25 @@ 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 (display asleep) while Mail AppleScript still lists the compose. */
+/**
+ * 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";
-export const DISPLAY_WAKE_SECONDS = 15;
+/** 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. Best-effort; never throws. */
-export function wakeDisplay() {
-  if (process.platform !== "darwin" || process.env.VITEST) return false;
+/**
+ * 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 safeSpawn("/usr/bin/caffeinate", ["-u", "-t", String(DISPLAY_WAKE_SECONDS)], { timeout: 5000 }).status === 0;
+    return spawnDetached("/usr/bin/caffeinate", ["-u", "-t", String(DISPLAY_WAKE_SECONDS)]) != null;
   } catch {
     return false;
   }
@@ -634,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
@@ -644,10 +663,12 @@ 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)
@@ -1316,7 +1337,7 @@ function failure(action, summary, result, secrets) {
     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, so System Events cannot see Mail's compose window (GUI unavailable even after a wake attempt); nothing was sent. Wake the display and retry.`;
+    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.`;

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/lib/writeTools.js

@@ -385,6 +385,46 @@ export function executeWriteToolLocally(name, args = {}) {
  * @param {object} [deps] - injected for tests
  * @returns {Promise<{ ok: boolean, message: string }>}
  */
+/**
+ * One-word reason for a failed write, for logs. Never includes addresses,
+ * subjects, or bodies (write results echo the recipient and subject).
+ */
+export function classifyWriteFailure(message) {
+  const t = String(message || "");
+  if (/GUI scripting is unavailable/i.test(t)) return "gui_scripting_unavailable";
+  if (/denied Accessibility|assistive access|-25211/i.test(t)) return "accessibility_denied";
+  if (/display is asleep|screen saver/i.test(t)) return "display_asleep_or_screen_saver";
+  if (/focus proof failed|caret|Keyboard focus/i.test(t)) return "compose_focus";
+  if (/timed out|ETIMEDOUT|-1712/i.test(t)) return "timeout";
+  if (/-1743|-10004|not authorized to send Apple events/i.test(t)) return "automation_denied";
+  if (/unconfirmed/i.test(t)) return "unconfirmed";
+  return "other";
+}
+
+/**
+ * Wrap the indexer's bridge handler so every bridged write leaves one
+ * timestamped line: tool, outcome, reason class, duration. The indexer log
+ * otherwise has no record of why an overnight send failed.
+ */
+export function loggedBridgeHandler(run, log, now = () => Date.now()) {
+  return async (tool, args) => {
+    const started = now();
+    let result;
+    try {
+      result = await run(tool, args);
+    } catch (e) {
+      log(`${new Date(started).toISOString()} write bridge: ${tool} threw after ${now() - started}ms (${classifyWriteFailure(e && e.message)})`);
+      throw e;
+    }
+    const ok = Boolean(result && result.ok);
+    // Dry runs and confirm-gated previews come back ok:false with planned:true — nothing failed.
+    const planned = !ok && Boolean(result && result.planned);
+    const why = ok || planned ? "" : ` (${classifyWriteFailure(result && result.message)}${result && result.unsupported ? ", unsupported" : ""})`;
+    log(`${new Date(started).toISOString()} write bridge: ${tool} ${ok ? "ok" : planned ? "planned (dry run / needs confirm)" : "failed"} in ${now() - started}ms${why}`);
+    return result;
+  };
+}
+
 export async function dispatchWriteTool(name, args = {}, deps = {}) {
   const {
     indexerMode = false,
@@ -406,16 +446,30 @@ export async function dispatchWriteTool(name, args = {}, deps = {}) {
 
   const route = planWriteRoute({ indexerMode, bridgeAvailable, toolName: name });
 
+  let declined = null;
   if (route.target === "daemon") {
     const { delivered, response, error } = await request({ socketPath, tool: name, args });
     const { fallbackLocal } = planAfterDelegation({ delivered, response });
     if (!fallbackLocal) {
       return response;
     }
-    log(`Write bridge unavailable for ${name} (${error || "no response"}); running locally.`);
+    if (delivered && response && typeof response === "object") {
+      // The daemon answered but couldn't do it (e.g. it couldn't drive Mail's
+      // compose window). Its reason is the real one: it holds the grants.
+      declined = response;
+      log(`Write bridge declined ${name} (${classifyWriteFailure(response.message)}); running locally.`);
+    } else {
+      log(`Write bridge unavailable for ${name} (${error || "no response"}); running locally.`);
+    }
   }
 
   const result = runLocally(name, args);
+  if (declined && result && result.ok === false && declined.message) {
+    return {
+      ...result,
+      message: `${declined.message} (Reported by the indexer daemon, which holds the Automation/Accessibility grants. The local fallback in this process also failed: ${classifyWriteFailure(result.message)}.)`
+    };
+  }
   if (
     result &&
     result.ok === false &&

package/package.json

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