apple-tools-mcp 3.4.1 → 3.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -141,7 +141,7 @@ apple-tools-indexer
141
141
 
142
142
  That command is `node index.js --mode=indexer`. A global install provides `apple-tools-indexer` (`bin/apple-tools-indexer.js`). From a clone, use `npm run indexer`.
143
143
 
144
- To keep it running across logins, use a LaunchAgent. LaunchAgents do not see your shell `PATH`, so put in the absolute paths from `which node` and `npm root -g`.
144
+ To keep it running across logins, use a LaunchAgent. LaunchAgents do not see your shell `PATH`, so put in the absolute paths from `which node` and `npm root -g`. Start it through `node` with the package script as an argument (as below, or `examples/com.apple-tools-indexer.plist`), never the `apple-tools-indexer` bin as the first program: macOS tracks a LaunchAgent by that first file, and every `npm install -g` rewrites the bin, which posts another "App Background Activity ... can run in the background" notice.
145
145
 
146
146
  Save this as `~/Library/LaunchAgents/com.apple-tools-mcp.indexer.plist` and replace both paths:
147
147
 
@@ -210,7 +210,7 @@ apple-tools-mcp http-token
210
210
 
211
211
  Under a secrets manager's runtime injection (for example `infisical run -- apple-tools-http`), set `APPLE_TOOLS_HTTP_TOKEN` and the server uses it instead of Keychain, which it then neither reads nor writes. To rotate without cutting off clients, start the server with the new token in `APPLE_TOOLS_HTTP_TOKEN` and the old one in `APPLE_TOOLS_HTTP_TOKEN_PREVIOUS`; once every client has the new token, restart without `APPLE_TOOLS_HTTP_TOKEN_PREVIOUS` and the old token stops working.
212
212
 
213
- The HTTP server never indexes and never takes `indexer.lock`: it serves the index the indexer daemon keeps fresh, so run the indexer too. It also refuses `rebuild_index`; rebuild from a stdio client or as described under the index rebuild below. Restarting either one in any order is safe.
213
+ The HTTP server never indexes and never takes `indexer.lock`: it serves the index the indexer daemon keeps fresh, so run the indexer too. It also refuses `rebuild_index`; rebuild from a stdio client or as described under the index rebuild below. Restarting either one in any order is safe. When the last finished index pass (`lastIndexPassTime` in `index-meta.json`) is older than three refresh intervals (at least 15 minutes), every index-backed reply starts with a note giving its age, so a stopped indexer shows up instead of serving a stale index silently.
214
214
 
215
215
  An example LaunchAgent is `examples/com.apple-tools-http.plist`. How to point Claude and other clients at it, including `apple-tools-http-proxy`, is in `examples/mcp-client.md`.
216
216
 
@@ -303,7 +303,7 @@ Your client can also call `audit_index`.
303
303
  | `calendar_free_time` | Open time on a date, read live from Calendar rather than the search index. |
304
304
  | `calendar_recurring` | Recurring events with their next occurrence, counting today's. |
305
305
 
306
- Calendar tools print links in event titles and locations without their query string or fragment (`https://zoom.us/j/123?pwd=...` prints as `https://zoom.us/j/123`), so a meeting passcode never reaches a chat that reads the calendar.
306
+ Calendar tools print links in event titles, locations and notes without their query string or fragment (`https://zoom.us/j/123?pwd=...` prints as `https://zoom.us/j/123`), and hide the value after a passcode label (`Passcode: [hidden]`, also `password`, `pwd`, `PIN`) and the passcode in a one-tap dial string (`,,,,*[hidden]#`), so a meeting passcode never reaches a chat that reads the calendar.
307
307
 
308
308
  ### Contacts
309
309
 
@@ -0,0 +1,44 @@
1
+ <?xml version="1.0" encoding="UTF-8"?>
2
+ <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
3
+ <!--
4
+ Always-on indexer (RunAtLoad + KeepAlive). Replace REPLACE_ME_WITH_NODE_BIN_DIR with
5
+ the directory of the node that runs it (for example ~/.local/node/bin) and
6
+ REPLACE_ME_WITH_PACKAGE_PATH with the global install (`npm root -g`/apple-tools-mcp).
7
+ The first program is node, never the npm bin symlink or the package script: macOS
8
+ Background Task Management tracks an agent by its first program, and an `npm install -g`
9
+ rewrites the bin, which would post another "App Background Activity" notice each upgrade.
10
+ Restart it with `launchctl kill TERM gui/$(id -u)/<label>`; a changed plist needs a
11
+ bootout and bootstrap.
12
+ -->
13
+ <plist version="1.0">
14
+ <dict>
15
+ <key>Label</key>
16
+ <string>com.REPLACE_ME.apple-tools-indexer</string>
17
+ <key>ProgramArguments</key>
18
+ <array>
19
+ <string>REPLACE_ME_WITH_NODE_BIN_DIR/node</string>
20
+ <string>REPLACE_ME_WITH_PACKAGE_PATH/bin/apple-tools-indexer.js</string>
21
+ </array>
22
+ <key>RunAtLoad</key>
23
+ <true/>
24
+ <key>KeepAlive</key>
25
+ <true/>
26
+ <key>ProcessType</key>
27
+ <string>Background</string>
28
+ <key>WorkingDirectory</key>
29
+ <string>/Users/REPLACE_ME</string>
30
+ <key>EnvironmentVariables</key>
31
+ <dict>
32
+ <key>PATH</key>
33
+ <string>REPLACE_ME_WITH_NODE_BIN_DIR:/usr/bin:/bin:/usr/sbin:/sbin</string>
34
+ <key>NODE_OPTIONS</key>
35
+ <string>--max-old-space-size=4096</string>
36
+ <key>HOME</key>
37
+ <string>/Users/REPLACE_ME</string>
38
+ </dict>
39
+ <key>StandardOutPath</key>
40
+ <string>/Users/REPLACE_ME/Library/Logs/apple-tools-indexer.out.log</string>
41
+ <key>StandardErrorPath</key>
42
+ <string>/Users/REPLACE_ME/Library/Logs/apple-tools-indexer.err.log</string>
43
+ </dict>
44
+ </plist>
package/index.js CHANGED
@@ -11,7 +11,7 @@ import http from "http";
11
11
  import fs from "fs";
12
12
  import path from "path";
13
13
  import { validateEmailPath, stripHtmlTags, unfoldRfc822Headers, validateLimit, validateDaysBack, validateWeekOffset, toUnixMillis } from "./lib/validators.js";
14
- import { cycleEndFlags, indexUnavailableMessage, indexQueryGate } from "./lib/indexGate.js";
14
+ import { cycleEndFlags, indexUnavailableMessage, indexQueryGate, staleIndexNote } from "./lib/indexGate.js";
15
15
  import { isIndexerMode, isPermissionsMode, isHttpMode, isHttpTokenMode } from "./lib/processMode.js";
16
16
  import { runPermissionsCommand } from "./lib/permissions.js";
17
17
  import { loadResolvedIndexInterval, logResolvedInterval, resolveHttpServerConfig } from "./lib/config.js";
@@ -42,7 +42,7 @@ import { closeEventKitSession, ensureEventKitSession } from "./lib/eventKitSessi
42
42
  import { EVENTKIT_JXA_HELPERS } from "./lib/calendarWrite.js";
43
43
  import { mailFind, MAILBOX_KINDS, MAIL_FIND_MAX_LIMIT } from "./lib/mailFind.js";
44
44
  import { mailLinks } from "./lib/mailLinks.js";
45
- import { stripUrlQueries } from "./lib/urlQuery.js";
45
+ import { hideMeetingSecrets } from "./lib/urlQuery.js";
46
46
 
47
47
  const PACKAGE_VERSION = JSON.parse(
48
48
  fs.readFileSync(new URL("./package.json", import.meta.url), "utf8")
@@ -199,7 +199,8 @@ import {
199
199
  loadContacts,
200
200
  searchContacts,
201
201
  lookupContact,
202
- getContactIdentifiers
202
+ getContactIdentifiers,
203
+ getLastIndexPassTime
203
204
  } from "./indexer.js";
204
205
  import {
205
206
  searchEmails,
@@ -408,6 +409,33 @@ async function requireIndex(type) {
408
409
  return gate.ok ? null : gate.message;
409
410
  }
410
411
 
412
+ // Tools that answer from the shared vector index. Their replies get a note
413
+ // when the index has not finished a pass in several intervals (indexer down).
414
+ const INDEX_BACKED_TOOLS = new Set([
415
+ "smart_search",
416
+ "person_search",
417
+ "mail_search",
418
+ "mail_recent",
419
+ "mail_date",
420
+ "mail_senders",
421
+ "mail_thread",
422
+ "messages_search",
423
+ "messages_recent",
424
+ "messages_conversation",
425
+ "calendar_search"
426
+ ]);
427
+
428
+ function withStaleIndexNote(toolName, text) {
429
+ if (!INDEX_BACKED_TOOLS.has(toolName) || typeof text !== "string") return text;
430
+ let note = null;
431
+ try {
432
+ note = staleIndexNote({ lastPassTime: getLastIndexPassTime(), intervalMs: INDEX_INTERVAL });
433
+ } catch (e) {
434
+ console.error(`Could not read index freshness: ${e.message}`);
435
+ }
436
+ return note ? `${note}\n\n${text}` : text;
437
+ }
438
+
411
439
  function waitForLockAndStartDaemon() {
412
440
  waitForIndexerLock(acquireLock, {
413
441
  retryMs: LOCK_RETRY_MS,
@@ -679,7 +707,7 @@ function formatSmartSearchResults(results, synthesizedGroups = null) {
679
707
  for (const group of synthesizedGroups.slice(0, 5)) {
680
708
  sections.push(`📅 ${group.timeWindow} (${group.totalItems} items)`);
681
709
  if (group.calendar.length > 0) {
682
- sections.push(` Calendar: ${group.calendar.map(c => stripUrlQueries(c.title)).join(', ')}`);
710
+ sections.push(` Calendar: ${group.calendar.map(c => hideMeetingSecrets(c.title)).join(', ')}`);
683
711
  }
684
712
  if (group.mail.length > 0) {
685
713
  sections.push(` Emails: ${group.mail.map(m => m.subject).join(', ')}`);
@@ -719,10 +747,10 @@ function formatSmartSearchResults(results, synthesizedGroups = null) {
719
747
  sections.push("📅 CALENDAR:");
720
748
  for (const r of results.calendar.results) {
721
749
  sections.push(` [${r.rank}] Score: ${r.score}`);
722
- sections.push(` Event: ${stripUrlQueries(r.title)}${r.isAllDay ? ' (All Day)' : ''}`);
750
+ sections.push(` Event: ${hideMeetingSecrets(r.title)}${r.isAllDay ? ' (All Day)' : ''}`);
723
751
  sections.push(` Start: ${r.start}`);
724
752
  sections.push(` Calendar: ${r.calendar}`);
725
- if (r.location) sections.push(` Location: ${stripUrlQueries(r.location)}`);
753
+ if (r.location) sections.push(` Location: ${hideMeetingSecrets(r.location)}`);
726
754
  }
727
755
  sections.push("");
728
756
  }
@@ -1061,7 +1089,7 @@ function formatPersonSearchResults(results) {
1061
1089
  if (results.calendar && results.calendar.results && results.calendar.results.length > 0) {
1062
1090
  sections.push(`📅 CALENDAR (${results.calendar.results.length}):`);
1063
1091
  for (const r of results.calendar.results.slice(0, 10)) {
1064
- sections.push(` • ${stripUrlQueries(r.title)}`);
1092
+ sections.push(` • ${hideMeetingSecrets(r.title)}`);
1065
1093
  sections.push(` ${r.start} | ${r.calendar}`);
1066
1094
  }
1067
1095
  sections.push("");
@@ -1673,7 +1701,7 @@ function createServer() {
1673
1701
  throw new Error(`Unknown tool: ${name}`);
1674
1702
  }
1675
1703
 
1676
- return { content: [{ type: "text", text: result }] };
1704
+ return { content: [{ type: "text", text: withStaleIndexNote(name, result) }] };
1677
1705
  } catch (error) {
1678
1706
  return {
1679
1707
  content: [{ type: "text", text: `Error: ${error.message}` }],
package/indexer.js CHANGED
@@ -1725,6 +1725,10 @@ export async function indexAll(progressCallback = null) {
1725
1725
 
1726
1726
  await maybeOptimizeIndex({ emails: emailResult, messages: messageResult, calendar: calendarResult });
1727
1727
 
1728
+ // Readers of the shared index (the HTTP server, lost-lock stdio clients)
1729
+ // use this to say when the index has stopped refreshing.
1730
+ saveIndexMeta({ ...loadIndexMeta(), lastIndexPassTime: Date.now() });
1731
+
1728
1732
  console.error("Full index complete.");
1729
1733
  return { emails: emailResult, messages: messageResult, calendar: calendarResult };
1730
1734
  }
@@ -1754,6 +1758,15 @@ async function maybeOptimizeIndex(results) {
1754
1758
  return result;
1755
1759
  }
1756
1760
 
1761
+ /**
1762
+ * When the last full index pass (emails, messages, calendar) finished, from
1763
+ * index-meta.json; null when no pass has recorded one yet.
1764
+ */
1765
+ export function getLastIndexPassTime() {
1766
+ const t = loadIndexMeta().lastIndexPassTime;
1767
+ return Number.isFinite(t) && t > 0 ? t : null;
1768
+ }
1769
+
1757
1770
  export async function isIndexReady(type = "emails") {
1758
1771
  await initDB();
1759
1772
  return tables[type] != null;
package/lib/indexGate.js CHANGED
@@ -106,3 +106,37 @@ export function indexQueryGate({
106
106
  }
107
107
  return { ok: true, message: null };
108
108
  }
109
+
110
+ /** A shared index older than this many refresh intervals gets a note. */
111
+ export const STALE_INDEX_INTERVALS = 3;
112
+ /** Never call the index stale sooner than this, whatever the interval. */
113
+ export const STALE_INDEX_FLOOR_MS = 15 * 60 * 1000;
114
+
115
+ function describeAge(ms) {
116
+ const minutes = Math.floor(ms / 60000);
117
+ if (minutes < 60) return `${minutes} min`;
118
+ const hours = Math.floor(minutes / 60);
119
+ if (hours < 48) {
120
+ const rest = minutes % 60;
121
+ return rest ? `${hours} h ${rest} min` : `${hours} h`;
122
+ }
123
+ return `${Math.floor(hours / 24)} days`;
124
+ }
125
+
126
+ /**
127
+ * Note for an index-backed reply when the shared index has not finished a pass
128
+ * in a while. The HTTP server never indexes (3.4.1), so with the indexer daemon
129
+ * down it would otherwise serve a stale index silently.
130
+ *
131
+ * @param {{ lastPassTime: number|null|undefined, now?: number, intervalMs: number }} args
132
+ * @returns {string|null} null when fresh or when no pass time is known
133
+ */
134
+ export function staleIndexNote({ lastPassTime, now = Date.now(), intervalMs }) {
135
+ if (!Number.isFinite(lastPassTime) || lastPassTime <= 0) return null;
136
+ const limit = Math.max(STALE_INDEX_INTERVALS * (Number(intervalMs) || 0), STALE_INDEX_FLOOR_MS);
137
+ const age = now - lastPassTime;
138
+ if (age <= limit) return null;
139
+ return `Note: the search index last finished a refresh ${describeAge(age)} ago ` +
140
+ `(${new Date(lastPassTime).toISOString()}), so mail, messages and events since then may be missing. ` +
141
+ `The indexer daemon (apple-tools-indexer) may be down.`;
142
+ }
package/lib/urlQuery.js CHANGED
@@ -12,3 +12,28 @@ export function stripUrlQueries(text) {
12
12
  if (typeof text !== "string" || !text) return text;
13
13
  return text.replace(URL_WITH_QUERY, (_, url, query) => url + (query.match(/[)\]]+$/) || [""])[0]);
14
14
  }
15
+
16
+ // Invite notes also carry passcodes as plain lines ("Passcode: 123456",
17
+ // "Meeting password: abc", "PIN: 123 456 789#", "Passcode 123456") and inside one-tap dial
18
+ // strings ("+15550100,,1000000001#,,,,*123456#"). The value after a passcode
19
+ // label is hidden to the end of its line; a dial string keeps its digits up to
20
+ // the passcode and hides the passcode itself.
21
+ const PASSCODE_LABEL = /\b((?:numeric\s+)?(?:meeting\s+)?(?:passcode|pass\s?code|password|pwd)\b\s*(?:[:=#]|is\b)\s*|\bpin\b\s*[:=#]\s*)[^\n]*/gi;
22
+ // "Passcode 123456" with no separator: only a following token with a digit.
23
+ const PASSCODE_BARE = /\b((?:meeting\s+)?(?:passcode|pass\s?code|password)\s+)(?=[^\s:=#]*\d)[^\s:=#]+/gi;
24
+ // Bounded comma run: an unbounded ,{2,} is quadratic on a long run of commas.
25
+ const DIAL_PASSCODE = /(,{2,12}\*)\d{1,20}#/g;
26
+ const HIDDEN = "[hidden]";
27
+
28
+ export function maskPasscodes(text) {
29
+ if (typeof text !== "string" || !text) return text;
30
+ return text
31
+ .replace(PASSCODE_LABEL, (_, label) => label + HIDDEN)
32
+ .replace(PASSCODE_BARE, (_, label) => label + HIDDEN)
33
+ .replace(DIAL_PASSCODE, (_, lead) => `${lead}${HIDDEN}#`);
34
+ }
35
+
36
+ /** URLs without their query strings, and passcode values hidden. */
37
+ export function hideMeetingSecrets(text) {
38
+ return maskPasscodes(stripUrlQueries(text));
39
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "apple-tools-mcp",
3
- "version": "3.4.1",
3
+ "version": "3.4.2",
4
4
  "description": "MCP server for semantic search and write actions across Apple Mail, Messages, Calendar, and Contacts. Speaks stdio (local) or bearer-token-authenticated Streamable HTTP (LAN / Tailscale).",
5
5
  "type": "module",
6
6
  "main": "index.js",
package/search.js CHANGED
@@ -4,7 +4,7 @@ import { safeMatch, validateSearchQuery, toUnixMillis } from "./lib/validators.j
4
4
  import { embed, getOpenTable, getRecentEmails, getEmailsByDateRange, getRecentMessages, getConversation, getEventsOnDate, resolveEmail, resolvePhone, resolveByExactName, normalizePhone, formatContact } from "./indexer.js";
5
5
  import { createMessageContactMatcher, describeMessagePeer } from "./lib/messageContact.js";
6
6
  import { indexUnavailableMessage } from "./lib/indexGate.js";
7
- import { stripUrlQueries } from "./lib/urlQuery.js";
7
+ import { hideMeetingSecrets } from "./lib/urlQuery.js";
8
8
 
9
9
  // ============ CACHING ============
10
10
 
@@ -1525,17 +1525,18 @@ export function formatCalendarResults(searchResult) {
1525
1525
  const results = searchResult.results.map(r => {
1526
1526
  let result = `[${r.rank || r.index}]`;
1527
1527
  if (r.score) result += ` Score: ${r.score}`;
1528
- // Meeting-link passcodes ride in URL query strings: titles and locations print URLs without them.
1529
- result += `\nEvent: ${stripUrlQueries(r.title)}`;
1528
+ // Meeting-link passcodes ride in URL query strings and "Passcode:" lines: titles, locations
1529
+ // and notes print URLs without queries and passcode values hidden.
1530
+ result += `\nEvent: ${hideMeetingSecrets(r.title)}`;
1530
1531
  if (r.isAllDay) result += " (All Day)";
1531
1532
  result += `\nCalendar: ${r.calendar}\nStart: ${r.start}\nEnd: ${r.end}`;
1532
1533
  if (r.eventId) result += `\nEvent ID: ${r.eventId}`;
1533
- if (r.location) result += `\nLocation: ${stripUrlQueries(r.location)}`;
1534
+ if (r.location) result += `\nLocation: ${hideMeetingSecrets(r.location)}`;
1534
1535
  if (r.attendees && r.attendees.length > 0) {
1535
1536
  const attendeeList = r.attendees.map(a => `${a.name} (${a.status})`).join(", ");
1536
1537
  result += `\nAttendees: ${attendeeList}`;
1537
1538
  }
1538
- if (r.notes) result += `\nNotes: ${r.notes}`;
1539
+ if (r.notes) result += `\nNotes: ${hideMeetingSecrets(r.notes)}`;
1539
1540
  return result + "\n---";
1540
1541
  }).join("\n");
1541
1542
 
@@ -1628,10 +1629,10 @@ export function formatUpcomingEventsResults(result) {
1628
1629
  let output = "";
1629
1630
  for (let i = 0; i < events.length; i++) {
1630
1631
  const e = events[i];
1631
- output += `${i + 1}. ${stripUrlQueries(e.title) || "No title"}${e.isAllDay ? " (All Day)" : ""}\n`;
1632
+ output += `${i + 1}. ${hideMeetingSecrets(e.title) || "No title"}${e.isAllDay ? " (All Day)" : ""}\n`;
1632
1633
  output += ` ${e.start}${e.isAllDay ? "" : ` - ${e.end}`}\n`;
1633
1634
  output += ` Calendar: ${e.calendar || "Unknown"}`;
1634
- if (e.location) output += ` | Location: ${stripUrlQueries(e.location)}`;
1635
+ if (e.location) output += ` | Location: ${hideMeetingSecrets(e.location)}`;
1635
1636
  output += "\n\n";
1636
1637
  }
1637
1638
 
@@ -1674,7 +1675,7 @@ export function formatWeekEventsResults(result) {
1674
1675
  output += `${day}:\n`;
1675
1676
  for (const e of dayEvents) {
1676
1677
  const time = e.isAllDay ? "All Day" : e.start.split(" ")[1];
1677
- output += ` • ${time} - ${stripUrlQueries(e.title) || "No title"}`;
1678
+ output += ` • ${time} - ${hideMeetingSecrets(e.title) || "No title"}`;
1678
1679
  if (e.calendar) output += ` [${e.calendar}]`;
1679
1680
  output += "\n";
1680
1681
  }
@@ -1725,7 +1726,7 @@ export function formatRecurringEventsResults(result) {
1725
1726
 
1726
1727
  let output = "";
1727
1728
  for (const e of events) {
1728
- output += ` • ${stripUrlQueries(e.title) || "No title"}${e.isAllDay ? " (All Day)" : ""}\n`;
1729
+ output += ` • ${hideMeetingSecrets(e.title) || "No title"}${e.isAllDay ? " (All Day)" : ""}\n`;
1729
1730
  output += ` Next: ${e.start} | Calendar: ${e.calendar || "Unknown"}\n`;
1730
1731
  output += ` Occurrences: ${e.occurrenceCount}\n\n`;
1731
1732
  }