fluxmail 0.2.0 → 0.3.0

package/dist/mcp/buildServer.js

@@ -1,11 +1,10 @@
-import { existsSync, statSync, writeFileSync } from 'node:fs';
-import path from 'node:path';
 import { VERSION } from '../version.js';
 import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { EmailError, isEmailError, parseSingleAddress, } from '@fluxmail/core';
+import { DEFAULT_MAX_ATTACHMENT_BYTES } from '../config.js';
+import { FULL_PERMISSION_POLICY, hasCapability, normalizePermissionPolicy, } from '../permissions.js';
 const MAX_BODY_CHARS = 50_000;
-const MAX_INLINE_ATTACHMENT_BYTES = 2 * 1024 * 1024;
 const accountIdParam = z
     .string()
     .min(1)
@@ -127,12 +126,9 @@ function truncateBody(message) {
     }
     return { ...message, body };
 }
-function ok(data, warning) {
+function ok(data) {
     return {
-        content: [
-            { type: 'text', text: JSON.stringify(data, null, 2) },
-            ...(warning ? [{ type: 'text', text: `Note: ${warning}` }] : []),
-        ],
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
     };
 }
 function toolError(err) {
@@ -141,55 +137,82 @@ function toolError(err) {
         : { error: 'internal', message: err instanceof Error ? err.message : String(err) };
     return { isError: true, content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
 }
-function handle(fn, gate) {
+function toolFeatureProperties(tool, args) {
+    if (!args || typeof args !== 'object')
+        return {};
+    const input = args;
+    switch (tool) {
+        case 'create_draft':
+            return { reply: input.replyToMessageId !== undefined, reply_all: input.replyAll === true };
+        case 'send_email':
+            return {
+                mode: input.draftId !== undefined ? 'draft' : input.replyToMessageId !== undefined ? 'reply' : 'direct',
+                scheduled: input.sendAt !== undefined,
+                reply_all: input.replyAll === true,
+            };
+        case 'forward_email':
+            return { include_attachments: input.includeAttachments !== false };
+        case 'modify_emails':
+            return typeof input.action === 'string' ? { action: input.action } : {};
+        case 'download_attachment':
+            return { destination: 'inline' };
+        default:
+            return {};
+    }
+}
+function captureToolTelemetry(options, properties) {
+    try {
+        options.telemetry?.capture('mcp tool called', { ...properties, product_surface: 'mcp' });
+    }
+    catch {
+        // An injected telemetry client must not affect MCP results.
+    }
+}
+function handleResult(tool, fn, gate, options = {}) {
     return async (...args) => {
+        const finishActivity = options.telemetry?.beginActivity?.();
+        const startedAt = performance.now();
         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?.();
-            return ok(await fn(...args), warning);
+            const result = await fn(...args);
+            if (warning)
+                result.content.push({ type: 'text', text: `Note: ${warning}` });
+            captureToolTelemetry(options, {
+                tool,
+                transport: options.transport ?? 'unknown',
+                outcome: 'success',
+                duration_ms: Math.round(performance.now() - startedAt),
+                ...toolFeatureProperties(tool, args[0]),
+            });
+            return result;
         }
         catch (err) {
+            captureToolTelemetry(options, {
+                tool,
+                transport: options.transport ?? 'unknown',
+                outcome: 'error',
+                error_code: isEmailError(err) ? err.code : 'internal',
+                duration_ms: Math.round(performance.now() - startedAt),
+                ...toolFeatureProperties(tool, args[0]),
+            });
             return toolError(err);
         }
+        finally {
+            finishActivity?.();
+        }
     };
 }
+function handle(tool, fn, gate, options = {}) {
+    return handleResult(tool, async (...args) => ok(await fn(...args)), gate, options);
+}
 function pageOpts(args) {
     return {
         ...(args.pageSize !== undefined ? { pageSize: args.pageSize } : {}),
         ...(args.pageToken !== undefined ? { pageToken: args.pageToken } : {}),
     };
 }
-export function resolveAttachmentSavePath(savePath, filename) {
-    const isDir = savePath.endsWith(path.sep) || (existsSync(savePath) && statSync(savePath).isDirectory());
-    if (!isDir)
-        return savePath;
-    const safeFilename = path.posix.basename(filename.replace(/\\/g, '/'));
-    if (!safeFilename || safeFilename === '.' || safeFilename === '..') {
-        throw new Error('Attachment filename is not safe to use');
-    }
-    const directory = path.resolve(savePath);
-    const target = path.resolve(directory, safeFilename);
-    if (path.dirname(target) !== directory) {
-        throw new Error('Attachment filename escapes the destination directory');
-    }
-    return target;
-}
-export function saveAttachment(savePath, filename, content) {
-    if (!path.isAbsolute(savePath))
-        throw new EmailError('invalid_request', 'savePath must be absolute');
-    const target = resolveAttachmentSavePath(savePath, filename);
-    try {
-        writeFileSync(target, content, { flag: 'wx' });
-    }
-    catch (err) {
-        if (err.code === 'EEXIST') {
-            throw new EmailError('invalid_request', `Refusing to overwrite an existing attachment file: ${target}`);
-        }
-        throw err;
-    }
-    return target;
-}
 function emailQuery(args) {
     const keys = [
         'folder',
@@ -210,205 +233,286 @@ function emailQuery(args) {
             q[key] = args[key];
     return q;
 }
-export function buildMcpServer(service) {
+const MODIFY_CAPABILITIES = {
+    markRead: 'mail.organize',
+    markUnread: 'mail.organize',
+    star: 'mail.organize',
+    unstar: 'mail.organize',
+    archive: 'mail.organize',
+    trash: 'mail.trash',
+    untrash: 'mail.trash',
+    delete: 'mail.delete',
+    move: 'mail.organize',
+    addLabels: 'mail.organize',
+    removeLabels: 'mail.organize',
+};
+const PROTECTED_MOVE_DESTINATIONS = new Set(['archive', 'trash']);
+const SYSTEM_LABELS = new Set(['inbox', 'sent', 'draft', 'drafts', 'trash', 'spam', 'starred', 'unread', 'important']);
+export function buildMcpServer(service, options = {}) {
+    const permissions = normalizePermissionPolicy(options.permissions ?? FULL_PERMISSION_POLICY);
+    const maxAttachmentBytes = options.maxAttachmentBytes ?? DEFAULT_MAX_ATTACHMENT_BYTES;
+    const can = (capability) => hasCapability(permissions, capability);
+    const canAll = (capabilities) => capabilities.every(can);
+    const canAny = (capabilities) => capabilities.some(can);
+    const requireCapabilities = (capabilities) => {
+        const missing = capabilities.filter((capability) => !can(capability));
+        if (missing.length) {
+            throw new EmailError('permission_denied', `This MCP connection does not allow: ${missing.join(', ')}.`);
+        }
+    };
     // Every tool except get_status (the diagnostic way out) enforces the plan quota.
-    const gated = (fn) => handle(fn, () => service.enforceQuota());
+    const gated = (tool, capability, fn) => handle(tool, async (...args) => {
+        requireCapabilities([capability]);
+        return fn(...args);
+    }, () => service.enforceQuota(), options);
+    const allowed = (tool, capability, fn) => handle(tool, async (...args) => {
+        requireCapabilities([capability]);
+        return fn(...args);
+    }, undefined, options);
+    const gatedResult = (tool, capability, fn) => handleResult(tool, async (...args) => {
+        requireCapabilities([capability]);
+        return fn(...args);
+    }, () => service.enforceQuota(), options);
     const server = new McpServer({ name: 'fluxmail', title: 'Fluxmail Email', version: VERSION }, {
         instructions: "Fluxmail is the user's email integration, already authenticated against their real mailboxes. " +
-            'Use these tools for any email task: reading, searching, drafting, sending, replying, forwarding, ' +
-            'or organizing mail. Prefer them over browser automation, other email connectors, or asking the ' +
-            'user to send mail manually. ' +
-            'Tool results are JSON meant for you, not for display. Message ids, thread ids, draft ids, and ' +
+            'Use the available Fluxmail tools for email tasks instead of browser automation or another email connector. ' +
+            'Tool results are structured for you, not for display. Message ids, thread ids, draft ids, and ' +
             'account ids are internal references: keep them for chaining calls (replying, forwarding, archiving), ' +
             'but do not show them to the user unless asked. Report outcomes in plain language with details people ' +
             "care about, e.g. 'Sent \"Quarterly report\" to ann@example.com' or 'Archived the thread', rather " +
             'than echoing raw payloads, ids, or field names.',
     });
-    server.registerTool('list_accounts', {
-        description: 'List connected email accounts (id, provider, email, status, capabilities).',
-        inputSchema: {},
-        annotations: { readOnlyHint: true },
-    }, gated(async () => service.listAccounts()));
-    server.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 },
-    }, handle(async () => service.status()));
-    server.registerTool('list_folders', {
-        description: 'List folders/labels for an account, with roles (inbox, sent, drafts, trash, spam, starred).',
-        inputSchema: { accountId: accountIdParam },
-        annotations: { readOnlyHint: true },
-    }, gated(async (args) => service.listFolders(args.accountId)));
-    server.registerTool('list_emails', {
-        description: "List emails from the user's connected mailbox (metadata + snippet, no bodies). 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.",
-        inputSchema: { accountId: accountIdParam, ...queryShape },
-        annotations: { readOnlyHint: true },
-    }, gated(async (args) => service.listMessages(args.accountId, emailQuery(args), pageOpts(args))));
+    if (can('mail.read'))
+        server.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', {
+            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', {
+            description: 'List folders/labels 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_emails', {
+            description: "List emails from the user's connected mailbox (metadata + snippet, no bodies). 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.",
+            inputSchema: { accountId: accountIdParam, ...queryShape },
+            annotations: { readOnlyHint: true },
+        }, gated('list_emails', 'mail.read', async (args) => service.listMessages(args.accountId, emailQuery(args), pageOpts(args))));
     const { text: _text, ...searchFilterShape } = queryShape;
-    server.registerTool('search_emails', {
-        description: 'Full-text search across an account\'s email. Same filters as list_emails; "query" is the search text.',
-        inputSchema: {
-            accountId: accountIdParam,
-            query: z.string().describe('Search text'),
-            ...searchFilterShape,
-        },
-        annotations: { readOnlyHint: true },
-    }, gated(async (args) => service.listMessages(args.accountId, { ...emailQuery(args), text: args.query }, pageOpts(args))));
-    server.registerTool('get_email', {
-        description: 'Fetch one email in full: body (text and/or HTML), recipients, attachment metadata.',
-        inputSchema: { accountId: accountIdParam, messageId: idParam },
-        annotations: { readOnlyHint: true },
-    }, gated(async (args) => truncateBody(await service.getMessage(args.accountId, args.messageId))));
-    server.registerTool('get_thread', {
-        description: 'Fetch a full conversation thread with all message bodies.',
-        inputSchema: { accountId: accountIdParam, threadId: idParam },
-        annotations: { readOnlyHint: true },
-    }, gated(async (args) => {
-        const thread = await service.getThread(args.accountId, args.threadId);
-        return { ...thread, messages: thread.messages.map(truncateBody) };
-    }));
-    server.registerTool('create_draft', {
-        description: 'Create a draft. For a reply draft, pass replyToMessageId (recipients/subject are derived; replyAll for reply-all).',
-        inputSchema: draftShape,
-    }, gated(async (args) => service.createDraft(args.accountId, toSendInput(args))));
-    server.registerTool('update_draft', {
-        description: 'Replace the content of an existing draft (full replacement, not a patch).',
-        inputSchema: { draftId: idParam, ...draftShape },
-    }, gated(async (args) => service.updateDraft(args.accountId, args.draftId, toSendInput(args))));
-    server.registerTool('delete_draft', {
-        description: 'Delete a draft.',
-        inputSchema: { accountId: accountIdParam, draftId: idParam },
-        annotations: { destructiveHint: true },
-    }, gated(async (args) => {
-        await service.deleteDraft(args.accountId, args.draftId);
-        return { deleted: args.draftId };
-    }));
-    server.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: {
-            draftId: idParam.optional().describe('Send this existing draft'),
-            ...draftShape,
-            sendAt: z
-                .string()
-                .datetime({ offset: true })
-                .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 ' +
-                'and sends it at this time; the server must be running then (anything missed while it was ' +
-                'down goes out at the next startup). Returns a scheduleId for list/cancel.'),
-        },
-        annotations: { destructiveHint: true },
-    }, gated(async (args) => {
-        const { sendAt, ...sendArgs } = args;
-        return sendAt !== undefined
-            ? service.scheduleSend(args.accountId, toSendRequest(sendArgs), sendAt)
-            : service.send(args.accountId, toSendRequest(sendArgs));
-    }));
-    server.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(async (args) => service.listScheduled(args.accountId)));
-    server.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(async (args) => service.cancelScheduled(args.scheduleId)));
-    server.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: {
-            accountId: accountIdParam,
-            messageId: idParam,
-            to: addressList.min(1),
-            cc: addressList.optional(),
-            comment: z.string().optional(),
-            includeAttachments: z.boolean().optional().describe('Default true'),
-        },
-        annotations: { destructiveHint: true },
-    }, gated(async (args) => {
-        const to = parseAddresses(args.to) ?? [];
-        const cc = parseAddresses(args.cc);
-        return service.forward(args.accountId, {
-            messageId: args.messageId,
-            to,
-            ...(cc?.length ? { cc } : {}),
-            ...(args.comment !== undefined ? { comment: args.comment } : {}),
-            ...(args.includeAttachments !== undefined ? { includeAttachments: args.includeAttachments } : {}),
-        });
-    }));
-    server.registerTool('modify_emails', {
-        description: 'Batch-modify emails: markRead, markUnread, star, unstar, archive, trash, untrash, delete (permanent!), ' +
-            'move (requires folder), addLabels/removeLabels (requires labels; Gmail only).',
-        inputSchema: {
-            accountId: accountIdParam,
-            messageIds: z.array(idParam).min(1),
-            action: z.enum([
-                'markRead',
-                'markUnread',
-                'star',
-                'unstar',
-                'archive',
-                'trash',
-                'untrash',
-                'delete',
-                'move',
-                'addLabels',
-                'removeLabels',
-            ]),
-            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'),
-        },
-        annotations: { destructiveHint: true },
-    }, gated(async (args) => {
-        let action;
-        if (args.action === 'move') {
-            if (!args.folder)
-                throw new EmailError('invalid_request', 'action=move requires "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"`);
+    if (can('mail.read'))
+        server.registerTool('search_emails', {
+            description: 'Full-text search across an account\'s email. Same filters as list_emails; "query" is the search text.',
+            inputSchema: {
+                accountId: accountIdParam,
+                query: z.string().describe('Search text'),
+                ...searchFilterShape,
+            },
+            annotations: { readOnlyHint: true },
+        }, gated('search_emails', 'mail.read', async (args) => service.listMessages(args.accountId, { ...emailQuery(args), text: args.query }, pageOpts(args))));
+    if (can('mail.read'))
+        server.registerTool('get_email', {
+            description: 'Fetch one email in full: body (text and/or HTML), recipients, attachment metadata.',
+            inputSchema: { accountId: accountIdParam, messageId: idParam },
+            annotations: { readOnlyHint: true },
+        }, gated('get_email', 'mail.read', async (args) => truncateBody(await service.getMessage(args.accountId, args.messageId))));
+    if (can('mail.read'))
+        server.registerTool('get_thread', {
+            description: 'Fetch a full conversation thread with all message bodies.',
+            inputSchema: { accountId: accountIdParam, threadId: idParam },
+            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) };
+        }));
+    if (can('mail.drafts'))
+        server.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) => {
+            if (args.replyToMessageId)
+                requireCapabilities(['mail.read']);
+            return service.createDraft(args.accountId, toSendInput(args));
+        }));
+    if (can('mail.drafts'))
+        server.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) => {
+            if (args.replyToMessageId)
+                requireCapabilities(['mail.read']);
+            return service.updateDraft(args.accountId, args.draftId, toSendInput(args));
+        }));
+    if (can('mail.drafts'))
+        server.registerTool('delete_draft', {
+            description: 'Delete a draft.',
+            inputSchema: { accountId: accountIdParam, draftId: idParam },
+            annotations: { destructiveHint: true },
+        }, gated('delete_draft', 'mail.drafts', async (args) => {
+            await service.deleteDraft(args.accountId, args.draftId);
+            return { deleted: args.draftId };
+        }));
+    if (can('mail.send'))
+        server.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: {
+                draftId: idParam.optional().describe('Send this existing draft'),
+                ...draftShape,
+                sendAt: z
+                    .string()
+                    .datetime({ offset: true })
+                    .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 ' +
+                    'and sends it at this time; the server must be running then (anything missed while it was ' +
+                    'down goes out at the next startup). Returns a scheduleId for list/cancel.'),
+            },
+            annotations: { destructiveHint: true },
+        }, handle('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));
+        }, () => service.enforceQuota(), options));
+    if (can('mail.read'))
+        server.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.drafts'))
+        server.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', {
+            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: {
+                accountId: accountIdParam,
+                messageId: idParam,
+                to: addressList.min(1),
+                cc: addressList.optional(),
+                comment: z.string().optional(),
+                includeAttachments: z.boolean().optional().describe('Default true'),
+            },
+            annotations: { destructiveHint: true },
+        }, handle('forward_email', async (args) => {
+            requireCapabilities(['mail.send', 'mail.read']);
+            const to = parseAddresses(args.to) ?? [];
+            const cc = parseAddresses(args.cc);
+            return service.forward(args.accountId, {
+                messageId: args.messageId,
+                to,
+                ...(cc?.length ? { cc } : {}),
+                ...(args.comment !== undefined ? { comment: args.comment } : {}),
+                ...(args.includeAttachments !== undefined ? { includeAttachments: args.includeAttachments } : {}),
+            });
+        }, () => 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', {
+            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),
+                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'),
+            },
+            annotations: {
+                destructiveHint: canAny(['mail.trash', 'mail.delete']),
+            },
+        }, handle('modify_emails', async (args) => {
+            if (!allowedModifyActions.has(args.action)) {
+                throw new EmailError('permission_denied', `This MCP connection does not allow action=${args.action}.`);
             }
-            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 };
-    }));
-    server.registerTool('download_attachment', {
-        description: 'Download an email attachment. With savePath, writes the file to disk and returns the path; ' +
-            'otherwise returns base64 content (up to 2 MB).',
-        inputSchema: {
-            accountId: accountIdParam,
-            messageId: idParam,
-            attachmentId: idParam,
-            savePath: z.string().min(1).optional().describe('Absolute file path or directory to write the attachment to'),
-        },
-        annotations: { readOnlyHint: false, destructiveHint: true },
-    }, gated(async (args) => {
-        const { meta, content } = await service.getAttachment(args.accountId, args.messageId, args.attachmentId);
-        if (args.savePath) {
-            const target = saveAttachment(args.savePath, meta.filename, content);
-            return { saved: target, ...meta };
-        }
-        if (content.length > MAX_INLINE_ATTACHMENT_BYTES) {
-            throw new EmailError('invalid_request', `Attachment is ${content.length} bytes (limit ${MAX_INLINE_ATTACHMENT_BYTES} inline). Pass savePath to write it to disk.`);
-        }
-        return { ...meta, contentBase64: content.toString('base64') };
-    }));
+            requireCapabilities([MODIFY_CAPABILITIES[args.action]]);
+            let action;
+            if (args.action === 'move') {
+                if (!args.folder)
+                    throw new EmailError('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');
+                }
+                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"`);
+                }
+                if (args.labels.some((label) => SYSTEM_LABELS.has(label.trim().toLowerCase()))) {
+                    throw new EmailError('invalid_request', 'System labels must be changed with their dedicated message action');
+                }
+                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 };
+        }, () => service.enforceQuota(), options));
+    }
+    if (can('mail.read'))
+        server.registerTool('download_attachment', {
+            description: 'Download an email attachment as an embedded MCP resource.',
+            inputSchema: {
+                accountId: accountIdParam,
+                messageId: idParam,
+                attachmentId: idParam,
+            },
+            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.', {
+                    sizeBytes: content.length,
+                    maxBytes: maxAttachmentBytes,
+                });
+            }
+            const uri = [
+                'fluxmail://attachment',
+                encodeURIComponent(args.accountId ?? 'default'),
+                encodeURIComponent(args.messageId),
+                encodeURIComponent(args.attachmentId),
+                encodeURIComponent(meta.filename),
+            ].join('/');
+            return {
+                content: [
+                    { type: 'text', text: JSON.stringify(meta, null, 2) },
+                    {
+                        type: 'resource',
+                        resource: {
+                            uri,
+                            mimeType: meta.mimeType || 'application/octet-stream',
+                            blob: content.toString('base64'),
+                        },
+                    },
+                ],
+            };
+        }));
     return server;
 }
 //# sourceMappingURL=buildServer.js.map