@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.
- package/LICENSE +21 -0
- package/README.md +318 -0
- package/dist/cli.d.ts +1 -0
- package/dist/cli.js +28 -0
- package/dist/cli.js.map +1 -0
- package/dist/index.d.ts +604 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +2 -0
- package/dist/server-OoiI7t3N.js +3350 -0
- package/dist/server-OoiI7t3N.js.map +1 -0
- package/package.json +70 -0
package/dist/index.d.ts
ADDED
|
@@ -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 };
|