apple-tools-mcp 1.1.4 → 1.2.0

package/README.md

@@ -39,6 +39,8 @@ If you installed from source, point your MCP client at the local `index.js` inst
 "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.
@@ -89,15 +91,22 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 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 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.
+
+**Who indexes**
 
-You can manually rebuild the index:
+- **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)
@@ -109,6 +118,96 @@ 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, your MCP client can use these tools:
@@ -206,12 +305,15 @@ Ensure Node.js has Full Disk Access (see Installation step 2).
 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 your MCP client to trigger a fresh rebuild
+# Restart the indexer daemon or your MCP client to trigger a fresh rebuild
 ```
 
 ### Monitor indexing progress
@@ -250,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 (MCP 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);
+}

package/lib/config.js

@@ -0,0 +1,312 @@
+/**
+ * User config for apple-tools-mcp.
+ *
+ * Path is fixed at ~/.apple-tools-mcp/config.json (or $HOME). Arbitrary paths
+ * from config contents are ignored — config is treated as data, not as
+ * instructions or path overrides.
+ *
+ * Interval precedence (highest wins):
+ *   1. INDEX_INTERVAL_MS environment variable
+ *   2. config.json `indexInterval` (or `indexIntervalMs`)
+ *   3. Product default (5 minutes)
+ *
+ * Values are clamped to [15s, 6h]. Human forms like `30s`, `1m`, `1h` are accepted.
+ */
+
+import fs from "fs";
+import os from "os";
+import path from "path";
+
+export const APPLE_TOOLS_DIR_NAME = ".apple-tools-mcp";
+export const CONFIG_FILE_NAME = "config.json";
+
+/** MacBook / MCP local-fallback default. */
+export const DEFAULT_INDEX_INTERVAL_MS = 5 * 60 * 1000;
+
+/** Documented floor: 15 seconds (30s remains allowed). */
+export const MIN_INDEX_INTERVAL_MS = 15 * 1000;
+
+/** Documented ceiling: 6 hours. */
+export const MAX_INDEX_INTERVAL_MS = 6 * 60 * 60 * 1000;
+
+/** Recommended Mini always-on value (set in config.json, not the product default). */
+export const MINI_RECOMMENDED_INDEX_INTERVAL_MS = 60 * 1000;
+
+const KNOWN_CONFIG_KEYS = new Set(["indexInterval", "indexIntervalMs"]);
+
+const MAX_DURATION_STRING_LENGTH = 32;
+
+function defaultWarn(message) {
+  console.error(message);
+}
+
+/**
+ * Directory that holds config.json, indexer.lock, and vector-index.
+ * Always under the user home directory — never a path from config contents.
+ *
+ * @param {{ env?: NodeJS.ProcessEnv, homedir?: () => string }} [options]
+ * @returns {string}
+ */
+export function getAppleToolsDir(options = {}) {
+  const env = options.env || process.env;
+  const homedir = options.homedir || (() => os.homedir());
+  const home = env.HOME || homedir();
+  return path.join(home, APPLE_TOOLS_DIR_NAME);
+}
+
+/**
+ * @param {{ env?: NodeJS.ProcessEnv, homedir?: () => string }} [options]
+ * @returns {string}
+ */
+export function getConfigPath(options = {}) {
+  return path.join(getAppleToolsDir(options), CONFIG_FILE_NAME);
+}
+
+/**
+ * Parse a millisecond count or human duration (`500ms`, `30s`, `1m`, `1h`).
+ * @param {unknown} value
+ * @returns {number|null} milliseconds, or null if unparseable
+ */
+export function parseDuration(value) {
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      return null;
+    }
+    return value;
+  }
+  if (typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trim();
+  if (trimmed.length === 0 || trimmed.length > MAX_DURATION_STRING_LENGTH) {
+    return null;
+  }
+  if (/^\d+$/.test(trimmed)) {
+    const n = Number(trimmed);
+    if (!Number.isSafeInteger(n)) {
+      return null;
+    }
+    return n;
+  }
+  const match = /^(\d+)(ms|s|m|h)$/i.exec(trimmed);
+  if (!match) {
+    return null;
+  }
+  const n = Number(match[1]);
+  if (!Number.isSafeInteger(n)) {
+    return null;
+  }
+  const unit = match[2].toLowerCase();
+  const multiplier = unit === "ms" ? 1
+    : unit === "s" ? 1000
+    : unit === "m" ? 60 * 1000
+    : 60 * 60 * 1000;
+  const result = n * multiplier;
+  if (!Number.isSafeInteger(result)) {
+    return null;
+  }
+  return result;
+}
+
+/**
+ * Compact human form for logs (`1m`, `30s`, `6h`, or `1500ms`).
+ * @param {number} ms
+ * @returns {string}
+ */
+export function formatIntervalMs(ms) {
+  if (!Number.isFinite(ms)) {
+    return String(ms);
+  }
+  const rounded = Math.round(ms);
+  if (rounded % (60 * 60 * 1000) === 0) {
+    return `${rounded / (60 * 60 * 1000)}h`;
+  }
+  if (rounded % (60 * 1000) === 0) {
+    return `${rounded / (60 * 1000)}m`;
+  }
+  if (rounded % 1000 === 0) {
+    return `${rounded / 1000}s`;
+  }
+  return `${rounded}ms`;
+}
+
+/**
+ * Clamp a parsed millisecond value. Invalid input yields the default (not the min).
+ *
+ * @param {unknown} raw
+ * @param {{ defaultMs?: number, minMs?: number, maxMs?: number }} [bounds]
+ * @returns {{ ms: number, human: string, clamped: boolean, invalid: boolean, requestedMs: number|null }}
+ */
+export function clampIndexInterval(raw, bounds = {}) {
+  const defaultMs = bounds.defaultMs ?? DEFAULT_INDEX_INTERVAL_MS;
+  const minMs = bounds.minMs ?? MIN_INDEX_INTERVAL_MS;
+  const maxMs = bounds.maxMs ?? MAX_INDEX_INTERVAL_MS;
+  const requestedMs = parseDuration(raw);
+
+  if (requestedMs === null) {
+    return {
+      ms: defaultMs,
+      human: formatIntervalMs(defaultMs),
+      clamped: false,
+      invalid: true,
+      requestedMs: null
+    };
+  }
+
+  const clampedMs = Math.min(maxMs, Math.max(minMs, requestedMs));
+  return {
+    ms: clampedMs,
+    human: formatIntervalMs(clampedMs),
+    clamped: clampedMs !== requestedMs,
+    invalid: false,
+    requestedMs
+  };
+}
+
+/**
+ * Load ~/.apple-tools-mcp/config.json. Missing file is fine. Invalid JSON
+ * does not throw — callers get empty data plus a warn log.
+ *
+ * @param {{
+ *   configPath?: string,
+ *   env?: NodeJS.ProcessEnv,
+ *   readFile?: (p: string) => string,
+ *   exists?: (p: string) => boolean,
+ *   warn?: (msg: string) => void
+ * }} [options]
+ * @returns {{ data: Record<string, unknown>, missing: boolean, invalid: boolean, path: string }}
+ */
+export function loadConfigFile(options = {}) {
+  const warn = options.warn || defaultWarn;
+  const configPath = options.configPath || getConfigPath({ env: options.env });
+  const exists = options.exists || ((p) => fs.existsSync(p));
+  const readFile = options.readFile || ((p) => fs.readFileSync(p, "utf8"));
+
+  if (!exists(configPath)) {
+    return { data: {}, missing: true, invalid: false, path: configPath };
+  }
+
+  try {
+    const raw = readFile(configPath);
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      warn("Invalid config.json: expected a JSON object. Using defaults.");
+      return { data: {}, missing: false, invalid: true, path: configPath };
+    }
+    for (const key of Object.keys(parsed)) {
+      if (!KNOWN_CONFIG_KEYS.has(key)) {
+        warn(`Ignoring unknown config key: ${key}`);
+      }
+    }
+    return { data: parsed, missing: false, invalid: false, path: configPath };
+  } catch (err) {
+    const message = err && err.message ? err.message : "parse error";
+    warn(`Invalid config.json (${message}). Using defaults.`);
+    return { data: {}, missing: false, invalid: true, path: configPath };
+  }
+}
+
+function fileIntervalRaw(data) {
+  if (!data || typeof data !== "object") {
+    return undefined;
+  }
+  if (Object.prototype.hasOwnProperty.call(data, "indexInterval")) {
+    return data.indexInterval;
+  }
+  if (Object.prototype.hasOwnProperty.call(data, "indexIntervalMs")) {
+    return data.indexIntervalMs;
+  }
+  return undefined;
+}
+
+/**
+ * Resolve the index refresh interval once at process start.
+ *
+ * @param {{
+ *   env?: NodeJS.ProcessEnv,
+ *   configPath?: string,
+ *   fileData?: Record<string, unknown>,
+ *   warn?: (msg: string) => void
+ * }} [options]
+ * @returns {{
+ *   ms: number,
+ *   human: string,
+ *   source: "env" | "config" | "default",
+ *   clamped: boolean,
+ *   invalid: boolean,
+ *   requestedMs: number|null,
+ *   raw: unknown
+ * }}
+ */
+export function resolveIndexInterval(options = {}) {
+  const env = options.env || process.env;
+  const warn = options.warn || defaultWarn;
+  const envRaw = env.INDEX_INTERVAL_MS;
+  const envSet = envRaw !== undefined && envRaw !== "";
+
+  let source = "default";
+  let raw = DEFAULT_INDEX_INTERVAL_MS;
+
+  if (envSet) {
+    source = "env";
+    raw = envRaw;
+  } else {
+    const data = options.fileData !== undefined
+      ? options.fileData
+      : loadConfigFile({ configPath: options.configPath, env, warn }).data;
+    const fromFile = fileIntervalRaw(data);
+    if (fromFile !== undefined) {
+      source = "config";
+      raw = fromFile;
+    }
+  }
+
+  const clamped = clampIndexInterval(raw);
+  if (clamped.invalid && source !== "default") {
+    warn(`Invalid index interval ${JSON.stringify(raw)} from ${source}; using default ${clamped.human} (${clamped.ms} ms)`);
+  } else if (clamped.clamped) {
+    const fromHuman = formatIntervalMs(clamped.requestedMs);
+    warn(
+      `Index interval ${fromHuman} (${clamped.requestedMs} ms) from ${source} is outside ${formatIntervalMs(MIN_INDEX_INTERVAL_MS)}–${formatIntervalMs(MAX_INDEX_INTERVAL_MS)}; clamped to ${clamped.human} (${clamped.ms} ms)`
+    );
+  }
+
+  return {
+    ms: clamped.ms,
+    human: clamped.human,
+    source: clamped.invalid && source !== "default" ? "default" : source,
+    clamped: clamped.clamped,
+    invalid: clamped.invalid,
+    requestedMs: clamped.requestedMs,
+    raw
+  };
+}
+
+/**
+ * Load config from disk (if present) and resolve the interval.
+ * @param {{ env?: NodeJS.ProcessEnv, configPath?: string, warn?: (msg: string) => void }} [options]
+ */
+export function loadResolvedIndexInterval(options = {}) {
+  const warn = options.warn || defaultWarn;
+  const loaded = loadConfigFile({
+    configPath: options.configPath,
+    env: options.env,
+    warn
+  });
+  return resolveIndexInterval({
+    env: options.env,
+    fileData: loaded.data,
+    warn
+  });
+}
+
+/**
+ * Log the effective interval once. Human form and milliseconds.
+ * @param {{ ms: number, human: string, source: string, clamped: boolean }} resolved
+ * @param {{ log?: (msg: string) => void }} [options]
+ */
+export function logResolvedInterval(resolved, options = {}) {
+  const log = options.log || defaultWarn;
+  const clampedNote = resolved.clamped ? ", clamped" : "";
+  log(`Effective index refresh interval: ${resolved.human} (${resolved.ms} ms) [source=${resolved.source}${clampedNote}]`);
+}

package/lib/indexerLock.js

@@ -0,0 +1,376 @@
+/**
+ * indexer.lock acquire / release / heartbeat.
+ *
+ * A live holder is never displaced, even if the lock timestamp is old
+ * (blocked event loop, long index cycle). Dead-PID takeover never renames
+ * the live lock path. Waiters take a wx mutex, re-read, unlink only if the
+ * contents are still the expected dead lock, wx-create the new lock, then
+ * drop the mutex — so a peer's freshly created lock is never deleted.
+ * An orphaned takeover mutex is never stolen with compare-then-unlink of
+ * the live `.takeover` path: waiters wx a fence named by the dead PID.
+ * Empty or unparsable mutex/lock contents are unknown — do not fence or steal
+ * (covers wx open-then-write and heartbeat truncate-then-write windows).
+ */
+
+import fs from "fs";
+import path from "path";
+
+export const DEFAULT_LOCK_TIMEOUT_MS = 30 * 60 * 1000;
+export const DEFAULT_LOCK_HEARTBEAT_MS = 60 * 1000;
+export const TAKEOVER_MUTEX_SUFFIX = ".takeover";
+export const TAKEOVER_FENCE_DEPTH = 8;
+
+/**
+ * @param {string} lockFile
+ * @returns {string}
+ */
+export function getTakeoverMutexPath(lockFile) {
+  return `${lockFile}${TAKEOVER_MUTEX_SUFFIX}`;
+}
+
+/**
+ * wx fence used when indexer.lock.takeover is orphaned (dead PID).
+ * @param {string} lockFile
+ * @param {...number|string} deadIds
+ * @returns {string}
+ */
+export function getTakeoverFencePath(lockFile, ...deadIds) {
+  let p = getTakeoverMutexPath(lockFile);
+  for (const id of deadIds) {
+    p = `${p}.${id}`;
+  }
+  return p;
+}
+
+/**
+ * @param {unknown} pid
+ * @param {(pid: number, signal: number) => void} [killFn]
+ * @returns {boolean}
+ */
+export function isProcessAlive(pid, killFn = (p, signal) => process.kill(p, signal)) {
+  try {
+    killFn(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} text
+ * @returns {{ pid: number, timestamp: number, raw: string } | null}
+ */
+export function parseLockData(text) {
+  if (typeof text !== "string" || text.length === 0) {
+    return null;
+  }
+  const [pidStr, timestampStr] = text.split(":");
+  const pid = parseInt(pidStr, 10);
+  const timestamp = parseInt(timestampStr, 10);
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return null;
+  }
+  return {
+    pid,
+    timestamp: Number.isInteger(timestamp) ? timestamp : 0,
+    raw: text
+  };
+}
+
+/**
+ * @param {number} pid
+ * @param {number} timestamp
+ * @returns {string}
+ */
+export function formatLockData(pid, timestamp) {
+  return `${pid}:${timestamp}`;
+}
+
+/**
+ * @param {{
+ *   lockFile: string,
+ *   pid?: number,
+ *   now?: () => number,
+ *   timeoutMs?: number,
+ *   isAlive?: (pid: number) => boolean,
+ *   fsApi?: Pick<typeof fs, "existsSync" | "readFileSync" | "writeFileSync" | "unlinkSync" | "mkdirSync">,
+ *   log?: (msg: string) => void,
+ *   setIntervalFn?: typeof setInterval,
+ *   clearIntervalFn?: typeof clearInterval
+ * }} options
+ */
+export function createIndexerLock(options) {
+  const lockFile = options.lockFile;
+  const mutexPath = getTakeoverMutexPath(lockFile);
+  const pid = options.pid ?? process.pid;
+  const now = options.now || (() => Date.now());
+  const timeoutMs = options.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
+  const isAlive = options.isAlive || ((holderPid) => isProcessAlive(holderPid));
+  const fsApi = options.fsApi || fs;
+  const log = options.log || ((msg) => console.error(msg));
+  const setIntervalFn = options.setIntervalFn || setInterval;
+  const clearIntervalFn = options.clearIntervalFn || clearInterval;
+
+  let ownsLock = false;
+  let heartbeatTimer = null;
+  let heldMutexPath = null;
+
+  function readLockFile() {
+    if (!fsApi.existsSync(lockFile)) {
+      return null;
+    }
+    return fsApi.readFileSync(lockFile, "utf8");
+  }
+
+  function skipLiveHolder(parsed) {
+    const lockAge = now() - parsed.timestamp;
+    if (lockAge > timeoutMs) {
+      log(
+        `Lock file is ${Math.round(lockAge / 60000)} minutes old, but PID ${parsed.pid} is still running. Not taking over.`
+      );
+    } else {
+      log(`Another indexing instance running (PID ${parsed.pid}). Skipping indexing.`);
+    }
+    ownsLock = false;
+    return false;
+  }
+
+  function refreshOwned() {
+    ownsLock = true;
+    try {
+      fsApi.writeFileSync(lockFile, formatLockData(pid, now()));
+    } catch {
+      // Heartbeat or the next cycle can retry the write.
+    }
+    return true;
+  }
+
+  function tryAcquireMutex() {
+    const token = formatLockData(pid, now());
+    let candidate = mutexPath;
+    try {
+      for (let depth = 0; depth < TAKEOVER_FENCE_DEPTH; depth++) {
+        let exists = false;
+        for (let spin = 0; spin < 4; spin++) {
+          try {
+            fsApi.writeFileSync(candidate, token, { flag: "wx" });
+            heldMutexPath = candidate;
+            return true;
+          } catch (err) {
+            if (err && err.code === "ENOENT") {
+              continue;
+            }
+            if (!err || err.code !== "EEXIST") {
+              throw err;
+            }
+            exists = true;
+            break;
+          }
+        }
+        if (!exists) {
+          return false;
+        }
+        let data;
+        try {
+          data = fsApi.readFileSync(candidate, "utf8");
+        } catch (err) {
+          if (err && err.code === "ENOENT") {
+            continue;
+          }
+          throw err;
+        }
+        const parsed = parseLockData(data);
+        if (!parsed) {
+          return false;
+        }
+        if (isAlive(parsed.pid)) {
+          return false;
+        }
+        candidate = `${candidate}.${parsed.pid}`;
+      }
+      return false;
+    } catch (err) {
+      if (err && err.code === "EEXIST") {
+        return false;
+      }
+      log(`Takeover mutex error: ${err.message}`);
+      return false;
+    }
+  }
+
+  function dropMutex() {
+    const held = heldMutexPath;
+    heldMutexPath = null;
+    if (!held) {
+      return;
+    }
+    try {
+      if (!fsApi.existsSync(held)) {
+        return;
+      }
+      const data = fsApi.readFileSync(held, "utf8");
+      const parsed = parseLockData(data);
+      if (parsed && parsed.pid === pid) {
+        fsApi.unlinkSync(held);
+      }
+    } catch (err) {
+      log(`Takeover mutex release error: ${err.message}`);
+    }
+  }
+
+  /**
+   * Under the wx mutex: re-read, unlink only the still-expected dead lock,
+   * then wx-create. Never rename the live path.
+   */
+  function finishAcquireUnderMutex(expectedStale) {
+    const current = readLockFile();
+
+    if (current !== null) {
+      const parsed = parseLockData(current);
+      if (!parsed) {
+        ownsLock = false;
+        return false;
+      }
+      if (parsed.pid === pid) {
+        return refreshOwned();
+      }
+      if (isAlive(parsed.pid)) {
+        return skipLiveHolder(parsed);
+      }
+      if (expectedStale === null || current !== expectedStale) {
+        ownsLock = false;
+        return false;
+      }
+      // Re-read immediately before unlink. Never delete a peer's wx lock.
+      const again = readLockFile();
+      if (again !== expectedStale) {
+        ownsLock = false;
+        return false;
+      }
+      try {
+        fsApi.unlinkSync(lockFile);
+      } catch (err) {
+        if (!err || err.code !== "ENOENT") {
+          throw err;
+        }
+      }
+      log(`Removing stale lock file (PID ${parsed ? parsed.pid : "unknown"} not running)`);
+    }
+
+    try {
+      fsApi.writeFileSync(lockFile, formatLockData(pid, now()), { flag: "wx" });
+      ownsLock = true;
+      return true;
+    } catch (err) {
+      if (err.code === "EEXIST") {
+        log("Another process acquired lock during race. Skipping indexing.");
+        ownsLock = false;
+        return false;
+      }
+      throw err;
+    }
+  }
+
+  function acquire() {
+    try {
+      const lockDir = path.dirname(lockFile);
+      if (!fsApi.existsSync(lockDir)) {
+        fsApi.mkdirSync(lockDir, { recursive: true });
+      }
+
+      const existing = readLockFile();
+      if (existing !== null) {
+        const parsed = parseLockData(existing);
+        if (!parsed) {
+          ownsLock = false;
+          return false;
+        }
+        if (parsed.pid === pid) {
+          return refreshOwned();
+        }
+        if (isAlive(parsed.pid)) {
+          return skipLiveHolder(parsed);
+        }
+      }
+
+      if (!tryAcquireMutex()) {
+        log("Another process acquired lock during race. Skipping indexing.");
+        ownsLock = false;
+        return false;
+      }
+      try {
+        return finishAcquireUnderMutex(existing);
+      } finally {
+        dropMutex();
+      }
+    } catch (e) {
+      log(`Lock file error: ${e.message}`);
+      ownsLock = false;
+      return false;
+    }
+  }
+
+  function release() {
+    try {
+      const lockData = readLockFile();
+      if (lockData) {
+        const parsed = parseLockData(lockData);
+        if (parsed && parsed.pid === pid) {
+          fsApi.unlinkSync(lockFile);
+          ownsLock = false;
+          log(`Released lock file (PID ${pid})`);
+        }
+      }
+    } catch (err) {
+      log(`Error releasing lock: ${err.message}`);
+    }
+  }
+
+  function refresh() {
+    try {
+      if (!ownsLock) {
+        return false;
+      }
+      const lockData = readLockFile();
+      if (!lockData) {
+        return false;
+      }
+      const parsed = parseLockData(lockData);
+      if (parsed && parsed.pid === pid) {
+        fsApi.writeFileSync(lockFile, formatLockData(pid, now()));
+        return true;
+      }
+      return false;
+    } catch (err) {
+      log(`Lock heartbeat error: ${err.message}`);
+      return false;
+    }
+  }
+
+  function startHeartbeat(intervalMs = DEFAULT_LOCK_HEARTBEAT_MS) {
+    if (heartbeatTimer) {
+      return;
+    }
+    heartbeatTimer = setIntervalFn(() => {
+      refresh();
+    }, intervalMs);
+  }
+
+  function stopHeartbeat() {
+    if (heartbeatTimer) {
+      clearIntervalFn(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+  }
+
+  return {
+    acquire,
+    release,
+    refresh,
+    startHeartbeat,
+    stopHeartbeat,
+    get ownsLock() {
+      return ownsLock;
+    }
+  };
+}

package/lib/indexerRuntime.js

@@ -0,0 +1,142 @@
+/**
+ * Indexer daemon vs MCP stdio runtime helpers.
+ * Kept separate from index.js so daemon paths can be tested without
+ * starting MCP stdio or loading the embedding model.
+ */
+
+/**
+ * @param {boolean} indexerMode
+ * @returns {boolean}
+ */
+export function shouldConnectMcpStdio(indexerMode) {
+  return !indexerMode;
+}
+
+/**
+ * @param {boolean} indexerMode
+ * @returns {boolean}
+ */
+export function shouldExitOnStdinClose(indexerMode) {
+  return !indexerMode;
+}
+
+/**
+ * Bind stdin `close` → callback only for MCP stdio clients.
+ * Indexer daemons must ignore stdin close (LaunchAgent often uses /dev/null).
+ *
+ * @param {{ on: (event: string, handler: () => void) => void }} stdin
+ * @param {boolean} indexerMode
+ * @param {() => void} onClose
+ * @returns {{ bound: boolean }}
+ */
+export function bindStdinCloseExit(stdin, indexerMode, onClose) {
+  if (!shouldExitOnStdinClose(indexerMode)) {
+    return { bound: false };
+  }
+  stdin.on("close", onClose);
+  return { bound: true };
+}
+
+/**
+ * Start one index cycle, or skip if a cycle is already running.
+ *
+ * @param {boolean} indexingInProgress
+ * @param {(msg: string) => void} [log]
+ * @returns {{ started: boolean, indexingInProgress: boolean }}
+ */
+export function beginIndexCycle(indexingInProgress, log = (msg) => console.error(msg)) {
+  if (indexingInProgress) {
+    log("Indexing already in progress, skipping cycle");
+    return { started: false, indexingInProgress: true };
+  }
+  return { started: true, indexingInProgress: true };
+}
+
+/**
+ * After a cycle: daemon keeps the lock; MCP local-fallback releases it.
+ *
+ * @param {{
+ *   success: boolean,
+ *   indexerMode: boolean,
+ *   cycleEndFlags: (success: boolean) => {
+ *     indexingInProgress: boolean,
+ *     sessionIndexComplete: boolean,
+ *     ownsIndexLock: boolean,
+ *     isFirstEverRun?: boolean
+ *   },
+ *   releaseLock: () => void
+ * }} args
+ */
+export function applyIndexerCycleEnd({ success, indexerMode, cycleEndFlags, releaseLock }) {
+  const flags = cycleEndFlags(success);
+  if (indexerMode) {
+    return {
+      indexingInProgress: flags.indexingInProgress,
+      sessionIndexComplete: flags.sessionIndexComplete,
+      ownsIndexLock: true,
+      isFirstEverRun: flags.isFirstEverRun,
+      released: false
+    };
+  }
+  releaseLock();
+  return {
+    indexingInProgress: flags.indexingInProgress,
+    sessionIndexComplete: flags.sessionIndexComplete,
+    ownsIndexLock: flags.ownsIndexLock,
+    isFirstEverRun: flags.isFirstEverRun,
+    released: true
+  };
+}
+
+/**
+ * MCP stdio startup: index locally only when the lock is free.
+ *
+ * @param {() => boolean} acquireLock
+ * @returns {{ startBackground: boolean, ownsIndexLock: boolean, startHeartbeat: boolean, reason: "local-fallback" | "lock-held" }}
+ */
+export function mcpIndexingStartup(acquireLock) {
+  if (!acquireLock()) {
+    return { startBackground: false, ownsIndexLock: false, startHeartbeat: false, reason: "lock-held" };
+  }
+  return { startBackground: true, ownsIndexLock: true, startHeartbeat: true, reason: "local-fallback" };
+}
+
+/**
+ * Shared path once this process owns indexer.lock: heartbeat + background cycles.
+ * MCP local-fallback must use this too, not only the daemon.
+ *
+ * @param {{ startHeartbeat: () => void, startBackground: () => void }} steps
+ */
+export function beginOwnedIndexing(steps) {
+  steps.startHeartbeat();
+  steps.startBackground();
+}
+
+/**
+ * Retry until the daemon owns indexer.lock, then run onAcquired.
+ *
+ * @param {() => boolean} acquireLock
+ * @param {{
+ *   retryMs: number,
+ *   onAcquired: () => void,
+ *   log?: (msg: string) => void,
+ *   setTimeoutFn?: typeof setTimeout
+ * }} options
+ */
+export function waitForIndexerLock(acquireLock, options) {
+  const retryMs = options.retryMs;
+  const onAcquired = options.onAcquired;
+  const log = options.log || ((msg) => console.error(msg));
+  const setTimeoutFn = options.setTimeoutFn || setTimeout;
+
+  const tryAcquire = () => {
+    if (acquireLock()) {
+      log("Indexer daemon acquired indexer.lock");
+      onAcquired();
+      return;
+    }
+    log("Indexer daemon waiting for indexer.lock...");
+    setTimeoutFn(tryAcquire, retryMs);
+  };
+  tryAcquire();
+}

package/lib/processMode.js

@@ -0,0 +1,28 @@
+/**
+ * Process mode detection for apple-tools-mcp.
+ *
+ * Canonical indexer entrypoint: `node index.js --mode=indexer`
+ * Convenience bin: `apple-tools-indexer` (same file; detected via argv[1]).
+ * MCP stdio remains the default when neither is present.
+ */
+
+import path from "path";
+
+/**
+ * @param {string[]} [argv=process.argv]
+ * @returns {boolean}
+ */
+export function isIndexerMode(argv = process.argv) {
+  if (!Array.isArray(argv) || argv.length === 0) {
+    return false;
+  }
+  if (argv.includes("--mode=indexer")) {
+    return true;
+  }
+  const modeIdx = argv.indexOf("--mode");
+  if (modeIdx !== -1 && argv[modeIdx + 1] === "indexer") {
+    return true;
+  }
+  const entry = argv[1] ? path.basename(argv[1]) : "";
+  return entry === "apple-tools-indexer";
+}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "apple-tools-mcp",
-  "version": "1.1.4",
+  "version": "1.2.0",
   "description": "MCP server for semantic search across Apple Mail, Messages, and Calendar",
   "type": "module",
   "main": "index.js",
   "bin": {
-    "apple-tools-mcp": "./index.js"
+    "apple-tools-mcp": "./index.js",
+    "apple-tools-indexer": "./index.js"
   },
   "author": "Peter Coates",
   "license": "MIT",
@@ -50,6 +51,7 @@
   ],
   "scripts": {
     "start": "node index.js",
+    "indexer": "node index.js --mode=indexer",
     "build-index": "node -e \"import('./indexer.js').then(i=>i.rebuildIndex()).catch(e=>{console.error(e.message);process.exit(1)})\"",
     "audit": "node scripts/audit-index.js",
     "test": "vitest run",