@miguelarios/email-mcp 0.9.0 → 0.11.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.
@@ -1,17 +1,53 @@
1
- import { toPimError } from "@miguelarios/pim-core";
1
+ import { realpathSync } from "node:fs";
2
+ import { resolve, sep } from "node:path";
3
+ import { confirmDestructive, fail, structured, toolError, } from "@miguelarios/pim-core/mcp";
2
4
  import { simpleParser } from "mailparser";
3
5
  import { htmlToMarkdown } from "../htmlToMarkdown.js";
6
+ import { attachmentSchema, createFolderResultSchema, deleteResultSchema, emailFullSchema, folderListSchema, folderStatusSchema, markResultSchema, moveResultSchema, rawEmailSchema, searchResultSchema, sendResultSchema, } from "./emailSchemas.js";
7
+ function assertAttachmentPathAllowed(p) {
8
+ const allowedRoot = process.env.EMAIL_ATTACHMENT_DIR;
9
+ if (!allowedRoot) {
10
+ throw new Error("attachments[].path is disabled — set EMAIL_ATTACHMENT_DIR to a directory to allow file attachments, or pass content instead");
11
+ }
12
+ const root = realpathSync(resolve(allowedRoot));
13
+ const target = realpathSync(resolve(p));
14
+ if (target !== root && !target.startsWith(root + sep)) {
15
+ throw new Error(`attachment path is outside EMAIL_ATTACHMENT_DIR: ${p}`);
16
+ }
17
+ }
18
+ /** Runs a handler body, converting anything thrown into a tool execution error. */
19
+ async function run(body) {
20
+ try {
21
+ return await body();
22
+ }
23
+ catch (err) {
24
+ return toolError(err);
25
+ }
26
+ }
27
+ function invalid(message) {
28
+ return fail("INVALID_INPUT", message);
29
+ }
30
+ const FOLDER_PROP = {
31
+ type: "string",
32
+ description: "IMAP folder. Defaults to INBOX.",
33
+ };
34
+ const UIDS_PROP = (description) => ({ type: "array", items: { type: "number" }, description });
35
+ const READ_ONLY = {
36
+ readOnlyHint: true,
37
+ destructiveHint: false,
38
+ idempotentHint: true,
39
+ openWorldHint: true,
40
+ };
4
41
  export const EMAIL_TOOLS = [
5
42
  {
6
43
  name: "search_emails",
44
+ title: "Search Emails",
7
45
  description: "Search and list emails in a folder. Returns email summaries with configurable sorting (default: date descending). All filters combine with AND logic. Use the dedicated fields (subject, from, to, etc.) for most searches. Note: for result sets >1000, non-date sort fields are approximate (sorted within page only).",
46
+ annotations: READ_ONLY,
8
47
  inputSchema: {
9
48
  type: "object",
10
49
  properties: {
11
- folder: {
12
- type: "string",
13
- description: 'IMAP folder path. Defaults to "INBOX".',
14
- },
50
+ folder: { type: "string", description: 'IMAP folder path. Defaults to "INBOX".' },
15
51
  subject: {
16
52
  type: "string",
17
53
  description: "Search subject line. Multiple words are ANDed. Use -term to exclude. Use quotes for exact phrase: '\"weekly report\"'.",
@@ -24,14 +60,8 @@ export const EMAIL_TOOLS = [
24
60
  type: "string",
25
61
  description: "Match recipient name or email address (substring match).",
26
62
  },
27
- cc: {
28
- type: "string",
29
- description: "Match CC recipient (substring match).",
30
- },
31
- bcc: {
32
- type: "string",
33
- description: "Match BCC recipient (substring match).",
34
- },
63
+ cc: { type: "string", description: "Match CC recipient (substring match)." },
64
+ bcc: { type: "string", description: "Match BCC recipient (substring match)." },
35
65
  body: {
36
66
  type: "string",
37
67
  description: "Search body text. Multiple words are ANDed. Use -term to exclude. Use quotes for exact phrase: '\"project update\"'.",
@@ -40,35 +70,17 @@ export const EMAIL_TOOLS = [
40
70
  type: "string",
41
71
  description: 'Search all message content (headers + body, IMAP TEXT). Multiple words are ANDed. Use quotes for exact phrase. Use -term for exclusion. Examples: "budget", "report -draft", \'"quarterly report"\'.',
42
72
  },
43
- since: {
44
- type: "string",
45
- description: "Emails on or after this date (YYYY-MM-DD).",
46
- },
47
- before: {
48
- type: "string",
49
- description: "Emails before this date (YYYY-MM-DD).",
50
- },
51
- unread: {
52
- type: "boolean",
53
- description: "Filter by unread status.",
54
- },
55
- flagged: {
56
- type: "boolean",
57
- description: "Filter by flagged/starred status.",
58
- },
59
- hasAttachment: {
60
- type: "boolean",
61
- description: "Filter for emails with attachments.",
62
- },
73
+ since: { type: "string", description: "Emails on or after this date (YYYY-MM-DD)." },
74
+ before: { type: "string", description: "Emails before this date (YYYY-MM-DD)." },
75
+ unread: { type: "boolean", description: "Filter by unread status." },
76
+ flagged: { type: "boolean", description: "Filter by flagged/starred status." },
77
+ hasAttachment: { type: "boolean", description: "Filter for emails with attachments." },
63
78
  tags: {
64
79
  type: "array",
65
80
  items: { type: "string" },
66
81
  description: "Filter by IMAP keyword flags.",
67
82
  },
68
- limit: {
69
- type: "number",
70
- description: "Max results to return. Defaults to 50.",
71
- },
83
+ limit: { type: "number", description: "Max results to return. Defaults to 50." },
72
84
  offset: {
73
85
  type: "number",
74
86
  description: "Number of results to skip for pagination. Defaults to 0.",
@@ -85,10 +97,37 @@ export const EMAIL_TOOLS = [
85
97
  },
86
98
  },
87
99
  },
100
+ outputSchema: searchResultSchema,
101
+ handler: (args, { imap }) => run(async () => {
102
+ const searchParams = {
103
+ hasWords: args.hasWords,
104
+ body: args.body,
105
+ from: args.from,
106
+ to: args.to,
107
+ cc: args.cc,
108
+ bcc: args.bcc,
109
+ subject: args.subject,
110
+ since: args.since,
111
+ before: args.before,
112
+ unread: args.unread,
113
+ flagged: args.flagged,
114
+ hasAttachment: args.hasAttachment,
115
+ tags: args.tags,
116
+ };
117
+ const emails = await imap.searchEmails(args.folder || "INBOX", searchParams, {
118
+ limit: args.limit || 50,
119
+ offset: args.offset || 0,
120
+ sortBy: args.sortBy ?? "date",
121
+ sortOrder: args.sortOrder ?? "desc",
122
+ });
123
+ return structured({ emails, count: emails.length });
124
+ }),
88
125
  },
89
126
  {
90
127
  name: "get_email",
128
+ title: "Get Email",
91
129
  description: "Fetch a full email by UID including headers, body, and attachment metadata. Returns body as markdown by default for token efficiency. Use format='html' or format='text' for raw content.",
130
+ annotations: READ_ONLY,
92
131
  inputSchema: {
93
132
  type: "object",
94
133
  properties: {
@@ -96,10 +135,7 @@ export const EMAIL_TOOLS = [
96
135
  type: "string",
97
136
  description: "IMAP folder containing the email. Defaults to INBOX.",
98
137
  },
99
- uid: {
100
- type: "number",
101
- description: "The UID of the email to fetch.",
102
- },
138
+ uid: { type: "number", description: "The UID of the email to fetch." },
103
139
  format: {
104
140
  type: "string",
105
141
  enum: ["markdown", "html", "text"],
@@ -108,10 +144,44 @@ export const EMAIL_TOOLS = [
108
144
  },
109
145
  required: ["uid"],
110
146
  },
147
+ outputSchema: emailFullSchema,
148
+ handler: (args, { imap }) => run(async () => {
149
+ const format = args.format || "markdown";
150
+ const email = await imap.fetchEmail(args.folder || "INBOX", args.uid);
151
+ if (format === "markdown") {
152
+ try {
153
+ if (email.htmlBody) {
154
+ email.markdownBody = await htmlToMarkdown(email.htmlBody);
155
+ }
156
+ else if (email.textBody) {
157
+ email.markdownBody = email.textBody;
158
+ }
159
+ delete email.htmlBody;
160
+ delete email.textBody;
161
+ }
162
+ catch {
163
+ // Conversion failed — fall back to returning raw bodies unchanged
164
+ }
165
+ }
166
+ else if (format === "text") {
167
+ delete email.htmlBody;
168
+ }
169
+ else if (format === "html") {
170
+ delete email.textBody;
171
+ }
172
+ return structured(email);
173
+ }),
111
174
  },
112
175
  {
113
176
  name: "send_email",
114
- description: "Compose and send an email, or save it as a draft. Supports replies with automatic threading — when replyToUid is provided, the tool fetches the original email and sets correct In-Reply-To/References headers and Re: subject prefix automatically. Set saveToDrafts to true to save to the Drafts folder instead of sending. Sent emails are automatically copied to the Sent folder.",
177
+ title: "Send Email",
178
+ description: "Compose and send an email, or save it as a draft. Supports replies with automatic threading — when replyToUid is provided, the tool fetches the original email and sets correct In-Reply-To/References headers and Re: subject prefix automatically. Set saveToDrafts to true to save to the Drafts folder instead of sending. Sending (but not saving a draft) asks the user to confirm first. Sent emails are automatically copied to the Sent folder.",
179
+ annotations: {
180
+ readOnlyHint: false,
181
+ destructiveHint: false,
182
+ idempotentHint: false,
183
+ openWorldHint: true,
184
+ },
115
185
  inputSchema: {
116
186
  type: "object",
117
187
  properties: {
@@ -120,28 +190,14 @@ export const EMAIL_TOOLS = [
120
190
  items: { type: "string" },
121
191
  description: "Recipient email addresses.",
122
192
  },
123
- cc: {
124
- type: "array",
125
- items: { type: "string" },
126
- description: "CC email addresses.",
127
- },
128
- bcc: {
129
- type: "array",
130
- items: { type: "string" },
131
- description: "BCC email addresses.",
132
- },
193
+ cc: { type: "array", items: { type: "string" }, description: "CC email addresses." },
194
+ bcc: { type: "array", items: { type: "string" }, description: "BCC email addresses." },
133
195
  subject: {
134
196
  type: "string",
135
197
  description: "Email subject line. Required for new emails. When replyToUid is set and subject is omitted, automatically uses 'Re: <original subject>'. When provided explicitly, used as-is.",
136
198
  },
137
- text: {
138
- type: "string",
139
- description: "Plain text body.",
140
- },
141
- html: {
142
- type: "string",
143
- description: "HTML body.",
144
- },
199
+ text: { type: "string", description: "Plain text body." },
200
+ html: { type: "string", description: "HTML body." },
145
201
  attachments: {
146
202
  type: "array",
147
203
  items: {
@@ -150,12 +206,9 @@ export const EMAIL_TOOLS = [
150
206
  filename: { type: "string" },
151
207
  path: {
152
208
  type: "string",
153
- description: "File path to attach.",
154
- },
155
- content: {
156
- type: "string",
157
- description: "String content to attach.",
209
+ description: "File path to attach. Disabled unless the server has EMAIL_ATTACHMENT_DIR set to an allowed directory; the resolved path must be inside it. Use content instead if unavailable.",
158
210
  },
211
+ content: { type: "string", description: "String content to attach." },
159
212
  },
160
213
  required: ["filename"],
161
214
  },
@@ -173,48 +226,158 @@ export const EMAIL_TOOLS = [
173
226
  type: "boolean",
174
227
  description: "When true, saves the composed email to the Drafts folder instead of sending it. The draft will appear in any email client and can be edited there. Defaults to false.",
175
228
  },
229
+ from: {
230
+ type: "string",
231
+ description: "Optional visible From address. Must be SMTP_USER or listed in the server's SMTP_ALLOWED_FROM allowlist; anything else is rejected. SMTP envelope delivery still uses the account sender, so an address on a different domain than SMTP_USER may fail DMARC at the recipient.",
232
+ },
233
+ fromName: {
234
+ type: "string",
235
+ description: "Optional visible display name for the From header. Useful when multiple agents share one allowed sender address. Changes only the display name, never the address.",
236
+ },
176
237
  },
177
238
  required: ["to"],
178
239
  },
240
+ outputSchema: sendResultSchema,
241
+ handler: async (args, { imap, smtp }, ctx) => {
242
+ const to = Array.isArray(args.to) ? args.to : [args.to];
243
+ const cc = args.cc == null ? undefined : Array.isArray(args.cc) ? args.cc : [args.cc];
244
+ const bcc = args.bcc == null ? undefined : Array.isArray(args.bcc) ? args.bcc : [args.bcc];
245
+ const saveToDrafts = args.saveToDrafts || false;
246
+ // Validation: subject required when not replying
247
+ if (!args.subject && !args.replyToUid) {
248
+ return invalid("subject is required when not replying to an existing email");
249
+ }
250
+ // Saving a draft is reversible; actually putting mail on the wire is not.
251
+ if (!saveToDrafts) {
252
+ const recipients = [...to, ...(cc ?? []), ...(bcc ?? [])].join(", ");
253
+ const gate = confirmDestructive(ctx, "confirm_send_email", `Send this email to ${recipients}${args.subject ? ` with subject "${args.subject}"` : ""}? This cannot be undone.`);
254
+ if (gate.status === "interrupt")
255
+ return gate.result;
256
+ }
257
+ return run(async () => {
258
+ for (const att of args.attachments ?? []) {
259
+ if (att.path)
260
+ assertAttachmentPathAllowed(att.path);
261
+ }
262
+ const replyToFolder = args.replyToFolder || "INBOX";
263
+ let subject = args.subject;
264
+ // Threading: fetch original email for reply context
265
+ let inReplyTo;
266
+ let references;
267
+ if (args.replyToUid) {
268
+ const original = await imap.fetchEmail(replyToFolder, args.replyToUid);
269
+ inReplyTo = original.messageId;
270
+ references = [...(original.references || [])];
271
+ if (original.messageId && !references.includes(original.messageId)) {
272
+ references.push(original.messageId);
273
+ }
274
+ if (!subject) {
275
+ const origSubject = original.subject || "";
276
+ subject = origSubject.startsWith("Re:") ? origSubject : `Re: ${origSubject}`;
277
+ }
278
+ }
279
+ // Compose RFC 822 message
280
+ const from = smtp.formatFromHeader(smtp.resolveFromAddress(args.from), args.fromName);
281
+ const messageOptions = {
282
+ from,
283
+ to,
284
+ cc,
285
+ bcc,
286
+ subject: subject,
287
+ text: args.text,
288
+ html: args.html,
289
+ attachments: args.attachments,
290
+ inReplyTo,
291
+ references,
292
+ };
293
+ if (saveToDrafts) {
294
+ // Draft mode: keep Bcc in the saved message so a later send_draft
295
+ // can still deliver to it — the header is stripped at send time.
296
+ const rawMessage = await smtp.composeRawMessage(messageOptions, { keepBcc: true });
297
+ // APPEND to Drafts folder
298
+ const draftsFolder = await imap.getSpecialUseFolder("\\Drafts");
299
+ const appendResult = await imap.appendMessage(draftsFolder, rawMessage, [
300
+ "\\Draft",
301
+ "\\Seen",
302
+ ]);
303
+ return structured({
304
+ status: "draft",
305
+ uid: appendResult.uid,
306
+ folder: draftsFolder,
307
+ });
308
+ }
309
+ // Send mode: SMTP send + APPEND to Sent (Bcc stripped per RFC 2822 default)
310
+ const rawMessage = await smtp.composeRawMessage(messageOptions);
311
+ const envelope = {
312
+ from: smtp.config.smtp.user,
313
+ to: [...to, ...(cc || []), ...(bcc || [])],
314
+ };
315
+ const sendResult = await smtp.sendRawMessage(rawMessage, envelope);
316
+ let sentFolderPath = "Sent";
317
+ if (!smtp.config.autoSent) {
318
+ try {
319
+ sentFolderPath = await imap.getSpecialUseFolder("\\Sent");
320
+ await imap.appendMessage(sentFolderPath, rawMessage, ["\\Seen"]);
321
+ }
322
+ catch (appendError) {
323
+ console.error("[email-mcp] Failed to copy to Sent folder:", appendError);
324
+ }
325
+ }
326
+ return structured({
327
+ status: "sent",
328
+ messageId: sendResult.messageId,
329
+ folder: sentFolderPath,
330
+ });
331
+ });
332
+ },
179
333
  },
180
334
  {
181
335
  name: "move_email",
336
+ title: "Move Email",
182
337
  description: "Move one or more emails to a different IMAP folder.",
338
+ annotations: {
339
+ readOnlyHint: false,
340
+ destructiveHint: false,
341
+ idempotentHint: true,
342
+ openWorldHint: true,
343
+ },
183
344
  inputSchema: {
184
345
  type: "object",
185
346
  properties: {
186
- folder: {
187
- type: "string",
188
- description: "Source IMAP folder. Defaults to INBOX.",
189
- },
190
- uids: {
191
- type: "array",
192
- items: { type: "number" },
193
- description: "UIDs of emails to move.",
194
- },
195
- destination: {
196
- type: "string",
197
- description: "Destination folder path.",
198
- },
347
+ folder: { type: "string", description: "Source IMAP folder. Defaults to INBOX." },
348
+ uids: UIDS_PROP("UIDs of emails to move."),
349
+ destination: { type: "string", description: "Destination folder path." },
199
350
  },
200
351
  required: ["uids", "destination"],
201
352
  },
353
+ outputSchema: moveResultSchema,
354
+ handler: (args, { imap }) => run(async () => {
355
+ if (!Array.isArray(args.uids) || args.uids.length === 0) {
356
+ return invalid("uids must be a non-empty array of message UIDs");
357
+ }
358
+ await imap.moveEmails(args.folder || "INBOX", args.uids, args.destination);
359
+ return structured({
360
+ status: "moved",
361
+ uids: args.uids,
362
+ destination: args.destination,
363
+ });
364
+ }),
202
365
  },
203
366
  {
204
367
  name: "mark_email",
368
+ title: "Mark Email",
205
369
  description: 'Set or unset flags on one or more emails. Common flags: "\\Seen" (read), "\\Flagged" (starred).',
370
+ annotations: {
371
+ readOnlyHint: false,
372
+ destructiveHint: false,
373
+ idempotentHint: true,
374
+ openWorldHint: true,
375
+ },
206
376
  inputSchema: {
207
377
  type: "object",
208
378
  properties: {
209
- folder: {
210
- type: "string",
211
- description: "IMAP folder. Defaults to INBOX.",
212
- },
213
- uids: {
214
- type: "array",
215
- items: { type: "number" },
216
- description: "UIDs of emails to modify.",
217
- },
379
+ folder: FOLDER_PROP,
380
+ uids: UIDS_PROP("UIDs of emails to modify."),
218
381
  flags: {
219
382
  type: "array",
220
383
  items: { type: "string" },
@@ -228,22 +391,36 @@ export const EMAIL_TOOLS = [
228
391
  },
229
392
  required: ["uids", "flags"],
230
393
  },
394
+ outputSchema: markResultSchema,
395
+ handler: (args, { imap }) => run(async () => {
396
+ if (!Array.isArray(args.uids) || args.uids.length === 0) {
397
+ return invalid("uids must be a non-empty array of message UIDs");
398
+ }
399
+ const action = args.action || "add";
400
+ await imap.markEmails(args.folder || "INBOX", args.uids, args.flags, action);
401
+ return structured({
402
+ status: "updated",
403
+ uids: args.uids,
404
+ flags: args.flags,
405
+ action,
406
+ });
407
+ }),
231
408
  },
232
409
  {
233
410
  name: "delete_email",
234
- description: "Delete one or more emails. Moves to Trash by default, or permanently deletes if specified.",
411
+ title: "Delete Email",
412
+ description: "Delete one or more emails. Moves to Trash by default, or permanently deletes if specified. A permanent delete asks the user to confirm first.",
413
+ annotations: {
414
+ readOnlyHint: false,
415
+ destructiveHint: true,
416
+ idempotentHint: true,
417
+ openWorldHint: true,
418
+ },
235
419
  inputSchema: {
236
420
  type: "object",
237
421
  properties: {
238
- folder: {
239
- type: "string",
240
- description: "IMAP folder. Defaults to INBOX.",
241
- },
242
- uids: {
243
- type: "array",
244
- items: { type: "number" },
245
- description: "UIDs of emails to delete.",
246
- },
422
+ folder: FOLDER_PROP,
423
+ uids: UIDS_PROP("UIDs of emails to delete."),
247
424
  permanent: {
248
425
  type: "boolean",
249
426
  description: "If true, permanently delete instead of moving to Trash. Defaults to false.",
@@ -251,43 +428,69 @@ export const EMAIL_TOOLS = [
251
428
  },
252
429
  required: ["uids"],
253
430
  },
431
+ outputSchema: deleteResultSchema,
432
+ handler: async (args, { imap }, ctx) => {
433
+ if (!Array.isArray(args.uids) || args.uids.length === 0) {
434
+ return invalid("uids must be a non-empty array of message UIDs");
435
+ }
436
+ const permanent = args.permanent || false;
437
+ // A Trash move is recoverable; an expunge is not.
438
+ if (permanent) {
439
+ const gate = confirmDestructive(ctx, "confirm_delete_email", `Permanently delete ${args.uids.length} email(s) from ${args.folder || "INBOX"}? They cannot be recovered.`);
440
+ if (gate.status === "interrupt")
441
+ return gate.result;
442
+ }
443
+ return run(async () => {
444
+ await imap.deleteEmails(args.folder || "INBOX", args.uids, permanent);
445
+ return structured({
446
+ status: permanent ? "permanently_deleted" : "moved_to_trash",
447
+ uids: args.uids,
448
+ });
449
+ });
450
+ },
254
451
  },
255
452
  {
256
453
  name: "list_folders",
454
+ title: "List Folders",
257
455
  description: "List all IMAP folders with their paths and special-use flags (Inbox, Sent, Trash, etc.).",
258
- inputSchema: {
259
- type: "object",
260
- properties: {},
261
- },
456
+ annotations: READ_ONLY,
457
+ inputSchema: { type: "object", properties: {} },
458
+ outputSchema: folderListSchema,
459
+ handler: (_args, { imap }) => run(async () => structured({ folders: await imap.listFolders() })),
262
460
  },
263
461
  {
264
462
  name: "create_folder",
463
+ title: "Create Folder",
265
464
  description: "Create a new IMAP folder.",
465
+ annotations: {
466
+ readOnlyHint: false,
467
+ destructiveHint: false,
468
+ idempotentHint: false,
469
+ openWorldHint: true,
470
+ },
266
471
  inputSchema: {
267
472
  type: "object",
268
473
  properties: {
269
- path: {
270
- type: "string",
271
- description: "Folder path to create (e.g., 'Projects/Work').",
272
- },
474
+ path: { type: "string", description: "Folder path to create (e.g., 'Projects/Work')." },
273
475
  },
274
476
  required: ["path"],
275
477
  },
478
+ outputSchema: createFolderResultSchema,
479
+ handler: (args, { imap }) => run(async () => {
480
+ await imap.createFolder(args.path);
481
+ return structured({ status: "created", path: args.path });
482
+ }),
276
483
  },
277
484
  {
278
485
  name: "download_attachment",
279
- description: "Download a specific attachment from an email. Returns the attachment content as base64.",
486
+ title: "Download Attachment",
487
+ description: "Download a specific attachment from an email. Returns the bytes as an embedded binary resource; structured output carries the filename, content type and size.",
488
+ annotations: READ_ONLY,
280
489
  inputSchema: {
281
490
  type: "object",
282
491
  properties: {
283
- folder: {
284
- type: "string",
285
- description: "IMAP folder. Defaults to INBOX.",
286
- },
287
- uid: {
288
- type: "number",
289
- description: "UID of the email containing the attachment.",
290
- },
492
+ folder: FOLDER_PROP,
493
+ uid: { type: "number", description: "UID of the email containing the attachment." },
291
494
  partId: {
292
495
  type: "string",
293
496
  description: "MIME part ID of the attachment (from get_email attachment metadata).",
@@ -295,48 +498,94 @@ export const EMAIL_TOOLS = [
295
498
  },
296
499
  required: ["uid", "partId"],
297
500
  },
501
+ outputSchema: attachmentSchema,
502
+ handler: (args, { imap }) => run(async () => {
503
+ const folder = args.folder || "INBOX";
504
+ const attachment = await imap.downloadAttachment(folder, args.uid, args.partId);
505
+ return {
506
+ // The bytes ride in the resource block only — repeating the base64 in
507
+ // structuredContent would double the response for large attachments.
508
+ // Same reasoning as get_email_raw below.
509
+ content: [
510
+ {
511
+ type: "resource",
512
+ resource: {
513
+ uri: `imap://${encodeURIComponent(folder)}/${args.uid}/${encodeURIComponent(args.partId)}`,
514
+ mimeType: attachment.contentType,
515
+ blob: attachment.content.toString("base64"),
516
+ },
517
+ },
518
+ ],
519
+ structuredContent: {
520
+ filename: attachment.filename,
521
+ contentType: attachment.contentType,
522
+ size: attachment.size,
523
+ },
524
+ };
525
+ }),
298
526
  },
299
527
  {
300
528
  name: "get_email_raw",
301
- description: "Export an email as raw .eml (RFC 822 source). Useful for archival or forwarding.",
529
+ title: "Get Raw Email",
530
+ description: "Export an email as raw .eml (RFC 822 source). Useful for archival or forwarding. The source is returned as an embedded message/rfc822 resource.",
531
+ annotations: READ_ONLY,
302
532
  inputSchema: {
303
533
  type: "object",
304
534
  properties: {
305
- folder: {
306
- type: "string",
307
- description: "IMAP folder. Defaults to INBOX.",
308
- },
309
- uid: {
310
- type: "number",
311
- description: "UID of the email to export.",
312
- },
535
+ folder: FOLDER_PROP,
536
+ uid: { type: "number", description: "UID of the email to export." },
313
537
  },
314
538
  required: ["uid"],
315
539
  },
540
+ outputSchema: rawEmailSchema,
541
+ handler: (args, { imap }) => run(async () => {
542
+ const folder = args.folder || "INBOX";
543
+ const raw = await imap.fetchRawEmail(folder, args.uid);
544
+ return {
545
+ // The source rides in the resource block rather than being repeated
546
+ // in both `content` and `structuredContent` — .eml payloads are large.
547
+ content: [
548
+ {
549
+ type: "resource",
550
+ resource: {
551
+ uri: `imap://${encodeURIComponent(folder)}/${args.uid}.eml`,
552
+ mimeType: "message/rfc822",
553
+ text: raw,
554
+ },
555
+ },
556
+ ],
557
+ structuredContent: { uid: args.uid, folder, size: raw.length },
558
+ };
559
+ }),
316
560
  },
317
561
  {
318
562
  name: "get_folder_status",
563
+ title: "Get Folder Status",
319
564
  description: "Get total and unread message counts for a folder via IMAP STATUS (single round-trip, no payload).",
565
+ annotations: READ_ONLY,
320
566
  inputSchema: {
321
567
  type: "object",
322
568
  properties: {
323
- folder: {
324
- type: "string",
325
- description: "IMAP folder path. Defaults to INBOX.",
326
- },
569
+ folder: { type: "string", description: "IMAP folder path. Defaults to INBOX." },
327
570
  },
328
571
  },
572
+ outputSchema: folderStatusSchema,
573
+ handler: (args, { imap }) => run(async () => structured(await imap.getFolderStatus(args.folder || "INBOX"))),
329
574
  },
330
575
  {
331
576
  name: "send_draft",
332
- description: "Send an existing email draft from the Drafts folder. Fetches the draft's raw RFC 822 source, sends it via SMTP, copies it to the Sent folder, and removes it from Drafts. The draft must already exist — use send_email with saveToDrafts: true to create one.",
577
+ title: "Send Draft",
578
+ description: "Send an existing email draft from the Drafts folder. Fetches the draft's raw RFC 822 source, sends it via SMTP, copies it to the Sent folder, and removes it from Drafts. Asks the user to confirm before sending. The draft must already exist — use send_email with saveToDrafts: true to create one.",
579
+ annotations: {
580
+ readOnlyHint: false,
581
+ destructiveHint: false,
582
+ idempotentHint: false,
583
+ openWorldHint: true,
584
+ },
333
585
  inputSchema: {
334
586
  type: "object",
335
587
  properties: {
336
- uid: {
337
- type: "number",
338
- description: "UID of the draft email in the Drafts folder.",
339
- },
588
+ uid: { type: "number", description: "UID of the draft email in the Drafts folder." },
340
589
  folder: {
341
590
  type: "string",
342
591
  description: "IMAP folder containing the draft. Defaults to the server's Drafts folder.",
@@ -344,208 +593,15 @@ export const EMAIL_TOOLS = [
344
593
  },
345
594
  required: ["uid"],
346
595
  },
347
- },
348
- ];
349
- export async function handleEmailTool(name, args, imapService, smtpService) {
350
- try {
351
- const folder = args.folder || "INBOX";
352
- switch (name) {
353
- case "search_emails": {
354
- const searchParams = {
355
- hasWords: args.hasWords,
356
- body: args.body,
357
- from: args.from,
358
- to: args.to,
359
- cc: args.cc,
360
- bcc: args.bcc,
361
- subject: args.subject,
362
- since: args.since,
363
- before: args.before,
364
- unread: args.unread,
365
- flagged: args.flagged,
366
- hasAttachment: args.hasAttachment,
367
- tags: args.tags,
368
- };
369
- const limit = args.limit || 50;
370
- const offset = args.offset || 0;
371
- const sortBy = args.sortBy ?? "date";
372
- const sortOrder = args.sortOrder ?? "desc";
373
- const emails = await imapService.searchEmails(folder, searchParams, {
374
- limit,
375
- offset,
376
- sortBy: sortBy,
377
- sortOrder: sortOrder,
378
- });
379
- return ok(JSON.stringify(emails, null, 2));
380
- }
381
- case "get_email": {
382
- const uid = args.uid;
383
- const format = args.format || "markdown";
384
- const email = await imapService.fetchEmail(folder, uid);
385
- if (format === "markdown") {
386
- try {
387
- if (email.htmlBody) {
388
- email.markdownBody = await htmlToMarkdown(email.htmlBody);
389
- }
390
- else if (email.textBody) {
391
- email.markdownBody = email.textBody;
392
- }
393
- delete email.htmlBody;
394
- delete email.textBody;
395
- }
396
- catch {
397
- // Conversion failed — fall back to returning raw bodies unchanged
398
- }
399
- }
400
- else if (format === "text") {
401
- delete email.htmlBody;
402
- }
403
- else if (format === "html") {
404
- delete email.textBody;
405
- }
406
- return ok(JSON.stringify(email, null, 2));
407
- }
408
- case "send_email": {
409
- const to = Array.isArray(args.to) ? args.to : [args.to];
410
- const cc = args.cc == null
411
- ? undefined
412
- : Array.isArray(args.cc)
413
- ? args.cc
414
- : [args.cc];
415
- const bcc = args.bcc == null
416
- ? undefined
417
- : Array.isArray(args.bcc)
418
- ? args.bcc
419
- : [args.bcc];
420
- const text = args.text;
421
- const html = args.html;
422
- const attachments = args.attachments;
423
- const replyToUid = args.replyToUid;
424
- const replyToFolder = args.replyToFolder || "INBOX";
425
- const saveToDrafts = args.saveToDrafts || false;
426
- let subject = args.subject;
427
- // Validation: subject required when not replying
428
- if (!subject && !replyToUid) {
429
- return error("subject is required when not replying to an existing email");
430
- }
431
- // Threading: fetch original email for reply context
432
- let inReplyTo;
433
- let references;
434
- if (replyToUid) {
435
- const original = await imapService.fetchEmail(replyToFolder, replyToUid);
436
- inReplyTo = original.messageId;
437
- references = [...(original.references || [])];
438
- if (original.messageId && !references.includes(original.messageId)) {
439
- references.push(original.messageId);
440
- }
441
- if (!subject) {
442
- const origSubject = original.subject || "";
443
- subject = origSubject.startsWith("Re:") ? origSubject : `Re: ${origSubject}`;
444
- }
445
- }
446
- // Compose RFC 822 message
447
- const from = smtpService.config.fromName
448
- ? `"${smtpService.config.fromName}" <${smtpService.config.smtp.user}>`
449
- : smtpService.config.smtp.user;
450
- const rawMessage = await smtpService.composeRawMessage({
451
- from,
452
- to,
453
- cc,
454
- bcc,
455
- subject: subject,
456
- text,
457
- html,
458
- attachments,
459
- inReplyTo,
460
- references,
461
- });
462
- if (saveToDrafts) {
463
- // Draft mode: APPEND to Drafts folder
464
- const draftsFolder = await imapService.getSpecialUseFolder("\\Drafts");
465
- const appendResult = await imapService.appendMessage(draftsFolder, rawMessage, [
466
- "\\Draft",
467
- "\\Seen",
468
- ]);
469
- return ok(JSON.stringify({ status: "draft", uid: appendResult.uid, folder: draftsFolder }));
470
- }
471
- // Send mode: SMTP send + APPEND to Sent
472
- const envelope = {
473
- from: smtpService.config.smtp.user,
474
- to: [...to, ...(cc || []), ...(bcc || [])],
475
- };
476
- const sendResult = await smtpService.sendRawMessage(rawMessage, envelope);
477
- let sentFolderPath = "Sent";
478
- if (!smtpService.config.autoSent) {
479
- try {
480
- sentFolderPath = await imapService.getSpecialUseFolder("\\Sent");
481
- await imapService.appendMessage(sentFolderPath, rawMessage, ["\\Seen"]);
482
- }
483
- catch (appendError) {
484
- console.error("[email-mcp] Failed to copy to Sent folder:", appendError);
485
- }
486
- }
487
- return ok(JSON.stringify({
488
- status: "sent",
489
- messageId: sendResult.messageId,
490
- folder: sentFolderPath,
491
- }));
492
- }
493
- case "move_email": {
494
- const uids = args.uids;
495
- const destination = args.destination;
496
- await imapService.moveEmails(folder, uids, destination);
497
- return ok(JSON.stringify({ status: "moved", uids, destination }));
498
- }
499
- case "mark_email": {
500
- const uids = args.uids;
501
- const flags = args.flags;
502
- const action = args.action || "add";
503
- await imapService.markEmails(folder, uids, flags, action);
504
- return ok(JSON.stringify({ status: "updated", uids, flags, action }));
505
- }
506
- case "delete_email": {
507
- const uids = args.uids;
508
- const permanent = args.permanent || false;
509
- await imapService.deleteEmails(folder, uids, permanent);
510
- return ok(JSON.stringify({
511
- status: permanent ? "permanently_deleted" : "moved_to_trash",
512
- uids,
513
- }));
514
- }
515
- case "list_folders": {
516
- const folders = await imapService.listFolders();
517
- return ok(JSON.stringify(folders, null, 2));
518
- }
519
- case "create_folder": {
520
- const path = args.path;
521
- await imapService.createFolder(path);
522
- return ok(JSON.stringify({ status: "created", path }));
523
- }
524
- case "download_attachment": {
525
- const uid = args.uid;
526
- const partId = args.partId;
527
- const attachment = await imapService.downloadAttachment(folder, uid, partId);
528
- return ok(JSON.stringify({
529
- filename: attachment.filename,
530
- contentType: attachment.contentType,
531
- size: attachment.size,
532
- content: attachment.content.toString("base64"),
533
- }));
534
- }
535
- case "get_email_raw": {
536
- const uid = args.uid;
537
- const raw = await imapService.fetchRawEmail(folder, uid);
538
- return ok(raw);
539
- }
540
- case "get_folder_status": {
541
- const status = await imapService.getFolderStatus(folder);
542
- return ok(JSON.stringify(status));
543
- }
544
- case "send_draft": {
545
- const uid = args.uid;
546
- const draftFolder = args.folder || (await imapService.getSpecialUseFolder("\\Drafts"));
596
+ outputSchema: sendResultSchema,
597
+ handler: async (args, { imap, smtp }, ctx) => {
598
+ const gate = confirmDestructive(ctx, "confirm_send_draft", `Send draft ${args.uid}? Once sent it cannot be recalled.`);
599
+ if (gate.status === "interrupt")
600
+ return gate.result;
601
+ return run(async () => {
602
+ const draftFolder = args.folder || (await imap.getSpecialUseFolder("\\Drafts"));
547
603
  // Fetch raw source
548
- const rawSource = await imapService.fetchRawSource(draftFolder, uid);
604
+ const rawSource = await imap.fetchRawSource(draftFolder, args.uid);
549
605
  // Parse headers for SMTP envelope
550
606
  const parsed = await simpleParser(rawSource);
551
607
  const toAddrs = (Array.isArray(parsed.to) ? parsed.to : parsed.to ? [parsed.to] : [])
@@ -562,46 +618,46 @@ export async function handleEmailTool(name, args, imapService, smtpService) {
562
618
  .filter((a) => !!a);
563
619
  const allRecipients = [...toAddrs, ...ccAddrs, ...bccAddrs];
564
620
  if (allRecipients.length === 0) {
565
- return error("Draft has no recipients — cannot send");
621
+ return invalid("Draft has no recipients — cannot send");
566
622
  }
567
- // Send via SMTP
623
+ // Send via SMTP. The envelope still carries bccAddrs (via
624
+ // allRecipients) so the MTA delivers to them, but the Bcc header
625
+ // itself must not go out on the wire — strip it from the
626
+ // transmitted copy while keeping rawSource intact for the Sent
627
+ // folder append below (so the sender keeps a record of who was bcc'd).
568
628
  const envelope = {
569
- from: smtpService.config.smtp.user,
629
+ from: smtp.config.smtp.user,
570
630
  to: allRecipients,
571
631
  };
572
- const sendResult = await smtpService.sendRawMessage(rawSource, envelope);
632
+ const sendResult = await smtp.sendRawMessage(stripBccHeader(rawSource), envelope);
573
633
  // Copy to Sent
574
634
  let sentFolderPath = "Sent";
575
- if (!smtpService.config.autoSent) {
635
+ if (!smtp.config.autoSent) {
576
636
  try {
577
- sentFolderPath = await imapService.getSpecialUseFolder("\\Sent");
578
- await imapService.appendMessage(sentFolderPath, rawSource, ["\\Seen"]);
637
+ sentFolderPath = await imap.getSpecialUseFolder("\\Sent");
638
+ await imap.appendMessage(sentFolderPath, rawSource, ["\\Seen"]);
579
639
  }
580
640
  catch (appendError) {
581
641
  console.error("[email-mcp] Failed to copy to Sent folder:", appendError);
582
642
  }
583
643
  }
584
644
  // Delete draft (permanently — not move to Trash)
585
- await imapService.deleteEmails(draftFolder, [uid], true);
586
- return ok(JSON.stringify({
645
+ await imap.deleteEmails(draftFolder, [args.uid], true);
646
+ return structured({
587
647
  status: "sent",
588
648
  messageId: sendResult.messageId,
589
649
  folder: sentFolderPath,
590
- }));
591
- }
592
- default:
593
- return error(`Unknown tool: ${name}`);
594
- }
595
- }
596
- catch (err) {
597
- const pimError = toPimError(err instanceof Error ? err : new Error(String(err)));
598
- return error(`${pimError.message}${pimError.isRetryable ? " (retryable)" : ""}`);
599
- }
600
- }
601
- function ok(text) {
602
- return { content: [{ type: "text", text }] };
603
- }
604
- function error(text) {
605
- return { content: [{ type: "text", text }], isError: true };
650
+ });
651
+ });
652
+ },
653
+ },
654
+ ];
655
+ function stripBccHeader(raw) {
656
+ const str = raw.toString("latin1");
657
+ const sep = str.indexOf("\r\n\r\n");
658
+ if (sep === -1)
659
+ return raw;
660
+ const headers = str.slice(0, sep + 2).replace(/^bcc:[^\r\n]*(?:\r\n[ \t][^\r\n]*)*\r\n/gim, "");
661
+ return Buffer.from(headers + str.slice(sep + 2), "latin1");
606
662
  }
607
663
  //# sourceMappingURL=emailTools.js.map