apple-tools-mcp 3.3.3 → 3.3.5

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
@@ -295,8 +295,8 @@ Your client can also call `audit_index`.
295
295
  | Tool | Description |
296
296
  |------|-------------|
297
297
  | `calendar_search` | Semantic search for events, with filters. |
298
- | `calendar_date` | Events on a date, read live from Calendar rather than the search index. |
299
- | `calendar_upcoming` | Next upcoming events. |
298
+ | `calendar_date` | Events on a date, read live from Calendar rather than the search index. A failed read is an error, never an empty day. |
299
+ | `calendar_upcoming` | Next events, starting with everything on today's date (all-day and earlier-today events included). A failed read is an error. |
300
300
  | `calendar_week` | Events for this week or a future week. |
301
301
  | `calendar_free_time` | Open time on a date, read live from Calendar rather than the search index. |
302
302
  | `calendar_recurring` | Recurring events. |
@@ -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
@@ -219,6 +219,7 @@ import {
219
219
  formatSendersResults,
220
220
  formatMessageContactsResults,
221
221
  formatUpcomingEventsResults,
222
+ requireCalendarRead,
222
223
  formatWeekEventsResults,
223
224
  formatEmailThreadResults,
224
225
  formatRecurringEventsResults
@@ -576,13 +577,11 @@ async function calendarSearch(query, options = {}) {
576
577
  }
577
578
 
578
579
  async function calendarDate(date) {
579
- const result = await getCalendarDateResults(date);
580
- return formatCalendarResults(result);
580
+ return formatCalendarResults(requireCalendarRead(await getCalendarDateResults(date)));
581
581
  }
582
582
 
583
583
  async function calendarFreeTime(date, options = {}) {
584
- const result = await calculateFreeTime(date, options);
585
- return formatFreeTimeResults(result);
584
+ return formatFreeTimeResults(requireCalendarRead(await calculateFreeTime(date, options)));
586
585
  }
587
586
 
588
587
  // Mail directory for path validation
@@ -601,7 +600,9 @@ function readFullEmail(filePath) {
601
600
 
602
601
  // Verify file exists
603
602
  if (!fs.existsSync(validatedPath)) {
604
- return "Email file not found.";
603
+ return "Email file not found. The search index may hold this email's old path " +
604
+ "(Mail moved or rebuilt its folders); the indexer re-paths moved mail on its next pass. " +
605
+ "Run mail_search again, or find the message with mail_find by subject or sender.";
605
606
  }
606
607
 
607
608
  const content = unfoldRfc822Headers(fs.readFileSync(validatedPath, 'utf-8'));
@@ -1616,7 +1617,7 @@ function createServer() {
1616
1617
 
1617
1618
  // Calendar tools
1618
1619
  case "calendar_upcoming":
1619
- result = formatUpcomingEventsResults(getUpcomingEvents(validateLimit(args?.limit, 30, 100)));
1620
+ result = formatUpcomingEventsResults(requireCalendarRead(getUpcomingEvents(validateLimit(args?.limit, 30, 100))));
1620
1621
  break;
1621
1622
 
1622
1623
  // ============ NEW TOOLS - PHASE 2 ============
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
- const emailIdSets = await getCachedIdSetsWithRetry("emails", EMAIL_ID_FIELDS);
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;
@@ -1814,19 +1990,15 @@ export function getMessageContacts(limit = 50) {
1814
1990
  }
1815
1991
  }
1816
1992
 
1817
- // calendar_upcoming: Get next N upcoming events
1818
- export function getUpcomingEvents(limit = 10) {
1819
- try {
1820
- // Validate limit to prevent SQL issues
1821
- const safeLimit = validateLimit(limit, 10, 100);
1822
- const nowMac = Math.floor(Date.now() / 1000) - 978307200;
1823
- const fetchLimit = safeLimit + 1; // Fetch one extra to detect if more exist
1824
-
1825
- // Query OccurrenceCache to include recurring event occurrences
1826
- const query = `
1993
+ // calendar_upcoming: Get next N upcoming events, starting with every event on the current local day.
1994
+ // OccurrenceCache.day is each occurrence's local midnight, so the lower bound is today's local midnight,
1995
+ // never now: comparing day to now dropped all of today (all-day and later-today events) after midnight.
1996
+ export function buildUpcomingEventsQuery(dayStartMac, fetchLimit) {
1997
+ const occStart = "COALESCE(oc.occurrence_end_date - (ci.end_date - ci.start_date), ci.start_date)";
1998
+ return `
1827
1999
  SELECT
1828
2000
  ci.summary as title,
1829
- datetime(COALESCE(oc.occurrence_end_date - (ci.end_date - ci.start_date), ci.start_date) + 978307200, 'unixepoch', 'localtime') as start,
2001
+ datetime(${occStart} + 978307200, 'unixepoch', 'localtime') as start,
1830
2002
  datetime(COALESCE(oc.occurrence_end_date, ci.end_date) + 978307200, 'unixepoch', 'localtime') as end,
1831
2003
  ci.all_day as isAllDay,
1832
2004
  c.title as calendar,
@@ -1836,11 +2008,35 @@ export function getUpcomingEvents(limit = 10) {
1836
2008
  INNER JOIN CalendarItem ci ON oc.event_id = ci.ROWID
1837
2009
  LEFT JOIN Calendar c ON ci.calendar_id = c.ROWID
1838
2010
  LEFT JOIN Location l ON ci.location_id = l.ROWID
1839
- WHERE oc.day >= ${nowMac} AND ci.summary IS NOT NULL AND ci.summary <> ''
1840
- ORDER BY sort_day ASC
2011
+ WHERE oc.day >= ${dayStartMac} AND ci.summary IS NOT NULL AND ci.summary <> ''
2012
+ ORDER BY sort_day ASC, ci.all_day DESC, ${occStart} ASC, title ASC
1841
2013
  LIMIT ${fetchLimit}
1842
2014
  `;
2015
+ }
2016
+
2017
+ // Start of the current local day, in Apple/Core Data seconds.
2018
+ function localTodayStartMac() {
2019
+ const midnight = new Date();
2020
+ midnight.setHours(0, 0, 0, 0);
2021
+ return Math.floor(midnight.getTime() / 1000) - MAC_ABSOLUTE_EPOCH;
2022
+ }
2023
+
2024
+ // A copy with no OccurrenceCache rows at all is not a readable calendar: say so instead of an empty day.
2025
+ function assertOccurrenceCache(dbPath) {
2026
+ const rows = safeSqlite3Json(dbPath, "SELECT COUNT(*) AS n FROM (SELECT 1 FROM OccurrenceCache LIMIT 1)", { timeout: 10000 });
2027
+ if (!rows.length || !Number(rows[0].n)) {
2028
+ throw new Error("Calendar OccurrenceCache is empty, so the calendar could not be read");
2029
+ }
2030
+ }
2031
+
2032
+ export function getUpcomingEvents(limit = 10) {
2033
+ try {
2034
+ // Validate limit to prevent SQL issues
2035
+ const safeLimit = validateLimit(limit, 10, 100);
2036
+ const fetchLimit = safeLimit + 1; // Fetch one extra to detect if more exist
2037
+ const query = buildUpcomingEventsQuery(localTodayStartMac(), fetchLimit);
1843
2038
  const events = withCalendarCopy((dbPath) => {
2039
+ assertOccurrenceCache(dbPath);
1844
2040
  return safeSqlite3Json(dbPath, query, { timeout: 10000 });
1845
2041
  });
1846
2042
  const hasMore = events.length > safeLimit;
@@ -1973,6 +2169,7 @@ export function getEventsOnDate(startMs, endMs) {
1973
2169
  const query = buildEventsOnDateQuery(startMac, endMac, { includeUid: attempt === 0 });
1974
2170
  try {
1975
2171
  const events = withCalendarCopy((dbPath) => {
2172
+ assertOccurrenceCache(dbPath);
1976
2173
  return safeSqlite3Json(dbPath, query, { timeout: 15000 });
1977
2174
  });
1978
2175
  return { events, error: null };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "apple-tools-mcp",
3
- "version": "3.3.3",
3
+ "version": "3.3.5",
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
+ }
package/search.js CHANGED
@@ -1601,6 +1601,18 @@ export function formatMessageContactsResults(contacts) {
1601
1601
  return output;
1602
1602
  }
1603
1603
 
1604
+ // A calendar tool result that failed to read the calendar becomes a thrown error, so the MCP
1605
+ // dispatcher answers isError: true. A failed read must never look like an empty day.
1606
+ export function requireCalendarRead(result) {
1607
+ if (result?.success === false) {
1608
+ throw new Error(result.error || "The calendar could not be read");
1609
+ }
1610
+ if (result?.error) {
1611
+ throw new Error(`Error getting upcoming events: ${result.error}`);
1612
+ }
1613
+ return result;
1614
+ }
1615
+
1604
1616
  // Format calendar_upcoming results
1605
1617
  export function formatUpcomingEventsResults(result) {
1606
1618
  if (result?.error) {