apple-tools-mcp 1.1.2 → 1.1.4

package/README.md

@@ -1,6 +1,6 @@
 # apple-tools-mcp
 
-An MCP (Model Context Protocol) server that provides semantic search across Apple Mail, Messages, Calendar, and Contacts on macOS. Use natural language to search your emails, iMessages, calendar events, and contacts directly from Claude.
+An MCP (Model Context Protocol) server that provides semantic search across Apple Mail, Messages, Calendar, and Contacts on macOS. Use natural language to search your emails, iMessages, calendar events, and contacts from any compatible MCP client over stdio.
 
 ## Features
 
@@ -14,7 +14,6 @@ An MCP (Model Context Protocol) server that provides semantic search across Appl
 
 - **macOS** (Ventura 13.0 or later recommended)
 - **Node.js** 18.0 or later
-- **Claude Desktop** app
 - **Full Disk Access** permission for the Node.js binary
 
 ## Installation
@@ -33,7 +32,7 @@ cd Apple-Tools-MCP
 npm install
 ```
 
-If you installed from source, point Claude Desktop at the local `index.js` instead of `npx` in step 3:
+If you installed from source, point your MCP client at the local `index.js` instead of `npx` in step 3:
 
 ```json
 "command": "node",
@@ -64,11 +63,18 @@ The MCP server needs access to read your Mail, Messages, and Calendar databases.
 
 7. Ensure the toggle for Node.js is enabled
 
-### 3. Configure Claude Desktop
+### 3. Configure your MCP client
 
-Add to your Claude Desktop config file:
+This server speaks MCP over **stdio**. Any compatible client can run it — Claude Desktop is one example, not the only one. Cursor, Grok Bot, and other stdio MCP clients work the same way: register the command below in that client's MCP settings.
 
-**Location:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Command**
+
+- `npx` with args `["-y", "apple-tools-mcp"]` (npm install)
+- or `node` with args `["/absolute/path/to/Apple-Tools-MCP/index.js"]` (from source)
+
+**Example: Claude Desktop**
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 ```json
 {
@@ -81,9 +87,11 @@ Add to your Claude Desktop config file:
 }
 ```
 
-### 4. Restart Claude Desktop
+Other clients use their own settings UI or config file. Use the same `command` and `args`; only the file path or UI differs.
+
+### 4. Restart your MCP client
 
-Quit and reopen Claude Desktop to load the MCP server.
+Quit and reopen the client so it loads the server. For Claude Desktop, fully quit (Cmd+Q) and reopen.
 
 ## Building the Index
 
@@ -103,7 +111,7 @@ The index is stored in `~/.apple-tools-mcp/vector-index/`.
 
 ## Available Tools
 
-Once configured, Claude can use these tools:
+Once configured, your MCP client can use these tools:
 
 ### Universal Search
 
@@ -159,7 +167,7 @@ Once configured, Claude can use these tools:
 
 ## Example Queries
 
-Ask Claude things like:
+Ask your MCP client things like:
 
 - "Find emails from John about the quarterly report"
 - "What messages did I get from Mom last week?"
@@ -187,11 +195,11 @@ Ensure Node.js has Full Disk Access (see Installation step 2).
 1. Check that the index was built: `ls ~/.apple-tools-mcp/vector-index/`
 2. Rebuild the index if needed: `npm run build-index`
 
-### Server not appearing in Claude
+### Server not appearing in the MCP client
 
-1. Verify your config file syntax is valid JSON
-2. Restart Claude Desktop completely (Cmd+Q, then reopen)
-3. Check Claude's MCP logs for errors
+1. Verify your client config is valid (JSON files must be valid JSON)
+2. Restart the MCP client completely (for Claude Desktop: Cmd+Q, then reopen)
+3. Check the client's MCP logs for errors
 
 ### Force rebuild the index
 
@@ -203,12 +211,12 @@ rm -rf ~/.apple-tools-mcp/vector-index
 rm -f ~/.apple-tools-mcp/index-meta.json
 rm -f ~/.apple-tools-mcp/indexer.lock
 
-# Restart Claude Desktop to trigger a fresh rebuild
+# Restart your MCP client to trigger a fresh rebuild
 ```
 
 ### Monitor indexing progress
 
-Watch the MCP server logs in real-time:
+Watch the MCP server logs in your client. Log locations vary by client; Claude Desktop example:
 
 ```bash
 tail -f ~/Library/Logs/Claude/mcp-server-apple-tools.log

package/index.js

@@ -9,10 +9,19 @@ 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";
+
+const PACKAGE_VERSION = JSON.parse(
+  fs.readFileSync(new URL("./package.json", import.meta.url), "utf8")
+).version;
 
 // Lock file to prevent duplicate indexing processes
 const LOCK_FILE = path.join(process.env.HOME, ".apple-tools-mcp", "indexer.lock");
 const LOCK_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes - if lock is older, assume hung process
+// True only while this process won the indexer lock. Distinct from
+// sessionIndexComplete: a secondary instance that lost the lock never
+// completes a local cycle and must not stay on "still indexing" forever.
+let ownsIndexLock = false;
 
 function acquireLock() {
   try {
@@ -32,6 +41,7 @@ function acquireLock() {
 
       // If we already hold the lock, return true
       if (pid === process.pid) {
+        ownsIndexLock = true;
         return true;
       }
 
@@ -44,6 +54,7 @@ function acquireLock() {
           fs.unlinkSync(LOCK_FILE);
         } else {
           console.error(`Another indexing instance running (PID ${pid}). Skipping indexing.`);
+          ownsIndexLock = false;
           return false;
         }
       } catch {
@@ -57,17 +68,20 @@ function acquireLock() {
     // This prevents TOCTOU race condition - will throw EEXIST if file was created between check and write
     try {
       fs.writeFileSync(LOCK_FILE, `${process.pid}:${Date.now()}`, { flag: 'wx' });
+      ownsIndexLock = true;
       return true;
     } catch (err) {
       if (err.code === 'EEXIST') {
         // Another process won the race
         console.error("Another process acquired lock during race. Skipping indexing.");
+        ownsIndexLock = false;
         return false;
       }
       throw err; // Re-throw unexpected errors
     }
   } catch (e) {
     console.error("Lock file error:", e.message);
+    ownsIndexLock = false;
     return false; // On error, fail safe - don't proceed
   }
 }
@@ -80,6 +94,7 @@ function releaseLock() {
       const pid = parseInt(pidStr);
       if (pid === process.pid) {
         fs.unlinkSync(LOCK_FILE);
+        ownsIndexLock = false;
         console.error(`Released lock file (PID ${process.pid})`);
       }
     }
@@ -125,7 +140,7 @@ process.on("unhandledRejection", (reason, promise) => {
   process.exit(1);
 });
 
-// Exit when stdin closes (Claude client disconnected)
+// Exit when stdin closes (MCP client disconnected)
 process.stdin.on("close", () => {
   console.error("Client disconnected. Exiting.");
   stopBackgroundIndexing();
@@ -259,11 +274,8 @@ function runIndexCycle() {
 
       lastIndexTime = Date.now();
       lastProgressTime = Date.now();
-      indexingInProgress = false;
-      sessionIndexComplete = true;
-      isFirstEverRun = false;  // After successful index, no longer first run
+      applyCycleEnd(true);
       console.error("Indexing complete.");
-      releaseLock(); // Allow other instances to index
       // Pre-warm tables to eliminate first-query latency
       await prewarmTables();
     }).catch(e => {
@@ -274,9 +286,7 @@ function runIndexCycle() {
       }
 
       console.error("Indexing error:", e.message);
-      indexingInProgress = false;
-      sessionIndexComplete = true;  // Mark complete even on error so queries can proceed
-      releaseLock(); // Allow other instances to index
+      applyCycleEnd(false);
     });
 }
 
@@ -313,6 +323,28 @@ function stopBackgroundIndexing() {
   console.error("Background indexing stopped");
 }
 
+// Unblock searches and drop the indexer lock after a cycle ends.
+// Must run on failure as well as success so tools are not stuck forever.
+function applyCycleEnd(success) {
+  const flags = cycleEndFlags(success);
+  indexingInProgress = flags.indexingInProgress;
+  sessionIndexComplete = flags.sessionIndexComplete;
+  ownsIndexLock = flags.ownsIndexLock;
+  if (flags.isFirstEverRun === false) {
+    isFirstEverRun = false;
+  }
+  releaseLock();
+}
+
+// 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();
+  }
+  return null;
+}
+
 // Initialize and start indexing
 async function initializeIndexing() {
   isFirstEverRun = await checkIfFirstRun();
@@ -321,6 +353,9 @@ async function initializeIndexing() {
   // indexing but keep the MCP server running so search still works.
   if (!acquireLock()) {
     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.
+    ownsIndexLock = false;
     return;
   }
 
@@ -338,13 +373,14 @@ async function mailSearch(query, options = {}) {
     return "Error: query parameter is required for mail_search";
   }
 
-  if (!sessionIndexComplete) {
-    return getIndexingMessage();
+  const indexing = stillIndexingMessage();
+  if (indexing) {
+    return indexing;
   }
 
   const ready = await isIndexReady("emails");
   if (!ready) {
-    return "Email index not available. Please try again shortly.";
+    return indexUnavailableMessage("emails");
   }
 
   const result = await searchEmails(query, options);
@@ -352,13 +388,14 @@ async function mailSearch(query, options = {}) {
 }
 
 async function mailRecent(limit = 30, daysBack = 7, unreadOnly = false, includeJunk = false) {
-  if (!sessionIndexComplete) {
-    return getIndexingMessage();
+  const indexing = stillIndexingMessage();
+  if (indexing) {
+    return indexing;
   }
 
   const ready = await isIndexReady("emails");
   if (!ready) {
-    return "Email index not available. Please try again shortly.";
+    return indexUnavailableMessage("emails");
   }
 
   const result = await getRecentEmailResults(limit, daysBack, unreadOnly, includeJunk);
@@ -366,13 +403,14 @@ async function mailRecent(limit = 30, daysBack = 7, unreadOnly = false, includeJ
 }
 
 async function mailDate(date, includeJunk = false) {
-  if (!sessionIndexComplete) {
-    return getIndexingMessage();
+  const indexing = stillIndexingMessage();
+  if (indexing) {
+    return indexing;
   }
 
   const ready = await isIndexReady("emails");
   if (!ready) {
-    return "Email index not available. Please try again shortly.";
+    return indexUnavailableMessage("emails");
   }
 
   const result = await getEmailDateResults(date, includeJunk);
@@ -380,13 +418,14 @@ async function mailDate(date, includeJunk = false) {
 }
 
 async function messagesSearch(query, options = {}) {
-  if (!sessionIndexComplete) {
-    return getIndexingMessage();
+  const indexing = stillIndexingMessage();
+  if (indexing) {
+    return indexing;
   }
 
   const ready = await isIndexReady("messages");
   if (!ready) {
-    return "Messages index not available. Please try again shortly.";
+    return indexUnavailableMessage("messages");
   }
 
   const result = await searchMessages(query, options);
@@ -394,13 +433,14 @@ async function messagesSearch(query, options = {}) {
 }
 
 async function messagesRecent(limit = 10, daysBack = 1) {
-  if (!sessionIndexComplete) {
-    return getIndexingMessage();
+  const indexing = stillIndexingMessage();
+  if (indexing) {
+    return indexing;
   }
 
   const ready = await isIndexReady("messages");
   if (!ready) {
-    return "Messages index not available. Please try again shortly.";
+    return indexUnavailableMessage("messages");
   }
 
   const result = await getRecentMessageResults(limit, daysBack);
@@ -408,13 +448,14 @@ async function messagesRecent(limit = 10, daysBack = 1) {
 }
 
 async function messagesConversation(contact, limit = 50) {
-  if (!sessionIndexComplete) {
-    return getIndexingMessage();
+  const indexing = stillIndexingMessage();
+  if (indexing) {
+    return indexing;
   }
 
   const ready = await isIndexReady("messages");
   if (!ready) {
-    return "Messages index not available. Please try again shortly.";
+    return indexUnavailableMessage("messages");
   }
 
   const result = await getConversationResults(contact, limit);
@@ -422,13 +463,14 @@ async function messagesConversation(contact, limit = 50) {
 }
 
 async function calendarSearch(query, options = {}) {
-  if (!sessionIndexComplete) {
-    return getIndexingMessage();
+  const indexing = stillIndexingMessage();
+  if (indexing) {
+    return indexing;
   }
 
   const ready = await isIndexReady("calendar");
   if (!ready) {
-    return "Calendar index not available. Please try again shortly.";
+    return indexUnavailableMessage("calendar");
   }
 
   const result = await searchCalendar(query, options);
@@ -591,8 +633,9 @@ function formatSmartSearchResults(results, synthesizedGroups = null) {
 
 // Smart search - routes to appropriate sources and optionally synthesizes results
 async function smartSearch(query, options = {}) {
-  if (!sessionIndexComplete) {
-    return getIndexingMessage();
+  const indexing = stillIndexingMessage();
+  if (indexing) {
+    return indexing;
   }
 
   const { limit = 5, synthesize = true } = options;
@@ -638,6 +681,10 @@ async function smartSearch(query, options = {}) {
 
   await Promise.all(searches);
 
+  if (Object.keys(results).length === 0) {
+    return indexUnavailableMessage();
+  }
+
   // Synthesize results into timeline if multiple sources returned data
   let synthesizedGroups = null;
   if (synthesize) {
@@ -763,8 +810,9 @@ function formatContactLookupResult(contact) {
 // ============ PERSON SEARCH (CROSS-SOURCE) ============
 
 async function personSearch(name, limit = 10) {
-  if (!sessionIndexComplete) {
-    return getIndexingMessage();
+  const indexing = stillIndexingMessage();
+  if (indexing) {
+    return indexing;
   }
 
   // First, try to find the contact to get all their identifiers
@@ -924,7 +972,7 @@ function formatPersonSearchResults(results) {
 // ============ MCP SERVER SETUP ============
 
 const server = new Server(
-  { name: "apple-tools-mcp", version: "2.0.0" },
+  { name: "apple-tools-mcp", version: PACKAGE_VERSION },
   { capabilities: { tools: {} } }
 );
 
@@ -1342,8 +1390,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
       // Mail tools
       case "mail_senders":
-        if (!sessionIndexComplete) {
-          result = getIndexingMessage();
+        {
+          const indexing = stillIndexingMessage();
+          if (indexing) {
+            result = indexing;
+            break;
+          }
+        }
+        if (!(await isIndexReady("emails"))) {
+          result = indexUnavailableMessage("emails");
           break;
         }
         result = formatSendersResults(await getFrequentSenders(
@@ -1356,13 +1411,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case "rebuild_index":
         // Check if indexing is already in progress in this session
         if (indexingInProgress) {
-          result = "⏳ Indexing is already in progress. Please wait for it to complete before starting a rebuild.";
+          result = "Indexing is already in progress. Please wait for it to complete before starting a rebuild.";
           break;
         }
 
         // Acquire lock to prevent parallel rebuilds across multiple MCP instances
         if (!acquireLock()) {
-          result = "Another indexing operation is already in progress in a different session. Please wait for it to complete.";
+          result = "Indexing is already in progress in a different session. Please wait for it to complete before starting a rebuild.";
           break;
         }
 
@@ -1373,10 +1428,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
         // Fire and forget - don't await
         rebuildIndex(rebuildSources).then((rebuildResult) => {
-          sessionIndexComplete = true;
-          isFirstEverRun = false;
-          indexingInProgress = false;
-          releaseLock();
+          applyCycleEnd(true);
           console.error("Index rebuild completed:", JSON.stringify({
             cleared: rebuildResult.cleared,
             indexed: Object.fromEntries(
@@ -1386,8 +1438,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           }));
         }).catch(e => {
           console.error("Index rebuild error:", e.message);
-          indexingInProgress = false;
-          releaseLock();
+          applyCycleEnd(false);
         });
 
         result = `🔄 Index rebuild started for: ${rebuildSources.join(", ")}.\n\nThis runs in the background and may take several minutes for large mailboxes. You can continue using other tools - searches will use the new index once complete.`;
@@ -1423,8 +1474,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       // ============ NEW TOOLS - PHASE 3 ============
 
       case "mail_thread":
-        if (!sessionIndexComplete) {
-          result = getIndexingMessage();
+        {
+          const indexing = stillIndexingMessage();
+          if (indexing) {
+            result = indexing;
+            break;
+          }
+        }
+        if (!(await isIndexReady("emails"))) {
+          result = indexUnavailableMessage("emails");
           break;
         }
         result = formatEmailThreadResults(await getEmailThread(args.file_path, validateLimit(args?.limit, 30)));
@@ -1465,7 +1523,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  console.error("Apple Tools MCP server running (v1.1.2)");
+  console.error(`Apple Tools MCP server running (v${PACKAGE_VERSION})`);
   // Background indexing runs automatically on startup and every INDEX_INTERVAL
 }
 

package/indexer.js

@@ -15,6 +15,7 @@ import {
   stripSubjectPrefixes
 } from "./lib/validators.js";
 import { safeSqlite3Json, safeOsascript, safeFind } from "./lib/shell.js";
+import { indexUnavailableMessage } from "./lib/indexGate.js";
 
 // Re-export contact functions for use by other modules
 export {
@@ -1936,7 +1937,7 @@ export function getWeekEvents(weekOffset = 0) {
 // Uses subject-based matching since Message-ID isn't indexed
 export async function getEmailThread(filePath, limit = 20) {
   await initDB();
-  if (!tables.emails) return { error: "Email index not ready", emails: [] };
+  if (!tables.emails) return { error: indexUnavailableMessage("emails"), emails: [] };
 
   try {
     // Validate file path to prevent path traversal attacks

package/lib/indexGate.js

@@ -0,0 +1,59 @@
+/**
+ * Index-session search gating.
+ *
+ * sessionIndexComplete means "this process finished (or abandoned) its own
+ * 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.
+ */
+
+/**
+ * Whether index-backed tools should return the still-indexing message.
+ *
+ * @param {boolean} sessionIndexComplete
+ * @param {boolean} ownsIndexLock true if this process won/holds the indexer lock
+ * @returns {boolean}
+ */
+export function isSearchBlockedByIndexing(sessionIndexComplete, ownsIndexLock) {
+  return Boolean(ownsIndexLock) && !sessionIndexComplete;
+}
+
+/**
+ * In-memory flags after an index or rebuild cycle ends.
+ * Searches must be unblocked on both success and failure.
+ *
+ * @param {boolean} success
+ * @returns {{ indexingInProgress: false, sessionIndexComplete: true, ownsIndexLock: false, isFirstEverRun?: false }}
+ */
+export function cycleEndFlags(success) {
+  const flags = {
+    indexingInProgress: false,
+    sessionIndexComplete: true,
+    ownsIndexLock: false
+  };
+  if (success) {
+    flags.isFirstEverRun = false;
+  }
+  return flags;
+}
+
+/**
+ * User-facing message when a source table is missing.
+ * Distinct from still-indexing: retry because the index is not there yet,
+ * not because this process is mid-cycle.
+ *
+ * @param {"emails"|"messages"|"calendar"|undefined} type
+ * @returns {string}
+ */
+export function indexUnavailableMessage(type) {
+  if (type === "messages") {
+    return "Messages index not available. Please try again shortly.";
+  }
+  if (type === "calendar") {
+    return "Calendar index not available. Please try again shortly.";
+  }
+  if (type === "emails") {
+    return "Email index not available. Please try again shortly.";
+  }
+  return "Index not available. Please try again shortly.";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-tools-mcp",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "MCP server for semantic search across Apple Mail, Messages, and Calendar",
   "type": "module",
   "main": "index.js",
@@ -27,8 +27,6 @@
     "messages",
     "imessage",
     "semantic-search",
-    "claude",
-    "anthropic",
     "macos"
   ],
   "engines": {

package/search.js

@@ -3,6 +3,7 @@ import * as chrono from "chrono-node";
 import { safeOsascript } from "./lib/shell.js";
 import { safeMatch, validateSearchQuery, toUnixMillis } from "./lib/validators.js";
 import { embed, INDEX_DIR, getRecentEmails, getEmailsByDateRange, getRecentMessages, getConversation, getEventsOnDate, resolveEmail, resolvePhone, formatContact } from "./indexer.js";
+import { indexUnavailableMessage } from "./lib/indexGate.js";
 
 let db = null;
 let tables = {};
@@ -106,12 +107,11 @@ function resolvePronouns(query) {
     return query;
   }
 
-  // Do not use RegExp#test with /g — lastIndex is stateful and can skip the
-  // first (or only) pronoun. replace() with a fresh regex is sufficient.
-  return query.replace(
-    /\b(they|them|their|he|him|his|she|her|hers)\b/gi,
-    queryContext.lastPerson
-  );
+  // Never use RegExp#test with a /g regex — lastIndex is stateful and can
+  // skip the first (or only) pronoun on this or a later call. A fresh
+  // regex plus replace() is lastIndex-safe; do not hoist or test() it.
+  const pronounRe = new RegExp('\\b(they|them|their|he|him|his|she|her|hers)\\b', 'gi');
+  return query.replace(pronounRe, queryContext.lastPerson);
 }
 
 // Extract entities (people, dates) from natural language query and convert to filters
@@ -627,7 +627,7 @@ export async function searchEmails(query, options = {}) {
   if (!tbl) {
     return {
       success: false,
-      error: "Email index not ready. Please wait for indexing to complete."
+      error: indexUnavailableMessage("emails")
     };
   }
 
@@ -1022,7 +1022,7 @@ export async function searchMessages(query, options = {}) {
   if (!tbl) {
     return {
       success: false,
-      error: "Messages index not ready. Please wait for indexing to complete."
+      error: indexUnavailableMessage("messages")
     };
   }
 
@@ -1252,7 +1252,7 @@ export async function searchCalendar(query, options = {}) {
   if (!tbl) {
     return {
       success: false,
-      error: "Calendar index not ready. Please wait for indexing to complete."
+      error: indexUnavailableMessage("calendar")
     };
   }
 
@@ -1673,6 +1673,9 @@ export function formatWeekEventsResults(result) {
 // Format mail_thread results
 export function formatEmailThreadResults(result) {
   if (result.error) {
+    if (result.error === indexUnavailableMessage("emails")) {
+      return result.error;
+    }
     return `Error: ${result.error}`;
   }