apple-tools-mcp 1.2.0 → 2.0.0

package/lib/messagesWrite.js

@@ -0,0 +1,281 @@
+/**
+ * Messages (iMessage / SMS) write operations.
+ *
+ * Supported identifiers:
+ * - `to`: a phone number in E.164 form (+15551234567) or an Apple ID email.
+ *   One or more; more than one requires confirmation.
+ * - `chat_id`: an existing chat GUID from chat.db (for example
+ *   "iMessage;-;+15551234567" for a 1:1 chat or "iMessage;+;chat123456789"
+ *   for a group). The GUID is verified against chat.db before sending, so a
+ *   made-up chat id is refused rather than silently delivered elsewhere.
+ */
+
+import fs from "fs";
+import path from "path";
+import { safeSqlite3Json } from "./shell.js";
+import { escapeSQL } from "./validators.js";
+import { runAppleScript, asString, TCC_GUIDANCE, ATTRIBUTION_GUIDANCE } from "./appleScript.js";
+import {
+  planWrite,
+  normalizeList,
+  isMessagesHandle,
+  validateChatGuid,
+  validateBody,
+  writeErrorMessage,
+  writeSuccessMessage,
+  isFlagTrue,
+  truncate,
+  MAX_RECIPIENTS
+} from "./writeGuards.js";
+
+const CHAT_DB = path.join(process.env.HOME || "", "Library", "Messages", "chat.db");
+
+export const SERVICE_IMESSAGE = "imessage";
+export const SERVICE_SMS = "sms";
+export const SERVICE_AUTO = "auto";
+
+/**
+ * Look up a chat GUID in chat.db and count its participants.
+ * @returns {{ found: boolean, participantCount: number, displayName: string, error: string|null }}
+ */
+export function lookupChat(guid, { queryFn = safeSqlite3Json, dbPath = CHAT_DB } = {}) {
+  try {
+    if (!fs.existsSync(dbPath)) {
+      return { found: false, participantCount: 0, displayName: "", error: "Messages database not found" };
+    }
+  } catch {
+    return { found: false, participantCount: 0, displayName: "", error: "Messages database not readable" };
+  }
+
+  const query = `
+    SELECT c.guid AS guid,
+           COALESCE(c.display_name, '') AS displayName,
+           COUNT(chj.handle_id) AS participantCount
+    FROM chat c
+    LEFT JOIN chat_handle_join chj ON chj.chat_id = c.ROWID
+    WHERE c.guid = '${escapeSQL(guid)}'
+    GROUP BY c.ROWID
+    LIMIT 1
+  `;
+
+  try {
+    const rows = queryFn(dbPath, query, { timeout: 15000 });
+    if (!rows || rows.length === 0) {
+      return { found: false, participantCount: 0, displayName: "", error: null };
+    }
+    return {
+      found: true,
+      participantCount: Number(rows[0].participantCount) || 1,
+      displayName: rows[0].displayName || "",
+      error: null
+    };
+  } catch (e) {
+    return { found: false, participantCount: 0, displayName: "", error: e.message };
+  }
+}
+
+/**
+ * Validate an attachment path supplied by the caller.
+ * The file must already exist on this host; the tool never creates files.
+ */
+export function validateAttachmentPath(value) {
+  if (value === undefined || value === null || value === "") return { filePath: null, error: null };
+  if (typeof value !== "string") return { filePath: null, error: "attachment_path must be a string" };
+  if (!path.isAbsolute(value)) return { filePath: null, error: "attachment_path must be an absolute path on this Mac" };
+  if (value.includes("\u0000")) return { filePath: null, error: "attachment_path contains invalid characters" };
+
+  let resolved;
+  try {
+    resolved = fs.realpathSync(value);
+    const stat = fs.statSync(resolved);
+    if (!stat.isFile()) return { filePath: null, error: "attachment_path must point to a file" };
+  } catch {
+    return { filePath: null, error: "attachment_path does not exist on this Mac" };
+  }
+  return { filePath: resolved, error: null };
+}
+
+function serviceHandler() {
+  return `on atmService(kind)
+  tell application "Messages"
+    repeat with acc in accounts
+      try
+        if kind is "sms" then
+          if (service type of acc) is SMS then return acc
+        else
+          if (service type of acc) is iMessage then return acc
+        end if
+      end try
+    end repeat
+  end tell
+  if kind is "sms" then
+    error "SMS_SERVICE_NOT_FOUND"
+  else
+    error "IMESSAGE_SERVICE_NOT_FOUND"
+  end if
+end atmService`;
+}
+
+export function buildSendToHandlesScript({ handles, text, service, attachmentPath }) {
+  const sends = handles
+    .map((handle) => {
+      const lines = [`  set theTarget to participant ${asString(handle)} of targetService`];
+      if (text) lines.push(`  send ${asString(text)} to theTarget`);
+      if (attachmentPath) lines.push(`  send (POSIX file ${asString(attachmentPath)}) to theTarget`);
+      return lines.join("\n");
+    })
+    .join("\n");
+
+  const primary = service === SERVICE_SMS ? "sms" : "imessage";
+  const fallback = service === SERVICE_AUTO
+    ? `if targetService is missing value then
+  set targetService to atmService("sms")
+end if`
+    : "";
+
+  return `${serviceHandler()}
+
+set targetService to missing value
+try
+  set targetService to atmService(${asString(primary)})
+end try
+${fallback}
+if targetService is missing value then error "IMESSAGE_SERVICE_NOT_FOUND"
+tell application "Messages"
+${sends}
+end tell
+return "OK"`;
+}
+
+export function buildSendToChatScript({ chatGuid, text, attachmentPath }) {
+  const lines = [`  set theChat to chat id ${asString(chatGuid)}`];
+  if (text) lines.push(`  send ${asString(text)} to theChat`);
+  if (attachmentPath) lines.push(`  send (POSIX file ${asString(attachmentPath)}) to theChat`);
+
+  return `tell application "Messages"
+${lines.join("\n")}
+end tell
+return "OK"`;
+}
+
+function failure(action, summary, result, secrets) {
+  if (result.kind === "tcc") {
+    return `${action} failed — attempted to ${summary}. ${TCC_GUIDANCE}`;
+  }
+  if (result.kind === "attribution") {
+    return `${action} failed — attempted to ${summary}. ${ATTRIBUTION_GUIDANCE}`;
+  }
+  if (result.kind === "app_unavailable") {
+    return `${action} failed — attempted to ${summary}. Messages.app could not be reached on this host.`;
+  }
+  const raw = String(result.error || "");
+  if (raw.includes("SMS_SERVICE_NOT_FOUND")) {
+    return `${action} failed — attempted to ${summary}. No SMS relay service is configured in Messages (Text Message Forwarding).`;
+  }
+  if (raw.includes("IMESSAGE_SERVICE_NOT_FOUND")) {
+    return `${action} failed — attempted to ${summary}. No enabled iMessage account was found in Messages.`;
+  }
+  return writeErrorMessage(action, summary, new Error(raw || "unknown error"), secrets);
+}
+
+/**
+ * Send an iMessage/SMS to one or more handles, or into an existing chat.
+ */
+export function messagesSend(args = {}, deps = {}) {
+  const action = "messages_send";
+
+  const body = validateBody(args.text, { required: false, field: "text" });
+  if (body.error) return { ok: false, message: `${action} refused: ${body.error}` };
+
+  const attachment = validateAttachmentPath(args.attachment_path);
+  if (attachment.error) return { ok: false, message: `${action} refused: ${attachment.error}` };
+
+  if (!body.text && !attachment.filePath) {
+    return { ok: false, message: `${action} refused: provide text, attachment_path, or both.` };
+  }
+
+  const serviceRaw = args.service === undefined ? SERVICE_AUTO : String(args.service).toLowerCase();
+  if (![SERVICE_AUTO, SERVICE_IMESSAGE, SERVICE_SMS].includes(serviceRaw)) {
+    return { ok: false, message: `${action} refused: service must be "auto", "imessage", or "sms"` };
+  }
+
+  const dryRun = isFlagTrue(args.dry_run);
+  const confirm = isFlagTrue(args.confirm);
+
+  if (args.chat_id) {
+    const guid = validateChatGuid(args.chat_id);
+    if (!guid) return { ok: false, message: `${action} refused: chat_id is not a valid chat GUID` };
+
+    const chat = lookupChat(guid, deps);
+    if (chat.error) {
+      return { ok: false, message: `${action} refused: could not verify chat_id against the Messages database (${truncate(chat.error, 120)})` };
+    }
+    if (!chat.found) {
+      return { ok: false, message: `${action} refused: chat_id ${truncate(guid, 80)} was not found in the Messages database. Use a chat GUID from an existing conversation; this tool does not invent chats.` };
+    }
+
+    const isGroup = chat.participantCount > 1;
+    const label = chat.displayName ? `"${truncate(chat.displayName, 60)}"` : guid;
+    const summary = `send a message to chat ${label} (${chat.participantCount} participant${chat.participantCount === 1 ? "" : "s"})${attachment.filePath ? " with an attachment" : ""}`;
+
+    const plan = planWrite({
+      action,
+      summary,
+      recipientCount: isGroup ? chat.participantCount : 1,
+      dryRun,
+      confirm
+    });
+    if (!plan.proceed) return { ok: true, message: plan.message, planned: true };
+
+    const result = runAppleScript(
+      buildSendToChatScript({ chatGuid: guid, text: body.text, attachmentPath: attachment.filePath }),
+      { timeout: 60000, appName: "Messages" }
+    );
+    if (!result.ok) return { ok: false, message: failure(action, summary, result, [body.text]) };
+
+    return {
+      ok: true,
+      message: writeSuccessMessage(action, "message sent", {
+        chat_id: guid,
+        participants: String(chat.participantCount),
+        attachment: attachment.filePath ? path.basename(attachment.filePath) : undefined
+      })
+    };
+  }
+
+  const handles = normalizeList(args.to);
+  if (handles.length === 0) {
+    return { ok: false, message: `${action} refused: "to" (phone number or Apple ID email) or "chat_id" is required. This tool never invents recipients.` };
+  }
+  if (handles.length > MAX_RECIPIENTS) {
+    return { ok: false, message: `${action} refused: ${handles.length} recipients exceeds the per-call limit of ${MAX_RECIPIENTS}` };
+  }
+  const invalid = handles.filter((h) => !isMessagesHandle(h));
+  if (invalid.length > 0) {
+    return { ok: false, message: `${action} refused: invalid recipient(s): ${invalid.map((h) => truncate(h, 40)).join(", ")}. Use E.164 phone numbers (+15551234567) or Apple ID emails.` };
+  }
+
+  const summary = `send a message to ${handles.join(", ")} over ${serviceRaw}${attachment.filePath ? " with an attachment" : ""}`;
+  const plan = planWrite({ action, summary, recipientCount: handles.length, dryRun, confirm });
+  if (!plan.proceed) return { ok: true, message: plan.message, planned: true };
+
+  const result = runAppleScript(
+    buildSendToHandlesScript({
+      handles,
+      text: body.text,
+      service: serviceRaw,
+      attachmentPath: attachment.filePath
+    }),
+    { timeout: 60000, appName: "Messages" }
+  );
+  if (!result.ok) return { ok: false, message: failure(action, summary, result, [body.text]) };
+
+  return {
+    ok: true,
+    message: writeSuccessMessage(action, "message sent", {
+      to: handles.join(", "),
+      service: serviceRaw,
+      attachment: attachment.filePath ? path.basename(attachment.filePath) : undefined
+    })
+  };
+}

package/lib/writeBridge.js

@@ -0,0 +1,214 @@
+/**
+ * Local write bridge between a short-lived MCP stdio process and the
+ * long-lived indexer daemon.
+ *
+ * Why this exists: macOS attributes an Apple event (and Contacts/Calendar
+ * access) to the *responsible process* of whoever sends it. When a host app
+ * spawns this server over stdio, the host - not node - is responsible, so a
+ * host without the Contacts/Calendars automation entitlement makes those
+ * writes fail regardless of node's own Full Disk Access. The indexer daemon
+ * is started by launchd, so node is responsible for its Apple events.
+ *
+ * The daemon therefore listens on a user-only unix socket and performs writes
+ * on behalf of stdio clients. Nothing leaves the machine: AF_UNIX socket,
+ * 0600, inside ~/.apple-tools-mcp/.
+ */
+
+import net from "net";
+import fs from "fs";
+import path from "path";
+
+export const WRITE_SOCKET_NAME = "writer.sock";
+export const DEFAULT_REQUEST_TIMEOUT_MS = 90000;
+const MAX_FRAME_BYTES = 1024 * 1024;
+
+export function defaultSocketPath(home = process.env.HOME || "") {
+  return path.join(home, ".apple-tools-mcp", WRITE_SOCKET_NAME);
+}
+
+/**
+ * Start the bridge server. Safe to call when a stale socket file is left over
+ * from a crash: an unconnectable socket file is removed first.
+ *
+ * @param {object} opts
+ * @param {string} opts.socketPath
+ * @param {(tool: string, args: object) => Promise<object>|object} opts.handler
+ * @param {(msg: string) => void} [opts.log]
+ * @returns {Promise<{ socketPath: string, close: () => void }>}
+ */
+export function startWriteBridgeServer({ socketPath, handler, log = () => {} }) {
+  return new Promise((resolve, reject) => {
+    const dir = path.dirname(socketPath);
+    try {
+      fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    } catch (e) {
+      reject(e);
+      return;
+    }
+
+    const server = net.createServer({ allowHalfOpen: false }, (socket) => {
+      socket.setEncoding("utf8");
+      let buffer = "";
+      let handled = false;
+
+      socket.on("data", async (chunk) => {
+        if (handled) return;
+        buffer += chunk;
+        if (buffer.length > MAX_FRAME_BYTES) {
+          socket.end(JSON.stringify({ ok: false, message: "Request too large" }) + "\n");
+          return;
+        }
+        const newline = buffer.indexOf("\n");
+        if (newline === -1) return;
+        handled = true;
+
+        let response;
+        try {
+          const request = JSON.parse(buffer.slice(0, newline));
+          response = await handler(request.tool, request.args || {});
+        } catch (e) {
+          response = { ok: false, message: `Write bridge error: ${e.message}` };
+        }
+        socket.end(JSON.stringify(response) + "\n");
+      });
+
+      socket.on("error", () => socket.destroy());
+    });
+
+    server.on("error", (e) => {
+      if (e.code === "EADDRINUSE") {
+        // Either a live daemon or a stale file. Probe it: a refused connect
+        // means nothing is listening, so the file can be replaced.
+        probeSocket(socketPath)
+          .then((alive) => {
+            if (alive) {
+              reject(new Error("Another apple-tools-mcp write bridge is already listening"));
+              return;
+            }
+            try {
+              fs.unlinkSync(socketPath);
+            } catch {
+              // best effort; listen will fail again below if it is still there
+            }
+            server.listen(socketPath, () => finish());
+          })
+          .catch(reject);
+        return;
+      }
+      reject(e);
+    });
+
+    const finish = () => {
+      try {
+        fs.chmodSync(socketPath, 0o600);
+      } catch {
+        // Socket files on some filesystems reject chmod; the parent dir is 0700.
+      }
+      log(`Write bridge listening at ${socketPath}`);
+      resolve({
+        socketPath,
+        close: () => {
+          try {
+            server.close();
+          } catch {
+            // already closed
+          }
+          try {
+            fs.unlinkSync(socketPath);
+          } catch {
+            // already gone
+          }
+        }
+      });
+    };
+
+    server.listen(socketPath, finish);
+  });
+}
+
+/**
+ * @returns {Promise<boolean>} true when something is listening on the socket
+ */
+export function probeSocket(socketPath, timeoutMs = 1000) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (value) => {
+      if (settled) return;
+      settled = true;
+      try {
+        client.destroy();
+      } catch {
+        // ignore
+      }
+      resolve(value);
+    };
+
+    const client = net.connect(socketPath);
+    client.setTimeout(timeoutMs);
+    client.on("connect", () => done(true));
+    client.on("error", () => done(false));
+    client.on("timeout", () => done(false));
+  });
+}
+
+/**
+ * Ask the daemon to run a write.
+ *
+ * @returns {Promise<{ delivered: boolean, response: object|null, error: string|null }>}
+ */
+export function requestWriteViaBridge({ socketPath, tool, args, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS }) {
+  return new Promise((resolve) => {
+    if (!socketPath) {
+      resolve({ delivered: false, response: null, error: "no socket path" });
+      return;
+    }
+
+    let settled = false;
+    let buffer = "";
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      try {
+        client.destroy();
+      } catch {
+        // ignore
+      }
+      resolve(value);
+    };
+
+    const client = net.connect(socketPath);
+    client.setEncoding("utf8");
+    client.setTimeout(timeoutMs);
+
+    client.on("connect", () => {
+      client.write(JSON.stringify({ tool, args: args || {} }) + "\n");
+    });
+
+    client.on("data", (chunk) => {
+      buffer += chunk;
+      const newline = buffer.indexOf("\n");
+      if (newline === -1) return;
+      try {
+        finish({ delivered: true, response: JSON.parse(buffer.slice(0, newline)), error: null });
+      } catch (e) {
+        finish({ delivered: false, response: null, error: `malformed bridge response: ${e.message}` });
+      }
+    });
+
+    client.on("end", () => {
+      if (settled) return;
+      if (buffer.trim().length > 0) {
+        try {
+          finish({ delivered: true, response: JSON.parse(buffer.trim()), error: null });
+          return;
+        } catch {
+          // fall through to the generic failure below
+        }
+      }
+      finish({ delivered: false, response: null, error: "write bridge closed without a response" });
+    });
+
+    client.on("timeout", () => finish({ delivered: false, response: null, error: "write bridge timed out" }));
+    client.on("error", (e) => finish({ delivered: false, response: null, error: e.code || e.message }));
+  });
+}