apple-tools-mcp 1.1.3 → 1.2.0

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,13 +32,15 @@ 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",
 "args": ["/absolute/path/to/Apple-Tools-MCP/index.js"]
 ```
 
+**Mac Mini** stays on a **global npm** install (`npm install -g apple-tools-mcp`) — no git clone on Mini. **MacBook / development** uses the clone above.
+
 ### 2. Grant Full Disk Access
 
 The MCP server needs access to read your Mail, Messages, and Calendar databases.
@@ -64,11 +65,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
+
+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.
+
+**Command**
 
-Add to your Claude Desktop config file:
+- `npx` with args `["-y", "apple-tools-mcp"]` (npm install)
+- or `node` with args `["/absolute/path/to/Apple-Tools-MCP/index.js"]` (from source)
 
-**Location:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Example: Claude Desktop**
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 ```json
 {
@@ -81,15 +89,24 @@ 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.
+
+MCP clients are **short-lived stdio** processes: they exit when the client closes stdin. Always-on indexing belongs on the **indexer daemon**, not a sleep-pipe wrapper around this binary.
+
+### 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
 
-On first use, the server will automatically build a vector index of your emails, messages, and calendar events. Email history is unlimited by default. This may take a while depending on the volume of data.
+On first use, a vector index of your emails, messages, and calendar events is built automatically. Email history is unlimited by default. This may take a while depending on the volume of data.
 
-You can manually rebuild the index:
+**Who indexes**
+
+- **Indexer daemon running** (recommended on Mac Mini): the daemon owns `~/.apple-tools-mcp/indexer.lock` and refreshes `~/.apple-tools-mcp/vector-index/`. MCP stdio clients only search; they do not start background refresh.
+- **No daemon** (default MacBook / Claude Desktop / Cursor): the MCP stdio process indexes **locally on startup**, same as previous versions, then exits when the client disconnects.
+
+You can manually rebuild the index (stop the indexer daemon first if it is running, so it is not writing at the same time):
 
 ```bash
 # Index all email history (default)
@@ -101,9 +118,99 @@ APPLE_TOOLS_INDEX_DAYS_BACK=30 npm run build-index
 
 The index is stored in `~/.apple-tools-mcp/vector-index/`.
 
+## Index refresh interval
+
+Resolved **once at process start**. Precedence (highest wins):
+
+1. `INDEX_INTERVAL_MS` environment variable (milliseconds or human form: `30s`, `1m`, `5m`, `1h`)
+2. `~/.apple-tools-mcp/config.json` keys `indexInterval` or `indexIntervalMs`
+3. Product default: **5 minutes** (`300000` ms) — typical MacBook / MCP local-fallback
+
+Values are **clamped** to **15 seconds** minimum and **6 hours** maximum. Invalid JSON, unknown keys, and unparseable intervals are logged and ignored (the process does not crash). The effective interval is logged at start, for example:
+
+```text
+Effective index refresh interval: 1m (60000 ms) [source=config]
+```
+
+A warn line is also logged when clamping occurs.
+
+### Example `~/.apple-tools-mcp/config.json` (Mac Mini)
+
+Recommended Mini always-on interval is **1 minute**. 30 seconds is allowed (at or above the 15s floor).
+
+```json
+{
+  "indexInterval": "1m"
+}
+```
+
+Equivalent: `"indexIntervalMs": 60000`, or `INDEX_INTERVAL_MS=60000` (env overrides the file).
+
+Missing `config.json` is fine — env then the 5-minute default apply.
+
+## Always-on indexer (Mac Mini LaunchAgent)
+
+On Mini, run the **indexer daemon**, not a sleep-pipe wrapper around `apple-tools-mcp`. Grok Bot, Claude Desktop, and other clients still attach via short-lived stdio MCP (`npx -y apple-tools-mcp` or the global `apple-tools-mcp` bin).
+
+**Entrypoint:** `node index.js --mode=indexer`  
+**Convenience bin:** `apple-tools-indexer` (same file; npm global install provides it)  
+**npm script (clone only):** `npm run indexer`  
+**One-shot rebuild:** `npm run build-index` (stop the indexer daemon first)
+
+LaunchAgent should invoke **node + `--mode=indexer`** on the **global** package (Mini has no git clone). LaunchAgent does not inherit your shell `PATH`, so use absolute paths from `which node` and `npm root -g`.
+
+```bash
+which node
+# Apple Silicon Homebrew example: /opt/homebrew/bin/node
+# Intel Homebrew / usr/local example: /usr/local/bin/node
+
+npm root -g
+# Example: /opt/homebrew/lib/node_modules
+```
+
+Example `~/Library/LaunchAgents/com.apple-tools-mcp.indexer.plist`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.apple-tools-mcp.indexer</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/opt/homebrew/bin/node</string>
+    <string>/opt/homebrew/lib/node_modules/apple-tools-mcp/index.js</string>
+    <string>--mode=indexer</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>/tmp/apple-tools-indexer.out.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/apple-tools-indexer.err.log</string>
+</dict>
+</plist>
+```
+
+Replace the node and `node_modules` paths with the values from `which node` and `npm root -g`. Load it with:
+
+```bash
+launchctl load ~/Library/LaunchAgents/com.apple-tools-mcp.indexer.plist
+```
+
+KeepAlive belongs on this indexer job only — not on the MCP stdio process.
+
 ## Available Tools
 
-Once configured, Claude can use these tools:
+Once configured, your MCP client can use these tools:
 
 ### Universal Search
 
@@ -159,7 +266,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,28 +294,31 @@ 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
 
 If the index becomes corrupted or out of sync:
 
 ```bash
+# If the Mini indexer LaunchAgent is running, unload it first
+# launchctl unload ~/Library/LaunchAgents/com.apple-tools-mcp.indexer.plist
+
 # Remove existing index files
 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 the indexer daemon or 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
@@ -242,12 +352,15 @@ npm install -D vitest @vitest/coverage-v8 fast-check
 # Run tests
 npm test
 
-# Run tests with verbose coverage report
-npx vitest run --coverage --reporter=verbose
+# Run the indexer daemon (owns indexer.lock + vector-index refresh)
+npm run indexer
 
-# Build index with debug output
+# One-shot rebuild (stop the indexer daemon first)
 npm run build-index
 
+# Run tests with verbose coverage report
+npx vitest run --coverage --reporter=verbose
+
 # Run audit to check index health
 npm run audit
 ```

package/index.js

@@ -10,142 +10,110 @@ 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 { isIndexerMode } from "./lib/processMode.js";
+import { loadResolvedIndexInterval, logResolvedInterval } from "./lib/config.js";
+import { createIndexerLock, DEFAULT_LOCK_HEARTBEAT_MS } from "./lib/indexerLock.js";
+import {
+  shouldConnectMcpStdio,
+  bindStdinCloseExit,
+  beginIndexCycle,
+  applyIndexerCycleEnd,
+  mcpIndexingStartup,
+  waitForIndexerLock,
+  beginOwnedIndexing
+} from "./lib/indexerRuntime.js";
 
 const PACKAGE_VERSION = JSON.parse(
   fs.readFileSync(new URL("./package.json", import.meta.url), "utf8")
 ).version;
 
+// Canonical indexer entrypoint: `node index.js --mode=indexer` or `apple-tools-indexer`.
+const INDEXER_MODE = isIndexerMode();
+const resolvedIndexInterval = loadResolvedIndexInterval();
+const INDEX_INTERVAL = resolvedIndexInterval.ms;
+const LOCK_HEARTBEAT_MS = DEFAULT_LOCK_HEARTBEAT_MS;
+const LOCK_RETRY_MS = 5 * 1000;
+
 // 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
+const indexerLock = createIndexerLock({
+  lockFile: LOCK_FILE,
+  log: (msg) => console.error(msg)
+});
 // 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 {
-    // Ensure directory exists first
-    const lockDir = path.dirname(LOCK_FILE);
-    if (!fs.existsSync(lockDir)) {
-      fs.mkdirSync(lockDir, { recursive: true });
-    }
+  const ok = indexerLock.acquire();
+  ownsIndexLock = indexerLock.ownsLock;
+  if (ok) {
+    startLockHeartbeat();
+  }
+  return ok;
+}
 
-    // Check for existing lock file
-    if (fs.existsSync(LOCK_FILE)) {
-      const lockData = fs.readFileSync(LOCK_FILE, "utf8");
-      const [pidStr, timestampStr] = lockData.split(':');
-      const pid = parseInt(pidStr);
-      const timestamp = parseInt(timestampStr) || Date.now();
-      const lockAge = Date.now() - timestamp;
-
-      // If we already hold the lock, return true
-      if (pid === process.pid) {
-        ownsIndexLock = true;
-        return true;
-      }
+function releaseLock() {
+  indexerLock.release();
+  ownsIndexLock = indexerLock.ownsLock;
+  if (!ownsIndexLock) {
+    stopLockHeartbeat();
+  }
+}
 
-      try {
-        process.kill(pid, 0); // Check if process exists (signal 0 = no-op)
-
-        // Process exists - check if lock is stale (hung process)
-        if (lockAge > LOCK_TIMEOUT_MS) {
-          console.error(`Lock file is ${Math.round(lockAge / 60000)} minutes old. Assuming hung process (PID ${pid}). Removing stale lock.`);
-          fs.unlinkSync(LOCK_FILE);
-        } else {
-          console.error(`Another indexing instance running (PID ${pid}). Skipping indexing.`);
-          ownsIndexLock = false;
-          return false;
-        }
-      } catch {
-        // Process doesn't exist, stale lock file - remove it
-        console.error(`Removing stale lock file (PID ${pid} not running)`);
-        fs.unlinkSync(LOCK_FILE);
-      }
-    }
+function startLockHeartbeat() {
+  indexerLock.startHeartbeat(LOCK_HEARTBEAT_MS);
+}
 
-    // Use atomic 'wx' flag to create lock file exclusively
-    // 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
-  }
+function stopLockHeartbeat() {
+  indexerLock.stopHeartbeat();
 }
 
-function releaseLock() {
-  try {
-    if (fs.existsSync(LOCK_FILE)) {
-      const lockData = fs.readFileSync(LOCK_FILE, "utf8");
-      const [pidStr] = lockData.split(':');
-      const pid = parseInt(pidStr);
-      if (pid === process.pid) {
-        fs.unlinkSync(LOCK_FILE);
-        ownsIndexLock = false;
-        console.error(`Released lock file (PID ${process.pid})`);
-      }
-    }
-  } catch (err) {
-    // Log error but don't throw - we're likely shutting down
-    console.error(`Error releasing lock: ${err.message}`);
+function shutdownIndexing(exitCode) {
+  stopBackgroundIndexing();
+  stopLockHeartbeat();
+  releaseLock();
+  if (exitCode !== undefined) {
+    process.exit(exitCode);
   }
 }
 
 // Clean up lock and timer on exit
 process.on("exit", () => {
   stopBackgroundIndexing();
+  stopLockHeartbeat();
   releaseLock();
 });
 process.on("SIGINT", () => {
-  stopBackgroundIndexing();
-  releaseLock();
+  shutdownIndexing();
   process.exit();
 });
 process.on("SIGTERM", () => {
-  stopBackgroundIndexing();
-  releaseLock();
+  shutdownIndexing();
   process.exit();
 });
 process.on("SIGHUP", () => {
-  stopBackgroundIndexing();
-  releaseLock();
+  shutdownIndexing();
   process.exit();
 });
 
 // Handle uncaught errors - cleanup before crashing
 process.on("uncaughtException", (err) => {
   console.error("Uncaught exception:", err);
-  stopBackgroundIndexing();
-  releaseLock();
-  process.exit(1);
+  shutdownIndexing(1);
 });
 
 process.on("unhandledRejection", (reason, promise) => {
   console.error("Unhandled rejection at:", promise, "reason:", reason);
-  stopBackgroundIndexing();
-  releaseLock();
-  process.exit(1);
+  shutdownIndexing(1);
 });
 
-// Exit when stdin closes (Claude client disconnected)
-process.stdin.on("close", () => {
+// MCP stdio clients exit when the host closes stdin. The indexer daemon must
+// not — LaunchAgent / KeepAlive often attaches stdin to /dev/null.
+bindStdinCloseExit(process.stdin, INDEXER_MODE, () => {
   console.error("Client disconnected. Exiting.");
-  stopBackgroundIndexing();
-  releaseLock();
-  process.exit(0);
+  shutdownIndexing(0);
 });
 
 // Vector search imports
@@ -199,10 +167,9 @@ let sessionIndexComplete = false;  // Track if this session's indexing is done
 let isFirstEverRun = true;  // True if no index exists yet
 let lastIndexTime = 0;
 let lastProgressTime = 0;  // Track when we last made progress (for hung detection)
-// Allow environment variable to override default 5-minute interval
-const INDEX_INTERVAL = parseInt(process.env.INDEX_INTERVAL_MS || (5 * 60 * 1000));
 let indexTimer = null;
 let progressCheckTimer = null;
+let loggedIndexInterval = false;
 
 // Check if this is the first ever run (no index exists)
 async function checkIfFirstRun() {
@@ -223,13 +190,15 @@ function getIndexingMessage() {
 
 // Run a single indexing cycle (called by background timer)
 function runIndexCycle() {
-  if (indexingInProgress) {
-    console.error("Indexing already in progress, skipping cycle");
+  const cycle = beginIndexCycle(indexingInProgress);
+  if (!cycle.started) {
     return;
   }
+  indexingInProgress = cycle.indexingInProgress;
 
   // Safety net: check lock before indexing
   if (!acquireLock()) {
+    indexingInProgress = false;
     console.error("Another instance is indexing. Skipping.");
     return;
   }
@@ -299,6 +268,11 @@ function triggerIndexIfNeeded() {
 
 // Start continuous background indexing
 function startBackgroundIndexing() {
+  if (!loggedIndexInterval) {
+    logResolvedInterval(resolvedIndexInterval);
+    loggedIndexInterval = true;
+  }
+
   // Run indexing immediately on startup
   runIndexCycle();
 
@@ -307,7 +281,7 @@ function startBackgroundIndexing() {
     runIndexCycle();
   }, INDEX_INTERVAL);
 
-  console.error(`Background indexing started (interval: ${INDEX_INTERVAL / 1000}s)`);
+  console.error(`Background indexing started (interval: ${resolvedIndexInterval.human} / ${INDEX_INTERVAL} ms)`);
 }
 
 // Stop background indexing and clean up timers
@@ -323,17 +297,22 @@ 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.
+// Unblock searches after a cycle ends. Must run on failure as well as success
+// so tools are not stuck forever. The indexer daemon keeps indexer.lock for
+// the process lifetime; MCP local-fallback still releases between cycles.
 function applyCycleEnd(success) {
-  const flags = cycleEndFlags(success);
-  indexingInProgress = flags.indexingInProgress;
-  sessionIndexComplete = flags.sessionIndexComplete;
-  ownsIndexLock = flags.ownsIndexLock;
-  if (flags.isFirstEverRun === false) {
+  const result = applyIndexerCycleEnd({
+    success,
+    indexerMode: INDEXER_MODE,
+    cycleEndFlags,
+    releaseLock
+  });
+  indexingInProgress = result.indexingInProgress;
+  sessionIndexComplete = result.sessionIndexComplete;
+  ownsIndexLock = result.ownsIndexLock;
+  if (result.isFirstEverRun === false) {
     isFirstEverRun = false;
   }
-  releaseLock();
 }
 
 // Index-backed tools wait only while THIS process owns the lock and has not
@@ -345,13 +324,35 @@ function stillIndexingMessage() {
   return null;
 }
 
+function waitForLockAndStartDaemon() {
+  waitForIndexerLock(acquireLock, {
+    retryMs: LOCK_RETRY_MS,
+    onAcquired: () => {
+      beginOwnedIndexing({
+        startHeartbeat: startLockHeartbeat,
+        startBackground: startBackgroundIndexing
+      });
+    }
+  });
+}
+
 // Initialize and start indexing
 async function initializeIndexing() {
   isFirstEverRun = await checkIfFirstRun();
 
-  // Try to acquire lock - if another instance is indexing, skip background
-  // indexing but keep the MCP server running so search still works.
-  if (!acquireLock()) {
+  if (INDEXER_MODE) {
+    console.error(`Apple Tools MCP indexer running (v${PACKAGE_VERSION})`);
+    logResolvedInterval(resolvedIndexInterval);
+    loggedIndexInterval = true;
+    waitForLockAndStartDaemon();
+    return;
+  }
+
+  // MCP stdio: if the indexer daemon (or another instance) holds the lock,
+  // skip background refresh and use the shared index. If nothing holds the
+  // lock, index locally as before so the stdio happy path still works.
+  const startup = mcpIndexingStartup(() => acquireLock());
+  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.
@@ -359,8 +360,13 @@ async function initializeIndexing() {
     return;
   }
 
-  // Start background indexing
-  startBackgroundIndexing();
+  // Start background indexing (local fallback when no daemon is running)
+  // using the same heartbeat path as the daemon so a long first-index cycle
+  // cannot look like a stale lock to another waiter.
+  beginOwnedIndexing({
+    startHeartbeat: startLockHeartbeat,
+    startBackground: startBackgroundIndexing
+  });
 }
 
 // Start indexing immediately on server startup
@@ -1524,7 +1530,10 @@ async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
   console.error(`Apple Tools MCP server running (v${PACKAGE_VERSION})`);
-  // Background indexing runs automatically on startup and every INDEX_INTERVAL
+  // Background indexing: indexer daemon when --mode=indexer; otherwise local
+  // fallback on this stdio process only if indexer.lock is free.
 }
 
-main().catch(console.error);
+if (shouldConnectMcpStdio(INDEXER_MODE)) {
+  main().catch(console.error);
+}