fluxmail 0.22.0 → 0.24.0

package/dist/mcp/buildServer.js

@@ -4,12 +4,12 @@ import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 import { CLIENT_INFO_META_KEY, PROTOCOL_VERSION_META_KEY, McpServer, ResourceTemplate, } from '@modelcontextprotocol/server';
 import { isEmailError, mergeEmailQueries, parseEmailSearch, parseSingleAddress, } from '@fluxmail/core';
-import { ATTACHMENT_URI_TEMPLATE, attachmentUri, bodyPage, MAX_BODY_CHARS, MAX_THREAD_PAGE_TOKEN_CHARS, selectBody, sharedTool, threadPage, threadPageOffset, toModifyAction, } from '@fluxmail/core/mcp';
-import { batchFailureCause } from '../service/emailService.js';
+import { ATTACHMENT_URI_TEMPLATE, attachmentUri, bodyPage, MAX_BODY_CHARS, MAX_THREAD_PAGE_TOKEN_CHARS, selectBody, sharedTool, sharedToolTarget, threadPage, threadPageOffset, toModifyAction, } from '@fluxmail/core/mcp';
+import { batchFailureCause, modifyFailure, } from '../service/emailService.js';
 import { DEFAULT_MAX_ATTACHMENT_BYTES } from '../config.js';
 import { DEFAULT_PERMISSION_POLICY, MCP_CAPABILITIES, MCP_CAPABILITY_DESCRIPTIONS, enableCapabilitiesInstructions, hasCapability, normalizePermissionPolicy, } from '../permissions.js';
 import { captureOperation } from '../telemetry.js';
-import { logFailure } from '../logging.js';
+import { logCodedFailure, logFailure } from '../logging.js';
 import { attachmentTooLarge, ClientInputError, isAttachmentSizeError, MissingCapabilityError, publicError, } from '../service/publicErrors.js';
 import { sendAtSchema } from '../sendAt.js';
 import { outputSchemas } from './outputSchemas.js';
@@ -32,6 +32,8 @@ function sizeLabel(bytes) {
 const TELEMETRY_ERROR = Symbol('telemetryError');
 /** The error behind a partial failure, read only for telemetry failure detail. */
 const TELEMETRY_FAILURE = Symbol('telemetryFailure');
+/** The telemetry error code for a partial failure. Defaults to `account_failure`. */
+const TELEMETRY_ERROR_CODE = Symbol('telemetryErrorCode');
 const EMPTY_INPUT_SCHEMA = {
     type: 'object',
     properties: {},
@@ -74,15 +76,76 @@ function toolJsonSchema(shape, pipeStrategy) {
         delete schema.$schema;
     return schema;
 }
+const MAX_REPORTED_ARGUMENT_PROBLEMS = 10;
+const MAX_REPORTED_ARGUMENT_CHARS = 100;
+function argumentPath(path) {
+    const formatted = path
+        .map((step, index) => {
+        if (typeof step === 'number')
+            return `[${step}]`;
+        return index ? `.${String(step)}` : String(step);
+    })
+        .join('');
+    return formatted.slice(0, MAX_REPORTED_ARGUMENT_CHARS);
+}
+/** Tool arguments that do not match the input schema. The message names client-supplied keys. */
+class InvalidToolArgumentsError extends ClientInputError {
+    constructor(tool, issues) {
+        // A misspelled argument often causes the other problems, so unknown arguments come first.
+        const problems = [
+            ...issues.flatMap((issue) => issue.code === 'unrecognized_keys'
+                ? issue.keys.map((key) => `unknown argument ${JSON.stringify(argumentPath([...issue.path, key]))}`)
+                : []),
+            ...issues
+                .filter((issue) => issue.code !== 'unrecognized_keys')
+                .map((issue) => `${issue.path.length ? argumentPath(issue.path) : 'arguments'}: ${issue.message}`),
+        ];
+        const shown = problems.slice(0, MAX_REPORTED_ARGUMENT_PROBLEMS);
+        const more = problems.length - shown.length;
+        super('invalid_request', `Invalid arguments for ${tool}: ${shown.join('; ')}${more ? `; and ${more} more` : ''}. ` +
+            "Check the tool's input schema.");
+    }
+}
+/**
+ * Raw tool arguments, parsed by the tool handler after its quota gate so that every
+ * schema problem becomes one invalid_request error.
+ */
+class ToolInput {
+    tool;
+    raw;
+    schema;
+    constructor(tool, raw, schema) {
+        this.tool = tool;
+        this.raw = raw;
+        this.schema = schema;
+    }
+    async parse() {
+        const result = await this.schema.safeParseAsync(this.raw ?? {});
+        if (!result.success)
+            throw new InvalidToolArgumentsError(this.tool, result.error.issues);
+        return result.data;
+    }
+}
+/**
+ * Tools with arguments reject undeclared ones, as their schemas advertise, even when every
+ * argument is optional. Dropping one could widen a search. Tools without arguments advertise
+ * an open schema and ignore extras, which some clients send to tools that take no arguments.
+ */
+function toolInputSchema(shape) {
+    return Object.keys(shape).length ? z.object(shape).strict() : z.object(shape);
+}
 // Retain the existing validators, transforms and JSON Schemas at the SDK boundary.
-// The SDK consumes only Standard Schema here.
-function mcpSchema(shape, strict = false) {
-    const schema = strict ? z.object(shape).strict() : z.object(shape);
+// The SDK consumes only Standard Schema here. Tool handlers parse inputs themselves, so the
+// input validator passes arguments through unchanged.
+function mcpSchema(shape, io) {
+    const schema = io === 'output' ? z.object(shape) : undefined;
     return {
         '~standard': {
             version: 1,
             vendor: 'fluxmail',
             validate: async (value) => {
+                if (!schema)
+                    return { value };
                 const result = await schema.safeParseAsync(value);
                 return result.success ? { value: result.data } : { issues: result.error.issues };
             },
@@ -117,21 +180,11 @@ const addressList = z
     .max(MAX_RECIPIENTS)
     .describe('Recipients, each "Name <a@x.com>" or "a@x.com"');
 const searchString = z.string().max(MAX_SEARCH_CHARS);
-const isoDate = z.string().regex(/^\d{4}-\d{2}-\d{2}$/);
 const queryShape = {
     folder: searchString
         .min(1)
         .optional()
         .describe("Folder role (inbox, sent, drafts, trash, spam, starred, archive, all) or a label/folder name. Use all or omit this field to search all mail except Spam and Trash. An IMAP server's \\All mailbox may use different rules."),
-    text: searchString.optional().describe('Literal full-text search terms'),
-    from: searchString.optional(),
-    to: searchString.optional(),
-    subject: searchString.optional(),
-    read: z.boolean().optional(),
-    starred: z.boolean().optional(),
-    hasAttachment: z.boolean().optional(),
-    after: isoDate.optional().describe('YYYY-MM-DD received date, inclusive in UTC'),
-    before: isoDate.optional().describe('YYYY-MM-DD received date, exclusive in UTC'),
     rawProviderQuery: searchString
         .optional()
         .describe('Provider-native Gmail syntax or Outlook KQL for one compatible account'),
@@ -141,8 +194,14 @@ const queryShape = {
     includeSearchContext: z
         .boolean()
         .optional()
-        .describe('Include a match-centered body excerpt; requires a portable text query'),
+        .describe('Include a match-centered body excerpt; requires search words in query'),
 };
+const sendAtParam = sendAtSchema
+    .optional()
+    .describe('Schedule delivery instead of sending now: ISO 8601 with timezone offset or Z ' +
+    '(e.g. 2026-07-11T09:00:00-07:00). Fluxmail saves the message as a real draft in the mailbox ' +
+    'for delivery by fluxmail serve or fluxmail scheduled run using the same store. Stdio does not ' +
+    'deliver schedules. Overdue mail may send when a worker starts. Returns a scheduleId for list/cancel.');
 const draftShape = {
     accountId: accountIdParam,
     from: z.string().email().optional().describe('Connected address or an available send-as address'),
@@ -157,7 +216,7 @@ const draftShape = {
     bodyHtml: z.string().optional().describe('HTML body'),
     replyToMessageId: idParam
         .optional()
-        .describe('Message being replied to; threads correctly, quotes it below the body and computes recipients if "to" is omitted'),
+        .describe('Message being replied to; threads correctly, quotes it below the body and computes recipients if "to" is omitted. To continue a conversation, reply to the first message get_thread returns with order newest'),
     replyAll: z.boolean().optional().describe('With replyToMessageId: reply to all original recipients'),
     timeZone: z
         .string()
@@ -170,7 +229,8 @@ const draftShape = {
         .optional()
         .describe('With replyToMessageId: set to false to leave the original message out of the reply. Defaults to true.'),
     attachments: z
-        .array(z.object({
+        .array(z
+        .object({
         filename: z.string().min(1).max(MAX_ATTACHMENT_FIELD_CHARS),
         mimeType: z.string().min(1).max(MAX_ATTACHMENT_FIELD_CHARS),
         content: z.string().describe('base64'),
@@ -181,7 +241,8 @@ const draftShape = {
             .optional()
             .describe('Content-ID for an inline image, referenced from bodyHtml as cid:<contentId>'),
         disposition: z.enum(['inline', 'attachment']).optional().describe('Defaults to attachment'),
-    }))
+    })
+        .strict())
         .optional(),
 };
 function parseAddresses(raw) {
@@ -289,7 +350,12 @@ function toolFeatureProperties(tool, args) {
                 reply_all: input.replyAll === true,
             };
         case 'forward_email':
-            return { include_attachments: input.includeAttachments !== false };
+            return { include_attachments: input.includeAttachments !== false, scheduled: input.sendAt !== undefined };
+        case 'list_emails':
+        case 'search_emails':
+        case 'list_emails_batch':
+        case 'search_emails_batch':
+            return { typed_query: typeof input.query === 'string' && input.query.trim() !== '' };
         case 'download_attachment':
             return {
                 destination: input.inline === true ? 'inline' : typeof input.pages === 'string' ? 'pdf_pages' : 'resource',
@@ -304,14 +370,21 @@ function toolTelemetryProperties(tool, args, options) {
         ...options.clientProperties?.(args[1]),
     };
 }
+/** Handlers built by handleResult, which parse their tool input. Only these can be registered. */
+const toolHandlers = new WeakSet();
 function handleResult(tool, fn, gate, options = {}) {
-    return async (...args) => {
+    const handler = async (...received) => {
         const finishActivity = options.telemetry?.beginActivity?.();
         const startedAt = performance.now();
+        const input = received[0] instanceof ToolInput ? received[0] : undefined;
+        // Until the input parses, telemetry reports no properties derived from it.
+        let args = (input ? [undefined, ...received.slice(1)] : received);
         try {
             // The gate throws when a lapsed license leaves the instance over quota,
             // and yields a renewal warning to attach while the license is in grace.
             const warning = gate?.();
+            if (input)
+                args = [await input.parse(), ...received.slice(1)];
             const result = await fn(...args);
             if (warning)
                 result.content.push({ type: 'text', text: `Note: ${warning}` });
@@ -321,7 +394,10 @@ function handleResult(tool, fn, gate, options = {}) {
                 operation: tool,
                 outcome: telemetryFailed ? 'error' : 'success',
                 ...(telemetryFailed
-                    ? { errorCode: 'account_failure', error: result[TELEMETRY_FAILURE] }
+                    ? {
+                        errorCode: result[TELEMETRY_ERROR_CODE] ?? 'account_failure',
+                        error: result[TELEMETRY_FAILURE],
+                    }
                     : {}),
                 durationMs: performance.now() - startedAt,
                 transport: options.transport ?? 'unknown',
@@ -331,12 +407,18 @@ function handleResult(tool, fn, gate, options = {}) {
         }
         catch (err) {
             const requestId = randomUUID();
-            logFailure(options.logger, 'mcp.operation_failed', err, {
+            const logContext = {
                 productSurface: 'mcp',
                 operation: tool,
                 durationMs: performance.now() - startedAt,
                 details: { request_id: requestId },
-            });
+            };
+            // The client sees which arguments were wrong; the log omits their names.
+            if (err instanceof InvalidToolArgumentsError) {
+                logCodedFailure(options.logger, 'mcp.operation_failed', err.code, 'Tool arguments did not match the input schema', logContext);
+            }
+            else
+                logFailure(options.logger, 'mcp.operation_failed', err, logContext);
             captureOperation(options.telemetry, {
                 productSurface: 'mcp',
                 operation: tool,
@@ -353,6 +435,8 @@ function handleResult(tool, fn, gate, options = {}) {
             finishActivity?.();
         }
     };
+    toolHandlers.add(handler);
+    return handler;
 }
 function handle(tool, fn, gate, options = {}) {
     return handleResult(tool, async (...args) => ok(await fn(...args)), gate, options);
@@ -365,20 +449,26 @@ function pageOpts(args) {
         ...(args.includeSearchContext !== undefined ? { includeSearchContext: args.includeSearchContext } : {}),
     };
 }
+function invalidSearch(diagnostics) {
+    return new ClientInputError('invalid_request', diagnostics.map((item) => item.message).join(' '), { diagnostics });
+}
+/**
+ * Parses a typed query and merges it with the structured filters sent beside it. Rejects either step's errors.
+ * A missing or blank query leaves the structured filters as they are.
+ */
+function typedSearch(query, structured) {
+    if (query === undefined || query.trim() === '')
+        return { query: structured, warnings: [] };
+    const parsed = parseEmailSearch(query);
+    if (!parsed.valid)
+        throw invalidSearch(parsed.diagnostics);
+    const merged = mergeEmailQueries(parsed.query, structured);
+    if (!merged.success)
+        throw invalidSearch(merged.diagnostics);
+    return { query: merged.query, warnings: parsed.diagnostics };
+}
 function emailQuery(args) {
-    const keys = [
-        'folder',
-        'text',
-        'from',
-        'to',
-        'subject',
-        'read',
-        'starred',
-        'hasAttachment',
-        'after',
-        'before',
-        'rawProviderQuery',
-    ];
+    const keys = ['folder', 'rawProviderQuery'];
     const q = {};
     for (const key of keys) {
         const value = args[key];
@@ -422,6 +512,7 @@ const PRODUCT_DESCRIPTIONS = {
     list_accounts: 'Each entry includes the account ID, provider, email address, status and capabilities.',
     list_emails: 'Use get_email for full bodies.',
     get_email: 'Use get_email_body to read the rest.',
+    forward_email: 'Add sendAt to schedule the forward instead of sending it now.',
     send_email: 'Confirm with the user when the intent is ambiguous. Add sendAt to any mode to schedule the message instead ' +
         'of sending it now.',
     delete_emails: "Gmail accounts connected through Fluxmail's built-in Google app cannot delete permanently; move their " +
@@ -526,14 +617,19 @@ export function buildMcpServer(service, options = {}) {
     const supportsResourceLinks = (ctx) => (protocolVersionOf(ctx) ?? '2025-03-26') >= '2025-06-18';
     const listedTools = [];
     const registerTool = (name, config, callback) => {
-        const outputSchema = outputSchemas[name];
+        // An alias returns the same result as the tool it names.
+        const outputSchema = outputSchemas[sharedToolTarget(name)];
         const inputShape = config.inputSchema;
         const inputSchema = inputShape && (name === 'send_feedback' ? inputShape : nullableOptionalInputs(inputShape));
+        if (!toolHandlers.has(callback))
+            throw new Error(`${name} must be registered with a tool handler`);
+        const run = callback;
+        const parser = toolInputSchema(inputSchema ?? {});
         const registered = server.registerTool(name, {
             ...config,
-            inputSchema: mcpSchema(inputSchema ?? {}, name === 'send_feedback'),
-            outputSchema: mcpSchema(outputSchema),
-        }, callback);
+            inputSchema: mcpSchema(inputSchema ?? {}, 'input'),
+            outputSchema: mcpSchema(outputSchema, 'output'),
+        }, ((args, ctx) => run(new ToolInput(name, args, parser), ctx)));
         listedTools.push({
             name,
             title: config.title,
@@ -546,7 +642,7 @@ export function buildMcpServer(service, options = {}) {
         return registered;
     };
     /** Registers a shared tool with its contract metadata when the connection has the tool's scopes. */
-    const registerSharedTool = (name, inputSchema, callback, productDescription = PRODUCT_DESCRIPTIONS[name]) => {
+    const registerSharedTool = (name, inputSchema, callback, productDescription = PRODUCT_DESCRIPTIONS[sharedToolTarget(name)]) => {
         if (!canAll(toolScopes(name)))
             return;
         const tool = sharedTool(name);
@@ -565,7 +661,7 @@ export function buildMcpServer(service, options = {}) {
             description: 'Account connection and scheduled-send status, including accounts that need re-authentication, and ' +
                 'the time zone for the date above the quoted message in replies. Administrators also see plan details.',
             inputSchema: {},
-            annotations: { readOnlyHint: true },
+            annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
         }, allowed('get_status', async () => {
             const update = options.availableUpdate?.();
             return { ...(await service.status()), ...(update ? { update } : {}) };
@@ -573,58 +669,28 @@ export function buildMcpServer(service, options = {}) {
     registerSharedTool('list_folders', { accountId: accountIdParam }, gated('list_folders', async (args) => service.listFolders(args.accountId)));
     registerSharedTool('list_labels', { accountId: accountIdParam }, gated('list_labels', async (args) => service.listLabels(args.accountId)));
     registerSharedTool('list_send_as', { accountId: accountIdParam }, gated('list_send_as', async (args) => service.listSendAs(args.accountId)));
-    registerSharedTool('list_emails', { accountId: accountIdParam, ...queryShape }, gated('list_emails', async (args) => service.listMessages(args.accountId, emailQuery(args), pageOpts(args))));
-    const { text: _text, ...searchFilterShape } = queryShape;
-    registerSharedTool('search_emails', {
-        accountId: accountIdParam,
-        query: searchString.min(1).describe('Typed portable search syntax'),
-        ...searchFilterShape,
-    }, gated('search_emails', async (args) => {
-        const parsed = parseEmailSearch(args.query);
-        if (!parsed.valid) {
-            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 ClientInputError('invalid_request', merged.diagnostics.map((item) => item.message).join(' '), {
-                diagnostics: merged.diagnostics,
-            });
-        }
-        const result = await service.listMessages(args.accountId, merged.query, pageOpts(args));
-        return {
-            ...result,
-            ...([...parsed.diagnostics, ...(result.diagnostics ?? [])].length
-                ? { diagnostics: [...parsed.diagnostics, ...(result.diagnostics ?? [])] }
-                : {}),
-        };
-    }));
-    const { pageToken: _batchPageToken, rawProviderQuery: _batchRawProviderQuery, ...batchSearchFilterShape } = searchFilterShape;
-    registerSharedTool('search_emails_batch', {
-        accounts: z
-            .array(z.object(nullableOptionalInputs({ accountId: idParam, pageToken: z.string().min(1).optional() })).strict())
-            .min(1)
-            .max(20),
-        query: searchString.min(1).describe('Typed portable search syntax'),
-        ...batchSearchFilterShape,
-        folder: z.enum(['inbox', 'sent', 'drafts', 'archive', 'spam', 'trash', 'all']).optional(),
-    }, gatedResult('search_emails_batch', async (args) => {
-        const parsed = parseEmailSearch(args.query);
-        if (!parsed.valid) {
-            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 ClientInputError('invalid_request', merged.diagnostics.map((item) => item.message).join(' '), {
-                diagnostics: merged.diagnostics,
-            });
-        }
+    const typedQuery = searchString
+        .optional()
+        .describe('Typed search. Plain words search the message text; quote a phrase or a value that has spaces. Filters: ' +
+        'from:, to:, subject:, in:inbox|sent|drafts|archive|spam|trash|all, is:read, is:unread, is:starred, ' +
+        'is:unstarred, has:attachment, -has:attachment, after:YYYY-MM-DD (inclusive) and before:YYYY-MM-DD ' +
+        '(exclusive), in UTC. Terms combine with AND; OR and parentheses are searched as text.');
+    const listEmails = async (args) => {
+        const { query, warnings } = typedSearch(args.query, emailQuery(args));
+        const result = await service.listMessages(args.accountId, query, pageOpts(args));
+        const diagnostics = [...warnings, ...(result.diagnostics ?? [])];
+        return { ...result, ...(diagnostics.length ? { diagnostics } : {}) };
+    };
+    const listEmailsShape = { accountId: accountIdParam, query: typedQuery, ...queryShape };
+    // search_emails is an alias of list_emails. It reports its own operation name so telemetry can tell them apart.
+    for (const name of ['list_emails', 'search_emails']) {
+        registerSharedTool(name, listEmailsShape, gated(name, listEmails));
+    }
+    const listEmailsBatch = async (args) => {
+        const { query, warnings } = typedSearch(args.query, emailQuery(args));
         const result = await service.searchMessagesBatch({
             accounts: args.accounts,
-            query: merged.query,
+            query: query,
             ...(args.pageSize !== undefined ? { pageSize: args.pageSize } : {}),
             ...(args.includeSnippet !== undefined ? { includeSnippet: args.includeSnippet } : {}),
             ...(args.includeSearchContext !== undefined ? { includeSearchContext: args.includeSearchContext } : {}),
@@ -634,7 +700,7 @@ export function buildMcpServer(service, options = {}) {
             groups: result.groups.map((group) => {
                 if (!group.page)
                     return group;
-                const diagnostics = [...parsed.diagnostics, ...(group.page.diagnostics ?? [])];
+                const diagnostics = [...warnings, ...(group.page.diagnostics ?? [])];
                 return {
                     ...group,
                     page: { ...group.page, ...(diagnostics.length ? { diagnostics } : {}) },
@@ -648,7 +714,24 @@ export function buildMcpServer(service, options = {}) {
             response[TELEMETRY_FAILURE] = batchFailureCause(result.groups);
         }
         return response;
-    }));
+    };
+    const { pageSize, includeSnippet, includeSearchContext } = queryShape;
+    const listEmailsBatchShape = {
+        accounts: z
+            .array(z.object(nullableOptionalInputs({ accountId: idParam, pageToken: z.string().min(1).optional() })).strict())
+            .min(1)
+            .max(20),
+        query: typedQuery,
+        // Custom folder names differ between accounts, so a batch takes only a folder role.
+        folder: z.enum(['inbox', 'sent', 'drafts', 'archive', 'spam', 'trash', 'all']).optional(),
+        pageSize,
+        includeSnippet,
+        includeSearchContext,
+    };
+    // search_emails_batch is an alias of list_emails_batch, with its own operation name in telemetry.
+    for (const name of ['list_emails_batch', 'search_emails_batch']) {
+        registerSharedTool(name, listEmailsBatchShape, gatedResult(name, listEmailsBatch));
+    }
     registerSharedTool('get_email', {
         accountId: accountIdParam,
         messageId: idParam,
@@ -661,12 +744,12 @@ export function buildMcpServer(service, options = {}) {
     registerSharedTool('get_email_body', {
         accountId: accountIdParam,
         messageId: idParam,
-        format: z.enum(['text', 'html']),
+        bodyFormat: z.enum(['text', 'html']).describe('The body part to read'),
         offset: z.number().int().min(0).optional(),
         maxChars: z.number().int().min(1).max(MAX_BODY_CHARS).optional(),
     }, gated('get_email_body', async (args) => {
         const message = await service.getMessage(args.accountId, args.messageId);
-        return bodyPage(message, args.format, args.offset, args.maxChars);
+        return bodyPage(message, args.bodyFormat, args.offset, args.maxChars);
     }));
     registerSharedTool('get_thread', {
         accountId: accountIdParam,
@@ -674,9 +757,13 @@ export function buildMcpServer(service, options = {}) {
         pageSize: z.number().int().min(1).max(25).optional(),
         pageToken: z.string().min(1).max(MAX_THREAD_PAGE_TOKEN_CHARS).optional(),
         bodyFormat: z.enum(['text', 'html', 'both', 'none']).optional(),
+        order: z
+            .enum(['oldest', 'newest'])
+            .optional()
+            .describe('oldest (default) starts with the first message; newest starts with the latest message and pages back in time'),
     }, gated('get_thread', async (args) => {
         const thread = await service.getThread(args.accountId, args.threadId);
-        const offset = threadPageOffset(args.threadId, args.pageToken);
+        const offset = threadPageOffset(args.threadId, args.pageToken, args.order);
         if (offset === undefined)
             throw new ClientInputError('invalid_request', 'Invalid thread page token.');
         return threadPage(thread, {
@@ -684,6 +771,7 @@ export function buildMcpServer(service, options = {}) {
             offset,
             pageSize: args.pageSize,
             bodyFormat: args.bodyFormat,
+            order: args.order,
         });
     }));
     registerSharedTool('get_draft', { accountId: accountIdParam, draftId: idParam }, gated('get_draft', async (args) => service.getDraft(args.accountId, args.draftId)));
@@ -715,12 +803,7 @@ export function buildMcpServer(service, options = {}) {
             .describe('Reuse this key when retrying the same delivery'),
         draftId: idParam.optional().describe('Send this existing draft'),
         ...draftShape,
-        sendAt: sendAtSchema
-            .optional()
-            .describe('Schedule delivery instead of sending now: ISO 8601 with timezone offset or Z ' +
-            '(e.g. 2026-07-11T09:00:00-07:00). Fluxmail saves the message as a real draft in the mailbox ' +
-            'for delivery by fluxmail serve or fluxmail scheduled run using the same store. Stdio does not ' +
-            'deliver schedules. Overdue mail may send when a worker starts. Returns a scheduleId for list/cancel.'),
+        sendAt: sendAtParam,
     }, handleResult('send_email', async (args) => {
         requireToolScopes('send_email');
         if (args.replyToMessageId !== undefined)
@@ -737,16 +820,16 @@ export function buildMcpServer(service, options = {}) {
                 'For failed entries, lastError says what went wrong. Pending sends only fire while the ' +
                 'Fluxmail server is running.',
             inputSchema: { accountId: accountIdParam },
-            annotations: { readOnlyHint: true },
+            annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
         }, gated('list_scheduled_emails', async (args) => service.listScheduled(args.accountId)));
-    registerSharedTool('get_delivery_operation', { accountId: idParam, operationId: idParam }, allowed('get_delivery_operation', async (args) => service.getDelivery(args.accountId, args.operationId)));
+    registerSharedTool('get_delivery_operation', { accountId: accountIdParam, operationId: idParam }, allowed('get_delivery_operation', async (args) => service.getDelivery(args.accountId, args.operationId)));
     if (canAll(toolScopes('cancel_scheduled_email')))
         registerTool('cancel_scheduled_email', {
             title: 'Cancel scheduled email',
-            description: 'Cancel a pending scheduled send by scheduleId (from send_email with sendAt, or list_scheduled_emails). ' +
+            description: 'Cancel a pending scheduled send by scheduleId (from send_email or forward_email with sendAt, or list_scheduled_emails). ' +
                 'The draft stays in the Drafts folder, so the content is not lost.',
             inputSchema: { scheduleId: idParam },
-            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
         }, gated('cancel_scheduled_email', async (args) => service.cancelScheduled(args.scheduleId)));
     registerSharedTool('forward_email', {
         idempotencyKey: z
@@ -758,23 +841,30 @@ export function buildMcpServer(service, options = {}) {
         from: z.string().email().optional().describe('Connected address or an available send-as address'),
         to: addressList.min(1),
         cc: addressList.optional(),
+        bcc: addressList.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'),
+        sendAt: sendAtParam,
     }, handleResult('forward_email', async (args) => {
         requireToolScopes('forward_email');
         const to = parseAddresses(args.to) ?? [];
         const cc = parseAddresses(args.cc);
-        return deliveryResult(await service.deliverForward(args.accountId, {
+        const bcc = parseAddresses(args.bcc);
+        const forward = {
             messageId: args.messageId,
             to,
             ...(cc?.length ? { cc } : {}),
+            ...(bcc?.length ? { bcc } : {}),
             ...(args.comment !== undefined ? { comment: args.comment } : {}),
             ...(args.includeAttachments !== undefined ? { includeAttachments: args.includeAttachments } : {}),
             ...(args.from !== undefined ? { from: args.from } : {}),
-        }, args.idempotencyKey));
+        };
+        return deliveryResult(await (args.sendAt !== undefined
+            ? service.scheduleDelivery(args.accountId, { forward }, args.sendAt, args.idempotencyKey)
+            : service.deliverForward(args.accountId, forward, args.idempotencyKey)));
     }, () => service.enforceQuota(), toolOptions));
     const modifyEmails = async (action, args) => {
         requireToolScopes(MODIFY_TOOLS[action].name);
@@ -783,9 +873,12 @@ export function buildMcpServer(service, options = {}) {
             throw new ClientInputError('invalid_request', mapped.error);
         const result = await service.modify(args.accountId, args.messageIds, mapped.action);
         const response = ok({ ...result, action });
-        if (result.failed.length || result.uncertainIds.length) {
+        const failure = modifyFailure(result);
+        if (failure) {
             response.isError = true;
             response[TELEMETRY_ERROR] = true;
+            response[TELEMETRY_ERROR_CODE] = failure.errorCode;
+            response[TELEMETRY_FAILURE] = failure.cause;
         }
         return response;
     };
@@ -836,10 +929,17 @@ export function buildMcpServer(service, options = {}) {
     }), `The size limit is ${sizeLabel(maxAttachmentBytes)}.`);
     if (can('mail.read'))
         server.registerResource('attachment', new ResourceTemplate(ATTACHMENT_URI_TEMPLATE, { list: undefined }), { description: 'Read one attachment from an authorized mailbox.' }, async (uri, variables) => {
-            requireCapabilities(['mail.read']);
-            service.enforceQuota();
-            const { meta, content } = await downloadAttachment(decodeURIComponent(String(variables.accountId)), decodeURIComponent(String(variables.messageId)), decodeURIComponent(String(variables.attachmentId)));
-            return { contents: [attachmentContents(uri.href, meta.mimeType || 'application/octet-stream', content)] };
+            // Like a tool call, a read in progress holds off shutdown so its provider connection stays open.
+            const finishActivity = options.telemetry?.beginActivity?.();
+            try {
+                requireCapabilities(['mail.read']);
+                service.enforceQuota();
+                const { meta, content } = await downloadAttachment(decodeURIComponent(String(variables.accountId)), decodeURIComponent(String(variables.messageId)), decodeURIComponent(String(variables.attachmentId)));
+                return { contents: [attachmentContents(uri.href, meta.mimeType || 'application/octet-stream', content)] };
+            }
+            finally {
+                finishActivity?.();
+            }
         });
     if (can('mail.read'))
         server.server.registerCapabilities({ resources: { listChanged: false } });