apple-mail-mcp 1.5.6 → 1.5.7

package/build/index.js

@@ -24,6 +24,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { AppleMailManager } from "./services/appleMailManager.js";
+import { createSerialGate } from "./utils/serialize.js";
 // =============================================================================
 // Shared Validation Schemas
 // =============================================================================
@@ -84,17 +85,30 @@ function errorResponse(message) {
     };
 }
 /**
- * Wraps a tool handler with consistent error handling.
+ * Serial execution gate for AppleScript-backed tool calls (issue #11).
+ *
+ * Concurrent MCP tool calls are funneled through this single gate so only one
+ * osascript invocation hits Mail.app's single-threaded AppleScript dispatch at
+ * a time, with a short settle delay between calls so the dispatch queue drains.
+ * Without it, a concurrent batch races into Mail.app, the later calls blow past
+ * their timeouts, and Mail.app is left half-recovered for the next batch.
+ */
+const serializeAppleScript = createSerialGate();
+/**
+ * Wraps a tool handler with consistent error handling, serialized through the
+ * AppleScript gate so concurrent MCP tool calls don't race into Mail.app (#11).
  */
 function withErrorHandling(handler, errorPrefix) {
     return async (params) => {
-        try {
-            return handler(params);
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : "Unknown error";
-            return errorResponse(`${errorPrefix}: ${message}`);
-        }
+        return serializeAppleScript(() => {
+            try {
+                return handler(params);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : "Unknown error";
+                return errorResponse(`${errorPrefix}: ${message}`);
+            }
+        });
     };
 }
 // =============================================================================

package/build/utils/applescript.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"applescript.d.ts","sourceRoot":"","sources":["../../src/utils/applescript.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAuOxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CA6HnB"}
+{"version":3,"file":"applescript.d.ts","sourceRoot":"","sources":["../../src/utils/applescript.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAmQxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CAoInB"}

package/build/utils/applescript.js

@@ -65,6 +65,32 @@ function escapeForShell(script) {
     // This is the standard shell escaping pattern for single-quoted strings
     return script.replace(/'/g, "'\\''");
 }
+/**
+ * Headroom (ms) between the in-AppleScript `with timeout` and the outer
+ * osascript process timeout. The script-level timeout must fire *first* so
+ * Mail.app aborts the operation from inside its own AppleScript dispatch —
+ * cleanly releasing the event queue — before Node SIGKILLs the osascript
+ * process. Killing osascript alone does not stop work already dispatched into
+ * Mail.app, which is what wedges Mail.app for subsequent calls (issue #11).
+ */
+const SCRIPT_TIMEOUT_HEADROOM_MS = 5000;
+/**
+ * Wraps a script body in an AppleScript `with timeout` block so any Apple
+ * Event that honors timeouts (most Mail.app operations do) aborts cleanly
+ * rather than holding Mail.app's single-threaded AppleScript dispatch queue
+ * open indefinitely.
+ *
+ * The timeout is set a few seconds below the osascript process timeout so the
+ * in-Mail abort wins the race against the outer process kill.
+ *
+ * @param script - The AppleScript body
+ * @param processTimeoutMs - The outer osascript process timeout
+ * @returns The script wrapped in `with timeout … end timeout`
+ */
+function wrapWithTimeout(script, processTimeoutMs) {
+    const seconds = Math.max(1, Math.ceil((processTimeoutMs - SCRIPT_TIMEOUT_HEADROOM_MS) / 1000));
+    return `with timeout of ${seconds} seconds\n${script}\nend timeout`;
+}
 /**
  * Checks if an error is a timeout error from execSync.
  *
@@ -270,8 +296,10 @@ export function executeAppleScript(script, options = {}) {
     // Prepare the script:
     // 1. Trim leading/trailing whitespace (cosmetic)
     // 2. Preserve internal newlines (required for AppleScript syntax)
-    // 3. Escape for shell execution
-    const preparedScript = escapeForShell(script.trim());
+    // 3. Wrap in `with timeout` so a stuck Mail.app operation aborts from
+    //    inside its own dispatch before the process timeout kills osascript (#11)
+    // 4. Escape for shell execution
+    const preparedScript = escapeForShell(wrapWithTimeout(script.trim(), timeoutMs));
     // Build the osascript command
     // We use single quotes to wrap the script, which is why we escape
     // single quotes within the script itself
@@ -292,6 +320,11 @@ export function executeAppleScript(script, options = {}) {
             const output = execSync(command, {
                 encoding: "utf8",
                 timeout: timeoutMs,
+                // SIGKILL (not the default SIGTERM): a wedged osascript blocked on an
+                // unresponsive Mail.app can ignore SIGTERM, leaking processes that pile
+                // up and worsen the contention. SIGKILL guarantees the process is reaped
+                // when the timeout fires. (#11)
+                killSignal: "SIGKILL",
                 // Capture stderr separately to get error details
                 stdio: ["pipe", "pipe", "pipe"],
             });

package/build/utils/serialize.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Serial execution gate.
+ *
+ * Mail.app's AppleScript handler is effectively single-threaded: concurrent
+ * `tell application "Mail"` calls queue inside Mail.app, and once enough stack
+ * up the later ones blow past their timeouts while earlier ones are still
+ * draining — the client sees a cascade of "Request timed out" errors and
+ * Mail.app is left half-recovered for the next batch (issue #11).
+ *
+ * A gate chains every task through a single promise so only one runs at a time,
+ * with an optional settle delay between tasks so Mail.app's dispatch queue can
+ * drain. Because tasks are chained on promises, awaiting the gate also yields
+ * the event loop between calls, keeping the server responsive to protocol
+ * traffic (pings, health-check) during a batch.
+ *
+ * @module utils/serialize
+ */
+/** A function that serializes a task behind all previously enqueued tasks. */
+export type SerialGate = <R>(task: () => R | PromiseLike<R>) => Promise<R>;
+/**
+ * Creates a serial execution gate.
+ *
+ * @param settleMs - Delay inserted after each task before the next one starts
+ *   (default 50ms). Set to 0 to disable.
+ * @returns A `serialize(task)` function. Tasks run strictly in enqueue order and
+ *   never overlap; each call resolves/rejects with its task's own result, and a
+ *   failing task never breaks serialization for later tasks.
+ */
+export declare function createSerialGate(settleMs?: number): SerialGate;
+//# sourceMappingURL=serialize.d.ts.map

package/build/utils/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../src/utils/serialize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,8EAA8E;AAC9E,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAE3E;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,SAAK,GAAG,UAAU,CAa1D"}

package/build/utils/serialize.js

@@ -0,0 +1,41 @@
+/**
+ * Serial execution gate.
+ *
+ * Mail.app's AppleScript handler is effectively single-threaded: concurrent
+ * `tell application "Mail"` calls queue inside Mail.app, and once enough stack
+ * up the later ones blow past their timeouts while earlier ones are still
+ * draining — the client sees a cascade of "Request timed out" errors and
+ * Mail.app is left half-recovered for the next batch (issue #11).
+ *
+ * A gate chains every task through a single promise so only one runs at a time,
+ * with an optional settle delay between tasks so Mail.app's dispatch queue can
+ * drain. Because tasks are chained on promises, awaiting the gate also yields
+ * the event loop between calls, keeping the server responsive to protocol
+ * traffic (pings, health-check) during a batch.
+ *
+ * @module utils/serialize
+ */
+/**
+ * Creates a serial execution gate.
+ *
+ * @param settleMs - Delay inserted after each task before the next one starts
+ *   (default 50ms). Set to 0 to disable.
+ * @returns A `serialize(task)` function. Tasks run strictly in enqueue order and
+ *   never overlap; each call resolves/rejects with its task's own result, and a
+ *   failing task never breaks serialization for later tasks.
+ */
+export function createSerialGate(settleMs = 50) {
+    let tail = Promise.resolve();
+    return (task) => {
+        const result = tail.then(task);
+        // Keep the chain alive regardless of this task's outcome, with a settle
+        // delay so the next task doesn't race straight back into Mail.app.
+        tail = result.then(() => settle(settleMs), () => settle(settleMs));
+        return result;
+    };
+}
+function settle(ms) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-mail-mcp",
-  "version": "1.5.6",
+  "version": "1.5.7",
   "description": "MCP server for Apple Mail - read, search, send, and manage emails via Claude",
   "type": "module",
   "main": "build/index.js",