apple-tools-mcp 1.2.0 → 2.0.0

package/lib/contactsWrite.js

@@ -0,0 +1,300 @@
+/**
+ * Contacts write operations: add, edit, remove.
+ *
+ * Contacts are addressed by their AddressBook unique id (Contacts.app's
+ * `id`, for example "ABCD1234-...:ABPerson"), which `contacts_search` and
+ * `contacts_lookup` report as "Contact ID" and `contacts_add` returns.
+ *
+ * Writes go through Contacts.app rather than the AddressBook sqlite file:
+ * writing that database directly corrupts iCloud sync.
+ */
+
+import { runAppleScript, asString, CONTACTS_TCC_GUIDANCE, ATTRIBUTION_GUIDANCE } from "./appleScript.js";
+import {
+  planWrite,
+  normalizeList,
+  isEmailAddress,
+  isPhoneNumber,
+  validateContactId,
+  validateSubject,
+  validateLabel,
+  writeErrorMessage,
+  writeSuccessMessage,
+  isFlagTrue,
+  truncate
+} from "./writeGuards.js";
+
+const MAX_VALUES_PER_FIELD = 10;
+
+function validateContactEmails(value, label) {
+  const emails = normalizeList(value);
+  if (emails.length > MAX_VALUES_PER_FIELD) {
+    return { emails: [], error: `at most ${MAX_VALUES_PER_FIELD} email addresses per contact` };
+  }
+  const bad = emails.filter((e) => !isEmailAddress(e));
+  if (bad.length > 0) {
+    return { emails: [], error: `invalid email address(es): ${bad.map((e) => truncate(e, 40)).join(", ")}` };
+  }
+  const resolvedLabel = validateLabel(label, "work");
+  if (!resolvedLabel) return { emails: [], error: "email_label must be letters and spaces only" };
+  return { emails: emails.map((email) => ({ value: email, label: resolvedLabel })), error: null };
+}
+
+function validateContactPhones(value, label) {
+  const phones = normalizeList(value);
+  if (phones.length > MAX_VALUES_PER_FIELD) {
+    return { phones: [], error: `at most ${MAX_VALUES_PER_FIELD} phone numbers per contact` };
+  }
+  const bad = phones.filter((p) => !isPhoneNumber(p));
+  if (bad.length > 0) {
+    return { phones: [], error: `invalid phone number(s): ${bad.map((p) => truncate(p, 40)).join(", ")}` };
+  }
+  const resolvedLabel = validateLabel(label, "mobile");
+  if (!resolvedLabel) return { phones: [], error: "phone_label must be letters and spaces only" };
+  return { phones: phones.map((phone) => ({ value: phone, label: resolvedLabel })), error: null };
+}
+
+function findPersonHandler() {
+  return `on atmFindPerson(theId)
+  tell application "Contacts"
+    try
+      return person id theId
+    end try
+    try
+      set hits to (every person whose id is theId)
+      if (count of hits) > 0 then return item 1 of hits
+    end try
+  end tell
+  error "CONTACT_NOT_FOUND"
+end atmFindPerson`;
+}
+
+function childLines(items, kind, personVar) {
+  return items
+    .map((item) => `  make new ${kind} at end of ${kind}s of ${personVar} with properties {label:${asString(item.label)}, value:${asString(item.value)}}`)
+    .join("\n");
+}
+
+function failure(action, summary, result, secrets = []) {
+  if (result.kind === "tcc") {
+    return `${action} failed — attempted to ${summary}. ${CONTACTS_TCC_GUIDANCE}`;
+  }
+  const raw = String(result.error || "");
+  if (raw.includes("CONTACT_NOT_FOUND")) {
+    return `${action} failed — attempted to ${summary}. No contact with that id was found; use the Contact ID from contacts_search or contacts_lookup.`;
+  }
+  if (result.kind === "attribution") {
+    return `${action} failed — attempted to ${summary}. ${ATTRIBUTION_GUIDANCE}`;
+  }
+  if (result.kind === "app_unavailable") {
+    return `${action} failed — attempted to ${summary}. Contacts.app could not be reached on this host.`;
+  }
+  return writeErrorMessage(action, summary, new Error(raw || "unknown error"), secrets);
+}
+
+export function buildAddContactScript({ properties, emails, phones }) {
+  const props = Object.entries(properties)
+    .map(([key, value]) => `${key}:${asString(value)}`)
+    .join(", ");
+
+  return `tell application "Contacts"
+  set newPerson to make new person with properties {${props}}
+${emails.length ? `${childLines(emails, "email", "newPerson")}\n` : ""}${phones.length ? `${childLines(phones, "phone", "newPerson")}\n` : ""}  save
+  set newId to id of newPerson
+end tell
+return newId`;
+}
+
+export function contactsAdd(args = {}) {
+  const action = "contacts_add";
+
+  const firstName = validateSubject(args.first_name);
+  if (firstName.error) return { ok: false, message: `${action} refused: ${firstName.error.replace("subject", "first_name")}` };
+  const lastName = validateSubject(args.last_name);
+  if (lastName.error) return { ok: false, message: `${action} refused: ${lastName.error.replace("subject", "last_name")}` };
+  const organization = validateSubject(args.organization);
+  if (organization.error) return { ok: false, message: `${action} refused: ${organization.error.replace("subject", "organization")}` };
+  const jobTitle = validateSubject(args.job_title);
+  if (jobTitle.error) return { ok: false, message: `${action} refused: ${jobTitle.error.replace("subject", "job_title")}` };
+
+  if (!firstName.text && !lastName.text && !organization.text) {
+    return { ok: false, message: `${action} refused: provide at least first_name, last_name, or organization.` };
+  }
+
+  const emails = validateContactEmails(args.emails, args.email_label);
+  if (emails.error) return { ok: false, message: `${action} refused: ${emails.error}` };
+  const phones = validateContactPhones(args.phones, args.phone_label);
+  if (phones.error) return { ok: false, message: `${action} refused: ${phones.error}` };
+
+  const displayName = [firstName.text, lastName.text].filter(Boolean).join(" ") || organization.text;
+  const summary = `create contact "${truncate(displayName, 100)}"` +
+    `${emails.emails.length ? ` with ${emails.emails.length} email(s)` : ""}` +
+    `${phones.phones.length ? ` and ${phones.phones.length} phone number(s)` : ""}`;
+
+  const plan = planWrite({ action, summary, dryRun: isFlagTrue(args.dry_run), confirm: isFlagTrue(args.confirm) });
+  if (!plan.proceed) return { ok: true, message: plan.message, planned: true };
+
+  const properties = {};
+  if (firstName.text) properties["first name"] = firstName.text;
+  if (lastName.text) properties["last name"] = lastName.text;
+  if (organization.text) properties.organization = organization.text;
+  if (jobTitle.text) properties["job title"] = jobTitle.text;
+
+  const result = runAppleScript(
+    buildAddContactScript({ properties, emails: emails.emails, phones: phones.phones }),
+    { timeout: 60000, appName: "Contacts" }
+  );
+  if (!result.ok) return { ok: false, message: failure(action, summary, result) };
+
+  return {
+    ok: true,
+    message: writeSuccessMessage(action, "contact created", {
+      contact_id: result.output,
+      name: displayName,
+      emails: emails.emails.map((e) => e.value).join(", ") || undefined,
+      phones: phones.phones.map((p) => p.value).join(", ") || undefined
+    })
+  };
+}
+
+export function buildEditContactScript({ contactId, properties, emails, phones, replaceEmails, replacePhones }) {
+  const lines = Object.entries(properties).map(([key, value]) => `  set ${key} of thePerson to ${asString(value)}`);
+  if (replaceEmails) {
+    lines.push(`  try
+    delete every email of thePerson
+  end try`);
+  }
+  if (replacePhones) {
+    lines.push(`  try
+    delete every phone of thePerson
+  end try`);
+  }
+
+  return `${findPersonHandler()}
+
+set thePerson to atmFindPerson(${asString(contactId)})
+tell application "Contacts"
+${lines.join("\n")}
+${emails.length ? `${childLines(emails, "email", "thePerson")}\n` : ""}${phones.length ? `${childLines(phones, "phone", "thePerson")}\n` : ""}  save
+  set editedName to name of thePerson
+end tell
+return editedName`;
+}
+
+export function contactsEdit(args = {}) {
+  const action = "contacts_edit";
+
+  const contactId = validateContactId(args.contact_id);
+  if (!contactId) {
+    return { ok: false, message: `${action} refused: contact_id is required (the "Contact ID" from contacts_search or contacts_lookup). This tool will not guess which contact you meant.` };
+  }
+
+  const properties = {};
+  const changed = [];
+
+  const fieldMap = {
+    first_name: "first name",
+    last_name: "last name",
+    organization: "organization",
+    job_title: "job title"
+  };
+  for (const [arg, applescriptProp] of Object.entries(fieldMap)) {
+    if (args[arg] === undefined) continue;
+    const validated = validateSubject(args[arg]);
+    if (validated.error) return { ok: false, message: `${action} refused: ${validated.error.replace("subject", arg)}` };
+    properties[applescriptProp] = validated.text;
+    changed.push(arg);
+  }
+
+  const emails = validateContactEmails(args.emails, args.email_label);
+  if (emails.error) return { ok: false, message: `${action} refused: ${emails.error}` };
+  const phones = validateContactPhones(args.phones, args.phone_label);
+  if (phones.error) return { ok: false, message: `${action} refused: ${phones.error}` };
+
+  const replaceEmails = isFlagTrue(args.replace_emails);
+  const replacePhones = isFlagTrue(args.replace_phones);
+  if (emails.emails.length) changed.push(`${replaceEmails ? "replace" : "add"} ${emails.emails.length} email(s)`);
+  if (phones.phones.length) changed.push(`${replacePhones ? "replace" : "add"} ${phones.phones.length} phone(s)`);
+  if (replaceEmails && emails.emails.length === 0) changed.push("remove all emails");
+  if (replacePhones && phones.phones.length === 0) changed.push("remove all phones");
+
+  if (changed.length === 0) {
+    return { ok: false, message: `${action} refused: nothing to change. Pass at least one of first_name, last_name, organization, job_title, emails, phones.` };
+  }
+
+  const summary = `update contact ${contactId}: ${changed.join(", ")}`;
+  // Dropping every email or phone is destructive, so it needs confirmation.
+  const destructive = (replaceEmails && emails.emails.length === 0) || (replacePhones && phones.phones.length === 0);
+  const plan = planWrite({
+    action,
+    summary,
+    destructive,
+    dryRun: isFlagTrue(args.dry_run),
+    confirm: isFlagTrue(args.confirm)
+  });
+  if (!plan.proceed) return { ok: true, message: plan.message, planned: true };
+
+  const result = runAppleScript(
+    buildEditContactScript({
+      contactId,
+      properties,
+      emails: emails.emails,
+      phones: phones.phones,
+      replaceEmails,
+      replacePhones
+    }),
+    { timeout: 60000, appName: "Contacts" }
+  );
+  if (!result.ok) return { ok: false, message: failure(action, summary, result) };
+
+  return {
+    ok: true,
+    message: writeSuccessMessage(action, "contact updated", {
+      contact_id: contactId,
+      name: truncate(result.output, 120) || undefined,
+      changed: changed.join(", ")
+    })
+  };
+}
+
+export function buildRemoveContactScript(contactId) {
+  return `${findPersonHandler()}
+
+set thePerson to atmFindPerson(${asString(contactId)})
+tell application "Contacts"
+  set removedName to name of thePerson
+  delete thePerson
+  save
+end tell
+return removedName`;
+}
+
+export function contactsRemove(args = {}) {
+  const action = "contacts_remove";
+
+  const contactId = validateContactId(args.contact_id);
+  if (!contactId) {
+    return { ok: false, message: `${action} refused: contact_id is required (the "Contact ID" from contacts_search or contacts_lookup). Deletes never run on a guessed id.` };
+  }
+
+  const summary = `delete contact ${contactId}`;
+  const plan = planWrite({
+    action,
+    summary,
+    destructive: true,
+    dryRun: isFlagTrue(args.dry_run),
+    confirm: isFlagTrue(args.confirm)
+  });
+  if (!plan.proceed) return { ok: true, message: plan.message, planned: true };
+
+  const result = runAppleScript(buildRemoveContactScript(contactId), { timeout: 60000, appName: "Contacts" });
+  if (!result.ok) return { ok: false, message: failure(action, summary, result) };
+
+  return {
+    ok: true,
+    message: writeSuccessMessage(action, "contact deleted", {
+      contact_id: contactId,
+      name: truncate(result.output, 120) || undefined
+    })
+  };
+}

package/lib/indexGate.js

@@ -5,6 +5,8 @@
  * index cycle." A second MCP instance that lost the indexer lock never runs
  * a cycle, so that flag stays false. Lost-lock must not be treated as
  * "still indexing" — callers still check isIndexReady() for a missing index.
+ * isIndexReady() / initDB() must re-list LanceDB tables on each check so a
+ * first empty catalog (daemon writer in flight) is not cached forever.
  */
 
 /**
@@ -57,3 +59,50 @@ export function indexUnavailableMessage(type) {
   }
   return "Index not available. Please try again shortly.";
 }
+
+export const BUILDING_INITIAL_INDEX_MESSAGE =
+  "Building initial index. This may take several minutes on first run. Please try again shortly.";
+
+export const INDEXING_NEW_DATA_MESSAGE =
+  "Indexing new data. Please try again in a moment.";
+
+/**
+ * Still-indexing copy. Only for a process that owns the lock and has not
+ * finished a local cycle — never for a lost-lock MCP reader.
+ *
+ * @param {boolean} isFirstEverRun
+ * @returns {string}
+ */
+export function indexingInProgressMessage(isFirstEverRun) {
+  return isFirstEverRun ? BUILDING_INITIAL_INDEX_MESSAGE : INDEXING_NEW_DATA_MESSAGE;
+}
+
+/**
+ * Preflight for index-backed MCP query tools.
+ * Readiness is `indexReady` (usable on-disk tables), not sessionIndexComplete.
+ * Lost-lock never returns "building initial index" / still-indexing.
+ *
+ * @param {{
+ *   sessionIndexComplete: boolean,
+ *   ownsIndexLock: boolean,
+ *   indexReady: boolean,
+ *   type?: "emails"|"messages"|"calendar",
+ *   isFirstEverRun?: boolean
+ * }} args
+ * @returns {{ ok: boolean, message: string|null }}
+ */
+export function indexQueryGate({
+  sessionIndexComplete,
+  ownsIndexLock,
+  indexReady,
+  type,
+  isFirstEverRun = false
+}) {
+  if (isSearchBlockedByIndexing(sessionIndexComplete, ownsIndexLock)) {
+    return { ok: false, message: indexingInProgressMessage(isFirstEverRun) };
+  }
+  if (!indexReady) {
+    return { ok: false, message: indexUnavailableMessage(type) };
+  }
+  return { ok: true, message: null };
+}

package/lib/lancedbTables.js

@@ -0,0 +1,307 @@
+/**
+ * Shared LanceDB table cache for the vector index.
+ *
+ * MCP stdio and the indexer daemon are separate processes. The daemon keeps a
+ * writer connection for its lifetime. A short-lived MCP reader must still see
+ * on-disk emails/messages/calendar tables — including when the first connect
+ * listed an empty catalog (writer commit in flight, stale snapshot, or a
+ * concurrent initDB that returned before openTable finished).
+ *
+ * Default LanceDB consistency does not re-check other processes. Readers pass
+ * readConsistencyInterval: 0 so tableNames()/openTable() see committed catalog.
+ */
+
+import fs from "fs";
+import path from "path";
+
+export const INDEX_TABLE_NAMES = ["emails", "messages", "calendar"];
+
+/** Strong cross-process read freshness (seconds). 0 = check on every read. */
+export const LANCE_READ_CONSISTENCY_INTERVAL = 0;
+
+export const LANCE_CONNECT_OPTIONS = {
+  readConsistencyInterval: LANCE_READ_CONSISTENCY_INTERVAL
+};
+
+/**
+ * LanceDB stores each table as `<name>.lance` under the index directory.
+ *
+ * @param {string} indexDir
+ * @param {string} name
+ * @param {(p: string) => boolean} [existsSync]
+ * @returns {boolean}
+ */
+export function lanceTableExistsOnDisk(indexDir, name, existsSync = fs.existsSync) {
+  if (!indexDir || !INDEX_TABLE_NAMES.includes(name)) {
+    return false;
+  }
+  try {
+    const tableDir = path.join(indexDir, `${name}.lance`);
+    const resolvedIndex = path.resolve(indexDir);
+    const resolvedTable = path.resolve(tableDir);
+    if (resolvedTable !== path.join(resolvedIndex, `${name}.lance`)) {
+      return false;
+    }
+    return existsSync(tableDir);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Open any INDEX_TABLE_NAMES entries not already in `tables`.
+ * Always re-lists tableNames — never assume a prior empty catalog is final.
+ *
+ * @param {{
+ *   db: { tableNames: () => Promise<string[]>, openTable: (name: string) => Promise<unknown>, close?: () => void },
+ *   tables: Record<string, unknown>,
+ *   indexDir: string,
+ *   existsSync?: (p: string) => boolean,
+ *   reconnect?: () => Promise<{ tableNames: () => Promise<string[]>, openTable: (name: string) => Promise<unknown>, close?: () => void }>,
+ *   isCurrent?: () => boolean,
+ *   log?: (msg: string) => void
+ * }} args
+ * @returns {Promise<{ db: object, tables: Record<string, unknown>, reconnected: boolean, aborted: boolean }>}
+ */
+export async function openMissingIndexTables({
+  db,
+  tables,
+  indexDir,
+  existsSync = fs.existsSync,
+  reconnect,
+  isCurrent = () => true,
+  log = (msg) => console.error(msg)
+}) {
+  const stillCurrent = () => {
+    try {
+      return isCurrent() !== false;
+    } catch {
+      return false;
+    }
+  };
+
+  const missing = INDEX_TABLE_NAMES.filter((name) => tables[name] == null);
+  if (missing.length === 0) {
+    return { db, tables, reconnected: false, aborted: false };
+  }
+
+  let tableNames = [];
+  try {
+    tableNames = await db.tableNames();
+  } catch (e) {
+    log(`Failed to list index tables: ${e.message}`);
+    return { db, tables, reconnected: false, aborted: !stillCurrent() };
+  }
+
+  if (!stillCurrent()) {
+    return { db, tables, reconnected: false, aborted: true };
+  }
+
+  const listed = new Set(tableNames);
+  const onDiskButUnlisted = missing.filter(
+    (name) => !listed.has(name) && lanceTableExistsOnDisk(indexDir, name, existsSync)
+  );
+
+  let reconnected = false;
+  let conn = db;
+  if (onDiskButUnlisted.length > 0 && typeof reconnect === "function") {
+    log("Index catalog missed on-disk tables; reconnecting to shared vector-index.");
+    for (const name of INDEX_TABLE_NAMES) {
+      delete tables[name];
+    }
+    try {
+      conn = await reconnect();
+      reconnected = true;
+      if (!stillCurrent()) {
+        return { db: conn, tables, reconnected, aborted: true };
+      }
+      tableNames = await conn.tableNames();
+    } catch (e) {
+      log(`Failed to reconnect to index: ${e.message}`);
+      return { db: conn, tables, reconnected, aborted: !stillCurrent() };
+    }
+  }
+
+  if (!stillCurrent()) {
+    return { db: conn, tables, reconnected, aborted: true };
+  }
+
+  const stillMissing = INDEX_TABLE_NAMES.filter((name) => tables[name] == null);
+  for (const name of stillMissing) {
+    if (!tableNames.includes(name)) {
+      continue;
+    }
+    try {
+      tables[name] = await conn.openTable(name);
+    } catch (e) {
+      log(`Failed to open ${name} table: ${e.message}`);
+    }
+    if (!stillCurrent()) {
+      return { db: conn, tables, reconnected, aborted: true };
+    }
+  }
+
+  return { db: conn, tables, reconnected, aborted: false };
+}
+
+/**
+ * Process-local LanceDB connection + table handles.
+ * `tables` is a stable object (reset deletes keys, does not replace the object)
+ * so indexer.js can alias it for createTable/dropTable mutation.
+ *
+ * @param {{
+ *   connect: (uri: string, options: object) => Promise<object>,
+ *   indexDir: string,
+ *   mkdirSync?: (p: string, opts?: object) => void,
+ *   existsSync?: (p: string) => boolean,
+ *   log?: (msg: string) => void,
+ *   connectOptions?: object
+ * }} options
+ */
+export function createLanceTableCache(options) {
+  const {
+    connect,
+    indexDir,
+    mkdirSync,
+    existsSync = fs.existsSync,
+    log = (msg) => console.error(msg),
+    connectOptions = LANCE_CONNECT_OPTIONS
+  } = options;
+
+  const tables = {};
+  let db = null;
+  let connecting = null;
+  let refreshing = null;
+  let generation = 0;
+
+  function rememberPromise(getSlot, setSlot, pending) {
+    // Store the .finally() chain, not the raw pending. Discarding the derived
+    // promise leaves connect() failures as unhandledRejection (index.js exits).
+    const tracked = pending.finally(() => {
+      if (getSlot() === tracked) {
+        setSlot(null);
+      }
+    });
+    setSlot(tracked);
+    return tracked;
+  }
+
+  async function ensureDb() {
+    if (db) {
+      return db;
+    }
+    if (!connecting) {
+      const gen = generation;
+      rememberPromise(
+        () => connecting,
+        (value) => {
+          connecting = value;
+        },
+        (async () => {
+          if (typeof mkdirSync === "function") {
+            mkdirSync(indexDir, { recursive: true });
+          }
+          const conn = await connect(indexDir, connectOptions);
+          if (gen !== generation) {
+            try {
+              conn?.close?.();
+            } catch {
+              // stale connect after reset
+            }
+            return ensureDb();
+          }
+          db = conn;
+          return db;
+        })()
+      );
+    }
+    return connecting;
+  }
+
+  async function initDB() {
+    if (!refreshing) {
+      const gen = generation;
+      rememberPromise(
+        () => refreshing,
+        (value) => {
+          refreshing = value;
+        },
+        (async () => {
+          await ensureDb();
+          if (gen !== generation) {
+            return;
+          }
+          const result = await openMissingIndexTables({
+            db,
+            tables,
+            indexDir,
+            existsSync,
+            log,
+            isCurrent: () => gen === generation,
+            reconnect: async () => {
+              if (gen !== generation) {
+                return ensureDb();
+              }
+              try {
+                db?.close?.();
+              } catch {
+                // ignore close errors on a stale handle
+              }
+              if (gen !== generation) {
+                return ensureDb();
+              }
+              db = null;
+              return ensureDb();
+            }
+          });
+          if (gen !== generation || result.aborted) {
+            return;
+          }
+          db = result.db;
+        })()
+      );
+    }
+    await refreshing;
+    return { db, tables };
+  }
+
+  async function isIndexReady(type = "emails") {
+    await initDB();
+    return tables[type] != null;
+  }
+
+  async function getOpenTable(type) {
+    await initDB();
+    return tables[type] || null;
+  }
+
+  function reset() {
+    generation += 1;
+    const toClose = db;
+    db = null;
+    connecting = null;
+    refreshing = null;
+    for (const key of Object.keys(tables)) {
+      delete tables[key];
+    }
+    try {
+      toClose?.close?.();
+    } catch {
+      // ignore
+    }
+  }
+
+  return {
+    initDB,
+    isIndexReady,
+    getOpenTable,
+    reset,
+    get db() {
+      return db;
+    },
+    set db(value) {
+      db = value;
+    },
+    tables
+  };
+}