apple-tools-mcp 2.1.1 → 2.1.2

package/README.md

@@ -104,7 +104,7 @@ If the invoked CLI path and `process.execPath` differ, the command prints a **WA
 
 On the host UI (Mini Screen Sharing or MacBook local), open **System Settings → Privacy & Security → Automation**, then run the command. Click **Allow** for **`node`** → Contacts, Calendar, Mail, Messages, and System Events. npm `postinstall` only **prints a reminder** — it does not run the probes unattended.
 
-This is a real Apple Events pass: Mail uses `make new outgoing message` (compose then discard; nothing is sent). Messages enumerates accounts (nothing is sent). `dry_run` of `mail_send` / `messages_send` never talks to those apps and **does not count**. Contacts creates and deletes a throwaway person in-script. Calendar lists calendars only (no leftover events). System Events is asked for its process name (nothing is typed) so the keystroke compose path can pop **Allow**.
+This is a real Apple Events pass: Mail uses `make new outgoing message` (compose then discard; nothing is sent). Messages enumerates accounts (nothing is sent). `dry_run` of `mail_send` / `messages_send` never talks to those apps and **does not count**. Contacts creates and deletes a throwaway person in-script. Calendar lists calendars only (no leftover events). System Events is probed with **process / GUI scripting** (`tell process` + `unix id` of System Events; nothing is typed) so the keystroke compose path can pop **Allow** and verify a real Automation grant. A soft `tell application "System Events" to get name` is **not** enough — that can succeed while TCC still has node → System Events **denied**. If a prior **Don't Allow** left a sticky Deny, `permissions` reports System Events **missing** and exits non-zero: turn **System Events** on for that node in System Settings → Privacy & Security → **Automation**, then **re-run `apple-tools-mcp permissions` after Allow**.
 
 **One-pass first-run:** Allow **`node`** to control **Mail**, **Messages**, **Contacts**, **Calendar**, and **System Events** in the same Automation pass. Contacts or Calendar being allowed does **not** grant Mail, Messages, or System Events — they are separate Apple Events targets. A denied Mail grant hangs `mail_send` / `mail_draft` / `mail_reply` / `mail_forward` until the client disconnects; `dry_run` never talks to Mail, so that deny is invisible until a real compose.
 
@@ -603,7 +603,7 @@ The message names which process macOS was actually asking about. Work through it
 
 1. **MacBook / Terminal (`permissions` CLI):** there is **no** always-on indexer. Re-run `apple-tools-mcp permissions` from **Terminal.app**, Allow the **printed `process.execPath`**, and check System Settings → Privacy & Security → **Automation** for that node → Contacts, Calendar, Mail, Messages, and System Events. Do **not** start `apple-tools-indexer`.
 2. **Mini only:** `pgrep -fl apple-tools-indexer` / `~/.apple-tools-mcp/writer.sock`. If the LaunchAgent is the product host, start it so writes run under launchd-owned node (see [Mini ship-gate](#mini-ship-gate-host-setup)).
-3. **Did you approve the Automation prompts for `node`?** Re-run `apple-tools-mcp permissions` with the product `node` (it prints `process.execPath`). Open System Settings → Privacy & Security → **Automation** and confirm **that printed node** is allowed to control **Mail**, **Messages**, Contacts, Calendar, and **System Events**. On Mini the LaunchAgent binary is whatever the plist / `which node` reports (`/Users/petercoates/.local/node/bin/node` is a Mini *example* only). MacBook Claude nvm is `/Users/petercoates/.nvm/versions/node/v22.21.1/bin/node`, not Homebrew. Watch the host — Allow **`node`**, not any other app. Contacts or Calendar being allowed does **not** grant Mail. A `mail_send` hang is **Automation denied**, not “Mail.app could not be reached”; `dry_run` never talks to Mail so it cannot detect this. Do **not** approve the MCP client / host app that launched a short-lived stdio server, and do **not** try to add `node` via **+** in the Contacts or Calendars privacy lists — those panes often have no Add button. `tccutil reset AppleEvents` re-arms the Automation prompt so you can Allow **`node`** again. Full Disk Access is a separate read grant; npm Trusted Publisher / tokens are unrelated.
+3. **Did you approve the Automation prompts for `node`?** Re-run `apple-tools-mcp permissions` with the product `node` (it prints `process.execPath`). Open System Settings → Privacy & Security → **Automation** and confirm **that printed node** is allowed to control **Mail**, **Messages**, Contacts, Calendar, and **System Events**. A prior **Don't Allow** for System Events is a sticky Deny — the Allow dialog will not appear again; turn **System Events** on for that node, then re-run `permissions` (it must not report granted from a soft name check). On Mini the LaunchAgent binary is whatever the plist / `which node` reports (`/Users/petercoates/.local/node/bin/node` is a Mini *example* only). MacBook Claude nvm is `/Users/petercoates/.nvm/versions/node/v22.21.1/bin/node`, not Homebrew. Watch the host — Allow **`node`**, not any other app. Contacts or Calendar being allowed does **not** grant Mail. A `mail_send` hang is **Automation denied**, not “Mail.app could not be reached”; `dry_run` never talks to Mail so it cannot detect this. Do **not** approve the MCP client / host app that launched a short-lived stdio server, and do **not** try to add `node` via **+** in the Contacts or Calendars privacy lists — those panes often have no Add button. `tccutil reset AppleEvents` re-arms the Automation prompt so you can Allow **`node`** again. Full Disk Access is a separate read grant; npm Trusted Publisher / tokens are unrelated.
 4. **Mini: is the daemon's node binary the one with Full Disk Access?** LaunchAgents do not inherit your shell `PATH`; confirm the plist points at the same path `which node` reports.
 5. **Is it actually the write path?** Contacts or Calendar *reads* failing with `EPERM` is a Full Disk Access / attribution problem, not the entitlement gap — fix FDA for the responsible process. Contacts or Calendar *CRUD* failing with no prompt under Claude Desktop is the [documented host limitation](#reads-and-writes-are-different-mechanisms): Claude.app carries neither the addressbook nor the calendars entitlement. On Mini, start the daemon so the write goes through the bridge. On MacBook, use Terminal.app + the printed node.
 6. **"Contacts.app / Calendar.app could not be reached"** with the app clearly installed is an **Automation / responsible-process** failure, not a missing app — macOS reports a refused Apple event as `-1728` / "can't get application". On MacBook / Terminal, Allow the printed `process.execPath`. On Mini, the write bridge / LaunchAgent may apply. A Contacts `-600` / “application isn't running” is a **cold launch**, not Automation — keep Contacts, Mail, and Messages running; Calendar does not need to stay open.

package/lib/appleScript.js

@@ -345,15 +345,19 @@ export const MAIL_ACCESSIBILITY_GUIDANCE =
   "This is not a Mail Automation deny (-1743 / -10004).";
 
 /**
- * System Events Apple Events / GUI scripting is missing, so the keystroke
- * compose path cannot run. Distinct from a Mail send hang: nothing was typed
- * or sent. Mini write-bridge should return unsupported so stdio falls back
- * in-process rather than wedging ~60s.
+ * Sticky Don't Allow for node → System Events: the Allow dialog will not
+ * reappear. Operators must flip the Automation row and re-run permissions.
  */
+export const SYSTEM_EVENTS_STICKY_DENY_GUIDANCE =
+  "A prior Don't Allow for node → System Events is a sticky Deny: the Allow dialog will not appear again. " +
+  "Turn System Events on for this node in System Settings → Privacy & Security → Automation, then re-run apple-tools-mcp permissions after Allow.";
+
+/** System Events GUI scripting missing — not a Mail send hang. */
 export const MAIL_GUI_SCRIPTING_GUIDANCE =
   "System Events GUI scripting is unavailable for this process, so the body cannot be typed into Mail. " +
   "mail_send / mail_draft use System Events keystrokes (Tab into the body, typed Returns) so Mail does not cite-wrap the Sent body (FB11734014). " +
   "Allow node → System Events in System Settings → Privacy & Security → Automation (run apple-tools-mcp permissions after install/upgrade) in addition to node → Mail, and keep Accessibility allowed. " +
+  SYSTEM_EVENTS_STICKY_DENY_GUIDANCE + " " +
   "This is not a Mail send timeout and not a Mail Automation deny (-1743 / -10004).";
 
 /**

package/lib/mailWrite.js

@@ -160,11 +160,13 @@ export const BODY_PASTE_MISDIRECTED_SENTINEL = "BODY_PASTE_MISDIRECTED";
 export const BODY_FOCUS_FAILED_SENTINEL = "BODY_FOCUS_FAILED";
 export const GUI_SCRIPTING_UNAVAILABLE_SENTINEL = "GUI_SCRIPTING_UNAVAILABLE";
 export const SYSTEM_EVENTS_PROBE_MARKER = "ATM_SYSTEM_EVENTS_PROBE";
+/** Permissions-only marker: process / GUI scripting, not application `name`. */
+export const SYSTEM_EVENTS_AUTOMATION_PROBE_MARKER = "ATM_SYSTEM_EVENTS_AUTOMATION_PROBE";
 /** Compose body AX height vs To/Subject/Cc fields (those are ~22px). Used to reject short header AXTextAreas after Tab; does not walk windows. */
 export const MAIL_BODY_MIN_AX_HEIGHT = 50;
 /** Mini-proven Tab count from default compose focus into the body. */
 export const MAIL_BODY_TAB_MAX = 6;
-/** Cheap System Events Automation probe used before compose; SIGKILL if it still hangs. */
+/** Cheap pre-compose System Events check; SIGKILL if it still hangs. Not the permissions grant. */
 export const MAIL_SE_PROBE_TIMEOUT_MS = 4000;
 /** First-run / upgrade permissions probe: long enough for the Allow click. */
 export const SYSTEM_EVENTS_AUTOMATION_PROBE_TIMEOUT_MS = 30000;
@@ -250,6 +252,11 @@ export function isSystemEventsProbeScript(script) {
   return String(script || "").includes(SYSTEM_EVENTS_PROBE_MARKER);
 }
 
+export function isSystemEventsAutomationProbeScript(script) {
+  return String(script || "").includes(SYSTEM_EVENTS_AUTOMATION_PROBE_MARKER);
+}
+
+/** Cheap pre-compose check. Do not use for `permissions` — `get name` can soft-pass. */
 export function buildSystemEventsProbeScript() {
   const secs = asInteger(MAIL_SE_PROBE_APPLEEVENT_TIMEOUT_SEC, {
     min: 1,
@@ -275,15 +282,41 @@ export function probeSystemEventsGui({ timeout = MAIL_SE_PROBE_TIMEOUT_MS } = {}
 }
 
 /**
- * First-run / upgrade probe: a live System Events Apple Event that pops
- * Automation → System Events. Does not type into the focused UI.
- * Timeout is long enough for the operator to click Allow.
+ * First-run / upgrade probe. Soft `tell application "System Events" to get
+ * name` is not enough — Mini @2.1.1 reported granted while TCC auth_value=0
+ * for node → com.apple.systemevents. Process / GUI scripting (`tell process`)
+ * is the grant mail_send actually needs. Does not type into the focused UI.
+ * Timeout is long enough for the operator to click Allow. No short inner
+ * AppleEvent timeout (same as the Mail compose-and-discard probe).
+ */
+export function buildSystemEventsAutomationProbeScript() {
+  return `-- ${SYSTEM_EVENTS_AUTOMATION_PROBE_MARKER}
+tell application "System Events"
+  tell process "System Events"
+    set atmPid to unix id
+    set atmShown to name
+    if atmShown is "" then error "${GUI_SCRIPTING_UNAVAILABLE_SENTINEL}"
+    if atmPid is missing value then error "${GUI_SCRIPTING_UNAVAILABLE_SENTINEL}"
+    if (atmPid as integer) is less than or equal to 0 then error "${GUI_SCRIPTING_UNAVAILABLE_SENTINEL}"
+    count of UI elements
+  end tell
+  set atmUi to UI elements enabled
+end tell
+if atmUi is false then error "${ACCESSIBILITY_DENIED_SENTINEL}"
+return "OK"`;
+}
+
+/**
+ * First-run / upgrade probe: a live System Events GUI-scripting Apple Event
+ * that creates or verifies Automation → System Events. Does not type.
  * @returns {{ ok: boolean, message: string, kind: string|null }}
  */
 export function probeSystemEventsAutomation() {
   const action = "system_events_automation_probe";
-  const summary = "ask System Events for its name (Automation / Apple Events check; nothing is typed)";
-  const result = probeSystemEventsGui({ timeout: SYSTEM_EVENTS_AUTOMATION_PROBE_TIMEOUT_MS });
+  const summary = "verify System Events process / GUI scripting (Automation / Apple Events grant; nothing is typed)";
+  const result = runAppleScript(buildSystemEventsAutomationProbeScript(), {
+    timeout: SYSTEM_EVENTS_AUTOMATION_PROBE_TIMEOUT_MS
+  });
   if (!result.ok) {
     const kind = systemEventsGrantKind(result);
     const guidance = isMailAccessibilityDenial(result)
@@ -300,7 +333,7 @@ export function probeSystemEventsAutomation() {
     kind: null,
     message: writeSuccessMessage(
       action,
-      "System Events Automation allowed (process name read; nothing was typed)"
+      "System Events Automation allowed (process GUI scripting verified; nothing was typed)"
     )
   };
 }

package/lib/permissions.js

@@ -10,11 +10,13 @@
  * points at a different node, print a WARN — Allows attach to execPath.
  * Mail and Messages use the existing live Apple Events helpers — dry_run of
  * mail_send / messages_send never talks to those apps and does not count.
+ * System Events uses process / GUI scripting (`tell process`), not a soft
+ * application `get name` — that can succeed without AppleEvents auth.
  */
 
 import fs from "fs";
 import path from "path";
-import { classifyAppleScriptError } from "./appleScript.js";
+import { classifyAppleScriptError, SYSTEM_EVENTS_STICKY_DENY_GUIDANCE } from "./appleScript.js";
 import { probeMailAutomation, probeSystemEventsAutomation } from "./mailWrite.js";
 import { probeMessagesAutomation } from "./messagesWrite.js";
 import { probeContactsAutomation } from "./contactsWrite.js";
@@ -272,7 +274,9 @@ function bannerLines(binary, version) {
     "Nothing is sent to third parties. Mail composes and discards a temporary outgoing message.",
     "Messages only enumerates accounts. Contacts creates and deletes a throwaway person in-script.",
     "Calendar lists calendars only — no events are created.",
-    "System Events is asked for its process name (mail_send keystrokes; nothing is typed)."
+    "System Events is probed with process / GUI scripting (tell process + unix id; nothing is typed).",
+    "A soft tell System Events to get name is not enough — that can succeed without AppleEvents auth.",
+    "A prior Don't Allow is a sticky Deny: turn System Events on for this node in Automation, then re-run this command."
   ];
 }
 
@@ -359,6 +363,9 @@ export async function runPermissionsCommand({
   } else {
     log("Result: INCOMPLETE — one or more required grants are missing or errored.");
     log(hostAdvice);
+    if (grants["System Events"] !== GRANT_GRANTED) {
+      log(SYSTEM_EVENTS_STICKY_DENY_GUIDANCE);
+    }
     log("Click Allow for the missing surfaces and re-run this command. Exit is non-zero (fail closed).");
   }
   return code;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-tools-mcp",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "MCP server for semantic search and write actions across Apple Mail, Messages, Calendar, and Contacts",
   "type": "module",
   "main": "index.js",