apple-tools-mcp 3.4.2 → 3.4.3

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
@@ -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. 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.
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. The note says why from `indexer.lock`: a live indexer that keeps checking in is still refreshing (a rebuild, a long first pass, or catching up after the Mac slept), one that stopped checking in may be stuck, and with no live holder the indexer may be down. A clean `rebuild_index` of all three sources counts as a finished pass.
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, 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.
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`, `PIN is`, Webex `Host key` and `Access code`, with a plain or full-width colon) 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
 
package/index.js CHANGED
@@ -17,7 +17,7 @@ import { runPermissionsCommand } from "./lib/permissions.js";
17
17
  import { loadResolvedIndexInterval, logResolvedInterval, resolveHttpServerConfig } from "./lib/config.js";
18
18
  import { acceptedHttpAuthTokens, loadOrCreateHttpAuthToken, verifyAuthHeader } from "./lib/httpAuth.js";
19
19
  import { createHttpRequestHandler } from "./lib/httpTransport.js";
20
- import { createIndexerLock, DEFAULT_LOCK_HEARTBEAT_MS } from "./lib/indexerLock.js";
20
+ import { createIndexerLock, DEFAULT_LOCK_HEARTBEAT_MS, readIndexerLockHolder } from "./lib/indexerLock.js";
21
21
  import {
22
22
  shouldConnectMcpStdio,
23
23
  bindStdinCloseExit,
@@ -410,7 +410,8 @@ async function requireIndex(type) {
410
410
  }
411
411
 
412
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).
413
+ // when the index has not finished a pass in several intervals, worded by
414
+ // whether the indexer.lock holder is alive (still refreshing, stuck, or down).
414
415
  const INDEX_BACKED_TOOLS = new Set([
415
416
  "smart_search",
416
417
  "person_search",
@@ -429,7 +430,11 @@ function withStaleIndexNote(toolName, text) {
429
430
  if (!INDEX_BACKED_TOOLS.has(toolName) || typeof text !== "string") return text;
430
431
  let note = null;
431
432
  try {
432
- note = staleIndexNote({ lastPassTime: getLastIndexPassTime(), intervalMs: INDEX_INTERVAL });
433
+ note = staleIndexNote({
434
+ lastPassTime: getLastIndexPassTime(),
435
+ intervalMs: INDEX_INTERVAL,
436
+ readHolder: () => readIndexerLockHolder({ lockFile: LOCK_FILE })
437
+ });
433
438
  } catch (e) {
434
439
  console.error(`Could not read index freshness: ${e.message}`);
435
440
  }
package/indexer.js CHANGED
@@ -1056,9 +1056,31 @@ export async function rebuildIndex(sources = ["emails", "messages", "calendar"],
1056
1056
  }
1057
1057
  }
1058
1058
 
1059
+ // A full clean rebuild is a finished pass over all three sources, like
1060
+ // indexAll; a partial one leaves the other sources as old as they were.
1061
+ if (isFullIndexPass(sources, results.errors)) {
1062
+ try {
1063
+ recordIndexPassTime();
1064
+ } catch (e) {
1065
+ console.error(`Could not record the index pass time: ${e.message}`);
1066
+ }
1067
+ }
1068
+
1059
1069
  return results;
1060
1070
  }
1061
1071
 
1072
+ /** True when a pass covered emails, messages and calendar with no error. */
1073
+ export function isFullIndexPass(sources, errors = []) {
1074
+ const covered = new Set(Array.isArray(sources) ? sources : []);
1075
+ return INDEX_TABLE_NAMES.every((s) => covered.has(s)) && errors.length === 0;
1076
+ }
1077
+
1078
+ // Readers of the shared index (the HTTP server, lost-lock stdio clients)
1079
+ // use this to say when the index has stopped refreshing.
1080
+ function recordIndexPassTime() {
1081
+ saveIndexMeta({ ...loadIndexMeta(), lastIndexPassTime: Date.now() });
1082
+ }
1083
+
1062
1084
  async function getIndexedIds(tableName, idField) {
1063
1085
  await initDB();
1064
1086
  if (!tables[tableName]) return new Set();
@@ -1725,9 +1747,7 @@ export async function indexAll(progressCallback = null) {
1725
1747
 
1726
1748
  await maybeOptimizeIndex({ emails: emailResult, messages: messageResult, calendar: calendarResult });
1727
1749
 
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() });
1750
+ recordIndexPassTime();
1731
1751
 
1732
1752
  console.error("Full index complete.");
1733
1753
  return { emails: emailResult, messages: messageResult, calendar: calendarResult };
package/lib/audit.js CHANGED
@@ -14,6 +14,7 @@
14
14
  import fs from "fs";
15
15
  import path from "path";
16
16
  import { safeSqlite3Json, safeFind } from "./shell.js";
17
+ import { hideMeetingSecrets } from "./urlQuery.js";
17
18
  import * as lancedb from "@lancedb/lancedb";
18
19
  import { LANCE_CONNECT_OPTIONS, openMissingIndexTables } from "./lancedbTables.js";
19
20
 
@@ -807,7 +808,7 @@ export function formatAuditReport(results) {
807
808
  report += ` Date: ${item.date}\n`;
808
809
  } else if (dataType === "calendar") {
809
810
  report += `Event ID: ${item.id}\n`;
810
- report += ` Title: ${item.title}\n`;
811
+ report += ` Title: ${hideMeetingSecrets(item.title)}\n`;
811
812
  report += ` Start: ${item.start}\n`;
812
813
  }
813
814
  report += ` Reason: ${item.reason}\n\n`;
@@ -830,7 +831,7 @@ export function formatAuditReport(results) {
830
831
  report += ` Subject: ${item.subject}\n`;
831
832
  } else if (dataType === "calendar") {
832
833
  report += `Event ID: ${item.id}\n`;
833
- report += ` Title: ${item.title}\n`;
834
+ report += ` Title: ${hideMeetingSecrets(item.title)}\n`;
834
835
  }
835
836
  report += ` Reason: ${item.reason}\n\n`;
836
837
  });
@@ -854,7 +855,7 @@ export function formatAuditReport(results) {
854
855
  report += ` Sender: ${item.sender}\n\n`;
855
856
  } else if (dataType === "calendar") {
856
857
  report += `Event ID ${item.id} indexed ${item.count} times:\n`;
857
- report += ` Title: ${item.title}\n\n`;
858
+ report += ` Title: ${hideMeetingSecrets(item.title)}\n\n`;
858
859
  }
859
860
  });
860
861
  }
@@ -1007,7 +1008,7 @@ export function formatAuditReport(results) {
1007
1008
  report += ` Date: ${item.date}\n`;
1008
1009
  } else if (dataType === "calendar") {
1009
1010
  report += `Event ID: ${item.id}\n`;
1010
- report += ` Title: ${item.title}\n`;
1011
+ report += ` Title: ${hideMeetingSecrets(item.title)}\n`;
1011
1012
  report += ` Start: ${item.start}\n`;
1012
1013
  }
1013
1014
  report += ` Reason: ${item.reason}\n\n`;
@@ -1034,7 +1035,7 @@ export function formatAuditReport(results) {
1034
1035
  report += ` Text: ${item.text}\n`;
1035
1036
  } else if (dataType === "calendar") {
1036
1037
  report += `Event ID: ${item.id}\n`;
1037
- report += ` Title: ${item.title}\n`;
1038
+ report += ` Title: ${hideMeetingSecrets(item.title)}\n`;
1038
1039
  }
1039
1040
  report += ` Reason: ${item.reason}\n\n`;
1040
1041
  itemNumber++;
@@ -1062,7 +1063,7 @@ export function formatAuditReport(results) {
1062
1063
  report += ` Sender: ${item.sender}\n\n`;
1063
1064
  } else if (dataType === "calendar") {
1064
1065
  report += `Event ID ${item.id} indexed ${item.count} times:\n`;
1065
- report += ` Title: ${item.title}\n\n`;
1066
+ report += ` Title: ${hideMeetingSecrets(item.title)}\n\n`;
1066
1067
  }
1067
1068
  itemNumber++;
1068
1069
  });
package/lib/indexGate.js CHANGED
@@ -123,20 +123,53 @@ function describeAge(ms) {
123
123
  return `${Math.floor(hours / 24)} days`;
124
124
  }
125
125
 
126
+ /**
127
+ * Why the index is stale, from who holds indexer.lock (readIndexerLockHolder).
128
+ * A live holder that keeps checking in is still working: a rebuild, a long
129
+ * first pass, or catching up after the Mac slept.
130
+ *
131
+ * @param {{ state: string, pid: number, checkedInMsAgo: number } | null | undefined} holder
132
+ * @returns {string}
133
+ */
134
+ function staleCause(holder) {
135
+ if (holder?.state === "running") {
136
+ return `The indexer (PID ${holder.pid}) is running, so a refresh is likely still in progress: ` +
137
+ `a rebuild, a long first pass, or catching up after the Mac slept.`;
138
+ }
139
+ if (holder?.state === "stuck") {
140
+ return `The indexer (PID ${holder.pid}) holds the index lock but last checked in ` +
141
+ `${describeAge(holder.checkedInMsAgo)} ago, so it may be stuck.`;
142
+ }
143
+ return `The indexer daemon (apple-tools-indexer) may be down.`;
144
+ }
145
+
126
146
  /**
127
147
  * Note for an index-backed reply when the shared index has not finished a pass
128
148
  * in a while. The HTTP server never indexes (3.4.1), so with the indexer daemon
129
149
  * down it would otherwise serve a stale index silently.
130
150
  *
131
- * @param {{ lastPassTime: number|null|undefined, now?: number, intervalMs: number }} args
151
+ * @param {{
152
+ * lastPassTime: number|null|undefined,
153
+ * now?: number,
154
+ * intervalMs: number,
155
+ * readHolder?: () => ({ state: string, pid: number, checkedInMsAgo: number } | null)
156
+ * }} args readHolder runs only once the index is stale; a throw words the note as "may be down"
132
157
  * @returns {string|null} null when fresh or when no pass time is known
133
158
  */
134
- export function staleIndexNote({ lastPassTime, now = Date.now(), intervalMs }) {
159
+ export function staleIndexNote({ lastPassTime, now = Date.now(), intervalMs, readHolder }) {
135
160
  if (!Number.isFinite(lastPassTime) || lastPassTime <= 0) return null;
136
161
  const limit = Math.max(STALE_INDEX_INTERVALS * (Number(intervalMs) || 0), STALE_INDEX_FLOOR_MS);
137
162
  const age = now - lastPassTime;
138
163
  if (age <= limit) return null;
164
+ let holder = null;
165
+ if (typeof readHolder === "function") {
166
+ try {
167
+ holder = readHolder();
168
+ } catch {
169
+ holder = null;
170
+ }
171
+ }
139
172
  return `Note: the search index last finished a refresh ${describeAge(age)} ago ` +
140
173
  `(${new Date(lastPassTime).toISOString()}), so mail, messages and events since then may be missing. ` +
141
- `The indexer daemon (apple-tools-indexer) may be down.`;
174
+ staleCause(holder);
142
175
  }
@@ -86,6 +86,42 @@ export function formatLockData(pid, timestamp) {
86
86
  return `${pid}:${timestamp}`;
87
87
  }
88
88
 
89
+ /** A holder whose heartbeat is older than this has stopped checking in. */
90
+ export const LOCK_HOLDER_FRESH_MS = 5 * DEFAULT_LOCK_HEARTBEAT_MS;
91
+
92
+ /**
93
+ * Who holds indexer.lock, for readers that never take it (the HTTP server,
94
+ * lost-lock stdio clients). Read only: never writes or removes anything.
95
+ *
96
+ * @param {{
97
+ * lockFile: string,
98
+ * now?: number,
99
+ * isAlive?: (pid: number) => boolean,
100
+ * fsApi?: Pick<typeof fs, "readFileSync">,
101
+ * freshMs?: number
102
+ * }} options
103
+ * @returns {{ state: "running" | "stuck" | "dead", pid: number, checkedInMsAgo: number } | null}
104
+ * null when no lock file or unreadable contents
105
+ */
106
+ export function readIndexerLockHolder(options) {
107
+ const fsApi = options.fsApi || fs;
108
+ const isAlive = options.isAlive || ((holderPid) => isProcessAlive(holderPid));
109
+ const now = Number.isFinite(options.now) ? options.now : Date.now();
110
+ const freshMs = options.freshMs ?? LOCK_HOLDER_FRESH_MS;
111
+ let text;
112
+ try {
113
+ text = fsApi.readFileSync(options.lockFile, "utf8");
114
+ } catch {
115
+ return null;
116
+ }
117
+ const parsed = parseLockData(text);
118
+ if (!parsed) return null;
119
+ const checkedInMsAgo = Math.max(0, now - parsed.timestamp);
120
+ if (!isAlive(parsed.pid)) return { state: "dead", pid: parsed.pid, checkedInMsAgo };
121
+ const state = parsed.timestamp > 0 && checkedInMsAgo <= freshMs ? "running" : "stuck";
122
+ return { state, pid: parsed.pid, checkedInMsAgo };
123
+ }
124
+
89
125
  /**
90
126
  * @param {{
91
127
  * lockFile: string,
package/lib/urlQuery.js CHANGED
@@ -14,13 +14,17 @@ export function stripUrlQueries(text) {
14
14
  }
15
15
 
16
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;
17
+ // "Meeting password: abc", "PIN: 123 456 789#", "PIN is 1234", Webex
18
+ // "Host key: 123456" and "Access code: 123 456", "Passcode 123456") and inside
19
+ // one-tap dial strings ("+15550100,,1000000001#,,,,*123456#"). The value after a
20
+ // passcode label is hidden to the end of its line; a dial string keeps its
21
+ // digits up to the passcode and hides the passcode itself. A full-width colon
22
+ // (U+FF1A) counts as a colon. "PIN is" needs a value with a digit ("the pin is
23
+ // in the drawer" stays). A bare ",,1000000001#" is the meeting or
24
+ // conference ID, which the tools print like any meeting ID.
25
+ const PASSCODE_LABEL = /\b((?:numeric\s+)?(?:meeting\s+)?(?:passcode|pass\s?code|password|pwd|host\s+key|access\s+code)\b\s*(?:[:=#\uFF1A]|is\b)\s*|\bpin\b\s*(?:[:=#\uFF1A]\s*|is\s+(?=\S*\d)))[^\n]*/gi;
22
26
  // "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;
27
+ const PASSCODE_BARE = /\b((?:meeting\s+)?(?:passcode|pass\s?code|password|host\s+key|access\s+code)\s+)(?=[^\s:=#\uFF1A]*\d)[^\s:=#\uFF1A]+/gi;
24
28
  // Bounded comma run: an unbounded ,{2,} is quadratic on a long run of commas.
25
29
  const DIAL_PASSCODE = /(,{2,12}\*)\d{1,20}#/g;
26
30
  const HIDDEN = "[hidden]";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "apple-tools-mcp",
3
- "version": "3.4.2",
3
+ "version": "3.4.3",
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",