@kbzowski/mcp-inbox 0.1.0

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.
Files changed (47) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +396 -0
  3. package/dist/cache/db.d.ts +34 -0
  4. package/dist/cache/idle.d.ts +32 -0
  5. package/dist/cache/queries.d.ts +66 -0
  6. package/dist/cache/schema.d.ts +456 -0
  7. package/dist/cache/sync.d.ts +38 -0
  8. package/dist/config/env.d.ts +103 -0
  9. package/dist/errors/mapper.d.ts +10 -0
  10. package/dist/errors/types.d.ts +25 -0
  11. package/dist/formatters/markdown.d.ts +13 -0
  12. package/dist/imap/client.d.ts +37 -0
  13. package/dist/imap/folders.d.ts +19 -0
  14. package/dist/imap/mime-builder.d.ts +32 -0
  15. package/dist/imap/search.d.ts +28 -0
  16. package/dist/index.d.ts +1 -0
  17. package/dist/index.js +2572 -0
  18. package/dist/index.js.map +7 -0
  19. package/dist/migrations/0000_mean_the_santerians.sql +49 -0
  20. package/dist/migrations/0001_wooden_doomsday.sql +2 -0
  21. package/dist/migrations/meta/0000_snapshot.json +337 -0
  22. package/dist/migrations/meta/0001_snapshot.json +224 -0
  23. package/dist/migrations/meta/_journal.json +20 -0
  24. package/dist/server.d.ts +8 -0
  25. package/dist/smtp/client.d.ts +28 -0
  26. package/dist/tools/attachments/get-attachment.d.ts +43 -0
  27. package/dist/tools/define-tool.d.ts +61 -0
  28. package/dist/tools/drafts/create-draft.d.ts +11 -0
  29. package/dist/tools/drafts/get-draft.d.ts +10 -0
  30. package/dist/tools/drafts/list-drafts.d.ts +11 -0
  31. package/dist/tools/drafts/update-draft.d.ts +12 -0
  32. package/dist/tools/emails/delete-email.d.ts +6 -0
  33. package/dist/tools/emails/get-email.d.ts +10 -0
  34. package/dist/tools/emails/list-emails.d.ts +14 -0
  35. package/dist/tools/emails/mark-read.d.ts +9 -0
  36. package/dist/tools/emails/move-to-folder.d.ts +6 -0
  37. package/dist/tools/emails/search-emails.d.ts +17 -0
  38. package/dist/tools/emails/shared.d.ts +74 -0
  39. package/dist/tools/folders/list-folders.d.ts +7 -0
  40. package/dist/tools/registry.d.ts +21 -0
  41. package/dist/tools/send/forward.d.ts +11 -0
  42. package/dist/tools/send/reply.d.ts +12 -0
  43. package/dist/tools/send/send-draft.d.ts +5 -0
  44. package/dist/tools/send/send-email.d.ts +10 -0
  45. package/dist/tools/send/shared.d.ts +40 -0
  46. package/dist/utils/logger.d.ts +40 -0
  47. package/package.json +90 -0
@@ -0,0 +1,456 @@
1
+ /**
2
+ * Cache schema for mcp-inbox.
3
+ *
4
+ * Single source of truth - `drizzle-kit generate` produces SQL migrations
5
+ * from this file into src/cache/migrations/, and `drizzle-orm/node-sqlite`
6
+ * infers the query types (InferSelectModel / InferInsertModel) directly.
7
+ *
8
+ * Column naming: camelCase in JS, snake_case in SQL. Drizzle handles the
9
+ * translation, so queries written against this schema stay idiomatic on
10
+ * both sides.
11
+ */
12
+ /**
13
+ * One row per IMAP folder/mailbox path we've observed. `uidValidity`
14
+ * and `highestModseq` drive the incremental-sync algorithm; a change
15
+ * in uidValidity invalidates every cached email in the folder.
16
+ */
17
+ export declare const folders: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
18
+ name: "folders";
19
+ schema: undefined;
20
+ columns: {
21
+ name: import("drizzle-orm/sqlite-core").SQLiteColumn<{
22
+ name: "name";
23
+ tableName: "folders";
24
+ dataType: "string";
25
+ columnType: "SQLiteText";
26
+ data: string;
27
+ driverParam: string;
28
+ notNull: true;
29
+ hasDefault: false;
30
+ isPrimaryKey: true;
31
+ isAutoincrement: false;
32
+ hasRuntimeDefault: false;
33
+ enumValues: [string, ...string[]];
34
+ baseColumn: never;
35
+ identity: undefined;
36
+ generated: undefined;
37
+ }, {}, {
38
+ length: number | undefined;
39
+ }>;
40
+ delimiter: import("drizzle-orm/sqlite-core").SQLiteColumn<{
41
+ name: "delimiter";
42
+ tableName: "folders";
43
+ dataType: "string";
44
+ columnType: "SQLiteText";
45
+ data: string;
46
+ driverParam: string;
47
+ notNull: true;
48
+ hasDefault: false;
49
+ isPrimaryKey: false;
50
+ isAutoincrement: false;
51
+ hasRuntimeDefault: false;
52
+ enumValues: [string, ...string[]];
53
+ baseColumn: never;
54
+ identity: undefined;
55
+ generated: undefined;
56
+ }, {}, {
57
+ length: number | undefined;
58
+ }>;
59
+ specialUse: import("drizzle-orm/sqlite-core").SQLiteColumn<{
60
+ name: "special_use";
61
+ tableName: "folders";
62
+ dataType: "string";
63
+ columnType: "SQLiteText";
64
+ data: string;
65
+ driverParam: string;
66
+ notNull: false;
67
+ hasDefault: false;
68
+ isPrimaryKey: false;
69
+ isAutoincrement: false;
70
+ hasRuntimeDefault: false;
71
+ enumValues: [string, ...string[]];
72
+ baseColumn: never;
73
+ identity: undefined;
74
+ generated: undefined;
75
+ }, {}, {
76
+ length: number | undefined;
77
+ }>;
78
+ uidValidity: import("drizzle-orm/sqlite-core").SQLiteColumn<{
79
+ name: "uid_validity";
80
+ tableName: "folders";
81
+ dataType: "number";
82
+ columnType: "SQLiteInteger";
83
+ data: number;
84
+ driverParam: number;
85
+ notNull: true;
86
+ hasDefault: false;
87
+ isPrimaryKey: false;
88
+ isAutoincrement: false;
89
+ hasRuntimeDefault: false;
90
+ enumValues: undefined;
91
+ baseColumn: never;
92
+ identity: undefined;
93
+ generated: undefined;
94
+ }, {}, {}>;
95
+ uidNext: import("drizzle-orm/sqlite-core").SQLiteColumn<{
96
+ name: "uid_next";
97
+ tableName: "folders";
98
+ dataType: "number";
99
+ columnType: "SQLiteInteger";
100
+ data: number;
101
+ driverParam: number;
102
+ notNull: false;
103
+ hasDefault: false;
104
+ isPrimaryKey: false;
105
+ isAutoincrement: false;
106
+ hasRuntimeDefault: false;
107
+ enumValues: undefined;
108
+ baseColumn: never;
109
+ identity: undefined;
110
+ generated: undefined;
111
+ }, {}, {}>;
112
+ highestModseq: import("drizzle-orm/sqlite-core").SQLiteColumn<{
113
+ name: "highest_modseq";
114
+ tableName: "folders";
115
+ dataType: "number";
116
+ columnType: "SQLiteInteger";
117
+ data: number;
118
+ driverParam: number;
119
+ notNull: false;
120
+ hasDefault: false;
121
+ isPrimaryKey: false;
122
+ isAutoincrement: false;
123
+ hasRuntimeDefault: false;
124
+ enumValues: undefined;
125
+ baseColumn: never;
126
+ identity: undefined;
127
+ generated: undefined;
128
+ }, {}, {}>;
129
+ lastSyncedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
130
+ name: "last_synced_at";
131
+ tableName: "folders";
132
+ dataType: "number";
133
+ columnType: "SQLiteInteger";
134
+ data: number;
135
+ driverParam: number;
136
+ notNull: true;
137
+ hasDefault: false;
138
+ isPrimaryKey: false;
139
+ isAutoincrement: false;
140
+ hasRuntimeDefault: false;
141
+ enumValues: undefined;
142
+ baseColumn: never;
143
+ identity: undefined;
144
+ generated: undefined;
145
+ }, {}, {}>;
146
+ };
147
+ dialect: "sqlite";
148
+ }>;
149
+ /**
150
+ * Cached envelope + optional body for each message, keyed by folder + UID.
151
+ * IMAP UIDs are folder-scoped (and reset when UIDVALIDITY changes), so the
152
+ * composite primary key is mandatory - never use UID alone.
153
+ */
154
+ export declare const emails: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
155
+ name: "emails";
156
+ schema: undefined;
157
+ columns: {
158
+ folder: import("drizzle-orm/sqlite-core").SQLiteColumn<{
159
+ name: "folder";
160
+ tableName: "emails";
161
+ dataType: "string";
162
+ columnType: "SQLiteText";
163
+ data: string;
164
+ driverParam: string;
165
+ notNull: true;
166
+ hasDefault: false;
167
+ isPrimaryKey: false;
168
+ isAutoincrement: false;
169
+ hasRuntimeDefault: false;
170
+ enumValues: [string, ...string[]];
171
+ baseColumn: never;
172
+ identity: undefined;
173
+ generated: undefined;
174
+ }, {}, {
175
+ length: number | undefined;
176
+ }>;
177
+ uid: import("drizzle-orm/sqlite-core").SQLiteColumn<{
178
+ name: "uid";
179
+ tableName: "emails";
180
+ dataType: "number";
181
+ columnType: "SQLiteInteger";
182
+ data: number;
183
+ driverParam: number;
184
+ notNull: true;
185
+ hasDefault: false;
186
+ isPrimaryKey: false;
187
+ isAutoincrement: false;
188
+ hasRuntimeDefault: false;
189
+ enumValues: undefined;
190
+ baseColumn: never;
191
+ identity: undefined;
192
+ generated: undefined;
193
+ }, {}, {}>;
194
+ messageId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
195
+ name: "message_id";
196
+ tableName: "emails";
197
+ dataType: "string";
198
+ columnType: "SQLiteText";
199
+ data: string;
200
+ driverParam: string;
201
+ notNull: false;
202
+ hasDefault: false;
203
+ isPrimaryKey: false;
204
+ isAutoincrement: false;
205
+ hasRuntimeDefault: false;
206
+ enumValues: [string, ...string[]];
207
+ baseColumn: never;
208
+ identity: undefined;
209
+ generated: undefined;
210
+ }, {}, {
211
+ length: number | undefined;
212
+ }>;
213
+ subject: import("drizzle-orm/sqlite-core").SQLiteColumn<{
214
+ name: "subject";
215
+ tableName: "emails";
216
+ dataType: "string";
217
+ columnType: "SQLiteText";
218
+ data: string;
219
+ driverParam: string;
220
+ notNull: false;
221
+ hasDefault: false;
222
+ isPrimaryKey: false;
223
+ isAutoincrement: false;
224
+ hasRuntimeDefault: false;
225
+ enumValues: [string, ...string[]];
226
+ baseColumn: never;
227
+ identity: undefined;
228
+ generated: undefined;
229
+ }, {}, {
230
+ length: number | undefined;
231
+ }>;
232
+ fromAddr: import("drizzle-orm/sqlite-core").SQLiteColumn<{
233
+ name: "from_addr";
234
+ tableName: "emails";
235
+ dataType: "string";
236
+ columnType: "SQLiteText";
237
+ data: string;
238
+ driverParam: string;
239
+ notNull: false;
240
+ hasDefault: false;
241
+ isPrimaryKey: false;
242
+ isAutoincrement: false;
243
+ hasRuntimeDefault: false;
244
+ enumValues: [string, ...string[]];
245
+ baseColumn: never;
246
+ identity: undefined;
247
+ generated: undefined;
248
+ }, {}, {
249
+ length: number | undefined;
250
+ }>;
251
+ toAddrs: import("drizzle-orm/sqlite-core").SQLiteColumn<{
252
+ name: "to_addrs";
253
+ tableName: "emails";
254
+ dataType: "json";
255
+ columnType: "SQLiteTextJson";
256
+ data: string[];
257
+ driverParam: string;
258
+ notNull: false;
259
+ hasDefault: false;
260
+ isPrimaryKey: false;
261
+ isAutoincrement: false;
262
+ hasRuntimeDefault: false;
263
+ enumValues: undefined;
264
+ baseColumn: never;
265
+ identity: undefined;
266
+ generated: undefined;
267
+ }, {}, {
268
+ $type: string[];
269
+ }>;
270
+ ccAddrs: import("drizzle-orm/sqlite-core").SQLiteColumn<{
271
+ name: "cc_addrs";
272
+ tableName: "emails";
273
+ dataType: "json";
274
+ columnType: "SQLiteTextJson";
275
+ data: string[];
276
+ driverParam: string;
277
+ notNull: false;
278
+ hasDefault: false;
279
+ isPrimaryKey: false;
280
+ isAutoincrement: false;
281
+ hasRuntimeDefault: false;
282
+ enumValues: undefined;
283
+ baseColumn: never;
284
+ identity: undefined;
285
+ generated: undefined;
286
+ }, {}, {
287
+ $type: string[];
288
+ }>;
289
+ date: import("drizzle-orm/sqlite-core").SQLiteColumn<{
290
+ name: "date";
291
+ tableName: "emails";
292
+ dataType: "number";
293
+ columnType: "SQLiteInteger";
294
+ data: number;
295
+ driverParam: number;
296
+ notNull: false;
297
+ hasDefault: false;
298
+ isPrimaryKey: false;
299
+ isAutoincrement: false;
300
+ hasRuntimeDefault: false;
301
+ enumValues: undefined;
302
+ baseColumn: never;
303
+ identity: undefined;
304
+ generated: undefined;
305
+ }, {}, {}>;
306
+ flags: import("drizzle-orm/sqlite-core").SQLiteColumn<{
307
+ name: "flags";
308
+ tableName: "emails";
309
+ dataType: "json";
310
+ columnType: "SQLiteTextJson";
311
+ data: string[];
312
+ driverParam: string;
313
+ notNull: true;
314
+ hasDefault: false;
315
+ isPrimaryKey: false;
316
+ isAutoincrement: false;
317
+ hasRuntimeDefault: false;
318
+ enumValues: undefined;
319
+ baseColumn: never;
320
+ identity: undefined;
321
+ generated: undefined;
322
+ }, {}, {
323
+ $type: string[];
324
+ }>;
325
+ hasAttachments: import("drizzle-orm/sqlite-core").SQLiteColumn<{
326
+ name: "has_attachments";
327
+ tableName: "emails";
328
+ dataType: "boolean";
329
+ columnType: "SQLiteBoolean";
330
+ data: boolean;
331
+ driverParam: number;
332
+ notNull: true;
333
+ hasDefault: true;
334
+ isPrimaryKey: false;
335
+ isAutoincrement: false;
336
+ hasRuntimeDefault: false;
337
+ enumValues: undefined;
338
+ baseColumn: never;
339
+ identity: undefined;
340
+ generated: undefined;
341
+ }, {}, {}>;
342
+ envelopeJson: import("drizzle-orm/sqlite-core").SQLiteColumn<{
343
+ name: "envelope_json";
344
+ tableName: "emails";
345
+ dataType: "string";
346
+ columnType: "SQLiteText";
347
+ data: string;
348
+ driverParam: string;
349
+ notNull: true;
350
+ hasDefault: false;
351
+ isPrimaryKey: false;
352
+ isAutoincrement: false;
353
+ hasRuntimeDefault: false;
354
+ enumValues: [string, ...string[]];
355
+ baseColumn: never;
356
+ identity: undefined;
357
+ generated: undefined;
358
+ }, {}, {
359
+ length: number | undefined;
360
+ }>;
361
+ bodyText: import("drizzle-orm/sqlite-core").SQLiteColumn<{
362
+ name: "body_text";
363
+ tableName: "emails";
364
+ dataType: "string";
365
+ columnType: "SQLiteText";
366
+ data: string;
367
+ driverParam: string;
368
+ notNull: false;
369
+ hasDefault: false;
370
+ isPrimaryKey: false;
371
+ isAutoincrement: false;
372
+ hasRuntimeDefault: false;
373
+ enumValues: [string, ...string[]];
374
+ baseColumn: never;
375
+ identity: undefined;
376
+ generated: undefined;
377
+ }, {}, {
378
+ length: number | undefined;
379
+ }>;
380
+ bodyHtml: import("drizzle-orm/sqlite-core").SQLiteColumn<{
381
+ name: "body_html";
382
+ tableName: "emails";
383
+ dataType: "string";
384
+ columnType: "SQLiteText";
385
+ data: string;
386
+ driverParam: string;
387
+ notNull: false;
388
+ hasDefault: false;
389
+ isPrimaryKey: false;
390
+ isAutoincrement: false;
391
+ hasRuntimeDefault: false;
392
+ enumValues: [string, ...string[]];
393
+ baseColumn: never;
394
+ identity: undefined;
395
+ generated: undefined;
396
+ }, {}, {
397
+ length: number | undefined;
398
+ }>;
399
+ modseq: import("drizzle-orm/sqlite-core").SQLiteColumn<{
400
+ name: "modseq";
401
+ tableName: "emails";
402
+ dataType: "number";
403
+ columnType: "SQLiteInteger";
404
+ data: number;
405
+ driverParam: number;
406
+ notNull: false;
407
+ hasDefault: false;
408
+ isPrimaryKey: false;
409
+ isAutoincrement: false;
410
+ hasRuntimeDefault: false;
411
+ enumValues: undefined;
412
+ baseColumn: never;
413
+ identity: undefined;
414
+ generated: undefined;
415
+ }, {}, {}>;
416
+ cachedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
417
+ name: "cached_at";
418
+ tableName: "emails";
419
+ dataType: "number";
420
+ columnType: "SQLiteInteger";
421
+ data: number;
422
+ driverParam: number;
423
+ notNull: true;
424
+ hasDefault: false;
425
+ isPrimaryKey: false;
426
+ isAutoincrement: false;
427
+ hasRuntimeDefault: false;
428
+ enumValues: undefined;
429
+ baseColumn: never;
430
+ identity: undefined;
431
+ generated: undefined;
432
+ }, {}, {}>;
433
+ bodyCachedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
434
+ name: "body_cached_at";
435
+ tableName: "emails";
436
+ dataType: "number";
437
+ columnType: "SQLiteInteger";
438
+ data: number;
439
+ driverParam: number;
440
+ notNull: false;
441
+ hasDefault: false;
442
+ isPrimaryKey: false;
443
+ isAutoincrement: false;
444
+ hasRuntimeDefault: false;
445
+ enumValues: undefined;
446
+ baseColumn: never;
447
+ identity: undefined;
448
+ generated: undefined;
449
+ }, {}, {}>;
450
+ };
451
+ dialect: "sqlite";
452
+ }>;
453
+ export type Folder = typeof folders.$inferSelect;
454
+ export type FolderInsert = typeof folders.$inferInsert;
455
+ export type Email = typeof emails.$inferSelect;
456
+ export type EmailInsert = typeof emails.$inferInsert;
@@ -0,0 +1,38 @@
1
+ import type { ImapFlow, MessageStructureObject } from 'imapflow';
2
+ import type { CacheDb } from './db';
3
+ export interface SyncContext {
4
+ db: CacheDb;
5
+ imap: ImapFlow;
6
+ }
7
+ export type SyncType = 'full' | 'incremental' | 'skipped';
8
+ export interface SyncResult {
9
+ folder: string;
10
+ syncType: SyncType;
11
+ fetched: number;
12
+ /** Time in ms spent inside syncFolder - useful for telemetry / tests. */
13
+ durationMs: number;
14
+ }
15
+ /**
16
+ * Synchronise a single folder's cache with the server.
17
+ *
18
+ * Algorithm:
19
+ * 1. SELECT the mailbox; read UIDVALIDITY, UIDNEXT, HIGHESTMODSEQ.
20
+ * 2. If cached UIDVALIDITY differs from server's → wipe folder cache
21
+ * and do a full envelope fetch.
22
+ * 3. If server supports CONDSTORE and we have a cached HIGHESTMODSEQ →
23
+ * fetch only messages with MODSEQ > cached.
24
+ * 4. Otherwise fall back to a full fetch (Phase 3b defers the
25
+ * UID-diff fallback for CONDSTORE-less servers).
26
+ * 5. Persist the new folder sync state.
27
+ */
28
+ export declare function syncFolder(ctx: SyncContext, folderPath: string): Promise<SyncResult>;
29
+ /**
30
+ * Walk an IMAP body structure tree, returning true if any part looks like
31
+ * a real attachment. A part counts when:
32
+ * - its Content-Disposition is "attachment", or
33
+ * - its dispositionParameters include a filename (even if disposition
34
+ * is missing or "inline" - some clients misclassify).
35
+ *
36
+ * Exported for unit testing - consumers outside sync.ts shouldn't need it.
37
+ */
38
+ export declare function hasAttachments(structure: MessageStructureObject | undefined): boolean;
@@ -0,0 +1,103 @@
1
+ import { z } from 'zod';
2
+ declare const EnvSchema: z.ZodPipe<z.ZodObject<{
3
+ IMAP_USER: z.ZodString;
4
+ IMAP_PASSWORD: z.ZodString;
5
+ IMAP_HOST: z.ZodString;
6
+ IMAP_PORT: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
7
+ IMAP_TLS: z.ZodDefault<z.ZodPipe<z.ZodEnum<{
8
+ true: "true";
9
+ false: "false";
10
+ }>, z.ZodTransform<boolean, "true" | "false">>>;
11
+ IMAP_TLS_REJECT_UNAUTHORIZED: z.ZodDefault<z.ZodPipe<z.ZodEnum<{
12
+ true: "true";
13
+ false: "false";
14
+ }>, z.ZodTransform<boolean, "true" | "false">>>;
15
+ IMAP_AUTH_TIMEOUT_MS: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
16
+ SMTP_HOST: z.ZodOptional<z.ZodString>;
17
+ SMTP_PORT: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
18
+ SMTP_SECURE: z.ZodDefault<z.ZodPipe<z.ZodEnum<{
19
+ true: "true";
20
+ false: "false";
21
+ }>, z.ZodTransform<boolean, "true" | "false">>>;
22
+ SMTP_USER: z.ZodOptional<z.ZodString>;
23
+ SMTP_PASSWORD: z.ZodOptional<z.ZodString>;
24
+ IMAP_CACHE_ENABLED: z.ZodDefault<z.ZodPipe<z.ZodEnum<{
25
+ true: "true";
26
+ false: "false";
27
+ }>, z.ZodTransform<boolean, "true" | "false">>>;
28
+ IMAP_CACHE_DIR: z.ZodOptional<z.ZodString>;
29
+ IMAP_CACHE_BODY_INLINE: z.ZodDefault<z.ZodPipe<z.ZodEnum<{
30
+ true: "true";
31
+ false: "false";
32
+ }>, z.ZodTransform<boolean, "true" | "false">>>;
33
+ IMAP_CACHE_DEFAULT_STALENESS_SEC: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
34
+ IMAP_CACHE_RETAIN_DAYS: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
35
+ IMAP_IDLE_ENABLED: z.ZodDefault<z.ZodPipe<z.ZodEnum<{
36
+ true: "true";
37
+ false: "false";
38
+ }>, z.ZodTransform<boolean, "true" | "false">>>;
39
+ IMAP_IDLE_FOLDERS: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>>;
40
+ DEBUG: z.ZodOptional<z.ZodString>;
41
+ }, z.core.$strip>, z.ZodTransform<{
42
+ imap: {
43
+ user: string;
44
+ password: string;
45
+ host: string;
46
+ port: number;
47
+ tls: boolean;
48
+ tlsRejectUnauthorized: boolean;
49
+ authTimeoutMs: number;
50
+ };
51
+ smtp: {
52
+ host: string;
53
+ port: number;
54
+ secure: boolean;
55
+ user: string;
56
+ password: string;
57
+ };
58
+ cache: {
59
+ enabled: boolean;
60
+ dir: string;
61
+ eagerBodyCache: boolean;
62
+ defaultStalenessSec: number;
63
+ retainDays: number;
64
+ };
65
+ idle: {
66
+ enabled: boolean;
67
+ folders: string[];
68
+ };
69
+ debug: string;
70
+ }, {
71
+ IMAP_USER: string;
72
+ IMAP_PASSWORD: string;
73
+ IMAP_HOST: string;
74
+ IMAP_PORT: number;
75
+ IMAP_TLS: boolean;
76
+ IMAP_TLS_REJECT_UNAUTHORIZED: boolean;
77
+ IMAP_AUTH_TIMEOUT_MS: number;
78
+ SMTP_PORT: number;
79
+ SMTP_SECURE: boolean;
80
+ IMAP_CACHE_ENABLED: boolean;
81
+ IMAP_CACHE_BODY_INLINE: boolean;
82
+ IMAP_CACHE_DEFAULT_STALENESS_SEC: number;
83
+ IMAP_CACHE_RETAIN_DAYS: number;
84
+ IMAP_IDLE_ENABLED: boolean;
85
+ IMAP_IDLE_FOLDERS: string[];
86
+ SMTP_HOST?: string | undefined;
87
+ SMTP_USER?: string | undefined;
88
+ SMTP_PASSWORD?: string | undefined;
89
+ IMAP_CACHE_DIR?: string | undefined;
90
+ DEBUG?: string | undefined;
91
+ }>>;
92
+ export type AppConfig = z.infer<typeof EnvSchema>;
93
+ /**
94
+ * Parses process.env and returns a validated AppConfig.
95
+ * Throws a readable error on invalid/missing configuration;
96
+ * the caller is responsible for exiting the process.
97
+ *
98
+ * Empty-string values are treated as "not set". This matches how users
99
+ * typically write optional env vars in .env files (`SMTP_HOST=`) and
100
+ * prevents empty strings from defeating the `??` fallbacks downstream.
101
+ */
102
+ export declare function loadConfig(env?: NodeJS.ProcessEnv): AppConfig;
103
+ export {};
@@ -0,0 +1,10 @@
1
+ import { ImapError, SmtpError, McpInboxError, type ErrorCode } from './types';
2
+ /**
3
+ * Convert raw IMAP/SMTP driver errors into actionable McpInboxError instances.
4
+ * The returned `userMessage` is safe to surface to the MCP client - no host,
5
+ * port, or credentials leak through.
6
+ */
7
+ export declare function mapImapError(err: unknown): ImapError;
8
+ export declare function mapSmtpError(err: unknown): SmtpError;
9
+ export declare function isMcpInboxError(err: unknown): err is McpInboxError;
10
+ export declare function errorCodeOf(err: unknown): ErrorCode;
@@ -0,0 +1,25 @@
1
+ /**
2
+ * Error hierarchy for mcp-inbox.
3
+ *
4
+ * - `McpInboxError` is the base; every error we throw should extend it.
5
+ * - `code` is a stable machine identifier (never change).
6
+ * - `userMessage` is the human-readable, actionable message returned to the
7
+ * MCP client. Never leak raw server output or credentials into this field.
8
+ * - `cause` is propagated via `Error`'s ES2022 `{ cause }` options object and
9
+ * inherited from the base class - no need to redeclare on subclasses.
10
+ */
11
+ export type ErrorCode = 'CONFIG_INVALID' | 'IMAP_AUTH_FAILED' | 'IMAP_HOST_UNREACHABLE' | 'IMAP_CONNECTION_REFUSED' | 'IMAP_TIMEOUT' | 'IMAP_FOLDER_NOT_FOUND' | 'IMAP_MESSAGE_NOT_FOUND' | 'IMAP_UIDVALIDITY_CHANGED' | 'IMAP_UNKNOWN' | 'SMTP_AUTH_FAILED' | 'SMTP_SEND_FAILED' | 'SMTP_UNKNOWN' | 'CACHE_IO_FAILED' | 'CACHE_SCHEMA_MISMATCH' | 'ATTACHMENT_TOO_LARGE' | 'ATTACHMENT_NOT_FOUND' | 'TOOL_INVALID_INPUT' | 'INTERNAL';
12
+ export declare class McpInboxError extends Error {
13
+ readonly code: ErrorCode;
14
+ readonly userMessage: string;
15
+ constructor(code: ErrorCode, userMessage: string, cause?: unknown);
16
+ }
17
+ export declare class ImapError extends McpInboxError {
18
+ }
19
+ export declare class SmtpError extends McpInboxError {
20
+ }
21
+ export declare class CacheError extends McpInboxError {
22
+ }
23
+ export declare class ToolInputError extends McpInboxError {
24
+ constructor(userMessage: string, cause?: unknown);
25
+ }
@@ -0,0 +1,13 @@
1
+ import type { Email } from '../cache/schema';
2
+ export interface FolderSummary {
3
+ path: string;
4
+ delimiter: string;
5
+ specialUse: string | null;
6
+ flags?: string[];
7
+ }
8
+ export declare function formatFoldersMarkdown(folders: readonly FolderSummary[]): string;
9
+ /**
10
+ * Compact one-email-per-row summary. Unseen messages are bolded so the
11
+ * agent can scan inbox status at a glance.
12
+ */
13
+ export declare function formatEmailListMarkdown(emails: readonly Email[]): string;
@@ -0,0 +1,37 @@
1
+ import { ImapFlow } from 'imapflow';
2
+ import type { AppConfig } from '../config/env';
3
+ /**
4
+ * Build and connect an ImapFlow instance from the env-level IMAP config.
5
+ * Callers decide whether to hold it long-lived (via ImapClient below) or
6
+ * dedicate it to a single purpose such as IDLE watching a folder.
7
+ *
8
+ * Driver errors are mapped to ImapError so auth and DNS failures surface
9
+ * with actionable messages instead of raw driver output.
10
+ */
11
+ export declare function createImapConnection(config: AppConfig['imap']): Promise<ImapFlow>;
12
+ /**
13
+ * Thin connection manager over ImapFlow.
14
+ *
15
+ * Responsibilities:
16
+ * - Own one long-lived connection for the process lifetime (avoid
17
+ * per-tool-call TLS handshake + LOGIN round trips, which some providers
18
+ * rate-limit at ~15 LOGIN/min per account).
19
+ * - Reconnect transparently when the connection drops (NAT timeouts,
20
+ * server restarts, network hiccups).
21
+ * - Map driver-level errors into actionable `ImapError` instances via
22
+ * `errors/mapper.ts` - callers never see raw ImapFlow errors.
23
+ * - Tear down cleanly on SIGINT/SIGTERM via `close()`.
24
+ */
25
+ export declare class ImapClient {
26
+ #private;
27
+ constructor(config: AppConfig['imap']);
28
+ /**
29
+ * Returns an authenticated ImapFlow instance, connecting if necessary.
30
+ * Multiple concurrent callers share the same in-flight connection attempt.
31
+ */
32
+ connection(): Promise<ImapFlow>;
33
+ /**
34
+ * Cleanly close the connection. Safe to call multiple times.
35
+ */
36
+ close(): Promise<void>;
37
+ }