fluxmail 0.9.0 → 0.11.0

package/dist/mcp/buildServer.js

@@ -1,11 +1,14 @@
 import { VERSION } from '../version.js';
+import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { EmailError, isEmailError, mergeEmailQueries, parseEmailSearch, parseSingleAddress, } from '@fluxmail/core';
 import { DEFAULT_MAX_ATTACHMENT_BYTES } from '../config.js';
 import { FULL_PERMISSION_POLICY, hasCapability, normalizePermissionPolicy, } from '../permissions.js';
 import { captureOperation } from '../telemetry.js';
 import { logFailure } from '../logging.js';
+import { ClientInputError, publicError } from '../service/publicErrors.js';
+import { outputSchemas } from './outputSchemas.js';
 const MAX_BODY_CHARS = 50_000;
 const TELEMETRY_ERROR = Symbol('telemetryError');
 const accountIdParam = z
@@ -38,6 +41,10 @@ const queryShape = {
     pageSize: z.number().int().min(1).max(100).optional().describe('Defaults to 25'),
     pageToken: z.string().min(1).optional().describe('nextPageToken from a previous call'),
     includeSnippet: z.boolean().optional().describe('Request or suppress message previews'),
+    includeSearchContext: z
+        .boolean()
+        .optional()
+        .describe('Include a match-centered body excerpt; requires a portable text query'),
 };
 const draftShape = {
     accountId: accountIdParam,
@@ -46,7 +53,10 @@ const draftShape = {
     cc: addressList.optional(),
     bcc: addressList.optional(),
     subject: z.string().optional().describe('Defaults to "Re: ..." when replying'),
-    bodyText: z.string().optional().describe('Plain-text body'),
+    bodyText: z
+        .string()
+        .optional()
+        .describe('Plain-text body. Line breaks appear in the sent email. Keep each prose paragraph on one continuous line and separate paragraphs with blank lines.'),
     bodyHtml: z.string().optional().describe('HTML body'),
     replyToMessageId: idParam
         .optional()
@@ -66,14 +76,14 @@ function parseAddresses(raw) {
     const parsed = raw.map((r) => {
         const addr = parseSingleAddress(r);
         if (!addr)
-            throw new EmailError('invalid_request', `Could not parse email address: "${r}"`);
+            throw new ClientInputError('invalid_request', `Could not parse email address: "${r}"`);
         return addr;
     });
     return parsed;
 }
 function toSendInput(args) {
     if (args.replyAll && !args.replyToMessageId) {
-        throw new EmailError('invalid_request', 'replyAll requires replyToMessageId');
+        throw new ClientInputError('invalid_request', 'replyAll requires replyToMessageId');
     }
     const input = {
         body: {
@@ -117,33 +127,51 @@ export function toSendRequest(args) {
             'from',
         ];
         if (contentKeys.some((key) => args[key] !== undefined)) {
-            throw new EmailError('invalid_request', 'draftId cannot be combined with message content; update the draft before sending it');
+            throw new ClientInputError('invalid_request', 'draftId cannot be combined with message content; update the draft before sending it');
         }
         return { draftId: args.draftId };
     }
     return toSendInput(args);
 }
-function truncateBody(message) {
-    if (!message.body)
-        return message;
-    const body = { ...message.body };
+function selectBody(message, format, budget) {
+    if (!message.body || format === 'none')
+        return { ...message, body: undefined };
+    const body = {};
+    const bodyTruncation = {};
+    let remaining = budget;
     for (const key of ['text', 'html']) {
-        const value = body[key];
-        if (value && value.length > MAX_BODY_CHARS) {
-            body[key] = value.slice(0, MAX_BODY_CHARS) + `\n… [truncated ${value.length - MAX_BODY_CHARS} characters]`;
-        }
+        if (format !== 'both' && format !== key)
+            continue;
+        const value = message.body[key];
+        if (value === undefined)
+            continue;
+        const selected = value.slice(0, remaining);
+        body[key] = selected;
+        bodyTruncation[key] = {
+            totalChars: value.length,
+            ...(selected.length < value.length ? { nextOffset: selected.length } : {}),
+        };
+        remaining -= selected.length;
     }
-    return { ...message, body };
+    return { ...message, body, bodyTruncation };
 }
 function ok(data) {
     return {
-        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        structuredContent: { data },
+        content: [{ type: 'text', text: JSON.stringify({ data }, null, 2) }],
     };
 }
-function toolError(err) {
-    const payload = isEmailError(err)
-        ? { error: err.code, message: err.message, ...(err.data ? { data: err.data } : {}) }
-        : { error: 'internal', message: err instanceof Error ? err.message : String(err) };
+function deliveryResult(operation) {
+    const result = ok(operation);
+    if (operation.status === 'failed' || operation.status === 'uncertain') {
+        result.isError = true;
+        result[TELEMETRY_ERROR] = true;
+    }
+    return result;
+}
+function toolError(err, requestId) {
+    const safe = publicError(err, requestId);
+    const payload = { error: safe.code, message: safe.message, requestId, ...(safe.data ? { data: safe.data } : {}) };
     return { isError: true, content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
 }
 function toolFeatureProperties(tool, args) {
@@ -164,7 +192,7 @@ function toolFeatureProperties(tool, args) {
         case 'modify_emails':
             return typeof input.action === 'string' ? { action: input.action } : {};
         case 'download_attachment':
-            return { destination: 'inline' };
+            return { destination: input.inline === true ? 'inline' : 'resource' };
         default:
             return {};
     }
@@ -193,10 +221,12 @@ function handleResult(tool, fn, gate, options = {}) {
             return result;
         }
         catch (err) {
+            const requestId = randomUUID();
             logFailure(options.logger, 'mcp.operation_failed', err, {
                 productSurface: 'mcp',
                 operation: tool,
                 durationMs: performance.now() - startedAt,
+                details: { request_id: requestId },
             });
             captureOperation(options.telemetry, {
                 productSurface: 'mcp',
@@ -207,7 +237,7 @@ function handleResult(tool, fn, gate, options = {}) {
                 transport: options.transport ?? 'unknown',
                 properties: toolFeatureProperties(tool, args[0]),
             });
-            return toolError(err);
+            return toolError(err, requestId);
         }
         finally {
             finishActivity?.();
@@ -222,6 +252,7 @@ function pageOpts(args) {
         ...(args.pageSize !== undefined ? { pageSize: args.pageSize } : {}),
         ...(args.pageToken !== undefined ? { pageToken: args.pageToken } : {}),
         ...(args.includeSnippet !== undefined ? { includeSnippet: args.includeSnippet } : {}),
+        ...(args.includeSearchContext !== undefined ? { includeSearchContext: args.includeSearchContext } : {}),
     };
 }
 function emailQuery(args) {
@@ -292,39 +323,40 @@ export function buildMcpServer(service, options = {}) {
             "care about, e.g. 'Sent \"Quarterly report\" to ann@example.com' or 'Archived the thread', rather " +
             'than echoing raw payloads, ids, or field names.',
     });
+    const registerTool = ((name, config, callback) => server.registerTool(name, { ...config, outputSchema: outputSchemas[name] }, callback));
     if (can('mail.read'))
-        server.registerTool('list_accounts', {
+        registerTool('list_accounts', {
             description: 'List connected email accounts (id, provider, email, status, capabilities).',
             inputSchema: {},
             annotations: { readOnlyHint: true },
         }, gated('list_accounts', 'mail.read', async () => service.listAccounts()));
     if (can('mail.read'))
-        server.registerTool('get_status', {
+        registerTool('get_status', {
             description: 'Account connection and scheduled-send status. Administrators also see plan details. ' +
                 'Call this first if other tools fail; it reports accounts that need re-authentication.',
             inputSchema: {},
             annotations: { readOnlyHint: true },
         }, allowed('get_status', 'mail.read', async () => service.status()));
     if (can('mail.read'))
-        server.registerTool('list_folders', {
+        registerTool('list_folders', {
             description: 'List navigable folders for an account, with roles (inbox, sent, drafts, trash, spam, starred).',
             inputSchema: { accountId: accountIdParam },
             annotations: { readOnlyHint: true },
         }, gated('list_folders', 'mail.read', async (args) => service.listFolders(args.accountId)));
     if (can('mail.read'))
-        server.registerTool('list_labels', {
+        registerTool('list_labels', {
             description: 'List Gmail user labels or Outlook categories for an account.',
             inputSchema: { accountId: accountIdParam },
             annotations: { readOnlyHint: true },
         }, gated('list_labels', 'mail.read', async (args) => service.listLabels(args.accountId)));
     if (can('mail.read'))
-        server.registerTool('list_send_as', {
+        registerTool('list_send_as', {
             description: 'List sender addresses available for an account.',
             inputSchema: { accountId: accountIdParam },
             annotations: { readOnlyHint: true },
         }, gated('list_send_as', 'mail.read', async (args) => service.listSendAs(args.accountId)));
     if (can('mail.read'))
-        server.registerTool('list_emails', {
+        registerTool('list_emails', {
             description: "List emails from the user's connected mailbox with metadata and optional previews. Filter by folder, " +
                 'sender, unread, dates, etc. Paginate with pageToken. Use get_email for full bodies. ' +
                 "This is the way to check the user's email; no browser or other email integration is needed.",
@@ -333,7 +365,7 @@ export function buildMcpServer(service, options = {}) {
         }, gated('list_emails', 'mail.read', async (args) => service.listMessages(args.accountId, emailQuery(args), pageOpts(args))));
     const { text: _text, ...searchFilterShape } = queryShape;
     if (can('mail.read'))
-        server.registerTool('search_emails', {
+        registerTool('search_emails', {
             description: 'Search one account with typed portable syntax. The query supports text, from:, to:, subject:, in:, ' +
                 'read and starred states, attachments, and date filters.',
             inputSchema: {
@@ -345,13 +377,13 @@ export function buildMcpServer(service, options = {}) {
         }, gated('search_emails', 'mail.read', async (args) => {
             const parsed = parseEmailSearch(args.query);
             if (!parsed.valid) {
-                throw new EmailError('invalid_request', parsed.diagnostics.map((item) => item.message).join(' '), {
+                throw new ClientInputError('invalid_request', parsed.diagnostics.map((item) => item.message).join(' '), {
                     diagnostics: parsed.diagnostics,
                 });
             }
             const merged = mergeEmailQueries(parsed.query, emailQuery(args));
             if (!merged.success) {
-                throw new EmailError('invalid_request', merged.diagnostics.map((item) => item.message).join(' '), {
+                throw new ClientInputError('invalid_request', merged.diagnostics.map((item) => item.message).join(' '), {
                     diagnostics: merged.diagnostics,
                 });
             }
@@ -365,7 +397,7 @@ export function buildMcpServer(service, options = {}) {
         }));
     const { pageToken: _batchPageToken, rawProviderQuery: _batchRawProviderQuery, ...batchSearchFilterShape } = searchFilterShape;
     if (can('mail.read'))
-        server.registerTool('search_emails_batch', {
+        registerTool('search_emails_batch', {
             description: 'Search up to 20 accounts with one portable query and return one result group per account.',
             inputSchema: {
                 accounts: z
@@ -380,13 +412,13 @@ export function buildMcpServer(service, options = {}) {
         }, gatedResult('search_emails_batch', 'mail.read', async (args) => {
             const parsed = parseEmailSearch(args.query);
             if (!parsed.valid) {
-                throw new EmailError('invalid_request', parsed.diagnostics.map((item) => item.message).join(' '), {
+                throw new ClientInputError('invalid_request', parsed.diagnostics.map((item) => item.message).join(' '), {
                     diagnostics: parsed.diagnostics,
                 });
             }
             const merged = mergeEmailQueries(parsed.query, emailQuery(args));
             if (!merged.success) {
-                throw new EmailError('invalid_request', merged.diagnostics.map((item) => item.message).join(' '), {
+                throw new ClientInputError('invalid_request', merged.diagnostics.map((item) => item.message).join(' '), {
                     diagnostics: merged.diagnostics,
                 });
             }
@@ -395,6 +427,7 @@ export function buildMcpServer(service, options = {}) {
                 query: merged.query,
                 ...(args.pageSize !== undefined ? { pageSize: args.pageSize } : {}),
                 ...(args.includeSnippet !== undefined ? { includeSnippet: args.includeSnippet } : {}),
+                ...(args.includeSearchContext !== undefined ? { includeSearchContext: args.includeSearchContext } : {}),
             });
             const response = ok({
                 ...result,
@@ -416,22 +449,91 @@ export function buildMcpServer(service, options = {}) {
             return response;
         }));
     if (can('mail.read'))
-        server.registerTool('get_email', {
+        registerTool('get_email', {
             description: 'Fetch one email in full: body (text and/or HTML), recipients, attachment metadata.',
-            inputSchema: { accountId: accountIdParam, messageId: idParam },
+            inputSchema: {
+                accountId: accountIdParam,
+                messageId: idParam,
+                bodyFormat: z.enum(['text', 'html', 'both', 'none']).optional(),
+            },
             annotations: { readOnlyHint: true },
-        }, gated('get_email', 'mail.read', async (args) => truncateBody(await service.getMessage(args.accountId, args.messageId))));
+        }, gated('get_email', 'mail.read', async (args) => selectBody(await service.getMessage(args.accountId, args.messageId), args.bodyFormat ?? 'both', MAX_BODY_CHARS)));
     if (can('mail.read'))
-        server.registerTool('get_thread', {
-            description: 'Fetch a full conversation thread with all message bodies.',
-            inputSchema: { accountId: accountIdParam, threadId: idParam },
+        registerTool('get_email_body', {
+            description: 'Read a bounded portion of one email body. Use nextOffset to continue.',
+            inputSchema: {
+                accountId: accountIdParam,
+                messageId: idParam,
+                format: z.enum(['text', 'html']),
+                offset: z.number().int().min(0).optional(),
+                maxChars: z.number().int().min(1).max(MAX_BODY_CHARS).optional(),
+            },
+            annotations: { readOnlyHint: true },
+        }, gated('get_email_body', 'mail.read', async (args) => {
+            const message = await service.getMessage(args.accountId, args.messageId);
+            const value = message.body?.[args.format] ?? '';
+            const offset = args.offset ?? 0;
+            const text = value.slice(offset, offset + (args.maxChars ?? MAX_BODY_CHARS));
+            return {
+                format: args.format,
+                text,
+                offset,
+                totalChars: value.length,
+                ...(offset + text.length < value.length ? { nextOffset: offset + text.length } : {}),
+            };
+        }));
+    if (can('mail.read'))
+        registerTool('get_thread', {
+            description: 'Fetch a page of conversation messages with bounded body content.',
+            inputSchema: {
+                accountId: accountIdParam,
+                threadId: idParam,
+                pageSize: z.number().int().min(1).max(25).optional(),
+                pageToken: z.string().min(1).optional(),
+                bodyFormat: z.enum(['text', 'html', 'both', 'none']).optional(),
+            },
             annotations: { readOnlyHint: true },
         }, gated('get_thread', 'mail.read', async (args) => {
             const thread = await service.getThread(args.accountId, args.threadId);
-            return { ...thread, messages: thread.messages.map(truncateBody) };
+            let offset = 0;
+            if (args.pageToken) {
+                try {
+                    const parsed = JSON.parse(Buffer.from(args.pageToken, 'base64url').toString('utf8'));
+                    if (parsed.threadId !== args.threadId || !Number.isInteger(parsed.offset) || parsed.offset < 0)
+                        throw new Error('token');
+                    offset = parsed.offset;
+                }
+                catch {
+                    throw new ClientInputError('invalid_request', 'Invalid thread page token.');
+                }
+            }
+            const pageSize = args.pageSize ?? 10;
+            let budget = MAX_BODY_CHARS;
+            const messages = thread.messages.slice(offset, offset + pageSize).map((message) => {
+                const selected = selectBody(message, args.bodyFormat ?? 'both', budget);
+                budget -= (selected.body?.text?.length ?? 0) + (selected.body?.html?.length ?? 0);
+                return selected;
+            });
+            const nextOffset = offset + messages.length;
+            return {
+                id: thread.id,
+                subject: thread.subject,
+                messages,
+                ...(nextOffset < thread.messages.length
+                    ? {
+                        nextPageToken: Buffer.from(JSON.stringify({ threadId: args.threadId, offset: nextOffset })).toString('base64url'),
+                    }
+                    : {}),
+            };
         }));
     if (can('mail.drafts'))
-        server.registerTool('create_draft', {
+        registerTool('get_draft', {
+            description: 'Read an existing draft by its draft ID.',
+            inputSchema: { accountId: accountIdParam, draftId: idParam },
+            annotations: { readOnlyHint: true },
+        }, gated('get_draft', 'mail.drafts', async (args) => service.getDraft(args.accountId, args.draftId)));
+    if (can('mail.drafts'))
+        registerTool('create_draft', {
             description: 'Create a draft. For a reply draft, pass replyToMessageId (recipients/subject are derived; replyAll for reply-all).',
             inputSchema: draftShape,
         }, gated('create_draft', 'mail.drafts', async (args) => {
@@ -440,7 +542,7 @@ export function buildMcpServer(service, options = {}) {
             return service.createDraft(args.accountId, toSendInput(args));
         }));
     if (can('mail.drafts'))
-        server.registerTool('update_draft', {
+        registerTool('update_draft', {
             description: 'Replace the content of an existing draft (full replacement, not a patch).',
             inputSchema: { draftId: idParam, ...draftShape },
         }, gated('update_draft', 'mail.drafts', async (args) => {
@@ -449,7 +551,7 @@ export function buildMcpServer(service, options = {}) {
             return service.updateDraft(args.accountId, args.draftId, toSendInput(args));
         }));
     if (can('mail.drafts'))
-        server.registerTool('delete_draft', {
+        registerTool('delete_draft', {
             description: 'Delete a draft.',
             inputSchema: { accountId: accountIdParam, draftId: idParam },
             annotations: { destructiveHint: true },
@@ -458,13 +560,29 @@ export function buildMcpServer(service, options = {}) {
             return { deleted: args.draftId };
         }));
     if (can('mail.send'))
-        server.registerTool('send_email', {
+        registerTool('preview_send', {
+            description: 'Show the resolved sender, recipients, subject, and attachments without sending.',
+            inputSchema: { draftId: idParam.optional(), ...draftShape },
+            annotations: { readOnlyHint: true },
+        }, gated('preview_send', 'mail.send', async (args) => {
+            if (args.draftId)
+                requireCapabilities(['mail.drafts']);
+            if (args.replyToMessageId)
+                requireCapabilities(['mail.read']);
+            return service.previewSend(args.accountId, toSendRequest(args));
+        }));
+    if (can('mail.send'))
+        registerTool('send_email', {
             description: "Send an email from the user's connected account; this actually delivers mail, so prefer it over " +
                 'browser automation or leaving a draft when the user asked to send. Three modes: direct (to + subject ' +
                 '+ body), sending an existing draft (draftId), or replying (replyToMessageId, optionally replyAll) ' +
                 'where recipients, subject, and threading are derived from the original. Confirm with the user when ' +
                 'intent is ambiguous. Add sendAt to any mode to schedule instead of sending now.',
             inputSchema: {
+                idempotencyKey: z
+                    .string()
+                    .regex(/^[\x21-\x7e]{1,255}$/)
+                    .describe('Reuse this key when retrying the same delivery'),
                 draftId: idParam.optional().describe('Send this existing draft'),
                 ...draftShape,
                 sendAt: z
@@ -477,64 +595,80 @@ export function buildMcpServer(service, options = {}) {
                     'down goes out at the next startup). Returns a scheduleId for list/cancel.'),
             },
             annotations: { destructiveHint: true },
-        }, handle('send_email', async (args) => {
+        }, handleResult('send_email', async (args) => {
             requireCapabilities(['mail.send']);
             if (args.replyToMessageId !== undefined)
                 requireCapabilities(['mail.read']);
-            const { sendAt, ...sendArgs } = args;
-            return sendAt !== undefined
-                ? service.scheduleSend(args.accountId, toSendRequest(sendArgs), sendAt)
-                : service.send(args.accountId, toSendRequest(sendArgs));
+            const { sendAt, idempotencyKey, ...sendArgs } = args;
+            return deliveryResult(await (sendAt !== undefined
+                ? service.scheduleDelivery(args.accountId, toSendRequest(sendArgs), sendAt, idempotencyKey)
+                : service.deliver(args.accountId, toSendRequest(sendArgs), idempotencyKey)));
         }, () => service.enforceQuota(), options));
     if (can('mail.read'))
-        server.registerTool('list_scheduled_emails', {
+        registerTool('list_scheduled_emails', {
             description: 'List scheduled sends: pending ones first (with sendAt), then past ones (sent, failed, canceled). ' +
                 'For failed entries, lastError says what went wrong. Pending sends only fire while the ' +
                 'Fluxmail server is running.',
             inputSchema: { accountId: accountIdParam },
             annotations: { readOnlyHint: true },
         }, gated('list_scheduled_emails', 'mail.read', async (args) => service.listScheduled(args.accountId)));
+    if (can('mail.send'))
+        registerTool('get_delivery_operation', {
+            description: 'Check whether a send or forward succeeded, failed, or has an uncertain outcome.',
+            inputSchema: { accountId: idParam, operationId: idParam },
+            annotations: { readOnlyHint: true },
+        }, allowed('get_delivery_operation', 'mail.send', async (args) => service.getDelivery(args.accountId, args.operationId)));
     if (can('mail.drafts'))
-        server.registerTool('cancel_scheduled_email', {
+        registerTool('cancel_scheduled_email', {
             description: 'Cancel a pending scheduled send by scheduleId (from send_email with sendAt, or list_scheduled_emails). ' +
                 'The draft stays in the Drafts folder, so the content is not lost.',
             inputSchema: { scheduleId: idParam },
         }, gated('cancel_scheduled_email', 'mail.drafts', async (args) => service.cancelScheduled(args.scheduleId)));
     if (canAll(['mail.send', 'mail.read']))
-        server.registerTool('forward_email', {
+        registerTool('forward_email', {
             description: 'Forward an email to new recipients: quoted original body, "Fwd:" subject, original attachments included ' +
                 'unless includeAttachments=false. Optional comment appears above the forwarded content.',
             inputSchema: {
+                idempotencyKey: z
+                    .string()
+                    .regex(/^[\x21-\x7e]{1,255}$/)
+                    .describe('Reuse this key when retrying the same forward'),
                 accountId: accountIdParam,
                 messageId: idParam,
                 from: z.string().email().optional().describe('Connected address or an available send-as address'),
                 to: addressList.min(1),
                 cc: addressList.optional(),
-                comment: z.string().optional(),
+                comment: z
+                    .string()
+                    .optional()
+                    .describe('Comment above the forwarded message. Keep prose paragraphs on one continuous line and separate paragraphs with blank lines.'),
                 includeAttachments: z.boolean().optional().describe('Default true'),
             },
             annotations: { destructiveHint: true },
-        }, handle('forward_email', async (args) => {
+        }, handleResult('forward_email', async (args) => {
             requireCapabilities(['mail.send', 'mail.read']);
             const to = parseAddresses(args.to) ?? [];
             const cc = parseAddresses(args.cc);
-            return service.forward(args.accountId, {
+            return deliveryResult(await service.deliverForward(args.accountId, {
                 messageId: args.messageId,
                 to,
                 ...(cc?.length ? { cc } : {}),
                 ...(args.comment !== undefined ? { comment: args.comment } : {}),
                 ...(args.includeAttachments !== undefined ? { includeAttachments: args.includeAttachments } : {}),
                 ...(args.from !== undefined ? { from: args.from } : {}),
-            });
+            }, args.idempotencyKey));
         }, () => service.enforceQuota(), options));
     const modifyActions = Object.keys(MODIFY_CAPABILITIES).filter((action) => can(MODIFY_CAPABILITIES[action]));
     if (modifyActions.length) {
         const allowedModifyActions = new Set(modifyActions);
-        server.registerTool('modify_emails', {
+        registerTool('modify_emails', {
             description: 'Batch-modify emails using the actions allowed for this connection. Moving requires folder; labels require labels.',
             inputSchema: {
                 accountId: accountIdParam,
-                messageIds: z.array(idParam).min(1),
+                messageIds: z
+                    .array(idParam)
+                    .min(1)
+                    .refine((ids) => new Set(ids).size <= 100, 'At most 100 distinct message IDs are allowed.'),
                 action: z.enum(modifyActions),
                 folder: z.string().min(1).optional().describe('Target folder for action=move'),
                 labels: z.array(z.string().min(1)).max(100).optional().describe('Labels for addLabels/removeLabels'),
@@ -542,7 +676,7 @@ export function buildMcpServer(service, options = {}) {
             annotations: {
                 destructiveHint: canAny(['mail.trash', 'mail.delete']),
             },
-        }, handle('modify_emails', async (args) => {
+        }, handleResult('modify_emails', async (args) => {
             if (!allowedModifyActions.has(args.action)) {
                 throw new EmailError('permission_denied', `This MCP connection does not allow action=${args.action}.`);
             }
@@ -550,63 +684,87 @@ export function buildMcpServer(service, options = {}) {
             let action;
             if (args.action === 'move') {
                 if (!args.folder)
-                    throw new EmailError('invalid_request', 'action=move requires "folder"');
+                    throw new ClientInputError('invalid_request', 'action=move requires "folder"');
                 if (PROTECTED_MOVE_DESTINATIONS.has(args.folder.trim().toLowerCase())) {
-                    throw new EmailError('invalid_request', 'Use the dedicated archive or trash action for this folder');
+                    throw new ClientInputError('invalid_request', 'Use the dedicated archive or trash action for this folder');
                 }
                 action = { move: args.folder };
             }
             else if (args.action === 'addLabels' || args.action === 'removeLabels') {
                 if (!args.labels?.length) {
-                    throw new EmailError('invalid_request', `action=${args.action} requires "labels"`);
+                    throw new ClientInputError('invalid_request', `action=${args.action} requires "labels"`);
                 }
                 action = args.action === 'addLabels' ? { addLabels: args.labels } : { removeLabels: args.labels };
             }
             else {
                 action = args.action;
             }
-            await service.modify(args.accountId, args.messageIds, action);
-            return { modified: args.messageIds.length, action: args.action };
+            const result = await service.modify(args.accountId, args.messageIds, action);
+            const response = ok({ ...result, action: args.action });
+            if (result.failed.length || result.uncertainIds.length) {
+                response.isError = true;
+                response[TELEMETRY_ERROR] = true;
+            }
+            return response;
         }, () => service.enforceQuota(), options));
     }
     if (can('mail.read'))
-        server.registerTool('download_attachment', {
-            description: 'Download an email attachment as an embedded MCP resource.',
+        registerTool('download_attachment', {
+            description: 'Get attachment metadata and a fetchable resource link. Set inline to embed the bytes.',
             inputSchema: {
-                accountId: accountIdParam,
+                accountId: idParam,
                 messageId: idParam,
                 attachmentId: attachmentIdParam,
+                inline: z.boolean().optional(),
             },
             annotations: { readOnlyHint: true, destructiveHint: false },
         }, gatedResult('download_attachment', 'mail.read', async (args) => {
             const { meta, content } = await service.getAttachment(args.accountId, args.messageId, args.attachmentId, maxAttachmentBytes);
             if (content.length > maxAttachmentBytes) {
-                throw new EmailError('invalid_request', 'Attachment is too large to return through MCP.', {
+                throw new ClientInputError('invalid_request', 'Attachment is too large to return through MCP.', {
                     sizeBytes: content.length,
                     maxBytes: maxAttachmentBytes,
                 });
             }
             const uri = [
                 'fluxmail://attachment',
-                encodeURIComponent(args.accountId ?? 'default'),
+                encodeURIComponent(args.accountId),
                 encodeURIComponent(args.messageId),
                 encodeURIComponent(args.attachmentId),
                 encodeURIComponent(meta.filename),
             ].join('/');
             return {
+                structuredContent: { data: meta },
                 content: [
-                    { type: 'text', text: JSON.stringify(meta, null, 2) },
-                    {
-                        type: 'resource',
-                        resource: {
-                            uri,
-                            mimeType: meta.mimeType || 'application/octet-stream',
-                            blob: content.toString('base64'),
-                        },
-                    },
+                    { type: 'text', text: JSON.stringify({ data: meta }, null, 2) },
+                    { type: 'resource_link', name: meta.filename, uri, mimeType: meta.mimeType },
+                    ...(args.inline
+                        ? [
+                            {
+                                type: 'resource',
+                                resource: {
+                                    uri,
+                                    mimeType: meta.mimeType || 'application/octet-stream',
+                                    blob: content.toString('base64'),
+                                },
+                            },
+                        ]
+                        : []),
                 ],
             };
         }));
+    if (can('mail.read'))
+        server.registerResource('attachment', new ResourceTemplate('fluxmail://attachment/{accountId}/{messageId}/{attachmentId}/{filename}', {
+            list: undefined,
+        }), { description: 'Read one attachment from an authorized mailbox.' }, async (uri, variables) => {
+            requireCapabilities(['mail.read']);
+            service.enforceQuota();
+            const { meta, content } = await service.getAttachment(decodeURIComponent(String(variables.accountId)), decodeURIComponent(String(variables.messageId)), decodeURIComponent(String(variables.attachmentId)), maxAttachmentBytes);
+            if (content.length > maxAttachmentBytes) {
+                throw new ClientInputError('invalid_request', 'Attachment is too large to return through MCP.');
+            }
+            return { contents: [{ uri: uri.href, mimeType: meta.mimeType, blob: content.toString('base64') }] };
+        });
     return server;
 }
 //# sourceMappingURL=buildServer.js.map