apple-tools-mcp 1.0.0 → 1.1.1

package/README.md

@@ -1,6 +1,6 @@
 # apple-tools-mcp
 
-An MCP (Model Context Protocol) server that provides semantic search across Apple Mail, Messages, and Calendar on macOS. Use natural language to search your emails, iMessages, and calendar events 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 directly from Claude.
 
 ## Features
 
@@ -25,17 +25,44 @@ An MCP (Model Context Protocol) server that provides semantic search across Appl
 npm install -g apple-tools-mcp
 ```
 
+Or from source:
+
+```bash
+git clone https://github.com/sfls1397/Apple-Tools-MCP.git
+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:
+
+```json
+"command": "node",
+"args": ["/absolute/path/to/Apple-Tools-MCP/index.js"]
+```
+
 ### 2. Grant Full Disk Access
 
 The MCP server needs access to read your Mail, Messages, and Calendar databases.
 
-1. Open **System Settings** → **Privacy & Security** → **Full Disk Access**
-2. Click the **+** button
-3. Navigate to your Node.js binary:
-   - For Homebrew: `/opt/homebrew/bin/node`
-   - For nvm: `~/.nvm/versions/node/v[VERSION]/bin/node`
-   - To find yours: `which node`
-4. Enable the toggle for Node.js
+1. First, find your Node.js path by running in Terminal:
+
+   ```bash
+   which node
+   ```
+
+   This will output something like `/opt/homebrew/bin/node` or `/usr/local/bin/node`
+
+2. Open **System Settings** → **Privacy & Security** → **Full Disk Access**
+
+3. Click the **+** button
+
+4. Press **Cmd+Shift+G** to open the "Go to Folder" dialog
+
+5. Paste the path from step 1 (e.g., `/opt/homebrew/bin/node`) and press Enter
+
+6. Select the `node` file and click **Open**
+
+7. Ensure the toggle for Node.js is enabled
 
 ### 3. Configure Claude Desktop
 
@@ -60,16 +87,16 @@ Quit and reopen Claude Desktop to load the MCP server.
 
 ## Building the Index
 
-On first use, the server will automatically build a vector index of your recent emails, messages, and calendar events. This may take a few minutes depending on the volume of data.
+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.
 
 You can manually rebuild the index:
 
 ```bash
-# Index last 30 days (default)
-npx apple-tools-mcp build-index
+# Index all email history (default)
+npm run build-index
 
-# Index more history
-APPLE_TOOLS_INDEX_DAYS_BACK=90 npx apple-tools-mcp build-index
+# Optional: cap email lookback (e.g. for a faster test rebuild)
+APPLE_TOOLS_INDEX_DAYS_BACK=30 npm run build-index
 ```
 
 The index is stored in `~/.apple-tools-mcp/vector-index/`.
@@ -78,15 +105,57 @@ The index is stored in `~/.apple-tools-mcp/vector-index/`.
 
 Once configured, Claude can use these tools:
 
+### Universal Search
+
+| Tool | Description |
+|------|-------------|
+| `smart_search` | Intelligent search across all sources - automatically determines which to search |
+| `person_search` | Find ALL communication with a person across Mail, Messages, and Calendar |
+
+### Email Tools
+
 | Tool | Description |
 |------|-------------|
-| `search_emails` | Search emails by content, sender, subject |
-| `search_messages` | Search iMessages and SMS |
-| `search_calendar` | Search calendar events |
-| `search_all` | Search across all sources |
-| `get_email` | Get full email by ID |
-| `get_message` | Get full message thread |
-| `get_calendar_event` | Get event details |
+| `mail_search` | Semantic search for emails with filters (sender, recipient, attachments, mailbox) |
+| `mail_recent` | Get most recent emails (supports unread filter) |
+| `mail_date` | Get emails from a specific date ("today", "yesterday", "Nov 13") |
+| `mail_read` | Read full email content by file path |
+| `mail_senders` | List most frequent email senders |
+| `mail_thread` | Get all emails in a conversation thread |
+
+### Messages Tools
+
+| Tool | Description |
+|------|-------------|
+| `messages_search` | Semantic search for iMessages/SMS with filters |
+| `messages_recent` | Get most recent messages |
+| `messages_conversation` | Get full conversation history with a contact |
+| `messages_contacts` | List all contacts you've messaged |
+
+### Calendar Tools
+
+| Tool | Description |
+|------|-------------|
+| `calendar_search` | Semantic search for events with filters |
+| `calendar_date` | Get events on a specific date (live Calendar.app, not the search index) |
+| `calendar_upcoming` | Get next N upcoming events |
+| `calendar_week` | Get all events for current or future week |
+| `calendar_free_time` | Find available time slots on a date (live Calendar.app, not the search index) |
+| `calendar_recurring` | List recurring events |
+
+### Contacts Tools
+
+| Tool | Description |
+|------|-------------|
+| `contacts_search` | Search contacts by name, email, phone, or organization |
+| `contacts_lookup` | Look up a specific contact's full details |
+
+### Admin Tools
+
+| Tool | Description |
+|------|-------------|
+| `rebuild_index` | Rebuild search index for one or all sources |
+| `audit_index` | Audit index health and coverage |
 
 ## Example Queries
 
@@ -97,6 +166,8 @@ Ask Claude things like:
 - "When is my next dentist appointment?"
 - "Search for emails about the AWS bill from November"
 - "Find all calendar events with Zoom links"
+- "What's Sarah's phone number?"
+- "Show me all communication with David from last month"
 
 ## Privacy & Security
 
@@ -114,7 +185,7 @@ Ensure Node.js has Full Disk Access (see Installation step 2).
 ### Empty search results
 
 1. Check that the index was built: `ls ~/.apple-tools-mcp/vector-index/`
-2. Rebuild the index if needed: `npx apple-tools-mcp build-index`
+2. Rebuild the index if needed: `npm run build-index`
 
 ### Server not appearing in Claude
 
@@ -122,19 +193,58 @@ Ensure Node.js has Full Disk Access (see Installation step 2).
 2. Restart Claude Desktop completely (Cmd+Q, then reopen)
 3. Check Claude's MCP logs for errors
 
+### Force rebuild the index
+
+If the index becomes corrupted or out of sync:
+
+```bash
+# 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
+```
+
+### Monitor indexing progress
+
+Watch the MCP server logs in real-time:
+
+```bash
+tail -f ~/Library/Logs/Claude/mcp-server-apple-tools.log
+```
+
+### Audit the index
+
+Check index health and coverage:
+
+```bash
+# Quick audit
+npm run audit
+
+# Detailed audit saved to file
+npm run audit -- --reporter=verbose > audit-report.txt
+```
+
 ## Development
 
 ```bash
 # Clone the repo
-git clone https://github.com/sfls1397/apple-tools-mcp.git
-cd apple-tools-mcp
+git clone https://github.com/sfls1397/Apple-Tools-MCP.git
+cd Apple-Tools-MCP
 
 # Install dependencies
 npm install
 
+# Install test dependencies
+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
+
 # Build index with debug output
 npm run build-index
 

package/index.js

@@ -89,35 +89,6 @@ function releaseLock() {
   }
 }
 
-// Kill any zombie MCP processes on startup (except this one)
-function cleanupZombieProcesses() {
-  try {
-    const { execSync } = require('child_process');
-    // Find all apple-tools-mcp index.js processes
-    const psOutput = execSync('ps aux | grep "apple-tools-mcp/index.js" | grep -v grep || true', { encoding: 'utf-8' });
-    const lines = psOutput.trim().split('\n').filter(l => l);
-
-    for (const line of lines) {
-      const parts = line.trim().split(/\s+/);
-      const pid = parseInt(parts[1]);
-
-      // Skip this process
-      if (pid === process.pid) continue;
-
-      // Check if process is still running and kill it
-      try {
-        process.kill(pid, 0); // Check if exists
-        console.error(`Killing zombie MCP process: ${pid}`);
-        process.kill(pid, 'SIGTERM');
-      } catch {
-        // Process already dead
-      }
-    }
-  } catch (e) {
-    // Ignore errors - cleanup is best-effort
-  }
-}
-
 // Clean up lock and timer on exit
 process.on("exit", () => {
   stopBackgroundIndexing();
@@ -235,16 +206,6 @@ function getIndexingMessage() {
   return "Indexing new data. Please try again in a moment.";
 }
 
-// Timeout wrapper for promises
-function withTimeout(promise, timeoutMs, operation = "Operation") {
-  return Promise.race([
-    promise,
-    new Promise((_, reject) =>
-      setTimeout(() => reject(new Error(`${operation} timed out after ${timeoutMs}ms`)), timeoutMs)
-    )
-  ]);
-}
-
 // Run a single indexing cycle (called by background timer)
 function runIndexCycle() {
   if (indexingInProgress) {
@@ -356,10 +317,11 @@ function stopBackgroundIndexing() {
 async function initializeIndexing() {
   isFirstEverRun = await checkIfFirstRun();
 
-  // Try to acquire lock - if another instance is running, exit
+  // Try to acquire lock - if another instance is indexing, skip background
+  // indexing but keep the MCP server running so search still works.
   if (!acquireLock()) {
-    console.error("Another apple-tools-mcp instance is running. Exiting.");
-    process.exit(0);
+    console.error("Another apple-tools-mcp instance is indexing. Server will run without background indexing.");
+    return;
   }
 
   // Start background indexing
@@ -474,29 +436,11 @@ async function calendarSearch(query, options = {}) {
 }
 
 async function calendarDate(date) {
-  if (!sessionIndexComplete) {
-    return getIndexingMessage();
-  }
-
-  const ready = await isIndexReady("calendar");
-  if (!ready) {
-    return "Calendar index not available. Please try again shortly.";
-  }
-
   const result = await getCalendarDateResults(date);
   return formatCalendarResults(result);
 }
 
 async function calendarFreeTime(date, options = {}) {
-  if (!sessionIndexComplete) {
-    return getIndexingMessage();
-  }
-
-  const ready = await isIndexReady("calendar");
-  if (!ready) {
-    return "Calendar index not available. Please try again shortly.";
-  }
-
   const result = await calculateFreeTime(date, options);
   return formatFreeTimeResults(result);
 }
@@ -1490,12 +1434,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
 // Start the server
 async function main() {
-  // Kill any zombie processes from previous sessions
-  cleanupZombieProcesses();
-
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  console.error("Apple Tools MCP server running (v2.0.0)");
+  console.error("Apple Tools MCP server running (v1.1.1)");
   // Background indexing runs automatically on startup and every INDEX_INTERVAL
 }
 

package/indexer.js

@@ -1,7 +1,5 @@
 import fs from "fs";
 import path from "path";
-import { exec } from "child_process";
-import { promisify } from "util";
 import * as lancedb from "@lancedb/lancedb";
 import { pipeline } from "@xenova/transformers";
 import {
@@ -13,7 +11,7 @@ import {
   escapeSQL,
   stripHtmlTags
 } from "./lib/validators.js";
-import { safeSqlite3Json, safeOsascript } from "./lib/shell.js";
+import { safeSqlite3Json, safeOsascript, safeFind } from "./lib/shell.js";
 
 // Re-export contact functions for use by other modules
 export {
@@ -28,16 +26,17 @@ export {
   getContactStats
 } from "./contacts.js";
 
-const execAsync = promisify(exec);
-
 // Support env var overrides for testing with separate index
 export const INDEX_DIR = process.env.APPLE_TOOLS_INDEX_DIR ||
   path.join(process.env.HOME, ".apple-tools-mcp", "vector-index");
 const META_FILE = process.env.APPLE_TOOLS_META_FILE ||
   path.join(process.env.HOME, ".apple-tools-mcp", "index-meta.json");
-// Support filtering by date for testing (default: null = no filter)
-const DAYS_BACK = process.env.APPLE_TOOLS_INDEX_DAYS_BACK ?
-  parseInt(process.env.APPLE_TOOLS_INDEX_DAYS_BACK, 10) : null;
+// Optional date filter for email indexing. Default is unlimited (index all emails).
+// Set APPLE_TOOLS_INDEX_DAYS_BACK=30 to cap the window (tests do this).
+// Set APPLE_TOOLS_INDEX_DAYS_BACK=0 to explicitly disable filtering.
+const DAYS_BACK = process.env.APPLE_TOOLS_INDEX_DAYS_BACK !== undefined
+  ? parseInt(process.env.APPLE_TOOLS_INDEX_DAYS_BACK, 10) || null  // 0 means null (no filter)
+  : null;  // Default: no date filter
 const MAIL_DIR = path.join(process.env.HOME, "Library", "Mail");
 
 // Load/save index metadata (timestamps, etc.)
@@ -59,11 +58,12 @@ function saveIndexMeta(meta) {
 }
 const MESSAGES_DB = path.join(process.env.HOME, "Library", "Messages", "chat.db");
 const CALENDAR_DB = path.join(process.env.HOME, "Library", "Group Containers", "group.com.apple.calendar", "Calendar.sqlitedb");
-const BATCH_SIZE = 32; // Optimized for batch embedding throughput
-const BATCH_DELAY_MS = 100; // Throttle to prevent thermal crashes
+const BATCH_SIZE = 64; // Optimized for batch embedding throughput (increased for faster indexing)
+const BATCH_DELAY_MS = 0; // No delay needed - benchmarks showed no thermal throttling
 
 // Mac Absolute Time epoch: Jan 1, 2001 00:00:00 UTC
 const MAC_ABSOLUTE_EPOCH = 978307200;
+export const CALENDAR_TMP_PREFIX = "apple-tools-cal-";
 
 let embeddingPipeline = null;
 let db = null;
@@ -89,11 +89,14 @@ const EMBEDDING_DIM = 384; // all-MiniLM-L6-v2 dimension
 
 // Timeout wrapper for promises
 function withTimeout(promise, timeoutMs, operation = "Operation") {
+  let timer;
+  const timeoutPromise = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`${operation} timed out after ${timeoutMs}ms`)), timeoutMs);
+    if (timer.unref) timer.unref();
+  });
   return Promise.race([
-    promise,
-    new Promise((_, reject) =>
-      setTimeout(() => reject(new Error(`${operation} timed out after ${timeoutMs}ms`)), timeoutMs)
-    )
+    promise.finally(() => clearTimeout(timer)),
+    timeoutPromise
   ]);
 }
 
@@ -333,10 +336,8 @@ function parseEmlx(filePath) {
 // Includes both .emlx and .partial.emlx files (partial = not fully downloaded via IMAP)
 async function findAllEmlxFiles() {
   try {
-    // Find both .emlx and .partial.emlx files
-    const cmd = `find "${MAIL_DIR}" \\( -name "*.emlx" -o -name "*.partial.emlx" \\) 2>/dev/null`;
-    const { stdout } = await execAsync(cmd, { encoding: "utf-8", maxBuffer: 50 * 1024 * 1024, timeout: 120000 });
-    return stdout.trim().split("\n").filter(f => f);
+    // "*.emlx" also matches "*.partial.emlx"
+    return safeFind(MAIL_DIR, { name: "*.emlx", type: "f" });
   } catch (e) {
     console.error("Error finding emlx files:", e.message);
     return [];
@@ -358,9 +359,7 @@ async function findNewEmlxFiles(sinceTimestamp) {
 
     // Use find with -mtime instead of mdfind for reliability
     // find is more reliable than Spotlight which can have stale/incomplete indexes
-    const cmd = `find "${MAIL_DIR}" \\( -name "*.emlx" -o -name "*.partial.emlx" \\) -mtime -${daysAgo} 2>/dev/null`;
-    const { stdout } = await execAsync(cmd, { encoding: "utf-8", maxBuffer: 50 * 1024 * 1024, timeout: 120000 });
-    const files = stdout.trim().split("\n").filter(f => f);
+    const files = safeFind(MAIL_DIR, { name: "*.emlx", type: "f", mtime: `-${daysAgo}` });
     console.error(`find found ${files.length} new/modified emails in last ${daysAgo} days`);
     return files;
   } catch (e) {
@@ -718,10 +717,6 @@ function getCalendarEvents() {
       const startTimestamp = macAbsoluteToUnixMs(row.start_date);
       const attendees = attendeesMap.get(row.id) || [];
 
-      if (row.all_day === 1) {
-        console.error(`[Indexing] All-day event: "${row.summary}" at ${new Date(startTimestamp).toISOString()}`);
-      }
-
       events.push({
         dbId: row.id,  // Stable database ID for deduplication
         title: row.summary,
@@ -909,15 +904,20 @@ export async function indexEmails(progressCallback = null, forceFullScan = false
   if (DAYS_BACK) {
     // DAYS_BACK is set - use it for mdfind filter (e.g., for testing or rebuild with constraints)
     lastEmailIndexTime = Date.now() - (DAYS_BACK * 24 * 60 * 60 * 1000);
-    console.error(`Using DAYS_BACK=${DAYS_BACK} for mdfind filter`);
+    console.error(`\n=== EMAIL INDEXING (DAYS_BACK=${DAYS_BACK}) ===`);
+    console.error(`Will search for emails modified since: ${new Date(lastEmailIndexTime).toISOString()}`);
   } else if (forceFullScan) {
     // Force full scan only when no DAYS_BACK constraint
     lastEmailIndexTime = null;
+    console.error("\n=== EMAIL INDEXING (FULL SCAN) ===");
     console.error("Force full scan requested - finding all emails");
   } else if (meta.lastEmailIndexTime) {
     lastEmailIndexTime = meta.lastEmailIndexTime - ONE_DAY_MS;
+    console.error(`\n=== EMAIL INDEXING (INCREMENTAL) ===`);
+    console.error(`Searching for emails modified since: ${new Date(lastEmailIndexTime).toISOString()}`);
   } else {
     lastEmailIndexTime = null;
+    console.error("\n=== EMAIL INDEXING (FIRST RUN - FULL SCAN) ===");
   }
 
   // Save the current time BEFORE we start - any emails arriving during indexing
@@ -926,6 +926,7 @@ export async function indexEmails(progressCallback = null, forceFullScan = false
 
   // Use fast incremental scan if we have a previous timestamp
   const startTime = Date.now();
+  console.error(`Calling findNewEmlxFiles with timestamp: ${lastEmailIndexTime ? new Date(lastEmailIndexTime).toISOString() : 'null (full scan)'}`);
   const newFiles = await findNewEmlxFiles(lastEmailIndexTime);
   console.error(`Found ${newFiles.length} new/modified email files (${Date.now() - startTime}ms)`);
 
@@ -950,6 +951,11 @@ export async function indexEmails(progressCallback = null, forceFullScan = false
   let processed = 0;
   let skippedCount = { parseNull: 0, shortSearchText: 0, duplicateMessageId: 0 };
 
+  // Progress tracking
+  const totalBatches = Math.ceil(toIndex.length / BATCH_SIZE);
+  const startProcessTime = Date.now();
+  console.error(`\nProcessing ${toIndex.length} emails in ${totalBatches} batches (batch size: ${BATCH_SIZE})...`);
+
   for (let i = 0; i < toIndex.length; i += BATCH_SIZE) {
     const batch = toIndex.slice(i, i + BATCH_SIZE);
 
@@ -1067,7 +1073,16 @@ export async function indexEmails(progressCallback = null, forceFullScan = false
     }
 
     processed += batch.length;
-    console.error(`Indexed ${processed}/${toIndex.length} emails...`);
+
+    // Calculate and display progress with time estimates
+    const currentBatch = Math.floor(i / BATCH_SIZE) + 1;
+    const elapsedMs = Date.now() - startProcessTime;
+    const avgTimePerBatch = elapsedMs / currentBatch;
+    const remainingBatches = totalBatches - currentBatch;
+    const estimatedRemainingMs = avgTimePerBatch * remainingBatches;
+    const estimatedRemainingMin = Math.ceil(estimatedRemainingMs / 60000);
+
+    console.error(`Batch ${currentBatch}/${totalBatches} complete | Processed: ${processed}/${toIndex.length} emails | Est. remaining: ${estimatedRemainingMin}m`);
 
     // Report progress after each batch
     if (progressCallback) {
@@ -1083,7 +1098,8 @@ export async function indexEmails(progressCallback = null, forceFullScan = false
   // Save timestamp for next incremental scan
   saveIndexMeta({ ...meta, lastEmailIndexTime: indexStartTime });
 
-  // Log skip summary
+  // Log skip summary with timing
+  const totalProcessingTime = Date.now() - startProcessTime;
   const totalSkipped = skippedCount.parseNull + skippedCount.shortSearchText + skippedCount.duplicateMessageId;
   console.error(`\nEmail indexing summary:`);
   console.error(`  Files to index: ${toIndex.length}`);
@@ -1092,7 +1108,8 @@ export async function indexEmails(progressCallback = null, forceFullScan = false
   console.error(`  Skipped - short searchText: ${skippedCount.shortSearchText}`);
   console.error(`  Skipped - duplicate messageId: ${skippedCount.duplicateMessageId}`);
   console.error(`  Total skipped: ${totalSkipped}`);
-  console.error(`  Discrepancy: ${toIndex.length - processed - totalSkipped}\n`);
+  console.error(`  Discrepancy: ${toIndex.length - processed - totalSkipped}`);
+  console.error(`  Total time: ${Math.round(totalProcessingTime / 1000)}s (${Math.round(totalProcessingTime / 60000)}m)\n`);
 
   // Return actual indexed count from database, not stale cache
   const finalIndexedPaths = await getIndexedIdsWithRetry("emails", "filePath");
@@ -1129,6 +1146,12 @@ export async function indexMessages(forceFullScan = false) {
   }
 
   let processed = 0;
+
+  // Progress tracking
+  const totalBatches = Math.ceil(toIndex.length / BATCH_SIZE);
+  const startProcessTime = Date.now();
+  console.error(`\nProcessing ${toIndex.length} messages in ${totalBatches} batches (batch size: ${BATCH_SIZE})...`);
+
   for (let i = 0; i < toIndex.length; i += BATCH_SIZE) {
     const batch = toIndex.slice(i, i + BATCH_SIZE);
 
@@ -1221,7 +1244,16 @@ export async function indexMessages(forceFullScan = false) {
     }
 
     processed += batch.length;
-    console.error(`Indexed ${processed}/${toIndex.length} messages...`);
+
+    // Calculate and display progress with time estimates
+    const currentBatch = Math.floor(i / BATCH_SIZE) + 1;
+    const elapsedMs = Date.now() - startProcessTime;
+    const avgTimePerBatch = elapsedMs / currentBatch;
+    const remainingBatches = totalBatches - currentBatch;
+    const estimatedRemainingMs = avgTimePerBatch * remainingBatches;
+    const estimatedRemainingMin = Math.ceil(estimatedRemainingMs / 60000);
+
+    console.error(`Batch ${currentBatch}/${totalBatches} complete | Processed: ${processed}/${toIndex.length} messages | Est. remaining: ${estimatedRemainingMin}m`);
 
     // Throttle to prevent thermal crashes
     if (i + BATCH_SIZE < toIndex.length) {
@@ -1656,6 +1688,117 @@ export function getUpcomingEvents(limit = 10) {
   }
 }
 
+// Convert local-day unix ms bounds to Apple/Core Data seconds (unix - 978307200)
+export function localDayToMacBounds(startMs, endMs) {
+  const startMac = Math.floor(Number(startMs) / 1000) - MAC_ABSOLUTE_EPOCH;
+  const endMac = Math.floor(Number(endMs) / 1000) - MAC_ABSOLUTE_EPOCH;
+  if (!Number.isFinite(startMac) || !Number.isFinite(endMac)) {
+    throw new Error("Invalid date bounds");
+  }
+  return { startMac, endMac };
+}
+
+// Date-bounded OccurrenceCache query: one row per occurrence, no GROUP BY ci.ROWID
+export function buildEventsOnDateQuery(startMac, endMac) {
+  const startBound = Math.floor(Number(startMac));
+  const endBound = Math.floor(Number(endMac));
+  if (!Number.isFinite(startBound) || !Number.isFinite(endBound)) {
+    throw new Error("Invalid Mac Absolute Time bounds");
+  }
+  const timedStart = "COALESCE(oc.occurrence_end_date - (ci.end_date - ci.start_date), ci.start_date)";
+  const occEnd = "COALESCE(oc.occurrence_end_date, ci.end_date)";
+  // First local day = occurrence-end local date minus (durationDays - 1). Day math, not seconds (DST-safe).
+  const allDayStartDate = `date(${occEnd} + 978307200, 'unixepoch', 'localtime', '-' || (CAST(round((ci.end_date - ci.start_date) / 86400.0) AS INTEGER) - 1) || ' days')`;
+  const allDayStartMac = `CAST(strftime('%s', ${allDayStartDate} || ' 00:00:00', 'utc') AS INTEGER) - 978307200`;
+  return `
+      SELECT DISTINCT
+        ci.ROWID as itemId,
+        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,
+        CASE WHEN ci.all_day THEN ${allDayStartMac} ELSE ${timedStart} END as startMac,
+        ${occEnd} as endMac,
+        ci.all_day as isAllDay,
+        c.title as calendar,
+        l.title as location
+      FROM OccurrenceCache oc
+      INNER JOIN CalendarItem ci ON oc.event_id = ci.ROWID
+      LEFT JOIN Calendar c ON ci.calendar_id = c.ROWID
+      LEFT JOIN Location l ON ci.location_id = l.ROWID
+      WHERE ci.summary IS NOT NULL AND ci.summary <> ''
+        AND (c.title IS NULL OR c.title NOT IN ('Found in Mail', 'Found in Natural Language'))
+        AND (
+          (oc.day >= ${startBound} AND oc.day < ${endBound})
+          OR (
+            ci.all_day = 0
+            AND ${timedStart} < ${startBound}
+            AND ${occEnd} > ${startBound}
+          )
+        )
+      ORDER BY startMac ASC, title ASC
+    `;
+}
+
+// Copy Calendar.sqlitedb (+ wal/shm) to /tmp for one query, then delete the copies.
+// Calendar.app holds a lock on the live db; sqlite can read a snapshot copy.
+function withCalendarCopy(fn) {
+  const id = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const tmpDb = path.join("/tmp", `${CALENDAR_TMP_PREFIX}${id}.sqlitedb`);
+  const tmpWal = `${tmpDb}-wal`;
+  const tmpShm = `${tmpDb}-shm`;
+  const srcWal = `${CALENDAR_DB}-wal`;
+  const srcShm = `${CALENDAR_DB}-shm`;
+
+  try {
+    if (!fs.existsSync(CALENDAR_DB)) {
+      throw new Error("Calendar database not found");
+    }
+    fs.copyFileSync(CALENDAR_DB, tmpDb);
+    if (fs.existsSync(srcWal)) {
+      fs.copyFileSync(srcWal, tmpWal);
+    }
+    if (fs.existsSync(srcShm)) {
+      fs.copyFileSync(srcShm, tmpShm);
+    }
+    return fn(tmpDb);
+  } finally {
+    for (const file of [tmpDb, tmpWal, tmpShm]) {
+      try {
+        fs.unlinkSync(file);
+      } catch {
+        // already gone or never created
+      }
+    }
+  }
+}
+
+// calendar_date: live OccurrenceCache for every occurrence on a local day
+export function getEventsOnDate(startMs, endMs) {
+  try {
+    if (!fs.existsSync(CALENDAR_DB)) {
+      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++) {
+      try {
+        const events = withCalendarCopy((dbPath) => {
+          return safeSqlite3Json(dbPath, query, { timeout: 15000 });
+        });
+        return { events, error: null };
+      } catch (e) {
+        lastError = e;
+        console.error(`Error getting events on date (attempt ${attempt + 1}):`, e.message);
+      }
+    }
+    return { events: [], error: lastError.message };
+  } catch (e) {
+    console.error("Error getting events on date:", e.message);
+    return { events: [], error: e.message };
+  }
+}
+
 // ============ NEW TOOLS - PHASE 2 ============
 
 // mail_unread_count: Get count of unread emails via AppleScript

package/lib/audit.js

@@ -13,8 +13,7 @@
 
 import fs from "fs";
 import path from "path";
-import { execSync } from "child_process";
-import { safeSqlite3Json } from "./shell.js";
+import { safeSqlite3Json, safeFind } from "./shell.js";
 import * as lancedb from "@lancedb/lancedb";
 
 // ============================================================================
@@ -38,6 +37,16 @@ const DAYS_BACK = process.env.APPLE_TOOLS_INDEX_DAYS_BACK ?
 // Exclude these folders from email indexing (matches indexer behavior)
 const EXCLUDED_FOLDERS = ["Junk.mbox", "Saved Junk.mbox", "Trash.mbox", "Deleted Messages.mbox"];
 
+function listEmailFiles() {
+  const options = { name: "*.emlx", type: "f" };
+  if (DAYS_BACK) {
+    options.mtime = `-${DAYS_BACK}`;
+  }
+  return safeFind(MAIL_DIR, options).filter(
+    p => !EXCLUDED_FOLDERS.some(folder => p.includes(`/${folder}/`))
+  );
+}
+
 let db = null;
 let tables = {};
 
@@ -82,15 +91,7 @@ export function countRawEmails() {
   if (!fs.existsSync(MAIL_DIR)) return 0;
 
   try {
-    // Build exclusion pattern for find command
-    const exclusions = EXCLUDED_FOLDERS.map(folder => `-path "*/${folder}/*"`).join(" -o ");
-
-    // Add time filter if DAYS_BACK is set (matches indexer behavior)
-    const timeFilter = DAYS_BACK ? `-mtime -${DAYS_BACK}` : "";
-    const cmd = `find "${MAIL_DIR}" \\( -name "*.emlx" -o -name "*.partial.emlx" \\) ! \\( ${exclusions} \\) ${timeFilter} -type f 2>/dev/null | wc -l`;
-
-    const result = execSync(cmd, { encoding: "utf-8", timeout: 120000 }).trim();
-    return parseInt(result) || 0;
+    return listEmailFiles().length;
   } catch (e) {
     console.error("Error counting emails:", e.message);
     return 0;
@@ -162,15 +163,7 @@ export function getRawEmailIds() {
   if (!fs.existsSync(MAIL_DIR)) return new Set();
 
   try {
-    const exclusions = EXCLUDED_FOLDERS.map(folder => `-path "*/${folder}/*"`).join(" -o ");
-
-    // Add time filter if DAYS_BACK is set (matches indexer behavior)
-    const timeFilter = DAYS_BACK ? `-mtime -${DAYS_BACK}` : "";
-    const cmd = `find "${MAIL_DIR}" \\( -name "*.emlx" -o -name "*.partial.emlx" \\) ! \\( ${exclusions} \\) ${timeFilter} -type f 2>/dev/null`;
-
-    const result = execSync(cmd, { encoding: "utf-8", timeout: 120000, maxBuffer: 50 * 1024 * 1024 }).trim();
-    const paths = result.split("\n").filter(p => p);
-    return new Set(paths);
+    return new Set(listEmailFiles());
   } catch (e) {
     console.error("Error getting email IDs:", e.message);
     return new Set();

package/lib/validators.js

@@ -137,8 +137,8 @@ export function validateMailboxName(mailbox) {
   }
 
   // Only allow alphanumeric, spaces, hyphens, underscores, and periods
-  // This prevents any AppleScript injection
-  if (!/^[a-zA-Z0-9\s\-_.]+$/.test(mailbox)) {
+  // Literal space only — \s would also allow newlines/tabs (injection risk)
+  if (!/^[a-zA-Z0-9._ -]+$/.test(mailbox)) {
     return null;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-tools-mcp",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "MCP server for semantic search across Apple Mail, Messages, and Calendar",
   "type": "module",
   "main": "index.js",
@@ -11,12 +11,12 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/sfls1397/apple-tools-mcp.git"
+    "url": "git+https://github.com/sfls1397/Apple-Tools-MCP.git"
   },
   "bugs": {
-    "url": "https://github.com/sfls1397/apple-tools-mcp/issues"
+    "url": "https://github.com/sfls1397/Apple-Tools-MCP/issues"
   },
-  "homepage": "https://github.com/sfls1397/apple-tools-mcp#readme",
+  "homepage": "https://github.com/sfls1397/Apple-Tools-MCP#readme",
   "keywords": [
     "mcp",
     "model-context-protocol",
@@ -34,6 +34,12 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "os": [
+    "darwin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "files": [
     "index.js",
     "indexer.js",
@@ -46,61 +52,28 @@
   ],
   "scripts": {
     "start": "node index.js",
-    "build-index": "APPLE_TOOLS_INDEX_DAYS_BACK=30 node -e \"import('./indexer.js').then(i=>i.rebuildIndex()).catch(e=>{console.error(e.message);process.exit(1)})\"",
-    "audit": "APPLE_TOOLS_INDEX_DAYS_BACK=30 node scripts/audit-index.js",
+    "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",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
     "test:unit": "vitest run tests/unit",
     "test:integration": "vitest run tests/integration",
-    "test:integration:periodic": "vitest run tests/integration/periodic-indexing-e2e.test.js --reporter=verbose",
-    "test:perf": "vitest run tests/performance",
-    "test:fuzz": "vitest run tests/fuzz",
-    "test:chaos": "vitest run tests/chaos",
-    "test:contract": "vitest run tests/contract",
-    "test:concurrency": "vitest run tests/concurrency",
-    "test:recovery": "vitest run tests/recovery",
-    "test:timezone": "vitest run tests/timezone",
-    "test:stress": "vitest run tests/stress",
-    "test:snapshot": "vitest run tests/snapshots",
-    "test:all": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "test:idx": "vitest run tests/indexing",
-    "test:idx:unit": "vitest run tests/indexing/unit",
-    "test:idx:integration": "vitest run tests/indexing/integration",
     "test:idx:accuracy": "vitest run tests/indexing/accuracy",
-    "test:idx:perf": "vitest run tests/indexing/performance",
     "test:idx:resource": "vitest run tests/indexing/resource",
-    "test:idx:edge": "vitest run tests/indexing/edge-cases",
-    "test:idx:security": "vitest run tests/indexing/security",
-    "test:idx:contacts": "vitest run tests/indexing/contacts",
-    "test:idx:cache": "vitest run tests/indexing/caching",
-    "test:idx:negative": "vitest run tests/indexing/negative",
-    "test:idx:watch": "vitest tests/indexing",
-    "test:idx:build": "node scripts/build-test-index.js",
-    "test:idx:clean": "node scripts/clean-test-index.js",
-    "perf": "USE_REAL_DATA=1 vitest run tests/perf --reporter=verbose",
-    "perf:mock": "vitest run tests/perf --reporter=verbose",
-    "perf:watch": "USE_REAL_DATA=1 vitest tests/perf",
-    "perf:indexing": "vitest run tests/perf/indexing.perf.test.js --reporter=verbose",
-    "perf:search": "vitest run tests/perf/search.perf.test.js --reporter=verbose",
-    "perf:tools": "vitest run tests/perf/tools.perf.test.js --reporter=verbose",
-    "perf:server": "vitest run tests/perf/mcp-server.perf.test.js --reporter=verbose",
-    "perf:embedding": "vitest run tests/perf/embedding.perf.test.js --reporter=verbose",
-    "perf:datasources": "vitest run tests/perf/datasources.perf.test.js --reporter=verbose",
-    "perf:memory": "vitest run tests/perf/memory.perf.test.js --reporter=verbose",
-    "perf:stress": "vitest run tests/perf/stress.perf.test.js --reporter=verbose --testTimeout=120000",
-    "perf:mail": "vitest run tests/perf/datasources.perf.test.js -t 'Email' --reporter=verbose",
-    "perf:messages": "vitest run tests/perf/datasources.perf.test.js -t 'Messages' --reporter=verbose",
-    "perf:calendar": "vitest run tests/perf/datasources.perf.test.js -t 'Calendar' --reporter=verbose",
-    "perf:contacts": "vitest run tests/perf/datasources.perf.test.js -t 'Contacts' --reporter=verbose",
-    "perf:quick": "vitest run tests/perf/tools.perf.test.js tests/perf/search.perf.test.js --reporter=verbose",
-    "perf:negative": "vitest run tests/perf/negative.perf.test.js --reporter=verbose",
-    "perf:edge-cases": "vitest run tests/perf/edge-cases.perf.test.js --reporter=verbose",
-    "perf:regression": "vitest run tests/perf/regression.perf.test.js --reporter=verbose",
-    "perf:lancedb": "vitest run tests/perf/lancedb.perf.test.js --reporter=verbose",
-    "perf:background": "vitest run tests/perf/background-indexing.perf.test.js --reporter=verbose",
-    "perf:dates": "vitest run tests/perf/date-parsing.perf.test.js --reporter=verbose",
-    "perf:full": "vitest run tests/perf --reporter=verbose --testTimeout=120000"
+    "test:security": "vitest run tests/indexing/security",
+    "perf": "vitest run tests/perf",
+    "perf:quick": "vitest run tests/perf/tools.perf.test.js",
+    "perf:embedding": "vitest run tests/perf/embedding.perf.test.js",
+    "perf:stress": "vitest run tests/perf/stress.perf.test.js",
+    "perf:indexing": "vitest run tests/perf/indexing.perf.test.js",
+    "perf:search": "vitest run tests/perf/search.perf.test.js",
+    "perf:negative": "vitest run tests/perf/negative.perf.test.js",
+    "perf:regression": "vitest run tests/perf/regression.perf.test.js",
+    "perf:lancedb": "vitest run tests/perf/lancedb.perf.test.js",
+    "perf:background": "vitest run tests/perf/background-indexing.perf.test.js",
+    "perf:dates": "vitest run tests/perf/date-parsing.perf.test.js"
   },
   "dependencies": {
     "@lancedb/lancedb": "^0.22.3",
@@ -109,8 +82,8 @@
     "chrono-node": "^2.9.0"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "^4.0.14",
-    "fast-check": "^3.15.0",
-    "vitest": "^4.0.14"
+    "vitest": "^2.1.0",
+    "@vitest/coverage-v8": "^2.1.0",
+    "fast-check": "^3.22.0"
   }
 }

package/search.js

@@ -2,7 +2,7 @@ import * as lancedb from "@lancedb/lancedb";
 import * as chrono from "chrono-node";
 import { safeOsascript } from "./lib/shell.js";
 import { safeMatch, validateSearchQuery } from "./lib/validators.js";
-import { embed, INDEX_DIR, getRecentEmails, getEmailsByDateRange, getRecentMessages, getConversation, getCalendarByDate, getAllCalendarEvents, resolveEmail, resolvePhone, formatContact } from "./indexer.js";
+import { embed, INDEX_DIR, getRecentEmails, getEmailsByDateRange, getRecentMessages, getConversation, getEventsOnDate, resolveEmail, resolvePhone, formatContact } from "./indexer.js";
 
 let db = null;
 let tables = {};
@@ -826,7 +826,7 @@ export async function getRecentEmailResults(limit = 30, daysBack = 7, unreadOnly
           const subject = (r.subject || "").trim().toLowerCase();
           // Index from field has two formats:
           // 1. "Coinbase via Cloaked (Coinbase)" - just display name
-          // 2. "Renita Tyson via Cloaked (AiEdge)" <email@domain.com> - display name + email
+          // 2. "Jane Smith via Cloaked (Company)" <email@domain.com> - display name + email
           // Extract just the display name from both formats
           const fromRaw = (r.from || "").trim().toLowerCase();
           const fromName = fromRaw.replace(/<[^>]+>$/, "").trim().replace(/^"|"$/g, "");
@@ -1319,28 +1319,40 @@ export async function searchCalendar(query, options = {}) {
   }
 }
 
-// Get events on a specific date
+// Local midnight of parsed date through next local midnight (handles DST; not +24h)
+export function getLocalDayBounds(dateStr) {
+  const start = parseNaturalDate(dateStr);
+  if (start == null) return null;
+  const endDate = new Date(start);
+  endDate.setDate(endDate.getDate() + 1);
+  return { start, end: endDate.getTime() };
+}
+
+// Get events on a specific date from live Calendar.sqlitedb (not the vector index)
 export async function getCalendarDateResults(dateStr) {
   try {
-    const range = getDateRange(dateStr);
+    const range = getLocalDayBounds(dateStr);
     if (!range) {
       return { success: false, error: `Could not parse date: ${dateStr}` };
     }
 
     console.error(`[Calendar Date] Query for "${dateStr}"`);
-    console.error(`[Calendar Date] Range: ${new Date(range.start).toISOString()} to ${new Date(range.end).toISOString()}`);
+    console.error(`[Calendar Date] Range: ${new Date(range.start).toString()} to ${new Date(range.end).toString()}`);
 
-    const results = await getCalendarByDate(range.start, range.end);
+    const { events, error } = getEventsOnDate(range.start, range.end);
+    if (error) {
+      return { success: false, error: `Error getting calendar events: ${error}` };
+    }
 
-    const formattedResults = results.map((row, idx) => ({
+    const formattedResults = events.map((row, idx) => ({
       index: idx + 1,
       title: row.title || "No title",
-      start: formatLocalDate(row.start) || "Unknown",
-      startTimestamp: row.startTimestamp || null,
-      end: formatLocalDate(row.end) || "Unknown",
+      start: formatLocalDate(row.start) || row.start || "Unknown",
+      startTimestamp: row.startMac != null ? (Number(row.startMac) + 978307200) * 1000 : null,
+      end: formatLocalDate(row.end) || row.end || "Unknown",
       calendar: row.calendar || "Unknown",
       location: row.location || "",
-      isAllDay: row.isAllDay || false
+      isAllDay: !!row.isAllDay
     }));
 
     const dateLabel = new Date(range.start).toLocaleDateString("en-US", {
@@ -1360,6 +1372,24 @@ export async function getCalendarDateResults(dateStr) {
   }
 }
 
+// Clamp a timed event to [dayStartMs, dayEndMs) and return minutes from local midnight.
+// Overnight events (23:00–01:00) contribute only the slice that falls on this day.
+export function clampBusyToLocalDay(evtStartMs, evtEndMs, dayStartMs, dayEndMs) {
+  const clampedStart = Math.max(evtStartMs, dayStartMs);
+  const clampedEnd = Math.min(evtEndMs, dayEndMs);
+  if (!(clampedEnd > clampedStart)) return null;
+
+  const startMinutes = clampedStart <= dayStartMs
+    ? 0
+    : new Date(clampedStart).getHours() * 60 + new Date(clampedStart).getMinutes();
+  const endMinutes = clampedEnd >= dayEndMs
+    ? 24 * 60
+    : new Date(clampedEnd).getHours() * 60 + new Date(clampedEnd).getMinutes();
+
+  if (!(endMinutes > startMinutes)) return null;
+  return { startMinutes, endMinutes };
+}
+
 // Calculate free time slots on a specific date
 export async function calculateFreeTime(dateStr, options = {}) {
   const {
@@ -1369,12 +1399,17 @@ export async function calculateFreeTime(dateStr, options = {}) {
   } = options;
 
   try {
-    const range = getDateRange(dateStr);
+    const range = getLocalDayBounds(dateStr);
     if (!range) {
       return { success: false, error: `Could not parse date: ${dateStr}` };
     }
 
-    let events = await getCalendarByDate(range.start, range.end);
+    const { events: liveEvents, error } = getEventsOnDate(range.start, range.end);
+    if (error) {
+      return { success: false, error: `Error calculating free time: ${error}` };
+    }
+
+    let events = liveEvents;
 
     // Filter by calendar if specified
     if (calendarName) {
@@ -1390,16 +1425,21 @@ export async function calculateFreeTime(dateStr, options = {}) {
         continue;
       }
 
-      const evtStart = new Date(evt.startTimestamp);
-      const evtEnd = evt.end ? parseDate(evt.end) : evt.startTimestamp + (60 * 60 * 1000); // Default 1 hour
+      const evtStart = evt.startMac != null
+        ? (Number(evt.startMac) + 978307200) * 1000
+        : (evt.startTimestamp || parseDate(evt.start));
+      const evtEnd = evt.endMac != null
+        ? (Number(evt.endMac) + 978307200) * 1000
+        : (evt.end ? parseDate(evt.end) : evtStart + (60 * 60 * 1000));
 
-      const startMinutes = evtStart.getHours() * 60 + evtStart.getMinutes();
-      const endMinutes = new Date(evtEnd).getHours() * 60 + new Date(evtEnd).getMinutes();
+      const clamped = clampBusyToLocalDay(evtStart, evtEnd, range.start, range.end);
+      if (!clamped) continue;
 
-      busyPeriods.push({
-        start: Math.max(startMinutes, startHour * 60),
-        end: Math.min(endMinutes, endHour * 60)
-      });
+      const start = Math.max(clamped.startMinutes, startHour * 60);
+      const end = Math.min(clamped.endMinutes, endHour * 60);
+      if (end > start) {
+        busyPeriods.push({ start, end });
+      }
     }
 
     // Sort busy periods