mcp-icloud 2.1.4 → 2.2.0

package/README.md

@@ -103,7 +103,7 @@ Tools marked local only return an error in cloud mode, because the iCloud protoc
 
 Reading requires the [`imsg`](https://github.com/steipete/imsg) CLI and Full Disk Access.
 
-- **list-chats**: `limit` (number, optional)
+- **list-chats**: `limit` (number, optional, max 1000), `since` (ISO 8601, optional — only chats active since that date, e.g. a weekly review)
 - **read-messages**: `chatId` (number); `limit` (number, optional); `start`, `end` (ISO 8601, optional); `attachments` (boolean, optional)
 - **send-message**: `to` (string), `body` (string), `file` (string, optional)
 - **react-message**: `chatId` (number), `type` (`love`, `like`, `dislike`, `laugh`, `emphasis`, `question`)
@@ -216,7 +216,11 @@ Mail.app tools iterate messages through AppleScript, which is slow on very large
 
 ### Known limitation: large calendar sets
 
-`list-events` in local mode suffers the same AppleScript wall. The date window is already filtered inside Calendar.app with a `whose` query, but on accounts with many calendars, especially subscribed ones carrying years of events (holidays, sports fixtures, travel feeds), the query can still exceed any reasonable timeout. `list-calendars` and the event write tools are not affected. Until the planned EventKit backend lands (see [#10](https://github.com/MrGo2/icloud-mcp/issues/11)), use cloud mode for reading events: CalDAV filters server-side and is fast at any scale.
+`list-events` in local mode no longer scripts Calendar.app when it can avoid it. It reads the date window straight from EventKit, the macOS calendar store, in one query that returns in about a tenth of a second even with dozens of subscribed calendars. EventKit needs its own permission, separate from Automation: the first `list-events` call asks the program that launches the server (Claude Desktop, your terminal, or your editor) for access to your calendars. Approve it once, or grant it later under **System Settings → Privacy & Security → Calendars**.
+
+If that access is denied, restricted or left unanswered, `list-events` falls back to the old Calendar.app query and logs `EventKit unavailable` on stderr. That path still filters the window inside Calendar.app with a `whose` query, but on accounts with many calendars, especially subscribed ones carrying years of events (holidays, sports fixtures, travel feeds), it can exceed any reasonable timeout. In that case grant Calendars access, or use cloud mode, where CalDAV filters server-side (see [#11](https://github.com/MrGo2/icloud-mcp/issues/11)).
+
+Through EventKit, a recurring event appears once per occurrence in the window, and every occurrence carries the series id. Passing that id to `update-event` or `delete-event` in local mode changes or deletes the whole series.
 
 ### App-specific password (cloud mode)
 

package/calendar/index.js

@@ -209,7 +209,7 @@ const calendarTools = [
   {
     name: 'update-event',
     title: 'Update Event',
-    description: 'Updates an existing calendar event. Only the fields you pass are changed. In cloud mode the CalDAV property-merge preserves recurrence, invitees and alarms (experimental: the live round-trip is not yet verified).',
+    description: 'Updates an existing calendar event. Only the fields you pass are changed. In cloud mode the CalDAV property-merge preserves recurrence, invitees and alarms (experimental: the live round-trip is not yet verified). In local mode, every occurrence of a recurring event shares the series UID, so this acts on the whole series, not one occurrence.',
     inputSchema: {
       eventUrl: z.string().describe('Event handle from list-events: the URL in cloud mode, the UID in local mode'),
       summary: z.string().optional().describe('New event title (optional)'),
@@ -224,7 +224,7 @@ const calendarTools = [
   {
     name: 'delete-event',
     title: 'Delete Event',
-    description: 'Deletes a calendar event',
+    description: 'Deletes a calendar event. In local mode, every occurrence of a recurring event shares the series UID, so this acts on the whole series, not one occurrence.',
     inputSchema: {
       eventUrl: z.string().describe('Event handle from list-events: the URL in cloud mode, the UID in local mode')
     },

package/calendar/local-client.js

@@ -6,8 +6,19 @@
 const { runAppleScript, runJXA, escapeAppleScript, escapeJXA, asInt, appleScriptDateStmts } = require('../utils/applescript');
 const config = require('../config');
 
+// EKAuthorizationStatus: 0 notDetermined, 1 restricted, 2 denied, 3 fullAccess, 4 writeOnly
+const EK_FULL_ACCESS = 3;
+// How long to wait for the user to answer the Calendars permission prompt.
+// The completion block never fires inside osascript, so the status is polled.
+const EK_REQUEST_TIMEOUT_SECONDS = 25;
+// Ask for access at most once per server process: a host that never shows the
+// prompt would otherwise pay the full timeout on every call.
+let eventKitRequested = false;
+
 /**
- * List upcoming events from every calendar
+ * List upcoming events from every calendar.
+ * Uses EventKit (fast, one store query) when the host has full Calendars
+ * access; otherwise falls back to scripting Calendar.app.
  * @param {number} count - Number of events to retrieve
  * @param {number} daysAhead - Number of days to look ahead
  * @returns {Promise<Array>} - List of events
@@ -16,6 +27,93 @@ async function listEvents(count = 25, daysAhead = 30) {
   const now = new Date();
   const future = new Date(now.getTime() + asInt(daysAhead, 30) * 24 * 60 * 60 * 1000);
 
+  let status;
+  try {
+    const result = JSON.parse(await runJXA(eventKitScript(now, future, !eventKitRequested)));
+    status = result.status;
+    if (result.requested) eventKitRequested = true;
+    if (status === EK_FULL_ACCESS && Array.isArray(result.events)) {
+      return sortAndSlice(result.events, count);
+    }
+  } catch (error) {
+    status = 'error: ' + error.message;
+  }
+
+  console.error(`[icloud-mcp] list-events: EventKit unavailable (status ${status}), using Calendar.app`);
+  return listEventsAppleScript(count, now, future);
+}
+
+/**
+ * JXA that reads the window from EventKit. Occurrences of recurring events
+ * are expanded; each carries its series' calendarItemIdentifier, which is
+ * the Calendar.app `uid` that update-event and delete-event resolve.
+ */
+function eventKitScript(now, future, request) {
+  return `
+    ObjC.import('EventKit');
+    ObjC.import('Foundation');
+    const T = $.EKEntityTypeEvent;
+    const store = $.EKEventStore.alloc.init;
+    const readStatus = () => Number($.EKEventStore.authorizationStatusForEntityType(T));
+    let status = readStatus();
+    let requested = false;
+
+    if (${request ? 'true' : 'false'} && (status === 0 || status === 4)) {
+      requested = true;
+      if (store.respondsToSelector('requestFullAccessToEventsWithCompletion:')) {
+        store.requestFullAccessToEventsWithCompletion((granted, err) => {});
+      } else {
+        store.requestAccessToEntityTypeCompletion(T, (granted, err) => {});
+      }
+      const deadline = Date.now() + ${asInt(EK_REQUEST_TIMEOUT_SECONDS, 25)} * 1000;
+      while (status !== 3 && Date.now() < deadline) {
+        $.NSRunLoop.currentRunLoop.runUntilDate($.NSDate.dateWithTimeIntervalSinceNow(0.2));
+        status = readStatus();
+        if (status === 1 || status === 2) break;
+      }
+    }
+
+    let events = null;
+    if (status === 3) {
+      const rangeStart = new Date(${JSON.stringify(now.toISOString())});
+      const rangeEnd = new Date(${JSON.stringify(future.toISOString())});
+      const nsDate = (d) => $.NSDate.dateWithTimeIntervalSince1970(d.getTime() / 1000);
+      const toDate = (ns) => ns && !ns.isNil() ? new Date(Number(ns.timeIntervalSince1970) * 1000) : null;
+      const pred = store.predicateForEventsWithStartDateEndDateCalendars(nsDate(rangeStart), nsDate(rangeEnd), $());
+      const evs = store.eventsMatchingPredicate(pred);
+      events = [];
+      for (let i = 0; i < evs.count; i++) {
+        const ev = evs.objectAtIndex(i);
+        const start = toDate(ev.startDate);
+        // Same window as the Calendar.app path: events starting inside it.
+        if (!start || start < rangeStart || start > rangeEnd) continue;
+        const end = toDate(ev.endDate);
+        events.push({
+          id: ObjC.unwrap(ev.calendarItemIdentifier),
+          summary: ObjC.unwrap(ev.title) || '',
+          startDate: start.toISOString(),
+          endDate: end ? end.toISOString() : null,
+          location: ObjC.unwrap(ev.location) || '',
+          calendar: ObjC.unwrap(ev.calendar.title)
+        });
+      }
+    }
+
+    JSON.stringify({ status, requested, events });
+  `;
+}
+
+function sortAndSlice(events, count) {
+  events.sort((a, b) => new Date(a.startDate) - new Date(b.startDate));
+  return events.slice(0, asInt(count, 25));
+}
+
+/**
+ * Calendar.app path: used when EventKit access is not granted.
+ * Slow on accounts with many or subscribed calendars.
+ */
+async function listEventsAppleScript(count, now, future) {
+
   // Batch property access: per-event JXA calls trigger AppleEvent errors.
   // The window is filtered inside the script so a busy calendar cannot push
   // upcoming events out of the result set before we ever see them.
@@ -70,9 +168,7 @@ async function listEvents(count = 25, daysAhead = 30) {
   const result = await runJXA(script);
   if (!result) return [];
 
-  const events = JSON.parse(result);
-  events.sort((a, b) => new Date(a.startDate) - new Date(b.startDate));
-  return events.slice(0, asInt(count, 25));
+  return sortAndSlice(JSON.parse(result), count);
 }
 
 /**

package/messages/index.js

@@ -9,7 +9,7 @@ const localClient = require('./local-client');
 const { formatError, formatSuccess, withErrorHandler } = require('../utils/error-handler');
 const { listOutput, listResult } = require('../utils/schemas');
 const { isLocalMode } = require('../mode');
-const { execFileSync } = require('child_process');
+const { execFile } = require('child_process');
 const fs = require('fs');
 
 // Homebrew's prefix differs between Apple Silicon and Intel, and an MCP server
@@ -29,6 +29,9 @@ function resolveImsg() {
   return 'imsg';
 }
 
+// Chats scanned when `since` is set; listing 5,000 takes well under a second.
+const SINCE_FETCH_LIMIT = 5000;
+
 function requireLocalMode(toolName) {
   if (!isLocalMode()) {
     return formatError(new Error(`${toolName} is only available in LOCAL mode. Use set-mode to switch.`));
@@ -36,14 +39,29 @@ function requireLocalMode(toolName) {
   return null;
 }
 
-function runImsg(args) {
-  let output;
-  try {
-    output = execFileSync(resolveImsg(), args, {
-      timeout: 15000,
+// Async on purpose: a synchronous call blocks the whole server, so parallel
+// reads from a client queue behind each other until they time out (#17).
+function execImsg(args) {
+  return new Promise((resolve, reject) => {
+    execFile(resolveImsg(), args, {
+      timeout: 30000,
       encoding: 'utf-8',
-      stdio: ['pipe', 'pipe', 'pipe']
+      maxBuffer: 64 * 1024 * 1024
+    }, (error, stdout, stderr) => {
+      if (error) {
+        error.stderr = stderr;
+        reject(error);
+      } else {
+        resolve(stdout);
+      }
     });
+  });
+}
+
+async function runImsg(args) {
+  let output;
+  try {
+    output = await execImsg(args);
   } catch (error) {
     const detail = (error.stderr || error.message || '').toString();
     if (detail.includes('permissionDenied')) {
@@ -52,6 +70,9 @@ function runImsg(args) {
     if (error.code === 'ENOENT') {
       throw new Error('The imsg CLI was not found. Install it (brew install imsg) or set ICLOUD_MCP_IMSG_PATH.');
     }
+    if (error.killed) {
+      throw new Error('imsg timed out after 30s');
+    }
     throw new Error(detail.trim() || 'imsg failed');
   }
 
@@ -70,17 +91,26 @@ const messagesTools = [
     name: 'list-chats',
     outputSchema: listOutput('Recent conversations'),
     title: 'List Chats',
-    description: 'List recent iMessage/SMS conversations with contact names and last message preview',
+    description: 'List recent iMessage/SMS conversations, most recent first. Use `since` to get only the conversations active after a date (e.g. the last 7 days).',
     inputSchema: {
-      limit: z.number().int().min(1).max(200).optional().describe('Number of conversations to show (default 20)')
+      limit: z.number().int().min(1).max(1000).optional().describe('Maximum number of conversations to return (default 20)'),
+      since: z.string().refine(v => !Number.isNaN(Date.parse(v)), 'since must be an ISO 8601 date')
+        .optional().describe('Only conversations with a message at or after this date (ISO 8601, optional)')
     },
     annotations: {"readOnlyHint":true,"idempotentHint":true,"openWorldHint":false},
-    handler: withErrorHandler(async ({ limit = 20 }) => {
+    handler: withErrorHandler(async ({ limit = 20, since }) => {
       const modeError = requireLocalMode('list-chats');
       if (modeError) return modeError;
-      const result = runImsg(['chats', '--limit', String(limit), '--json']);
+      // imsg has no date filter, but returns chats newest first, so fetch a
+      // wide window and cut it at `since` here.
+      const fetchLimit = since ? Math.max(limit, SINCE_FETCH_LIMIT) : limit;
+      const result = await runImsg(['chats', '--limit', String(fetchLimit), '--json']);
       // imsg emits JSONL, and runImsg unwraps a single line to a bare object.
-      const chats = Array.isArray(result) ? result : (result ? [result] : []);
+      let chats = Array.isArray(result) ? result : (result ? [result] : []);
+      if (since) {
+        const cutoff = Date.parse(since);
+        chats = chats.filter(c => Date.parse(c.last_message_at) >= cutoff).slice(0, limit);
+      }
       return formatSuccess(JSON.stringify(chats, null, 2), listResult(chats));
     }, 'list-chats')
   },
@@ -103,7 +133,7 @@ const messagesTools = [
       if (start) args.push('--start', start);
       if (end) args.push('--end', end);
       if (attachments) args.push('--attachments');
-      const result = runImsg(args);
+      const result = await runImsg(args);
       return formatSuccess(JSON.stringify(result, null, 2));
     }, 'read-messages')
   },
@@ -128,7 +158,7 @@ const messagesTools = [
         try {
           const args = ['send', '--to', to, '--text', body];
           if (file) args.push('--file', file);
-          const result = runImsg(args);
+          const result = await runImsg(args);
           return formatSuccess(JSON.stringify(result, null, 2));
         } catch (e) {
           throw new Error(`${error.message} (imsg fallback also failed: ${e.message})`);
@@ -148,7 +178,7 @@ const messagesTools = [
     handler: withErrorHandler(async ({ chatId, type }) => {
       const modeError = requireLocalMode('react-message');
       if (modeError) return modeError;
-      const result = runImsg(['react', '--chat-id', String(chatId), '--type', type]);
+      const result = await runImsg(['react', '--chat-id', String(chatId), '--type', type]);
       return formatSuccess(JSON.stringify(result, null, 2));
     }, 'react-message')
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-icloud",
   "mcpName": "io.github.MrGo2/icloud-mcp",
-  "version": "2.1.4",
+  "version": "2.2.0",
   "description": "MCP server for Apple services - Email, Calendar, Contacts, Reminders, Notes, Messages and Safari - with dual local (AppleScript) and cloud (IMAP/CalDAV/CardDAV) modes",
   "main": "index.js",
   "bin": {
@@ -27,7 +27,7 @@
   ],
   "scripts": {
     "start": "node index.js",
-    "test": "node test/security.test.js && node test/local-output.test.js && node test/email-read.test.js",
+    "test": "node test/security.test.js && node test/local-output.test.js && node test/email-read.test.js && node test/messages.test.js && node test/calendar-eventkit.test.js",
     "test-mode": "USE_TEST_MODE=true node index.js",
     "inspect": "npx @modelcontextprotocol/inspector node index.js",
     "test:local": "node test/local-output.test.js"