@mgcrea/mcp-apple-mail 0.0.0-bootstrap

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.
@@ -0,0 +1,604 @@
1
+ import { AppBusyError as MailBusyError, AppNotRunningError as MailNotRunningError, AppleAutomationError, AppleAutomationError as AppleMailError, BuildInfo, IndexUnavailableError, JxaEnvelope, Logger, OsascriptRunner, OsascriptTimeoutError, PlatformError, PreconditionError, ProtocolError, SchemaDriftError, TccDeniedError, WritesDisabledError, assertStaticScript, createOsascriptRunner, inspectFile, mapOsaError, withBusyRetry } from "@mgcrea/mcp-apple-core";
2
+ import { z } from "zod";
3
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
4
+ import { DatabaseSync } from "node:sqlite";
5
+ //#region src/build-info.d.ts
6
+ declare const BUILD_INFO: BuildInfo;
7
+ //#endregion
8
+ //#region src/client/errors.d.ts
9
+ /** A MessageRef no longer resolves — the message was moved, deleted, or the index is stale. */
10
+ declare class MessageNotFoundError extends AppleAutomationError {
11
+ readonly name = "MessageNotFoundError";
12
+ constructor(ref: string);
13
+ }
14
+ //#endregion
15
+ //#region src/client/locate.d.ts
16
+ /**
17
+ * Find Mail's data root and its Envelope Index.
18
+ *
19
+ * The obvious approach — glob `~/Library/Mail/V*` — does not work: that
20
+ * directory is TCC-protected, so without Full Disk Access the glob returns
21
+ * nothing even though the path is right there. Mail itself will hand us the
22
+ * answer though: `account.accountDirectory()` returns
23
+ * `~/Library/Mail/V10/<accountUuid>` over Apple Events, which need only the
24
+ * Automation permission. So Mail naming its own directory is the primary
25
+ * strategy and the glob is the fallback, not the other way round.
26
+ *
27
+ * A second subtlety, learned the same way: `statSync` SUCCEEDS on a
28
+ * TCC-protected file — you get the real size and mtime — and only open(2) and
29
+ * access(2) are denied. Existence and readability are therefore different
30
+ * questions here, and only readability tells you whether FDA is granted.
31
+ */
32
+ type LocateResult = {
33
+ /** e.g. /Users/me/Library/Mail/V10 */
34
+ mailRoot: string | null;
35
+ /** e.g. V10 */
36
+ dataVersion: string | null;
37
+ envelopeIndexPath: string | null;
38
+ /** How mailRoot was decided — reported by diagnostics so a bug report is self-describing. */
39
+ strategy: "config" | "accountDirectory" | "glob" | "none";
40
+ exists: boolean;
41
+ readable: boolean;
42
+ sizeBytes: number | null;
43
+ mtime: string | null;
44
+ /** Whether a -wal file is present, i.e. whether `immutable=1` COULD miss recent mail. */
45
+ walPresent: boolean;
46
+ walSizeBytes: number | null;
47
+ reason: string | null;
48
+ };
49
+ type LocateOptions = {
50
+ /** Explicit index path from config — wins outright. */
51
+ envelopeIndexPath?: string | undefined;
52
+ /** Explicit Mail root from config. */
53
+ mailRoot?: string | undefined;
54
+ /** Any account directory reported by Mail, e.g. ~/Library/Mail/V10/<uuid>. */
55
+ accountDirectory?: string | undefined;
56
+ /** Injectable for tests. */
57
+ home?: string | undefined;
58
+ };
59
+ declare const locateEnvelopeIndex: (opts?: LocateOptions) => LocateResult;
60
+ //#endregion
61
+ //#region src/config.d.ts
62
+ /**
63
+ * Configuration is environment-only. The sibling servers that also read a
64
+ * `~/.config/<service>/config.json` do so because they hold a private key or an
65
+ * OAuth token; this server holds no secret at all — its access comes from macOS
66
+ * permissions granted to the host process — so a second config source would be
67
+ * machinery without a job.
68
+ */
69
+ /**
70
+ * `allowWrites`, `debug`, `osascriptPath`, `osascriptTimeoutMs` and `maxResults`
71
+ * come from `BaseConfigSchema` — every Apple-app server has them, with the same
72
+ * bounds and the same defaults.
73
+ */
74
+ declare const ConfigSchema: z.ZodObject<{
75
+ allowWrites: z.ZodDefault<z.ZodBoolean>;
76
+ debug: z.ZodDefault<z.ZodBoolean>;
77
+ osascriptPath: z.ZodDefault<z.ZodString>;
78
+ osascriptTimeoutMs: z.ZodDefault<z.ZodNumber>;
79
+ maxResults: z.ZodDefault<z.ZodNumber>;
80
+ accounts: z.ZodDefault<z.ZodArray<z.ZodString>>;
81
+ mailRoot: z.ZodOptional<z.ZodString>;
82
+ envelopeIndexPath: z.ZodOptional<z.ZodString>;
83
+ indexMode: z.ZodDefault<z.ZodEnum<{
84
+ auto: "auto";
85
+ immutable: "immutable";
86
+ off: "off";
87
+ ro: "ro";
88
+ }>>;
89
+ degradedMaxMessages: z.ZodDefault<z.ZodNumber>;
90
+ bodyMaxBytes: z.ZodDefault<z.ZodNumber>;
91
+ bodyScanMax: z.ZodDefault<z.ZodNumber>;
92
+ bodyScanBytes: z.ZodDefault<z.ZodNumber>;
93
+ attachmentDir: z.ZodDefault<z.ZodString>;
94
+ mailboxCacheTtlMs: z.ZodDefault<z.ZodNumber>;
95
+ }, z.core.$strict>;
96
+ type Config = z.infer<typeof ConfigSchema>;
97
+ /**
98
+ * `env` is a parameter with a default so tests are hermetic — they pass their
99
+ * own object rather than mutating (and having to restore) process.env.
100
+ */
101
+ declare const loadConfig: (env?: NodeJS.ProcessEnv) => Config;
102
+ //#endregion
103
+ //#region src/client/mime.d.ts
104
+ type Attachment = {
105
+ filename: string | null;
106
+ contentType: string;
107
+ contentId: string | null;
108
+ /**
109
+ * Size in bytes, or null if genuinely unknowable.
110
+ *
111
+ * The DECODED length when the bytes are in this file, otherwise null — the
112
+ * parser cannot know. `readEmlx` fills it in from the sidecar file on disk,
113
+ * which is both exact and the only way to know if it can be fetched. Never 0,
114
+ * which would read as a measurement rather than an absence.
115
+ */
116
+ sizeBytes: number | null;
117
+ /** False when the bytes were stripped into a sidecar file (.partial.emlx). */
118
+ inline: boolean;
119
+ };
120
+ //#endregion
121
+ //#region src/client/emlx.d.ts
122
+ /**
123
+ * Reading Apple's `.emlx` message files.
124
+ *
125
+ * The container is simple:
126
+ *
127
+ * 1255\n <- byte length of the MIME payload
128
+ * From: ... <- exactly that many bytes of RFC 5322
129
+ * <?xml ...><plist>...</plist> <- Apple's own metadata trailer
130
+ *
131
+ * `.partial.emlx` is the same container with attachment bodies stripped out
132
+ * into a sibling `Attachments/` tree, which is why an attachment can be listed
133
+ * with a name and type but no bytes.
134
+ *
135
+ * The hard part is not the format, it is finding the file. The directory layout
136
+ * is undocumented, so we derive the path, verify it, and fall back to scanning
137
+ * — the derivation is a fast path, not a promise.
138
+ */
139
+ type ParsedMessage = {
140
+ headers: Record<string, string | null>;
141
+ body: string;
142
+ bodyFrom: "text/plain" | "text/html" | "none";
143
+ /** `retrievable` says whether save_attachment can actually fetch the bytes. */
144
+ attachments: (Attachment & {
145
+ retrievable: boolean;
146
+ })[];
147
+ truncated: boolean;
148
+ sizeBytes: number;
149
+ path: string;
150
+ partial: boolean;
151
+ };
152
+ //#endregion
153
+ //#region src/client/schema.d.ts
154
+ type IndexCapabilities = {
155
+ fingerprint: string;
156
+ tables: Record<string, string[]>;
157
+ has: {
158
+ labels: boolean;
159
+ recipients: boolean;
160
+ attachments: boolean;
161
+ subjects: boolean;
162
+ addresses: boolean;
163
+ subjectPrefix: boolean;
164
+ conversationId: boolean;
165
+ flagged: boolean;
166
+ dateSent: boolean;
167
+ messageIdHeader: boolean;
168
+ mailboxCounts: boolean;
169
+ };
170
+ /** Detected, never assumed — prior art disagrees about which epoch this is. */
171
+ epochOffset: number;
172
+ epochReason: string;
173
+ missing: string[];
174
+ };
175
+ //#endregion
176
+ //#region src/client/envelope.d.ts
177
+ type MessageRow = {
178
+ rowid: number;
179
+ mailboxUrl: string;
180
+ subject: string | null;
181
+ senderAddress: string | null;
182
+ senderName: string | null;
183
+ dateReceived: string | null;
184
+ dateSent: string | null;
185
+ read: boolean;
186
+ flagged: boolean;
187
+ size: number | null;
188
+ conversationId: number | null;
189
+ hasAttachment: boolean;
190
+ };
191
+ type SearchFilters = {
192
+ query?: string | undefined;
193
+ sender?: string | undefined;
194
+ recipient?: string | undefined;
195
+ subject?: string | undefined;
196
+ mailboxRowids?: number[] | undefined;
197
+ unreadOnly?: boolean | undefined;
198
+ flaggedOnly?: boolean | undefined;
199
+ hasAttachment?: boolean | undefined;
200
+ dateFrom?: string | undefined;
201
+ dateTo?: string | undefined;
202
+ limit: number;
203
+ offset: number;
204
+ };
205
+ type OpenResult = {
206
+ db: DatabaseSync;
207
+ /** Which mode actually opened. `immutable` results are WAL-blind — say so. */
208
+ mode: "ro" | "immutable";
209
+ caps: IndexCapabilities;
210
+ };
211
+ declare class EnvelopeIndex {
212
+ #private;
213
+ readonly caps: IndexCapabilities;
214
+ readonly mode: "ro" | "immutable";
215
+ constructor(opened: OpenResult);
216
+ close(): void;
217
+ /** id -> url for every mailbox, so results can be mapped back to scriptable names. */
218
+ mailboxes(): {
219
+ rowid: number;
220
+ url: string;
221
+ total: number | null;
222
+ unread: number | null;
223
+ }[];
224
+ search(filters: SearchFilters): MessageRow[];
225
+ count(filters: Omit<SearchFilters, "limit" | "offset">): {
226
+ total: number;
227
+ unread: number;
228
+ };
229
+ /** Every message in one conversation, oldest first. */
230
+ thread(conversationId: number, limit: number): MessageRow[];
231
+ /** conversation_id for one message, so get_thread can start from a ref. */
232
+ conversationOf(rowid: number): number | null;
233
+ }
234
+ //#endregion
235
+ //#region src/client/mailbox-map.d.ts
236
+ /**
237
+ * The account/mailbox join table, and the single choke point for the account
238
+ * allowlist.
239
+ *
240
+ * Everything downstream — search, reads, writes — resolves through here, so
241
+ * filtering the account list once at construction is enough to guarantee that
242
+ * no query path can reach an account the user excluded. Enforcing it in each
243
+ * tool instead would be a list of places to forget.
244
+ */
245
+ type MailAccount = {
246
+ id: string;
247
+ name: string;
248
+ enabled: boolean;
249
+ accountType: string | null;
250
+ emailAddresses: string[];
251
+ fullName: string | null;
252
+ directory: string | null;
253
+ messageCaching: string | null;
254
+ mailboxes: string[];
255
+ };
256
+ type MailboxMapOptions = {
257
+ runner: OsascriptRunner;
258
+ /** Names or UUIDs. Empty = every account. */
259
+ allowlist: string[];
260
+ ttlMs: number;
261
+ now?: () => number;
262
+ };
263
+ declare class MailboxMap {
264
+ #private;
265
+ constructor(opts: MailboxMapOptions);
266
+ accounts(force?: boolean): Promise<MailAccount[]>;
267
+ /** Resolve an account by UUID or display name. Case-insensitive on the name. */
268
+ resolveAccount(needle: string): Promise<MailAccount>;
269
+ /**
270
+ * Resolve a mailbox name within an account using the same ladder the JXA side
271
+ * uses, so a name that works in one lane works in the other: exact, then
272
+ * `[Gmail]/`-stripped, then final path segment, then case-insensitive.
273
+ */
274
+ resolveMailboxName(account: MailAccount, wanted: string): string;
275
+ /**
276
+ * Map an Envelope Index `mailboxes.url` onto a scriptable account + mailbox.
277
+ * The URL host is the account UUID (verified against live Mail), so this join
278
+ * is exact rather than a heuristic on display names.
279
+ */
280
+ resolveIndexUrl(url: string): Promise<{
281
+ account: MailAccount;
282
+ mailbox: string;
283
+ } | null>;
284
+ invalidate(): void;
285
+ }
286
+ //#endregion
287
+ //#region src/client/mail.d.ts
288
+ /**
289
+ * The facade every tool talks to. It owns three things the tools should not
290
+ * each re-decide: which lane answers a question, what to say when a lane is
291
+ * unavailable, and the read-after-write rule.
292
+ */
293
+ type MessageSummary = {
294
+ ref: string;
295
+ id: number;
296
+ accountUuid: string;
297
+ mailbox: string;
298
+ subject: string | null;
299
+ sender: string | null;
300
+ dateReceived: string | null;
301
+ dateSent?: string | null;
302
+ messageId?: string | null;
303
+ read: boolean | null;
304
+ flagged?: boolean | null;
305
+ junk?: boolean | null;
306
+ size?: number | null;
307
+ content?: string | null;
308
+ source?: string | null;
309
+ allHeaders?: string | null;
310
+ };
311
+ type LaneStatus = {
312
+ applescript: "live" | "unavailable";
313
+ index: "live" | "unavailable" | "disabled";
314
+ indexReason: string | null;
315
+ indexMode?: string;
316
+ schemaFingerprint?: string;
317
+ };
318
+ /**
319
+ * What a body search actually did, reported alongside the results.
320
+ *
321
+ * The bound is declared rather than hidden. A scan that silently stopped at the
322
+ * newest N messages would answer "not found" for older mail indistinguishably
323
+ * from a real absence, and the model has no way to tell the two apart — so when
324
+ * the candidate set is too wide this says so, with both numbers, and returns
325
+ * nothing rather than a partial answer dressed as a complete one.
326
+ */
327
+ type BodyScanReport = {
328
+ status: "ok";
329
+ candidates: number;
330
+ scanned: number;
331
+ matched: number;
332
+ /** Candidates with no readable message file. Usually a missing grant. */
333
+ unreadable: number;
334
+ elapsedMs: number;
335
+ bound: number;
336
+ } | {
337
+ status: "over-bound";
338
+ candidates: number;
339
+ bound: number;
340
+ };
341
+ type AppleMailClientOptions = {
342
+ config: Config;
343
+ logger?: Logger | undefined;
344
+ osascript?: OsascriptRunner | undefined;
345
+ };
346
+ declare class AppleMailClient {
347
+ #private;
348
+ readonly config: Config;
349
+ readonly runner: OsascriptRunner;
350
+ readonly mailboxes: MailboxMap;
351
+ constructor(opts: AppleMailClientOptions);
352
+ accounts(force?: boolean): Promise<MailAccount[]>;
353
+ /**
354
+ * Where the Envelope Index is and whether we may read it. Resolved lazily and
355
+ * cached: it needs an Apple Event to ask Mail for its own directory, and that
356
+ * answer does not change while the process lives.
357
+ */
358
+ locate(force?: boolean): Promise<LocateResult>;
359
+ lanes(): Promise<LaneStatus>;
360
+ listMailboxes(opts: {
361
+ accountUuids?: string[];
362
+ withCounts: boolean;
363
+ }): Promise<{
364
+ accountUuid: string;
365
+ accountName: string;
366
+ name: string;
367
+ unread?: number;
368
+ total?: number;
369
+ }[]>;
370
+ countMailbox(account: MailAccount, mailbox: string): Promise<{
371
+ accountUuid: string;
372
+ mailbox: string;
373
+ total: number | null;
374
+ unread: number | null;
375
+ }>;
376
+ /**
377
+ * The degraded listing lane. Capped rather than paginated on purpose: each
378
+ * extra message costs another ~42ms per property, so a "just fetch 500" call
379
+ * is a 20-second call, and a limit the model can see beats a timeout it cannot.
380
+ */
381
+ listRecent(account: MailAccount, mailbox: string, limit: number): Promise<{
382
+ mailbox: string;
383
+ total: number;
384
+ messages: MessageSummary[];
385
+ }>;
386
+ /** Resolve message ids inside one mailbox. This is the search-to-action bridge. */
387
+ getMessages(ref: {
388
+ accountUuid: string;
389
+ mailbox: string;
390
+ }, ids: number[], opts?: {
391
+ withContent?: boolean;
392
+ withSource?: boolean;
393
+ withHeaders?: boolean;
394
+ }): Promise<MessageSummary[]>;
395
+ /**
396
+ * Open the index on first use, once. A failure is remembered rather than
397
+ * retried on every call: the usual cause is a missing permission, which will
398
+ * not change until the user restarts the host app anyway.
399
+ */
400
+ index(): Promise<EnvelopeIndex | null>;
401
+ get indexError(): string | null;
402
+ /** How stale the index file is, so callers can see when they are reading history. */
403
+ indexAgeSeconds(): Promise<number | null>;
404
+ searchMessages(opts: Omit<SearchFilters, "mailboxRowids"> & {
405
+ account?: string | undefined;
406
+ mailbox?: string | undefined;
407
+ /** Free text matched against message BODIES. See body-scan.ts. */
408
+ body?: string | undefined;
409
+ }): Promise<{
410
+ messages: MessageSummary[];
411
+ source: "index" | "index+body-scan";
412
+ indexMode: string;
413
+ indexAgeSeconds: number | null;
414
+ walBlind: boolean;
415
+ bodyScan?: BodyScanReport;
416
+ } | null>;
417
+ threadOf(ref: string, limit: number): Promise<MessageSummary[] | null>;
418
+ countViaIndex(opts: {
419
+ account?: string | undefined;
420
+ mailbox?: string | undefined;
421
+ }): Promise<{
422
+ total: number;
423
+ unread: number;
424
+ } | null>;
425
+ /**
426
+ * Read a message body.
427
+ *
428
+ * Preferred path is the `.emlx` file on disk, which is instant and gives us
429
+ * the real MIME structure. Falls back to asking Mail for `content` (~250ms),
430
+ * which also covers accounts whose message caching keeps headers only — so a
431
+ * missing file is a slow answer, not a failure.
432
+ */
433
+ getMessageBody(ref: string, opts?: {
434
+ maxBodyBytes?: number;
435
+ }): Promise<{
436
+ message: MessageSummary;
437
+ parsed: ParsedMessage | null;
438
+ source: "emlx" | "applescript";
439
+ /** Why the file lane was not used. Present only when it was not. */
440
+ fallbackReason?: string;
441
+ }>;
442
+ getMessageSource(ref: string, opts: {
443
+ offset: number;
444
+ maxBytes: number;
445
+ }): Promise<{
446
+ source: string;
447
+ totalBytes: number | null;
448
+ truncated: boolean;
449
+ via: "emlx" | "applescript";
450
+ fallbackReason?: string;
451
+ }>;
452
+ /**
453
+ * Walk the message-file lane end to end, per account, and report what broke.
454
+ *
455
+ * This exists because the lane fails silently by construction: every reader
456
+ * falls back to AppleScript, so a lane that has been dead for months looks
457
+ * like a lane that is merely slow. Diagnostics reporting
458
+ * `fullDiskAccess: granted` beside a lane where every file read fails is the
459
+ * misleading part, and this is what replaces the guess with a probe.
460
+ *
461
+ * Deliberately per-account: the failure that motivated it was an account-level
462
+ * layout difference (Gmail nesting its mailboxes under `[Gmail].mbox/`), so a
463
+ * single-account probe would have reported a healthy lane.
464
+ */
465
+ probeMessageFile(): Promise<{
466
+ account: string;
467
+ accountUuid: string;
468
+ status: "ok" | "unreachable" | "headers-only" | "not-probed";
469
+ mailbox?: string;
470
+ rowid?: number;
471
+ path?: string;
472
+ reason?: string;
473
+ probed?: string[];
474
+ }[]>;
475
+ /**
476
+ * Save one attachment into the configured directory.
477
+ *
478
+ * The destination is resolved and then checked to be inside
479
+ * `APPLE_MAIL_ATTACHMENT_DIR`, so a filename of `../../.ssh/authorized_keys`
480
+ * lands nowhere. Existing files are never overwritten.
481
+ */
482
+ saveAttachment(ref: string, filename: string, opts?: {
483
+ overwrite?: boolean;
484
+ }): Promise<{
485
+ path: string;
486
+ bytes: number;
487
+ from: "inline" | "sidecar";
488
+ }>;
489
+ /** Set flags across refs, one Apple Event per distinct mailbox. */
490
+ setFlags(refs: string[], flags: {
491
+ read?: boolean;
492
+ flagged?: boolean;
493
+ flagIndex?: number;
494
+ junk?: boolean;
495
+ }): Promise<{
496
+ changed: number;
497
+ failed: number;
498
+ results: unknown[];
499
+ }>;
500
+ moveMessages(refs: string[], opts: {
501
+ destinationMailbox: string;
502
+ destinationAccount?: string;
503
+ }): Promise<{
504
+ moved: number;
505
+ failed: number;
506
+ destination: string;
507
+ results: unknown[];
508
+ }>;
509
+ deleteMessages(refs: string[]): Promise<{
510
+ deleted: number;
511
+ failed: number;
512
+ movedToTrash: boolean | null;
513
+ results: unknown[];
514
+ }>;
515
+ checkForNewMail(account?: string): Promise<unknown>;
516
+ sendMessage(opts: {
517
+ account?: string;
518
+ to: string[];
519
+ cc: string[];
520
+ bcc: string[];
521
+ subject: string;
522
+ body: string;
523
+ sendNow: boolean;
524
+ }): Promise<unknown>;
525
+ replyOrForward(ref: string, opts: {
526
+ mode: "reply" | "forward";
527
+ body?: string;
528
+ to?: string[];
529
+ replyToAll?: boolean;
530
+ sendNow: boolean;
531
+ }): Promise<unknown>;
532
+ }
533
+ //#endregion
534
+ //#region src/client/ref.d.ts
535
+ /**
536
+ * MessageRef — the one identifier any tool accepts or returns.
537
+ *
538
+ * A bare row id is not enough: the same integer means different messages in
539
+ * different mailboxes, and `messages.byId` is only resolvable inside a mailbox
540
+ * (a global `Mail.messages.byId(...)` fails with -1728). Handing the model a
541
+ * naked integer would let it address the wrong message; the ref carries the
542
+ * mailbox with it so that cannot happen.
543
+ *
544
+ * Wire format: m1:<accountUuid>/<mailboxPath>#<id>
545
+ *
546
+ * The `m1:` prefix is deliberate. If the Phase 0 spike ever shows that the
547
+ * SQLite ROWID is not the AppleScript message id, resolution has to fall back
548
+ * to the RFC 5322 Message-ID — and a versioned prefix makes that an additive
549
+ * change instead of a silent reinterpretation of every ref already in a
550
+ * conversation.
551
+ */
552
+ declare const REF_VERSION = "m1";
553
+ type MessageRef = {
554
+ accountUuid: string;
555
+ mailbox: string;
556
+ id: number;
557
+ };
558
+ declare const encodeRef: (ref: MessageRef) => string;
559
+ declare const decodeRef: (raw: string) => MessageRef;
560
+ /** Group refs by mailbox so a batch of them costs one Apple Event per mailbox, not per message. */
561
+ declare const groupRefsByMailbox: (refs: MessageRef[]) => Map<string, MessageRef[]>;
562
+ //#endregion
563
+ //#region src/server.d.ts
564
+ declare const SERVER_NAME: string;
565
+ declare const SERVER_VERSION: string;
566
+ type CreateServerOptions = {
567
+ config: Config;
568
+ logger?: Logger;
569
+ /** Injected by tests so nothing spawns a process or touches a real Mail. */
570
+ osascript?: OsascriptRunner;
571
+ };
572
+ type CreatedServer = {
573
+ server: McpServer;
574
+ client: AppleMailClient;
575
+ };
576
+ /**
577
+ * Build the server. Side-effect free: it opens no connection, spawns no
578
+ * process and reads no file, so a test can construct it freely and every
579
+ * external dependency arrives through an option.
580
+ */
581
+ declare const createServer: (opts: CreateServerOptions) => CreatedServer;
582
+ //#endregion
583
+ //#region src/tools/index.d.ts
584
+ type ToolContext = {
585
+ /**
586
+ * Register the mutating tools too. Off by default — with the flag off they are
587
+ * not merely refused, they are invisible and cannot be called at all.
588
+ */
589
+ allowWrites: boolean;
590
+ };
591
+ /**
592
+ * Register the Apple Mail tools.
593
+ *
594
+ * The registered set is a pure function of `allowWrites` and nothing else. In
595
+ * particular it does NOT vary with whether Full Disk Access is granted: that is
596
+ * a runtime condition which can change while the process lives, and MCP clients
597
+ * cache the tool list, so a tool that appears and disappears would leave clients
598
+ * calling names the server no longer has. Tools that need the index instead
599
+ * return a structured `degraded` result naming the missing capability.
600
+ */
601
+ declare const registerTools: (server: McpServer, client: AppleMailClient, ctx: ToolContext) => void;
602
+ //#endregion
603
+ export { AppleMailClient, AppleMailError, BUILD_INFO, type BuildInfo, type Config, type CreateServerOptions, IndexUnavailableError, type JxaEnvelope, type LaneStatus, type LocateResult, type Logger, type MailAccount, MailBusyError, MailNotRunningError, MailboxMap, MessageNotFoundError, type MessageRef, type MessageSummary, type OsascriptRunner, OsascriptTimeoutError, PlatformError, PreconditionError, ProtocolError, REF_VERSION, SERVER_NAME, SERVER_VERSION, SchemaDriftError, TccDeniedError, type ToolContext, WritesDisabledError, assertStaticScript, createOsascriptRunner, createServer, decodeRef, encodeRef, groupRefsByMailbox, inspectFile, loadConfig, locateEnvelopeIndex, mapOsaError, registerTools, withBusyRetry };
604
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","names":[],"sources":["../src/build-info.ts","../src/client/errors.ts","../src/client/locate.ts","../src/config.ts","../src/client/mime.ts","../src/client/emlx.ts","../src/client/schema.ts","../src/client/envelope.ts","../src/client/mailbox-map.ts","../src/client/mail.ts","../src/client/ref.ts","../src/server.ts","../src/tools/index.ts"],"mappings":"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"}
package/dist/index.js ADDED
@@ -0,0 +1,2 @@
1
+ import { A as WritesDisabledError, C as MessageNotFoundError, D as ProtocolError, E as PreconditionError, O as SchemaDriftError, S as MailNotRunningError, T as PlatformError, _ as locateEnvelopeIndex, a as loadConfig, c as decodeRef, d as assertStaticScript, f as createOsascriptRunner, g as inspectFile, h as MailboxMap, i as registerTools, j as BUILD_INFO, k as TccDeniedError, l as encodeRef, m as withBusyRetry, n as SERVER_VERSION, o as AppleMailClient, p as mapOsaError, r as createServer, s as REF_VERSION, t as SERVER_NAME, u as groupRefsByMailbox, v as AppleMailError, w as OsascriptTimeoutError, x as MailBusyError, y as IndexUnavailableError } from "./server-OoiI7t3N.js";
2
+ export { AppleMailClient, AppleMailError, BUILD_INFO, IndexUnavailableError, MailBusyError, MailNotRunningError, MailboxMap, MessageNotFoundError, OsascriptTimeoutError, PlatformError, PreconditionError, ProtocolError, REF_VERSION, SERVER_NAME, SERVER_VERSION, SchemaDriftError, TccDeniedError, WritesDisabledError, assertStaticScript, createOsascriptRunner, createServer, decodeRef, encodeRef, groupRefsByMailbox, inspectFile, loadConfig, locateEnvelopeIndex, mapOsaError, registerTools, withBusyRetry };