apple-tools-mcp 3.3.3 → 3.3.4
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 +6 -0
- package/index.js +3 -1
- package/indexer.js +179 -3
- package/package.json +3 -1
- package/scripts/smoke-mail-read.js +68 -0
package/README.md
CHANGED
|
@@ -477,6 +477,12 @@ npm run smoke:writes -- --apply
|
|
|
477
477
|
|
|
478
478
|
`npm run smoke:writes` checks the write path without creating lasting contacts or events. `npm run smoke:writes -- --apply` performs real creates, edits, and deletes, then removes the test items. The extra `--` is required so npm forwards `--apply`. `--apply` fails if Mail, Messages, Contacts, or Calendar Automation is missing.
|
|
479
479
|
|
|
480
|
+
```bash
|
|
481
|
+
npm run smoke:mail-read
|
|
482
|
+
```
|
|
483
|
+
|
|
484
|
+
`npm run smoke:mail-read` is read-only: it runs a few `mail_search` queries against the live index and checks that `mail_read` can open every hit. A failure means the index holds old file paths (for example after moving to a new Mac); the indexer re-paths moved mail by Message-ID on its next pass, keeping the existing embeddings.
|
|
485
|
+
|
|
480
486
|
## License
|
|
481
487
|
|
|
482
488
|
MIT License. See [LICENSE](LICENSE).
|
package/index.js
CHANGED
|
@@ -601,7 +601,9 @@ function readFullEmail(filePath) {
|
|
|
601
601
|
|
|
602
602
|
// Verify file exists
|
|
603
603
|
if (!fs.existsSync(validatedPath)) {
|
|
604
|
-
return "Email file not found."
|
|
604
|
+
return "Email file not found. The search index may hold this email's old path " +
|
|
605
|
+
"(Mail moved or rebuilt its folders); the indexer re-paths moved mail on its next pass. " +
|
|
606
|
+
"Run mail_search again, or find the message with mail_find by subject or sender.";
|
|
605
607
|
}
|
|
606
608
|
|
|
607
609
|
const content = unfoldRfc822Headers(fs.readFileSync(validatedPath, 'utf-8'));
|
package/indexer.js
CHANGED
|
@@ -392,6 +392,162 @@ async function findAllEmlxFiles() {
|
|
|
392
392
|
return safeFindAsync(MAIL_DIR, { name: "*.emlx", type: "f" });
|
|
393
393
|
}
|
|
394
394
|
|
|
395
|
+
// Message-ID of an .emlx file, read from its first bytes the same way
|
|
396
|
+
// parseEmlx reads it ("" when the file has none or cannot be read).
|
|
397
|
+
const EMLX_HEADER_READ_BYTES = 64 * 1024;
|
|
398
|
+
function readEmlxMessageId(filePath) {
|
|
399
|
+
let fd;
|
|
400
|
+
try {
|
|
401
|
+
fd = fs.openSync(filePath, "r");
|
|
402
|
+
const buf = Buffer.alloc(EMLX_HEADER_READ_BYTES);
|
|
403
|
+
const n = fs.readSync(fd, buf, 0, buf.length, 0);
|
|
404
|
+
let content = buf.subarray(0, n).toString("utf-8");
|
|
405
|
+
const firstNewline = content.indexOf("\n");
|
|
406
|
+
if (firstNewline >= 0 && /^\d+\s*$/.test(content.slice(0, firstNewline))) {
|
|
407
|
+
content = content.slice(firstNewline + 1);
|
|
408
|
+
}
|
|
409
|
+
const match = unfoldRfc822Headers(content).match(/^Message-ID:\s*(.+)$/im);
|
|
410
|
+
return match?.[1]?.trim() || "";
|
|
411
|
+
} catch {
|
|
412
|
+
return "";
|
|
413
|
+
} finally {
|
|
414
|
+
if (fd !== undefined) {
|
|
415
|
+
try { fs.closeSync(fd); } catch { /* already closed */ }
|
|
416
|
+
}
|
|
417
|
+
}
|
|
418
|
+
}
|
|
419
|
+
|
|
420
|
+
const STALE_EMAIL_CHUNK = 500;
|
|
421
|
+
|
|
422
|
+
// Gone means ENOENT/ENOTDIR only: a file that exists but cannot be read
|
|
423
|
+
// right now (EACCES on one mailbox) is not stale and keeps its row.
|
|
424
|
+
function emailFileGone(filePath) {
|
|
425
|
+
try {
|
|
426
|
+
fs.statSync(filePath);
|
|
427
|
+
return false;
|
|
428
|
+
} catch (e) {
|
|
429
|
+
return e.code === "ENOENT" || e.code === "ENOTDIR";
|
|
430
|
+
}
|
|
431
|
+
}
|
|
432
|
+
|
|
433
|
+
// SQL string literal for a LanceDB (DataFusion) filter: only a single quote
|
|
434
|
+
// needs escaping; a backslash is literal there, so escapeSQL's doubling would
|
|
435
|
+
// make a path containing one never match.
|
|
436
|
+
function lanceStringLiteral(value) {
|
|
437
|
+
return `'${String(value).replace(/'/g, "''")}'`;
|
|
438
|
+
}
|
|
439
|
+
|
|
440
|
+
/**
|
|
441
|
+
* Email rows whose file is gone: Mail rebuilt or renamed its mailbox folders
|
|
442
|
+
* (a move to a new Mac), a .partial.emlx finished downloading, or a message
|
|
443
|
+
* moved to another mailbox. Without this pass those rows keep dead paths
|
|
444
|
+
* forever (mail_read fails on every hit) and the live copies are skipped as
|
|
445
|
+
* Message-ID duplicates of the dead rows.
|
|
446
|
+
*
|
|
447
|
+
* A stale row whose Message-ID matches an unindexed live file is re-pathed to
|
|
448
|
+
* it and keeps its embedding; the rest are removed. Quiet passes only stat the
|
|
449
|
+
* cached paths (no table reads). Returns null when nothing changed, else the
|
|
450
|
+
* counts plus the full-scan file list the pass should index from, so live
|
|
451
|
+
* files that matched no stale row are picked up even when older than the
|
|
452
|
+
* incremental lookback.
|
|
453
|
+
*/
|
|
454
|
+
async function reconcileStaleEmailRows(indexedPaths) {
|
|
455
|
+
let staleCount = 0;
|
|
456
|
+
for (const p of indexedPaths) {
|
|
457
|
+
if (emailFileGone(p)) staleCount++;
|
|
458
|
+
}
|
|
459
|
+
if (staleCount === 0 || !tables.emails) return null;
|
|
460
|
+
|
|
461
|
+
// Never treat an unreadable Mail folder (lost Full Disk Access, a scan
|
|
462
|
+
// error) as "every email is gone": that would empty the email index.
|
|
463
|
+
let allFiles;
|
|
464
|
+
try {
|
|
465
|
+
fs.readdirSync(MAIL_DIR);
|
|
466
|
+
allFiles = await findAllEmlxFiles();
|
|
467
|
+
} catch (e) {
|
|
468
|
+
console.error(`Stale email check skipped: Mail folder unreadable (${e.message})`);
|
|
469
|
+
return null;
|
|
470
|
+
}
|
|
471
|
+
if (allFiles.length === 0) {
|
|
472
|
+
console.error(`Stale email check skipped: ${staleCount} indexed paths are missing but the Mail scan found no .emlx files`);
|
|
473
|
+
return null;
|
|
474
|
+
}
|
|
475
|
+
|
|
476
|
+
console.error(`\n=== STALE EMAIL ROWS: ${staleCount} indexed paths no longer exist ===`);
|
|
477
|
+
const started = Date.now();
|
|
478
|
+
|
|
479
|
+
// Message-IDs of the stale rows (one ID read, only on a pass with stale rows)
|
|
480
|
+
const idRows = await tables.emails.query().select(["filePath", "messageId"]).toArray();
|
|
481
|
+
const stale = idRows.filter(r => emailFileGone(r.filePath));
|
|
482
|
+
const wantedIds = new Set(stale.map(r => r.messageId).filter(Boolean));
|
|
483
|
+
|
|
484
|
+
// Unindexed live files that carry one of those Message-IDs; keep the copy
|
|
485
|
+
// from the highest-priority mailbox, as a fresh index would.
|
|
486
|
+
const liveById = new Map();
|
|
487
|
+
for (const filePath of allFiles) {
|
|
488
|
+
if (indexedPaths.has(filePath)) continue;
|
|
489
|
+
const messageId = readEmlxMessageId(filePath);
|
|
490
|
+
if (!messageId || !wantedIds.has(messageId)) continue;
|
|
491
|
+
const current = liveById.get(messageId);
|
|
492
|
+
if (!current || getMailboxPriority(filePath) < getMailboxPriority(current)) {
|
|
493
|
+
liveById.set(messageId, filePath);
|
|
494
|
+
}
|
|
495
|
+
}
|
|
496
|
+
|
|
497
|
+
const repath = new Map(); // old path -> new path
|
|
498
|
+
const drop = [];
|
|
499
|
+
for (const row of stale) {
|
|
500
|
+
const target = row.messageId ? liveById.get(row.messageId) : undefined;
|
|
501
|
+
if (target) {
|
|
502
|
+
repath.set(row.filePath, target);
|
|
503
|
+
liveById.delete(row.messageId); // one row per live file
|
|
504
|
+
} else {
|
|
505
|
+
drop.push(row.filePath);
|
|
506
|
+
}
|
|
507
|
+
}
|
|
508
|
+
|
|
509
|
+
const inList = (paths) => `\`filePath\` IN (${paths.map(lanceStringLiteral).join(", ")})`;
|
|
510
|
+
let repathed = 0;
|
|
511
|
+
let removed = 0;
|
|
512
|
+
const oldPaths = [...repath.keys()];
|
|
513
|
+
for (let i = 0; i < oldPaths.length; i += STALE_EMAIL_CHUNK) {
|
|
514
|
+
const chunk = oldPaths.slice(i, i + STALE_EMAIL_CHUNK);
|
|
515
|
+
const rows = await tables.emails.query().where(inList(chunk)).toArray();
|
|
516
|
+
const seen = new Set();
|
|
517
|
+
const records = rows.filter(row => {
|
|
518
|
+
// A duplicated old path must not become a duplicated new path.
|
|
519
|
+
if (seen.has(row.filePath)) return false;
|
|
520
|
+
seen.add(row.filePath);
|
|
521
|
+
return true;
|
|
522
|
+
}).map(row => {
|
|
523
|
+
const filePath = repath.get(row.filePath);
|
|
524
|
+
const mailbox = extractMailbox(filePath);
|
|
525
|
+
return {
|
|
526
|
+
...row,
|
|
527
|
+
filePath,
|
|
528
|
+
mailbox,
|
|
529
|
+
isSent: mailbox.toLowerCase().includes("sent"),
|
|
530
|
+
vector: Array.from(row.vector)
|
|
531
|
+
};
|
|
532
|
+
});
|
|
533
|
+
// Add before delete: a failed delete leaves a stale row that the next
|
|
534
|
+
// pass removes; a failed add loses nothing.
|
|
535
|
+
if (records.length > 0) await tables.emails.add(records);
|
|
536
|
+
await tables.emails.delete(inList(chunk));
|
|
537
|
+
repathed += records.length;
|
|
538
|
+
}
|
|
539
|
+
for (let i = 0; i < drop.length; i += STALE_EMAIL_CHUNK) {
|
|
540
|
+
const chunk = drop.slice(i, i + STALE_EMAIL_CHUNK);
|
|
541
|
+
await tables.emails.delete(inList(chunk));
|
|
542
|
+
removed += chunk.length;
|
|
543
|
+
}
|
|
544
|
+
|
|
545
|
+
indexedIdCache.invalidate("emails");
|
|
546
|
+
duplicateEmailPaths.clear();
|
|
547
|
+
console.error(`Stale email rows: re-pathed ${repathed}, removed ${removed} (${Date.now() - started}ms)`);
|
|
548
|
+
return { repathed, removed, allFiles };
|
|
549
|
+
}
|
|
550
|
+
|
|
395
551
|
// Fast incremental scan - uses find with -mtime filter (more reliable than mdfind/Spotlight)
|
|
396
552
|
async function findNewEmlxFiles(sinceTimestamp) {
|
|
397
553
|
if (!sinceTimestamp) {
|
|
@@ -1014,7 +1170,25 @@ export async function indexEmails(progressCallback = null, forceFullScan = false
|
|
|
1014
1170
|
console.error(`Found ${newFiles.length} new/modified email files (${Date.now() - startTime}ms)`);
|
|
1015
1171
|
|
|
1016
1172
|
// One read of both ID columns, served from memory while the table is unchanged.
|
|
1017
|
-
|
|
1173
|
+
let emailIdSets = await getCachedIdSetsWithRetry("emails", EMAIL_ID_FIELDS);
|
|
1174
|
+
|
|
1175
|
+
// Re-path or drop rows whose file is gone, then index from the full scan so
|
|
1176
|
+
// relocated mail older than the lookback window is not missed.
|
|
1177
|
+
let staleResult = null;
|
|
1178
|
+
try {
|
|
1179
|
+
staleResult = await reconcileStaleEmailRows(emailIdSets.filePath);
|
|
1180
|
+
} catch (e) {
|
|
1181
|
+
indexedIdCache.invalidate("emails");
|
|
1182
|
+
console.error(`Stale email check failed; continuing with the normal pass: ${e.message}`);
|
|
1183
|
+
}
|
|
1184
|
+
if (staleResult) {
|
|
1185
|
+
// A DAYS_BACK cap keeps its own window; otherwise use the full scan.
|
|
1186
|
+
if (!DAYS_BACK) newFiles = staleResult.allFiles;
|
|
1187
|
+
emailIdSets = await getCachedIdSetsWithRetry("emails", EMAIL_ID_FIELDS);
|
|
1188
|
+
}
|
|
1189
|
+
const staleCounts = staleResult
|
|
1190
|
+
? { repathed: staleResult.repathed, removed: staleResult.removed }
|
|
1191
|
+
: {};
|
|
1018
1192
|
const indexedPaths = emailIdSets.filePath;
|
|
1019
1193
|
const indexedMessageIds = emailIdSets.messageId;
|
|
1020
1194
|
console.error(`Already indexed: ${indexedPaths.size} emails`);
|
|
@@ -1043,7 +1217,7 @@ export async function indexEmails(progressCallback = null, forceFullScan = false
|
|
|
1043
1217
|
if (toIndex.length === 0) {
|
|
1044
1218
|
// Save timestamp for next incremental scan
|
|
1045
1219
|
saveIndexMeta({ ...meta, lastEmailIndexTime: indexStartTime });
|
|
1046
|
-
return { indexed: indexedPaths.size, added: 0 };
|
|
1220
|
+
return { indexed: indexedPaths.size, added: 0, ...staleCounts };
|
|
1047
1221
|
}
|
|
1048
1222
|
|
|
1049
1223
|
let processed = 0;
|
|
@@ -1234,7 +1408,7 @@ export async function indexEmails(progressCallback = null, forceFullScan = false
|
|
|
1234
1408
|
// Indexed count from the version-checked ID cache (re-reads only if the
|
|
1235
1409
|
// table moved by something other than this pass's own adds)
|
|
1236
1410
|
const finalIndexedPaths = (await getCachedIdSetsWithRetry("emails", EMAIL_ID_FIELDS)).filePath;
|
|
1237
|
-
return { indexed: finalIndexedPaths.size, added: indexedCount };
|
|
1411
|
+
return { indexed: finalIndexedPaths.size, added: indexedCount, ...staleCounts };
|
|
1238
1412
|
}
|
|
1239
1413
|
|
|
1240
1414
|
export async function indexMessages(forceFullScan = false) {
|
|
@@ -1563,6 +1737,8 @@ export async function indexAll(progressCallback = null) {
|
|
|
1563
1737
|
async function maybeOptimizeIndex(results) {
|
|
1564
1738
|
const wroteSomething =
|
|
1565
1739
|
(results.emails?.added || 0) > 0 ||
|
|
1740
|
+
(results.emails?.repathed || 0) > 0 ||
|
|
1741
|
+
(results.emails?.removed || 0) > 0 ||
|
|
1566
1742
|
(results.messages?.added || 0) > 0 ||
|
|
1567
1743
|
(results.calendar?.added || 0) > 0 ||
|
|
1568
1744
|
(results.calendar?.removed || 0) > 0;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "apple-tools-mcp",
|
|
3
|
-
"version": "3.3.
|
|
3
|
+
"version": "3.3.4",
|
|
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",
|
|
@@ -55,6 +55,7 @@
|
|
|
55
55
|
"docs/mail-send-reconciliation.md",
|
|
56
56
|
"scripts/audit-index.js",
|
|
57
57
|
"scripts/smoke-writes.js",
|
|
58
|
+
"scripts/smoke-mail-read.js",
|
|
58
59
|
"scripts/postinstall.js",
|
|
59
60
|
"README.md",
|
|
60
61
|
"LICENSE"
|
|
@@ -69,6 +70,7 @@
|
|
|
69
70
|
"build-index": "node -e \"import('./indexer.js').then(i=>i.rebuildIndex()).catch(e=>{console.error(e.message);process.exit(1)})\"",
|
|
70
71
|
"audit": "node scripts/audit-index.js",
|
|
71
72
|
"smoke:writes": "node scripts/smoke-writes.js",
|
|
73
|
+
"smoke:mail-read": "node scripts/smoke-mail-read.js",
|
|
72
74
|
"test": "vitest run",
|
|
73
75
|
"test:watch": "vitest",
|
|
74
76
|
"test:unit": "vitest run tests/unit",
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Read-only smoke test: every mail_search hit must be readable by mail_read.
|
|
4
|
+
*
|
|
5
|
+
* Runs a few semantic searches against the live index and, for each hit,
|
|
6
|
+
* checks what mail_read needs: the File path passes validateEmailPath, the
|
|
7
|
+
* file exists, and its headers parse. A hit whose file is gone means the
|
|
8
|
+
* index holds stale paths (for example after a move to a new Mac); the
|
|
9
|
+
* indexer re-paths those on its next pass.
|
|
10
|
+
*
|
|
11
|
+
* Writes nothing, sends nothing, needs no indexer lock.
|
|
12
|
+
*
|
|
13
|
+
* Usage:
|
|
14
|
+
* node scripts/smoke-mail-read.js # default queries, 10 hits each
|
|
15
|
+
* node scripts/smoke-mail-read.js --limit=30 "receipt" "meeting"
|
|
16
|
+
*
|
|
17
|
+
* Exit 0 when every hit is readable, 1 when any is not, 2 when there were no hits.
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
import fs from "fs";
|
|
21
|
+
import path from "path";
|
|
22
|
+
import { searchEmails } from "../search.js";
|
|
23
|
+
import { validateEmailPath, unfoldRfc822Headers } from "../lib/validators.js";
|
|
24
|
+
|
|
25
|
+
const MAIL_DIR = path.join(process.env.HOME, "Library", "Mail");
|
|
26
|
+
const DEFAULT_QUERIES = ["receipt", "meeting", "invoice"];
|
|
27
|
+
|
|
28
|
+
export function checkReadable(filePath, mailDir = MAIL_DIR) {
|
|
29
|
+
let validated;
|
|
30
|
+
try {
|
|
31
|
+
validated = validateEmailPath(filePath, mailDir);
|
|
32
|
+
} catch (e) {
|
|
33
|
+
return { ok: false, reason: `invalid path: ${e.message}` };
|
|
34
|
+
}
|
|
35
|
+
if (!fs.existsSync(validated)) return { ok: false, reason: "file not found" };
|
|
36
|
+
const head = unfoldRfc822Headers(fs.readFileSync(validated, "utf-8").slice(0, 65536));
|
|
37
|
+
if (!/^(From|Subject):/m.test(head)) return { ok: false, reason: "no From/Subject header" };
|
|
38
|
+
return { ok: true };
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
async function main(argv) {
|
|
42
|
+
const limitArg = argv.find((a) => a.startsWith("--limit="));
|
|
43
|
+
const limit = limitArg ? Number(limitArg.slice("--limit=".length)) || 10 : 10;
|
|
44
|
+
const queries = argv.filter((a) => !a.startsWith("--"));
|
|
45
|
+
let hits = 0;
|
|
46
|
+
const failures = [];
|
|
47
|
+
for (const query of queries.length ? queries : DEFAULT_QUERIES) {
|
|
48
|
+
const result = await searchEmails(query, { limit });
|
|
49
|
+
const rows = result?.results || [];
|
|
50
|
+
for (const row of rows) {
|
|
51
|
+
hits++;
|
|
52
|
+
const check = checkReadable(row.filePath);
|
|
53
|
+
if (!check.ok) failures.push({ query, filePath: row.filePath, reason: check.reason });
|
|
54
|
+
}
|
|
55
|
+
console.log(`"${query}": ${rows.length} hits`);
|
|
56
|
+
}
|
|
57
|
+
console.log(`mail_search hits checked: ${hits}, unreadable: ${failures.length}`);
|
|
58
|
+
for (const f of failures.slice(0, 10)) console.log(` FAIL "${f.query}" ${f.reason}: ${f.filePath}`);
|
|
59
|
+
if (hits === 0) return 2;
|
|
60
|
+
return failures.length ? 1 : 0;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
if (import.meta.url === `file://${process.argv[1]}`) {
|
|
64
|
+
main(process.argv.slice(2)).then((code) => process.exit(code), (e) => {
|
|
65
|
+
console.error(e);
|
|
66
|
+
process.exit(1);
|
|
67
|
+
});
|
|
68
|
+
}
|