apple-tools-mcp 1.2.0 → 2.0.0

package/index.js

@@ -9,7 +9,7 @@ import {
 import fs from "fs";
 import path from "path";
 import { validateEmailPath, stripHtmlTags, unfoldRfc822Headers, validateLimit, validateDaysBack, validateWeekOffset, toUnixMillis } from "./lib/validators.js";
-import { isSearchBlockedByIndexing, cycleEndFlags, indexUnavailableMessage } from "./lib/indexGate.js";
+import { cycleEndFlags, indexUnavailableMessage, indexQueryGate } from "./lib/indexGate.js";
 import { isIndexerMode } from "./lib/processMode.js";
 import { loadResolvedIndexInterval, logResolvedInterval } from "./lib/config.js";
 import { createIndexerLock, DEFAULT_LOCK_HEARTBEAT_MS } from "./lib/indexerLock.js";
@@ -22,6 +22,13 @@ import {
   waitForIndexerLock,
   beginOwnedIndexing
 } from "./lib/indexerRuntime.js";
+import {
+  WRITE_TOOL_DEFINITIONS,
+  isWriteTool,
+  dispatchWriteTool,
+  executeWriteToolLocally
+} from "./lib/writeTools.js";
+import { startWriteBridgeServer, defaultSocketPath } from "./lib/writeBridge.js";
 
 const PACKAGE_VERSION = JSON.parse(
   fs.readFileSync(new URL("./package.json", import.meta.url), "utf8")
@@ -70,9 +77,37 @@ function stopLockHeartbeat() {
   indexerLock.stopHeartbeat();
 }
 
+// Daemon-only: serves writes for stdio clients whose host app cannot be
+// granted Contacts/Calendar automation (see lib/writeBridge.js).
+const WRITE_SOCKET_PATH = defaultSocketPath();
+let writeBridge = null;
+
+function stopWriteBridge() {
+  if (!writeBridge) return;
+  try {
+    writeBridge.close();
+  } catch (e) {
+    console.error("Error closing write bridge:", e.message);
+  }
+  writeBridge = null;
+}
+
+async function startWriteBridge() {
+  try {
+    writeBridge = await startWriteBridgeServer({
+      socketPath: WRITE_SOCKET_PATH,
+      handler: (tool, args) => executeWriteToolLocally(tool, args),
+      log: (msg) => console.error(msg)
+    });
+  } catch (e) {
+    console.error(`Write bridge unavailable: ${e.message}. Writes will run in each MCP process.`);
+  }
+}
+
 function shutdownIndexing(exitCode) {
   stopBackgroundIndexing();
   stopLockHeartbeat();
+  stopWriteBridge();
   releaseLock();
   if (exitCode !== undefined) {
     process.exit(exitCode);
@@ -83,6 +118,7 @@ function shutdownIndexing(exitCode) {
 process.on("exit", () => {
   stopBackgroundIndexing();
   stopLockHeartbeat();
+  stopWriteBridge();
   releaseLock();
 });
 process.on("SIGINT", () => {
@@ -180,14 +216,6 @@ async function checkIfFirstRun() {
   return !(emailsReady || messagesReady || calendarReady);
 }
 
-// Get appropriate status message based on indexing state
-function getIndexingMessage() {
-  if (isFirstEverRun) {
-    return "Building initial index. This may take several minutes on first run. Please try again shortly.";
-  }
-  return "Indexing new data. Please try again in a moment.";
-}
-
 // Run a single indexing cycle (called by background timer)
 function runIndexCycle() {
   const cycle = beginIndexCycle(indexingInProgress);
@@ -318,10 +346,30 @@ function applyCycleEnd(success) {
 // Index-backed tools wait only while THIS process owns the lock and has not
 // finished its cycle. Lost-lock secondaries fall through to isIndexReady().
 function stillIndexingMessage() {
-  if (isSearchBlockedByIndexing(sessionIndexComplete, ownsIndexLock)) {
-    return getIndexingMessage();
+  const gate = indexQueryGate({
+    sessionIndexComplete,
+    ownsIndexLock,
+    indexReady: true,
+    isFirstEverRun
+  });
+  return gate.ok ? null : gate.message;
+}
+
+/** Shared preflight for index-backed query tools (on-disk tables, not local cycle). */
+async function requireIndex(type) {
+  const indexing = stillIndexingMessage();
+  if (indexing) {
+    return indexing;
   }
-  return null;
+  const ready = await isIndexReady(type);
+  const gate = indexQueryGate({
+    sessionIndexComplete,
+    ownsIndexLock,
+    indexReady: ready,
+    type,
+    isFirstEverRun
+  });
+  return gate.ok ? null : gate.message;
 }
 
 function waitForLockAndStartDaemon() {
@@ -338,12 +386,27 @@ function waitForLockAndStartDaemon() {
 
 // Initialize and start indexing
 async function initializeIndexing() {
-  isFirstEverRun = await checkIfFirstRun();
-
   if (INDEXER_MODE) {
     console.error(`Apple Tools MCP indexer running (v${PACKAGE_VERSION})`);
     logResolvedInterval(resolvedIndexInterval);
     loggedIndexInterval = true;
+    // launchd started this process, so node owns its TCC prompts. Offer the
+    // write bridge to stdio clients whose host app cannot get those grants.
+    // This happens before any index work: writes must stay available even if
+    // the vector index is missing, locked, or unreadable.
+    await startWriteBridge();
+  }
+
+  try {
+    isFirstEverRun = await checkIfFirstRun();
+  } catch (e) {
+    // A failed readiness probe must not take the daemon (or its write
+    // bridge) down; assume a first run and let the cycle report the details.
+    console.error(`Could not determine index state: ${e.message}`);
+    isFirstEverRun = true;
+  }
+
+  if (INDEXER_MODE) {
     waitForLockAndStartDaemon();
     return;
   }
@@ -355,7 +418,8 @@ async function initializeIndexing() {
   if (!startup.startBackground) {
     console.error("Another apple-tools-mcp instance is indexing. Server will run without background indexing.");
     // Lost lock is not "still indexing": this process will never complete a
-    // local cycle. Searches proceed whenever isIndexReady() is true.
+    // local cycle. Searches proceed whenever isIndexReady() is true (initDB
+    // re-lists shared on-disk tables; it must not cache an empty first connect).
     ownsIndexLock = false;
     return;
   }
@@ -369,8 +433,12 @@ async function initializeIndexing() {
   });
 }
 
-// Start indexing immediately on server startup
-initializeIndexing();
+// Start indexing immediately on server startup. A startup failure is logged
+// rather than rejected: an unhandled rejection would tear down the daemon,
+// taking the write bridge with it.
+initializeIndexing().catch((e) => {
+  console.error(`Indexing startup failed: ${e.message}`);
+});
 
 // ============ SEMANTIC SEARCH FUNCTIONS ============
 
@@ -379,14 +447,9 @@ async function mailSearch(query, options = {}) {
     return "Error: query parameter is required for mail_search";
   }
 
-  const indexing = stillIndexingMessage();
-  if (indexing) {
-    return indexing;
-  }
-
-  const ready = await isIndexReady("emails");
-  if (!ready) {
-    return indexUnavailableMessage("emails");
+  const blocked = await requireIndex("emails");
+  if (blocked) {
+    return blocked;
   }
 
   const result = await searchEmails(query, options);
@@ -394,14 +457,9 @@ async function mailSearch(query, options = {}) {
 }
 
 async function mailRecent(limit = 30, daysBack = 7, unreadOnly = false, includeJunk = false) {
-  const indexing = stillIndexingMessage();
-  if (indexing) {
-    return indexing;
-  }
-
-  const ready = await isIndexReady("emails");
-  if (!ready) {
-    return indexUnavailableMessage("emails");
+  const blocked = await requireIndex("emails");
+  if (blocked) {
+    return blocked;
   }
 
   const result = await getRecentEmailResults(limit, daysBack, unreadOnly, includeJunk);
@@ -409,14 +467,9 @@ async function mailRecent(limit = 30, daysBack = 7, unreadOnly = false, includeJ
 }
 
 async function mailDate(date, includeJunk = false) {
-  const indexing = stillIndexingMessage();
-  if (indexing) {
-    return indexing;
-  }
-
-  const ready = await isIndexReady("emails");
-  if (!ready) {
-    return indexUnavailableMessage("emails");
+  const blocked = await requireIndex("emails");
+  if (blocked) {
+    return blocked;
   }
 
   const result = await getEmailDateResults(date, includeJunk);
@@ -424,14 +477,9 @@ async function mailDate(date, includeJunk = false) {
 }
 
 async function messagesSearch(query, options = {}) {
-  const indexing = stillIndexingMessage();
-  if (indexing) {
-    return indexing;
-  }
-
-  const ready = await isIndexReady("messages");
-  if (!ready) {
-    return indexUnavailableMessage("messages");
+  const blocked = await requireIndex("messages");
+  if (blocked) {
+    return blocked;
   }
 
   const result = await searchMessages(query, options);
@@ -439,14 +487,9 @@ async function messagesSearch(query, options = {}) {
 }
 
 async function messagesRecent(limit = 10, daysBack = 1) {
-  const indexing = stillIndexingMessage();
-  if (indexing) {
-    return indexing;
-  }
-
-  const ready = await isIndexReady("messages");
-  if (!ready) {
-    return indexUnavailableMessage("messages");
+  const blocked = await requireIndex("messages");
+  if (blocked) {
+    return blocked;
   }
 
   const result = await getRecentMessageResults(limit, daysBack);
@@ -454,14 +497,9 @@ async function messagesRecent(limit = 10, daysBack = 1) {
 }
 
 async function messagesConversation(contact, limit = 50) {
-  const indexing = stillIndexingMessage();
-  if (indexing) {
-    return indexing;
-  }
-
-  const ready = await isIndexReady("messages");
-  if (!ready) {
-    return indexUnavailableMessage("messages");
+  const blocked = await requireIndex("messages");
+  if (blocked) {
+    return blocked;
   }
 
   const result = await getConversationResults(contact, limit);
@@ -469,14 +507,9 @@ async function messagesConversation(contact, limit = 50) {
 }
 
 async function calendarSearch(query, options = {}) {
-  const indexing = stillIndexingMessage();
-  if (indexing) {
-    return indexing;
-  }
-
-  const ready = await isIndexReady("calendar");
-  if (!ready) {
-    return indexUnavailableMessage("calendar");
+  const blocked = await requireIndex("calendar");
+  if (blocked) {
+    return blocked;
   }
 
   const result = await searchCalendar(query, options);
@@ -772,6 +805,7 @@ function formatContactsSearchResults(contacts) {
     output += `• ${c.displayName}`;
     if (c.organization) output += ` (${c.organization})`;
     output += "\n";
+    if (c.uniqueId) output += `  Contact ID: ${c.uniqueId}\n`;
     if (c.emails.length > 0) {
       output += `  Emails: ${c.emails.map(e => e.email).join(", ")}\n`;
     }
@@ -791,6 +825,7 @@ function formatContactLookupResult(contact) {
   let output = `Contact: ${contact.displayName}\n`;
   output += "─".repeat(40) + "\n";
 
+  if (contact.uniqueId) output += `Contact ID: ${contact.uniqueId}\n`;
   if (contact.organization) output += `Organization: ${contact.organization}\n`;
   if (contact.department) output += `Department: ${contact.department}\n`;
   if (contact.jobTitle) output += `Job Title: ${contact.jobTitle}\n`;
@@ -1292,6 +1327,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ["name"],
       },
     },
+
+    // ============ WRITE TOOLS (2.0.0) ============
+    // Mail / Messages / Calendar / Contacts writes with dry_run + confirm.
+    ...WRITE_TOOL_DEFINITIONS,
   ],
 }));
 
@@ -1302,6 +1341,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   try {
     let result;
 
+    // Writes never wait on the vector index: they talk to Mail / Messages /
+    // Calendar / Contacts directly and must keep working while the indexer
+    // daemon holds the lock.
+    if (isWriteTool(name)) {
+      const writeResult = await dispatchWriteTool(name, args || {}, {
+        indexerMode: INDEXER_MODE,
+        socketPath: WRITE_SOCKET_PATH,
+        log: (msg) => console.error(msg)
+      });
+      return {
+        content: [{ type: "text", text: writeResult.message }],
+        ...(writeResult.ok === false ? { isError: true } : {})
+      };
+    }
+
     switch (name) {
       // Smart search (agentic)
       case "smart_search":
@@ -1397,16 +1451,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       // Mail tools
       case "mail_senders":
         {
-          const indexing = stillIndexingMessage();
-          if (indexing) {
-            result = indexing;
+          const blocked = await requireIndex("emails");
+          if (blocked) {
+            result = blocked;
             break;
           }
         }
-        if (!(await isIndexReady("emails"))) {
-          result = indexUnavailableMessage("emails");
-          break;
-        }
         result = formatSendersResults(await getFrequentSenders(
           validateLimit(args?.limit, 30),
           validateDaysBack(args?.days_back),
@@ -1481,16 +1531,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
       case "mail_thread":
         {
-          const indexing = stillIndexingMessage();
-          if (indexing) {
-            result = indexing;
+          const blocked = await requireIndex("emails");
+          if (blocked) {
+            result = blocked;
             break;
           }
         }
-        if (!(await isIndexReady("emails"))) {
-          result = indexUnavailableMessage("emails");
-          break;
-        }
         result = formatEmailThreadResults(await getEmailThread(args.file_path, validateLimit(args?.limit, 30)));
         break;
 

package/indexer.js

@@ -16,6 +16,7 @@ import {
 } from "./lib/validators.js";
 import { safeSqlite3Json, safeOsascript, safeFind } from "./lib/shell.js";
 import { indexUnavailableMessage } from "./lib/indexGate.js";
+import { createLanceTableCache, LANCE_CONNECT_OPTIONS } from "./lib/lancedbTables.js";
 
 // Re-export contact functions for use by other modules
 export {
@@ -70,8 +71,17 @@ const MAC_ABSOLUTE_EPOCH = 978307200;
 export const CALENDAR_TMP_PREFIX = "apple-tools-cal-";
 
 let embeddingPipeline = null;
+
+// One connection per process. Do not early-return a first connect that saw an
+// empty catalog — MCP stdio must pick up tables the indexer daemon already wrote.
+const lanceCache = createLanceTableCache({
+  connect: (uri, options) => lancedb.connect(uri, options),
+  indexDir: INDEX_DIR,
+  mkdirSync: (p, o) => fs.mkdirSync(p, o),
+  connectOptions: LANCE_CONNECT_OPTIONS
+});
+const tables = lanceCache.tables;
 let db = null;
-let tables = {};
 
 async function getEmbedder() {
   if (!embeddingPipeline) {
@@ -751,23 +761,19 @@ function getCalendarEvents() {
 // ============ DATABASE FUNCTIONS ============
 
 export async function initDB() {
-  if (db) return { db, tables };
-
-  fs.mkdirSync(INDEX_DIR, { recursive: true });
-  db = await lancedb.connect(INDEX_DIR);
+  const result = await lanceCache.initDB();
+  db = result.db;
+  return { db, tables };
+}
 
-  const tableNames = await db.tableNames();
-  if (tableNames.includes("emails")) {
-    tables.emails = await db.openTable("emails");
-  }
-  if (tableNames.includes("messages")) {
-    tables.messages = await db.openTable("messages");
-  }
-  if (tableNames.includes("calendar")) {
-    tables.calendar = await db.openTable("calendar");
-  }
+export async function getOpenTable(type) {
+  await initDB();
+  return tables[type] || null;
+}
 
-  return { db, tables };
+function resetLanceConnection() {
+  lanceCache.reset();
+  db = null;
 }
 
 export async function clearEmailsTable() {
@@ -828,10 +834,9 @@ export async function rebuildIndex(sources = ["emails", "messages", "calendar"],
     }
   }
 
-  // Reset module-level cache after dropping tables
-  // This ensures that initDB() will re-initialize and pick up the newly created tables
-  db = null;
-  tables = {};
+  // Reset connection cache after dropping tables so initDB() re-opens
+  // (or recreates) them instead of holding stale/empty handles.
+  resetLanceConnection();
 
   // Re-index requested sources
   for (const source of sources) {
@@ -1451,7 +1456,7 @@ export async function indexAll(progressCallback = null) {
 
 export async function isIndexReady(type = "emails") {
   await initDB();
-  return tables[type] !== null && tables[type] !== undefined;
+  return tables[type] != null;
 }
 
 // ============ DIRECT QUERIES (for recent items) ============
@@ -1736,7 +1741,9 @@ export function localDayToMacBounds(startMs, endMs) {
 }
 
 // Date-bounded OccurrenceCache query: one row per occurrence, no GROUP BY ci.ROWID
-export function buildEventsOnDateQuery(startMac, endMac) {
+// includeUid adds the iCal UID that the calendar write tools address events by.
+// Older Calendar schemas may lack the column, so callers can retry without it.
+export function buildEventsOnDateQuery(startMac, endMac, { includeUid = true } = {}) {
   const startBound = Math.floor(Number(startMac));
   const endBound = Math.floor(Number(endMac));
   if (!Number.isFinite(startBound) || !Number.isFinite(endBound)) {
@@ -1750,6 +1757,7 @@ export function buildEventsOnDateQuery(startMac, endMac) {
   return `
       SELECT DISTINCT
         ci.ROWID as itemId,
+        ${includeUid ? "ci.unique_identifier as uid," : "'' as uid,"}
         ci.summary as title,
         datetime(CASE WHEN ci.all_day THEN ${allDayStartMac} ELSE ${timedStart} END + 978307200, 'unixepoch', 'localtime') as start,
         datetime(${occEnd} + 978307200, 'unixepoch', 'localtime') as end,
@@ -1816,9 +1824,11 @@ export function getEventsOnDate(startMs, endMs) {
       return { events: [], error: "Calendar database not found" };
     }
     const { startMac, endMac } = localDayToMacBounds(startMs, endMs);
-    const query = buildEventsOnDateQuery(startMac, endMac);
     let lastError;
     for (let attempt = 0; attempt < 3; attempt++) {
+      // Drop the UID column after a failed first attempt: a schema without
+      // unique_identifier must still return events for calendar_date.
+      const query = buildEventsOnDateQuery(startMac, endMac, { includeUid: attempt === 0 });
       try {
         const events = withCalendarCopy((dbPath) => {
           return safeSqlite3Json(dbPath, query, { timeout: 15000 });