apple-tools-mcp 2.0.1 → 2.0.3

package/lib/permissions.js

@@ -0,0 +1,360 @@
+/**
+ * First-run / upgrade permissions command.
+ *
+ * Probes Contacts, Calendar, Mail, and Messages under process.execPath so
+ * macOS can pop Allow dialogs for that node binary. The user clicks Allow;
+ * this command cannot grant silently.
+ *
+ * Always runs in this process (never via the write bridge): the point is to
+ * attach the dialogs to process.execPath. If the invoked CLI / shebang
+ * 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.
+ */
+
+import fs from "fs";
+import path from "path";
+import { classifyAppleScriptError } from "./appleScript.js";
+import { probeMailAutomation } from "./mailWrite.js";
+import { probeMessagesAutomation } from "./messagesWrite.js";
+import { probeContactsAutomation } from "./contactsWrite.js";
+import { probeCalendarAutomation } from "./calendarWrite.js";
+import { detectLaunchAgentContext, hostAutomationAdvice } from "./writeRouting.js";
+
+export const REQUIRED_SURFACES = ["Contacts", "Calendar", "Mail", "Messages"];
+
+/** Mini ship-gate host example — not a universal path. */
+export const EXAMPLE_MINI_NODE = "/Users/petercoates/.local/node/bin/node";
+
+/** MacBook Claude nvm example — not Homebrew. */
+export const EXAMPLE_MACBOOK_NVM_NODE = "/Users/petercoates/.nvm/versions/node/v22.21.1/bin/node";
+
+export const GRANT_GRANTED = "granted";
+export const GRANT_MISSING = "missing";
+export const GRANT_ERROR = "error";
+
+/**
+ * @param {string} [execPath=process.execPath]
+ * @returns {{ execPath: string, miniExample: string, macbookExample: string }}
+ */
+export function describeProbeBinary(execPath = process.execPath) {
+  return {
+    execPath: String(execPath || ""),
+    miniExample: EXAMPLE_MINI_NODE,
+    macbookExample: EXAMPLE_MACBOOK_NVM_NODE
+  };
+}
+
+/**
+ * Resolve a path for comparison. Symlinks collapse to the real file when
+ * possible so `.../bin/node` and its target are treated as the same binary.
+ */
+export function normalizeNodePath(filePath, { realpathSync = fs.realpathSync } = {}) {
+  if (!filePath) return "";
+  const resolved = path.resolve(String(filePath));
+  try {
+    return realpathSync(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
+/**
+ * First-line `#!` interpreter of an invoked CLI script, if any.
+ * @returns {{ kind: "env"|"absolute", target: string, raw: string }|null}
+ */
+export function readShebangTarget(scriptPath, { readFileSync = fs.readFileSync } = {}) {
+  if (!scriptPath) return null;
+  try {
+    const line = String(readFileSync(scriptPath, "utf8")).split(/\r?\n/, 1)[0] || "";
+    if (!line.startsWith("#!")) return null;
+    const raw = line.slice(2).trim();
+    const parts = raw.split(/\s+/).filter(Boolean);
+    if (parts.length === 0) return null;
+    if (parts[0] === "/usr/bin/env" || parts[0].endsWith("/env")) {
+      return { kind: "env", target: parts[1] || "node", raw };
+    }
+    return { kind: "absolute", target: parts[0], raw };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Detect when the invoked `apple-tools-mcp` path / shebang / argv[0] is a
+ * different node than process.execPath. Allows attach to execPath.
+ */
+export function detectExecPathMismatch({
+  execPath = process.execPath,
+  argv = process.argv,
+  realpathSync = fs.realpathSync,
+  existsSync = fs.existsSync,
+  readFileSync = fs.readFileSync
+} = {}) {
+  const deps = { realpathSync, existsSync, readFileSync };
+  const execNorm = normalizeNodePath(execPath, deps);
+  const argv0 = argv && argv[0] ? String(argv[0]) : "";
+  const invokedCli = argv && argv[1] ? String(argv[1]) : "";
+  const argv0Norm = argv0 ? normalizeNodePath(argv0, deps) : "";
+
+  const reasons = [];
+  let siblingNode = "";
+  let shebangTarget = "";
+
+  if (argv0Norm && execNorm && argv0Norm !== execNorm) {
+    reasons.push("argv0");
+  }
+
+  if (invokedCli) {
+    const sibling = path.join(path.dirname(path.resolve(invokedCli)), "node");
+    if (existsSync(sibling)) {
+      siblingNode = normalizeNodePath(sibling, deps);
+      if (siblingNode && execNorm && siblingNode !== execNorm) {
+        reasons.push("sibling");
+      }
+    }
+    const shebang = readShebangTarget(invokedCli, deps);
+    if (shebang && shebang.kind === "absolute" && shebang.target) {
+      shebangTarget = normalizeNodePath(shebang.target, deps);
+      if (shebangTarget && execNorm && shebangTarget !== execNorm) {
+        reasons.push("shebang");
+      }
+    }
+  }
+
+  return {
+    mismatch: reasons.length > 0,
+    reasons,
+    execPath: execNorm || String(execPath || ""),
+    argv0: argv0Norm || argv0,
+    invokedCli,
+    siblingNode,
+    shebangTarget
+  };
+}
+
+/**
+ * Loud WARN: Allows attach to execPath, not the CLI path the user typed.
+ */
+export function formatExecPathMismatchWarn(info) {
+  if (!info || !info.mismatch) return [];
+  const cli = info.invokedCli || "apple-tools-mcp";
+  return [
+    "",
+    "WARN: Allow dialogs attach to process.execPath, not the apple-tools-mcp path you typed.",
+    `  Invoked CLI:        ${cli}`,
+    `  process.argv[0]:    ${info.argv0 || "(unknown)"}`,
+    info.siblingNode ? `  Node next to CLI:   ${info.siblingNode}` : null,
+    info.shebangTarget ? `  CLI shebang target: ${info.shebangTarget}` : null,
+    `  process.execPath:   ${info.execPath}  ← Allows attach HERE`,
+    "Re-run with that exact node so execPath matches the binary you intend:",
+    `  ${info.execPath} ${cli} permissions`,
+    "  or: $(which node) $(which apple-tools-mcp) permissions",
+    '  or: node "$(dirname "$(which node)")/../lib/node_modules/apple-tools-mcp/index.js" permissions',
+    ""
+  ].filter((line) => line !== null);
+}
+
+/**
+ * Map a probe result to the grant report vocabulary.
+ * TCC / timeout / attribution on a live Apple Event is a missing Allow.
+ *
+ * @param {{ ok?: boolean, kind?: string|null, message?: string, error?: string }} result
+ * @returns {"granted"|"missing"|"error"}
+ */
+export function classifyGrantStatus(result) {
+  if (result && result.ok === true) return GRANT_GRANTED;
+  const text = String((result && (result.message || result.error)) || "");
+  const kind = (result && result.kind) || classifyAppleScriptError(text);
+  if (kind === "tcc" || kind === "timeout" || kind === "attribution") {
+    return GRANT_MISSING;
+  }
+  if (kind === "app_not_running") {
+    return GRANT_ERROR;
+  }
+  if (/tcc|automation deny|not authorized|not permitted|not allowed|timed out|etimedout|responsible-process|attribution/i.test(text)) {
+    return GRANT_MISSING;
+  }
+  return GRANT_ERROR;
+}
+
+/**
+ * @param {Record<string, string>} grants
+ * @returns {string[]}
+ */
+export function formatGrantReport(grants) {
+  return REQUIRED_SURFACES.map((name) => `${name} = ${grants[name] || GRANT_ERROR}`);
+}
+
+/**
+ * Fail closed: any required surface that is not granted is a non-zero exit.
+ *
+ * @param {Record<string, string>} grants
+ * @returns {number}
+ */
+export function exitCodeForGrants(grants) {
+  return REQUIRED_SURFACES.every((name) => grants[name] === GRANT_GRANTED) ? 0 : 1;
+}
+
+/**
+ * Advisory Full Disk Access touch. Read tools need FDA on this node; it is
+ * not one of the four required Automation grants and never fails the command.
+ *
+ * @returns {{ status: "readable"|"missing"|"skipped", message: string }}
+ */
+export function probeFullDiskAccess({
+  home = process.env.HOME,
+  accessFn = fs.accessSync
+} = {}) {
+  if (!home) {
+    return { status: "skipped", message: "HOME is unset; skipped Full Disk Access probe" };
+  }
+  const targets = [
+    path.join(home, "Library", "Mail"),
+    path.join(home, "Library", "Messages", "chat.db"),
+    path.join(home, "Library", "Application Support", "AddressBook")
+  ];
+  let sawPath = false;
+  for (const target of targets) {
+    try {
+      accessFn(target, fs.constants.R_OK);
+      sawPath = true;
+    } catch (e) {
+      const code = e && e.code ? e.code : "";
+      if (code === "EPERM" || code === "EACCES") {
+        return {
+          status: "missing",
+          message: `Full Disk Access looks missing for this node (${code} reading ${path.basename(target)}). Reads need FDA on node; that is separate from Automation.`
+        };
+      }
+      if (code === "ENOENT") {
+        continue;
+      }
+      return {
+        status: "skipped",
+        message: `Full Disk Access probe skipped (${code || "error"} on ${path.basename(target)})`
+      };
+    }
+  }
+  if (!sawPath) {
+    return { status: "skipped", message: "Mail / Messages / AddressBook paths are not present; skipped Full Disk Access probe" };
+  }
+  return { status: "readable", message: "Mail / Messages / AddressBook paths are readable (Full Disk Access looks present)" };
+}
+
+export function defaultPermissionsProbes() {
+  return {
+    Contacts: probeContactsAutomation,
+    Calendar: probeCalendarAutomation,
+    Mail: probeMailAutomation,
+    Messages: probeMessagesAutomation
+  };
+}
+
+function bannerLines(binary, version) {
+  return [
+    `Apple Tools MCP permissions (v${version})`,
+    "=".repeat(60),
+    `Probing node binary: ${binary.execPath}`,
+    "This is process.execPath — the node that is running this command.",
+    `Mini example:     ${binary.miniExample}`,
+    `MacBook example:  ${binary.macbookExample}  (Claude nvm; not Homebrew)`,
+    "Invoke this command with the product node so Allow dialogs attach to it.",
+    "",
+    "Open System Settings → Privacy & Security → Automation on this Mac.",
+    "When macOS asks, click Allow for THIS node — not the MCP host app.",
+    "Do not add node via + in the Contacts or Calendars privacy lists.",
+    "dry_run of mail_send / messages_send does not count: this command uses real Apple Events.",
+    "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."
+  ];
+}
+
+/**
+ * Run the four live probes and print a grant report.
+ *
+ * @param {object} [options]
+ * @param {string} [options.execPath]
+ * @param {string[]} [options.argv]
+ * @param {string} [options.version]
+ * @param {(msg: string) => void} [options.stdout]
+ * @param {Record<string, () => object|Promise<object>>} [options.probes]
+ * @param {() => { status: string, message: string }} [options.fdaProbe]
+ * @returns {Promise<number>}
+ */
+export async function runPermissionsCommand({
+  execPath = process.execPath,
+  argv = process.argv,
+  version = "",
+  stdout = console.log,
+  probes,
+  fdaProbe = probeFullDiskAccess,
+  realpathSync = fs.realpathSync,
+  existsSync = fs.existsSync,
+  readFileSync = fs.readFileSync
+} = {}) {
+  const binary = describeProbeBinary(execPath);
+  const mismatch = detectExecPathMismatch({
+    execPath,
+    argv,
+    realpathSync,
+    existsSync,
+    readFileSync
+  });
+  const launchAgent = detectLaunchAgentContext({ existsSync });
+  const hostAdvice = hostAutomationAdvice({ launchAgent, execPath });
+  const probeFns = { ...defaultPermissionsProbes(), ...(probes || {}) };
+  const log = (msg) => {
+    stdout(msg);
+  };
+
+  for (const line of bannerLines(binary, version)) {
+    log(line);
+  }
+  for (const line of formatExecPathMismatchWarn(mismatch)) {
+    log(line);
+  }
+
+  const grants = {};
+  for (const surface of REQUIRED_SURFACES) {
+    log("");
+    log(`--- ${surface} ---`);
+    log(`Next dialog: click Allow for node → ${surface} (if asked). Already-granted surfaces stay quiet.`);
+    let result;
+    try {
+      result = await Promise.resolve(probeFns[surface]());
+    } catch (e) {
+      result = { ok: false, message: e && e.message ? e.message : String(e), kind: "unknown" };
+    }
+    const status = classifyGrantStatus(result);
+    grants[surface] = status;
+    log(`[${status}] ${surface}: ${result && result.message ? result.message : ""}`);
+    if (status !== GRANT_GRANTED) {
+      log(`  ${hostAdvice}`);
+    }
+  }
+
+  const fda = fdaProbe();
+  log("");
+  log(`--- Full Disk Access (advisory) ---`);
+  log(`[${fda.status}] ${fda.message}`);
+
+  log("");
+  log("=".repeat(60));
+  log("Grant report");
+  for (const line of formatGrantReport(grants)) {
+    log(`  ${line}`);
+  }
+
+  const code = exitCodeForGrants(grants);
+  if (code === 0) {
+    log("Result: PASS — Contacts, Calendar, Mail, and Messages are granted for this node.");
+    log("Safe to re-run; already-granted surfaces report OK without another click.");
+  } else {
+    log("Result: INCOMPLETE — one or more required grants are missing or errored.");
+    log(hostAdvice);
+    log("Click Allow for the missing surfaces and re-run this command. Exit is non-zero (fail closed).");
+  }
+  return code;
+}

package/lib/processMode.js

@@ -2,12 +2,56 @@
  * Process mode detection for apple-tools-mcp.
  *
  * Canonical indexer entrypoint: `node index.js --mode=indexer`
- * Convenience bin: `apple-tools-indexer` (same file; detected via argv[1]).
+ * Convenience bin: `apple-tools-indexer` (`bin/apple-tools-indexer.js`;
+ * detected via argv[1] or `--mode=indexer`).
+ * Permissions CLI: `apple-tools-mcp permissions` / `--mode=permissions`.
  * MCP stdio remains the default when neither is present.
  */
 
 import path from "path";
 
+/**
+ * First positional user argument, skipping flags (`--foo` / `--foo=bar`).
+ * Used so `node index.js permissions` and `apple-tools-mcp permissions`
+ * both resolve as the permissions CLI.
+ *
+ * @param {string[]} argv
+ * @returns {string|null}
+ */
+function firstPositionalArg(argv) {
+  const rest = Array.isArray(argv) ? argv.slice(2) : [];
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === "--mode") {
+      i += 1;
+      continue;
+    }
+    if (typeof arg === "string" && arg.startsWith("-")) {
+      continue;
+    }
+    return arg || null;
+  }
+  return null;
+}
+
+/**
+ * @param {string[]} [argv=process.argv]
+ * @returns {boolean}
+ */
+export function isPermissionsMode(argv = process.argv) {
+  if (!Array.isArray(argv) || argv.length === 0) {
+    return false;
+  }
+  if (argv.includes("--mode=permissions")) {
+    return true;
+  }
+  const modeIdx = argv.indexOf("--mode");
+  if (modeIdx !== -1 && argv[modeIdx + 1] === "permissions") {
+    return true;
+  }
+  return firstPositionalArg(argv) === "permissions";
+}
+
 /**
  * @param {string[]} [argv=process.argv]
  * @returns {boolean}
@@ -16,6 +60,10 @@ export function isIndexerMode(argv = process.argv) {
   if (!Array.isArray(argv) || argv.length === 0) {
     return false;
   }
+  // permissions is a short-lived CLI on the same bin; it wins over indexer.
+  if (isPermissionsMode(argv)) {
+    return false;
+  }
   if (argv.includes("--mode=indexer")) {
     return true;
   }
@@ -24,5 +72,5 @@ export function isIndexerMode(argv = process.argv) {
     return true;
   }
   const entry = argv[1] ? path.basename(argv[1]) : "";
-  return entry === "apple-tools-indexer";
+  return entry === "apple-tools-indexer" || entry === "apple-tools-indexer.js";
 }

package/lib/shell.js

@@ -310,6 +310,33 @@ export function safeFind(searchPath, options = {}) {
  * @param {object} options - spawnSync options
  * @returns {object} { stdout, stderr, status }
  */
+/**
+ * Launch a first-party app with `open -a` (argv only, never a shell).
+ * Contacts cold-start under launchd does not reliably auto-launch from
+ * `tell application "Contacts"`; `open -a Contacts` is the host-proven path.
+ */
+export const OPEN_APP_ALLOWLIST = Object.freeze(["Contacts", "Mail", "Messages"]);
+
+export function safeOpenApp(appName, options = {}) {
+  const { timeout = 15000, spawn = spawnSync } = options;
+  if (!OPEN_APP_ALLOWLIST.includes(appName)) {
+    throw new Error("open -a app name is not allowed");
+  }
+  const result = spawn("open", ["-a", appName], {
+    encoding: "utf-8",
+    timeout,
+    shell: false
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    const stderr = String(result.stderr || "").trim();
+    throw new Error(stderr || `open -a ${appName} exited ${result.status}`);
+  }
+  return String(result.stdout || "").trim();
+}
+
 export function safeSpawn(command, args = [], options = {}) {
   const {
     timeout = 30000,

package/lib/writeRouting.js

@@ -12,10 +12,16 @@
  * - An MCP stdio process delegates to the daemon when the write bridge is up.
  * - If delegation is impossible, it runs locally and, on a TCC denial,
  *   explains the host constraint instead of reporting a generic failure.
+ * - Mini LaunchAgent / write-bridge hosts may be told to use the daemon.
+ *   MacBook / Terminal / permissions CLI (no writer.sock) must not be told
+ *   to start apple-tools-indexer — that path is Mini-only.
  *
  * These helpers are pure so the routing policy is testable off-macOS.
  */
 
+import fs from "fs";
+import { defaultSocketPath } from "./writeBridge.js";
+
 /**
  * Writes that macOS gates behind per-app privacy (TCC) rather than plain
  * file permissions. All of them benefit from running in the daemon.
@@ -58,12 +64,76 @@ export function planAfterDelegation({ delivered, response }) {
 }
 
 /**
- * Advice appended when a local write is denied by TCC and no daemon was
- * available to take over.
+ * Mini always-on indexer / write bridge is present (writer.sock or this
+ * process is the daemon). Absent on MacBook / short-lived Terminal CLI.
  */
-export function tccFallbackAdvice({ bridgeAvailable }) {
-  if (bridgeAvailable) {
-    return "The indexer daemon was reachable but the write was still denied; grant the daemon's node binary Full Disk Access (reads) and Allow node in System Settings > Privacy & Security > Automation for Mail.app, Messages.app, Contacts.app, and Calendar.app. A hang or timeout on Mail compose is TCC / Automation denied, not Mail.app missing. Do not add node via + in the Contacts or Calendars privacy lists — those panes often have no Add button.";
+export function detectLaunchAgentContext({
+  indexerMode = false,
+  bridgeAvailable = false,
+  socketPath,
+  existsSync = fs.existsSync
+} = {}) {
+  if (indexerMode || bridgeAvailable) return true;
+  const sock = socketPath || defaultSocketPath();
+  try {
+    return Boolean(sock && existsSync(sock));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * MacBook / Terminal / permissions CLI — no always-on indexer.
+ * Allows attach to the printed process.execPath.
+ */
+export function terminalAutomationAdvice(execPath = process.execPath) {
+  const printed = execPath ? ` (${execPath})` : "";
+  return (
+    `Run this from Terminal.app (short-lived CLI / MacBook host — no always-on indexer). ` +
+    `Click Allow for the printed process.execPath${printed}. ` +
+    `Check System Settings → Privacy & Security → Automation for that node → Contacts, Calendar, Mail, and Messages. ` +
+    `Do not start apple-tools-indexer.`
+  );
+}
+
+/**
+ * Mini host with a live write-bridge / LaunchAgent.
+ */
+export function miniLaunchAgentAdvice() {
+  return (
+    "This Mac has a Mini write-bridge / LaunchAgent. Grant the daemon's node Full Disk Access (reads) and " +
+    "Allow that node in System Settings → Privacy & Security → Automation for Mail.app, Messages.app, Contacts.app, and Calendar.app. " +
+    "Do not add node via + in the Contacts or Calendars privacy lists."
+  );
+}
+
+export function hostAutomationAdvice({
+  launchAgent = false,
+  execPath = process.execPath
+} = {}) {
+  return launchAgent ? miniLaunchAgentAdvice() : terminalAutomationAdvice(execPath);
+}
+
+/**
+ * Advice appended when a local write is denied by TCC.
+ * No writer.sock / LaunchAgent → Terminal + printed execPath only.
+ */
+export function tccFallbackAdvice({
+  bridgeAvailable,
+  execPath = process.execPath,
+  launchAgent
+} = {}) {
+  const mini = launchAgent === undefined ? Boolean(bridgeAvailable) : Boolean(launchAgent);
+  if (mini && bridgeAvailable) {
+    return (
+      "The indexer daemon was reachable but the write was still denied; grant the daemon's node binary Full Disk Access (reads) and " +
+      "Allow node in System Settings > Privacy & Security > Automation for Mail.app, Messages.app, Contacts.app, and Calendar.app. " +
+      "A hang or timeout on Mail compose is TCC / Automation denied, not Mail.app missing. " +
+      "Do not add node via + in the Contacts or Calendars privacy lists — those panes often have no Add button."
+    );
+  }
+  if (mini) {
+    return miniLaunchAgentAdvice();
   }
-  return "No indexer daemon is running on this Mac. Start apple-tools-indexer (the LaunchAgent) so writes execute under node, which macOS can grant Mail, Messages, Contacts, and Calendar Automation to directly.";
+  return terminalAutomationAdvice(execPath);
 }

package/lib/writeTools.js

@@ -32,7 +32,7 @@ import {
 import { contactsAdd, contactsEdit, contactsRemove } from "./contactsWrite.js";
 import { planWriteRoute, planAfterDelegation, tccFallbackAdvice } from "./writeRouting.js";
 import { requestWriteViaBridge, probeSocket, defaultSocketPath } from "./writeBridge.js";
-import { isTccDenial } from "./appleScript.js";
+import { needsHostTccAdvice } from "./appleScript.js";
 
 const CONFIRM_PROPS = {
   dry_run: { type: "boolean", description: "Preview only: report what would happen and change nothing (default false)" },
@@ -48,7 +48,7 @@ export const WRITE_TOOL_DEFINITIONS = [
   // ============ MAIL WRITES ============
   {
     name: "mail_send",
-    description: "Send an email through Mail.app. Sending to more than one recipient in total (to + cc + bcc) requires confirm=true. Use dry_run=true to preview.",
+    description: "Send an email through Mail.app. Sending to more than one recipient in total (to + cc + bcc) requires confirm=true. Use dry_run=true to preview. A send hang is a timeout, not TCC, unless Mail reports -1743/-10004; the tool checks Sent before failing. Clients must Sent-check before retrying a timed-out send.",
     inputSchema: {
       type: "object",
       properties: {
@@ -82,7 +82,7 @@ export const WRITE_TOOL_DEFINITIONS = [
   },
   {
     name: "mail_reply",
-    description: "Reply to an existing email. reply_all=true fans out to every original recipient and requires confirm=true.",
+    description: "Reply to an existing email. reply_all=true fans out to every original recipient and requires confirm=true. A send hang is a timeout, not TCC, unless Mail reports -1743/-10004; the tool checks Sent before failing. Clients must Sent-check before retrying a timed-out send.",
     inputSchema: {
       type: "object",
       properties: {
@@ -97,7 +97,7 @@ export const WRITE_TOOL_DEFINITIONS = [
   },
   {
     name: "mail_forward",
-    description: "Forward an existing email to new recipients. More than one recipient requires confirm=true.",
+    description: "Forward an existing email to new recipients. More than one recipient requires confirm=true. A send hang is a timeout, not TCC, unless Mail reports -1743/-10004; the tool checks Sent before failing. Clients must Sent-check before retrying a timed-out send.",
     inputSchema: {
       type: "object",
       properties: {
@@ -403,9 +403,12 @@ export async function dispatchWriteTool(name, args = {}, deps = {}) {
     result &&
     result.ok === false &&
     result.suppressTccAdvice !== true &&
-    isTccDenial(result.message)
+    needsHostTccAdvice(result.message)
   ) {
-    return { ...result, message: `${result.message} ${tccFallbackAdvice({ bridgeAvailable })}` };
+    return {
+      ...result,
+      message: `${result.message} ${tccFallbackAdvice({ bridgeAvailable, execPath: process.execPath })}`
+    };
   }
   return result;
 }

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "apple-tools-mcp",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "MCP server for semantic search and write actions across Apple Mail, Messages, Calendar, and Contacts",
   "type": "module",
   "main": "index.js",
   "bin": {
-    "apple-tools-mcp": "./index.js",
-    "apple-tools-indexer": "./index.js"
+    "apple-tools-mcp": "bin/apple-tools-mcp.js",
+    "apple-tools-indexer": "bin/apple-tools-indexer.js"
   },
   "author": "Peter Coates",
   "license": "MIT",
@@ -45,14 +45,18 @@
     "search.js",
     "contacts.js",
     "lib/",
+    "bin/",
     "scripts/audit-index.js",
     "scripts/smoke-writes.js",
+    "scripts/postinstall.js",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "start": "node index.js",
     "indexer": "node index.js --mode=indexer",
+    "permissions": "node index.js permissions",
+    "postinstall": "node scripts/postinstall.js",
     "build-index": "node -e \"import('./indexer.js').then(i=>i.rebuildIndex()).catch(e=>{console.error(e.message);process.exit(1)})\"",
     "audit": "node scripts/audit-index.js",
     "smoke:writes": "node scripts/smoke-writes.js",

package/scripts/postinstall.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/**
+ * Print-only reminder after npm install / upgrade.
+ *
+ * Must not run GUI / TCC probes unattended: a LaunchAgent or headless
+ * npm cannot click Allow. The operator runs `apple-tools-mcp permissions`
+ * on the host UI.
+ */
+
+export function postinstallReminderText() {
+  return [
+    "apple-tools-mcp: after first install or upgrade, run permissions on the Mac UI",
+    "(with System Settings → Privacy & Security → Automation open):",
+    "",
+    "  $(which node) $(which apple-tools-mcp) permissions",
+    "  apple-tools-mcp permissions",
+    "  npx apple-tools-mcp permissions",
+    "",
+    "Use the same node binary the product uses (process.execPath).",
+    "A shebang `apple-tools-mcp` can start a different node than the path you typed;",
+    "Allows attach to execPath. Re-run with that exact node if the command WARNs.",
+    "This reminder does not grant anything and does not run the probes."
+  ].join("\n");
+}
+
+export function printPostinstallReminder(write = console.log) {
+  write(postinstallReminderText());
+}
+
+if (process.argv[1] && /postinstall\.js$/.test(process.argv[1])) {
+  printPostinstallReminder();
+}