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 +2 -2
- package/index.js +8 -3
- package/indexer.js +23 -3
- package/lib/audit.js +7 -6
- package/lib/indexGate.js +36 -3
- package/lib/indexerLock.js +36 -0
- package/lib/urlQuery.js +10 -6
- package/package.json +1 -1
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
|
|
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({
|
|
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
|
-
|
|
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 {{
|
|
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
|
-
|
|
174
|
+
staleCause(holder);
|
|
142
175
|
}
|
package/lib/indexerLock.js
CHANGED
|
@@ -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#", "
|
|
18
|
-
//
|
|
19
|
-
//
|
|
20
|
-
//
|
|
21
|
-
|
|
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
|
|
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.
|
|
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",
|