fluxmail 0.13.0 → 0.14.0

package/dist/mcp/attachmentContent.js

@@ -0,0 +1,155 @@
+import { fileURLToPath } from 'node:url';
+import { Worker } from 'node:worker_threads';
+import { z } from 'zod';
+const TEXT_TYPES = /^(text\/[\w.+-]+|application\/(json|xml|csv|yaml|x-yaml|javascript|[\w.-]+\+(json|xml)))$/;
+const IMAGE_TYPES = /^image\/(png|jpeg|gif|webp)$/;
+// At most `workers` extractions run at once in this process, so concurrent requests cannot
+// multiply the heap limit. Waiting for a worker shares the same timeout as extraction.
+const PDF_TEXT_LIMITS = { maxPages: 200, maxChars: 80_000, heapMb: 128, timeoutMs: 15_000, workers: 2 };
+export function mediaType(mimeType) {
+    return mimeType.split(';')[0].trim().toLowerCase();
+}
+function decodeText(content) {
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(content);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Some clients, including claude.ai, only pass a blob to the model through
+ * file storage, so UTF-8 text attachments go out as text.
+ */
+export function attachmentContents(uri, mimeType, content) {
+    const text = TEXT_TYPES.test(mediaType(mimeType)) ? decodeText(content) : undefined;
+    return text === undefined ? { uri, mimeType, blob: content.toString('base64') } : { uri, mimeType, text };
+}
+export function inlineContent(uri, mimeType, content) {
+    if (IMAGE_TYPES.test(mediaType(mimeType)))
+        return { type: 'image', data: content.toString('base64'), mimeType };
+    return { type: 'resource', resource: attachmentContents(uri, mimeType, content) };
+}
+function parsePages(pages) {
+    const [first, last = first] = pages.split('-').map(Number);
+    return { first, last };
+}
+export const pageRange = z
+    .string()
+    .regex(/^[1-9]\d{0,5}(-[1-9]\d{0,5})?$/)
+    .refine((value) => {
+    const { first, last } = parsePages(value);
+    return last >= first;
+}, { message: 'Use a page or an ascending range such as 201-400.' })
+    .describe('PDF page or page range to read as text, such as 201-400');
+// The build emits the worker next to this module; tests load the source.
+const PDF_WORKER_URL = new URL(import.meta.url.endsWith('.ts') ? './pdfTextWorker.ts' : './pdfTextWorker.js', import.meta.url);
+// Character maps for PDFs that use predefined CJK encodings, copied from pdfjs-dist at the
+// pdf.js version unpdf bundles. Refresh them when upgrading unpdf. Same path from src and dist.
+export const PDF_CMAP_PDFJS_VERSION = '5.6.205';
+const PDF_CMAP_DIRECTORY = fileURLToPath(new URL('../../pdf-cmaps/', import.meta.url));
+let runningWorkers = 0;
+const workerQueue = [];
+/** Resolves true once a worker slot is held, or false when the signal aborts first. */
+function acquireWorkerSlot(signal) {
+    if (signal.aborted)
+        return Promise.resolve(false);
+    if (runningWorkers < PDF_TEXT_LIMITS.workers) {
+        runningWorkers++;
+        return Promise.resolve(true);
+    }
+    return new Promise((resolve) => {
+        const grant = () => {
+            signal.removeEventListener('abort', cancel);
+            resolve(true);
+        };
+        const cancel = () => {
+            workerQueue.splice(workerQueue.indexOf(grant), 1);
+            resolve(false);
+        };
+        workerQueue.push(grant);
+        signal.addEventListener('abort', cancel, { once: true });
+    });
+}
+/** Hand the slot to the next waiting extraction, or free it. */
+function releaseWorkerSlot() {
+    const next = workerQueue.shift();
+    if (next)
+        next();
+    else
+        runningWorkers--;
+}
+/** Extract PDF text in a memory-limited worker. Resolves undefined when extraction fails or is aborted. */
+export async function pdfText(content, signal, pages = '1-999999', onError) {
+    const waitTimeout = AbortSignal.timeout(PDF_TEXT_LIMITS.timeoutMs);
+    if (!(await acquireWorkerSlot(AbortSignal.any([signal, waitTimeout])))) {
+        if (waitTimeout.aborted && !signal.aborted)
+            onError?.(new Error('PDF text extraction timed out waiting for a worker.'));
+        return undefined;
+    }
+    try {
+        return await runPdfWorker(content, signal, pages, onError);
+    }
+    finally {
+        releaseWorkerSlot();
+    }
+}
+function runPdfWorker(content, signal, pages, onError) {
+    const { first: firstPage, last: lastPage } = parsePages(pages);
+    return new Promise((resolve) => {
+        if (signal.aborted)
+            return resolve(undefined);
+        const bytes = new Uint8Array(content);
+        const worker = new Worker(PDF_WORKER_URL, {
+            workerData: {
+                bytes,
+                cMapDirectory: PDF_CMAP_DIRECTORY,
+                firstPage,
+                lastPage,
+                maxPages: PDF_TEXT_LIMITS.maxPages,
+                maxChars: PDF_TEXT_LIMITS.maxChars,
+            },
+            transferList: [bytes.buffer],
+            resourceLimits: { maxOldGenerationSizeMb: PDF_TEXT_LIMITS.heapMb },
+        });
+        let settled = false;
+        const finish = (result, error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal.removeEventListener('abort', abort);
+            if (error)
+                onError?.(error);
+            // Resolve after the thread stops so a released slot no longer holds its heap.
+            void worker.terminate().finally(() => resolve(result));
+        };
+        const abort = () => finish();
+        const timer = setTimeout(() => finish(undefined, new Error('PDF text extraction timed out.')), PDF_TEXT_LIMITS.timeoutMs);
+        signal.addEventListener('abort', abort, { once: true });
+        worker.once('message', (result) => finish(result));
+        worker.once('error', (error) => finish(undefined, error));
+        worker.once('exit', (code) => finish(undefined, new Error(`PDF text worker exited with code ${code}.`)));
+    });
+}
+export function pdfTextContent(filename, pdf) {
+    if (!pdf)
+        return [];
+    const { firstPage, lastPage, totalPages } = pdf;
+    if (lastPage < firstPage) {
+        return [{ type: 'text', text: `${filename} has ${totalPages} ${totalPages === 1 ? 'page' : 'pages'}.` }];
+    }
+    const whole = firstPage === 1 && lastPage === totalPages && !pdf.cut;
+    const pages = firstPage === lastPage ? `page ${firstPage}` : `pages ${firstPage}-${lastPage}`;
+    const cut = pdf.cut ? `, cut at ${PDF_TEXT_LIMITS.maxChars.toLocaleString('en-US')} characters` : '';
+    const scope = whole ? '' : ` (${pages} of ${totalPages}${cut})`;
+    return [
+        {
+            type: 'text',
+            text: pdf.text
+                ? `Text extracted from ${filename}${scope}:\n\n${pdf.text}`
+                : `No text found in ${filename}${scope}.`,
+        },
+    ];
+}
+//# sourceMappingURL=attachmentContent.js.map

package/dist/mcp/attachmentContent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachmentContent.js","sourceRoot":"","sources":["../../src/mcp/attachmentContent.ts"],"names":[],"mappings":"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"}

package/dist/mcp/buildServer.d.ts

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { EmailService, SendInput } from '../service/emailService.js';
-import { type PermissionPolicy } from '../permissions.js';
+import { type PermissionPolicy, type PermissionSource } from '../permissions.js';
 import { type Telemetry } from '../telemetry.js';
 import { type Logger } from '../logging.js';
 type DraftArgs = {
@@ -28,6 +28,8 @@ export declare function toSendRequest(args: DraftArgs & {
 export type McpTransport = 'http' | 'stdio' | 'unknown';
 export interface BuildMcpServerOptions {
     permissions?: PermissionPolicy;
+    /** How the connection's permissions can be changed. Defaults to the stdio options for stdio transport. */
+    permissionSource?: PermissionSource;
     maxAttachmentBytes?: number;
     telemetry?: Telemetry;
     transport?: McpTransport;

package/dist/mcp/buildServer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buildServer.d.ts","sourceRoot":"","sources":["../../src/mcp/buildServer.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,SAAS,EAAoB,MAAM,yCAAyC,CAAC;AAgBtF,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAG1E,OAAO,EAKL,KAAK,gBAAgB,EACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAoB,KAAK,SAAS,EAA4B,MAAM,iBAAiB,CAAC;AAC7F,OAAO,EAAc,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AAyHxD,KAAK,SAAS,GAAG;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC9E,CAAC;AA0BF,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAuBrG;AAoDD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAExD,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,gBAAgB,GAAG,qBAAqB,CAAC;AAkJrD,wBAAgB,cAAc,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,GAAE,qBAA0B,GAAG,SAAS,CA0xBpG"}
+{"version":3,"file":"buildServer.d.ts","sourceRoot":"","sources":["../../src/mcp/buildServer.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,SAAS,EAAoB,MAAM,yCAAyC,CAAC;AA2BtF,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAG1E,OAAO,EAQL,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAoB,KAAK,SAAS,EAA4B,MAAM,iBAAiB,CAAC;AAC7F,OAAO,EAAc,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AAsIxD,KAAK,SAAS,GAAG;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC9E,CAAC;AA0BF,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAuBrG;AAoDD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAExD,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,0GAA0G;IAC1G,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,gBAAgB,GAAG,qBAAqB,CAAC;AAuKrD,wBAAgB,cAAc,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,GAAE,qBAA0B,GAAG,SAAS,CAg2BpG"}

package/dist/mcp/buildServer.js

@@ -3,15 +3,20 @@ import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { isInitializeRequest, LATEST_PROTOCOL_VERSION, ListToolsRequestSchema, SUPPORTED_PROTOCOL_VERSIONS, } from '@modelcontextprotocol/sdk/types.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 { 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 { ClientInputError, publicError } from '../service/publicErrors.js';
+import { ClientInputError, MissingCapabilityError, publicError } from '../service/publicErrors.js';
 import { outputSchemas } from './outputSchemas.js';
+import { attachmentContents, inlineContent, mediaType, pageRange, pdfText, pdfTextContent, } from './attachmentContent.js';
 const MAX_BODY_CHARS = 50_000;
+const BYTES_PER_MEGABYTE = 1024 * 1024;
+function sizeLabel(bytes) {
+    return bytes % BYTES_PER_MEGABYTE === 0 ? `${bytes / BYTES_PER_MEGABYTE} MB` : `${bytes} bytes`;
+}
 const TELEMETRY_ERROR = Symbol('telemetryError');
 const EMPTY_INPUT_SCHEMA = {
     type: 'object',
@@ -219,7 +224,9 @@ function toolFeatureProperties(tool, args) {
         case 'modify_emails':
             return typeof input.action === 'string' ? { action: input.action } : {};
         case 'download_attachment':
-            return { destination: input.inline === true ? 'inline' : 'resource' };
+            return {
+                destination: input.inline === true ? 'inline' : typeof input.pages === 'string' ? 'pdf_pages' : 'resource',
+            };
         default:
             return {};
     }
@@ -316,8 +323,22 @@ const MODIFY_CAPABILITIES = {
     removeLabels: 'mail.organize',
 };
 const PROTECTED_MOVE_DESTINATIONS = new Set(['archive', 'trash']);
+function disabledCapabilitiesInstructions(permissions, source) {
+    const disabled = MCP_CAPABILITIES.filter((capability) => !hasCapability(permissions, capability));
+    if (!disabled.length)
+        return '';
+    const actions = disabled.map((capability) => `- ${capability} (${MCP_CAPABILITY_DESCRIPTIONS[capability].replace(/\.$/, '')}). ` +
+        enableCapabilitiesInstructions(permissions, [capability], source));
+    return ('\n\nThis connection has limited permissions. Tools for the disabled actions below are not available. ' +
+        'When the user asks for a disabled action, such as sending, replying to, or forwarding mail, tell them ' +
+        'it is disabled for this Fluxmail connection and how to enable it. Before changing permissions, explain ' +
+        "the access the change grants and get the user's explicit approval for that permission change. A request " +
+        'to perform an email action does not authorize changing permissions.\n' +
+        actions.join('\n'));
+}
 export function buildMcpServer(service, options = {}) {
-    const permissions = normalizePermissionPolicy(options.permissions ?? FULL_PERMISSION_POLICY);
+    const permissions = normalizePermissionPolicy(options.permissions ?? DEFAULT_PERMISSION_POLICY);
+    const permissionSource = options.permissionSource ?? (options.transport === 'stdio' ? { kind: 'stdio' } : undefined);
     const maxAttachmentBytes = options.maxAttachmentBytes ?? DEFAULT_MAX_ATTACHMENT_BYTES;
     const can = (capability) => hasCapability(permissions, capability);
     const canAll = (capabilities) => capabilities.every(can);
@@ -325,9 +346,20 @@ export function buildMcpServer(service, options = {}) {
     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(', ')}.`);
+            throw new MissingCapabilityError(`This MCP connection does not allow: ${missing.join(', ')}. ` +
+                enableCapabilitiesInstructions(permissions, missing, permissionSource), missing);
         }
     };
+    const downloadAttachment = async (accountId, messageId, attachmentId) => {
+        const attachment = await service.getAttachment(accountId, messageId, attachmentId, maxAttachmentBytes);
+        if (attachment.content.length > maxAttachmentBytes) {
+            throw new ClientInputError('invalid_request', 'Attachment is too large to return through MCP.', {
+                sizeBytes: attachment.content.length,
+                maxBytes: maxAttachmentBytes,
+            });
+        }
+        return attachment;
+    };
     // Every tool except get_status (the diagnostic way out) enforces the plan quota.
     const gated = (tool, capability, fn) => handle(tool, async (...args) => {
         requireCapabilities([capability]);
@@ -343,13 +375,41 @@ export function buildMcpServer(service, options = {}) {
     }, () => 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 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.',
+            'than echoing raw payloads, ids, or field names.' +
+            disabledCapabilitiesInstructions(permissions, permissionSource),
     });
+    // resource_link arrived in MCP 2025-06-18. Streamable HTTP sends the version on each request;
+    // stdio negotiates it once, so remember it. The SDK has no public accessor for the negotiated
+    // version, so observe the initialize request. The SDK installs onmessage before starting the
+    // transport, and this wrapper runs before the SDK handles each message.
+    let negotiatedProtocolVersion;
+    const connect = server.connect.bind(server);
+    server.connect = (transport) => {
+        const start = transport.start.bind(transport);
+        transport.start = () => {
+            const onmessage = transport.onmessage;
+            transport.onmessage = (message, extra) => {
+                if (isInitializeRequest(message)) {
+                    const requested = message.params.protocolVersion;
+                    negotiatedProtocolVersion = SUPPORTED_PROTOCOL_VERSIONS.includes(requested)
+                        ? requested
+                        : LATEST_PROTOCOL_VERSION;
+                }
+                onmessage?.(message, extra);
+            };
+            return start();
+        };
+        return connect(transport);
+    };
+    const supportsResourceLinks = (extra) => {
+        const header = extra.requestInfo?.headers['mcp-protocol-version'];
+        const version = (typeof header === 'string' ? header : undefined) ?? negotiatedProtocolVersion ?? '2025-03-26';
+        return version >= '2025-06-18';
+    };
     const listedTools = [];
     const registerTool = ((name, config, callback) => {
         const outputSchema = outputSchemas[name];
@@ -370,46 +430,52 @@ export function buildMcpServer(service, options = {}) {
     });
     if (can('mail.read'))
         registerTool('list_accounts', {
+            title: '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'))
         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.',
+            title: 'Get status',
+            description: 'Account connection and scheduled-send status, including accounts that need re-authentication. ' +
+                'Administrators also see plan details.',
             inputSchema: {},
             annotations: { readOnlyHint: true },
         }, allowed('get_status', 'mail.read', async () => service.status()));
     if (can('mail.read'))
         registerTool('list_folders', {
+            title: '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'))
         registerTool('list_labels', {
+            title: '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'))
         registerTool('list_send_as', {
+            title: 'List sender addresses',
             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'))
         registerTool('list_emails', {
+            title: '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.",
+                'sender, unread, dates, etc. Paginate with pageToken. Use get_email for full bodies.',
             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;
     if (can('mail.read'))
         registerTool('search_emails', {
+            title: '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: {
@@ -442,6 +508,7 @@ export function buildMcpServer(service, options = {}) {
     const { pageToken: _batchPageToken, rawProviderQuery: _batchRawProviderQuery, ...batchSearchFilterShape } = searchFilterShape;
     if (can('mail.read'))
         registerTool('search_emails_batch', {
+            title: 'Search multiple accounts',
             description: 'Search up to 20 accounts with one portable query and return one result group per account.',
             inputSchema: {
                 accounts: z
@@ -496,6 +563,7 @@ export function buildMcpServer(service, options = {}) {
         }));
     if (can('mail.read'))
         registerTool('get_email', {
+            title: 'Get email',
             description: 'Fetch one email in full: body (text and/or HTML), recipients, attachment metadata.',
             inputSchema: {
                 accountId: accountIdParam,
@@ -506,6 +574,7 @@ export function buildMcpServer(service, options = {}) {
         }, 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'))
         registerTool('get_email_body', {
+            title: 'Read email body',
             description: 'Read a bounded portion of one email body. Use nextOffset to continue.',
             inputSchema: {
                 accountId: accountIdParam,
@@ -530,6 +599,7 @@ export function buildMcpServer(service, options = {}) {
         }));
     if (can('mail.read'))
         registerTool('get_thread', {
+            title: 'Get thread',
             description: 'Fetch a page of conversation messages with bounded body content.',
             inputSchema: {
                 accountId: accountIdParam,
@@ -574,14 +644,17 @@ export function buildMcpServer(service, options = {}) {
         }));
     if (can('mail.drafts'))
         registerTool('get_draft', {
+            title: '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', {
+            title: 'Create draft',
             description: 'Create a draft. For a reply draft, pass replyToMessageId (recipients/subject are derived; replyAll for reply-all).',
             inputSchema: draftShape,
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
         }, gated('create_draft', 'mail.drafts', async (args) => {
             if (args.replyToMessageId)
                 requireCapabilities(['mail.read']);
@@ -589,8 +662,10 @@ export function buildMcpServer(service, options = {}) {
         }));
     if (can('mail.drafts'))
         registerTool('update_draft', {
+            title: 'Update draft',
             description: 'Replace the content of an existing draft (full replacement, not a patch).',
             inputSchema: { draftId: idParam, ...draftShape },
+            annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
         }, gated('update_draft', 'mail.drafts', async (args) => {
             if (args.replyToMessageId)
                 requireCapabilities(['mail.read']);
@@ -598,15 +673,17 @@ export function buildMcpServer(service, options = {}) {
         }));
     if (can('mail.drafts'))
         registerTool('delete_draft', {
+            title: 'Delete draft',
             description: 'Delete a draft.',
             inputSchema: { accountId: accountIdParam, draftId: idParam },
-            annotations: { destructiveHint: true },
+            annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
         }, gated('delete_draft', 'mail.drafts', async (args) => {
             await service.deleteDraft(args.accountId, args.draftId);
             return { deleted: args.draftId };
         }));
     if (can('mail.send'))
         registerTool('preview_send', {
+            title: 'Preview send',
             description: 'Show the resolved sender, recipients, subject, and attachments without sending.',
             inputSchema: { draftId: idParam.optional(), ...draftShape },
             annotations: { readOnlyHint: true },
@@ -619,9 +696,9 @@ export function buildMcpServer(service, options = {}) {
         }));
     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) ' +
+            title: 'Send email',
+            description: "Send an email from the user's connected account. 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: {
@@ -640,7 +717,7 @@ export function buildMcpServer(service, options = {}) {
                     '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.'),
             },
-            annotations: { destructiveHint: true },
+            annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
         }, handleResult('send_email', async (args) => {
             requireCapabilities(['mail.send']);
             if (args.replyToMessageId !== undefined)
@@ -652,6 +729,7 @@ export function buildMcpServer(service, options = {}) {
         }, () => service.enforceQuota(), options));
     if (can('mail.read'))
         registerTool('list_scheduled_emails', {
+            title: '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.',
@@ -660,18 +738,22 @@ export function buildMcpServer(service, options = {}) {
         }, gated('list_scheduled_emails', 'mail.read', async (args) => service.listScheduled(args.accountId)));
     if (can('mail.send'))
         registerTool('get_delivery_operation', {
+            title: 'Get delivery status',
             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'))
         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). ' +
                 'The draft stays in the Drafts folder, so the content is not lost.',
             inputSchema: { scheduleId: idParam },
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
         }, gated('cancel_scheduled_email', 'mail.drafts', async (args) => service.cancelScheduled(args.scheduleId)));
     if (canAll(['mail.send', 'mail.read']))
         registerTool('forward_email', {
+            title: '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: {
@@ -690,7 +772,7 @@ export function buildMcpServer(service, options = {}) {
                     .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 },
+            annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
         }, handleResult('forward_email', async (args) => {
             requireCapabilities(['mail.send', 'mail.read']);
             const to = parseAddresses(args.to) ?? [];
@@ -708,6 +790,7 @@ export function buildMcpServer(service, options = {}) {
     if (modifyActions.length) {
         const allowedModifyActions = new Set(modifyActions);
         registerTool('modify_emails', {
+            title: 'Modify emails',
             description: 'Batch-modify emails using the actions allowed for this connection. Moving requires folder; labels require labels.',
             inputSchema: {
                 accountId: accountIdParam,
@@ -720,7 +803,9 @@ export function buildMcpServer(service, options = {}) {
                 labels: z.array(z.string().min(1)).max(100).optional().describe('Labels for addLabels/removeLabels'),
             },
             annotations: {
+                readOnlyHint: false,
                 destructiveHint: canAny(['mail.trash', 'mail.delete']),
+                idempotentHint: true,
             },
         }, handleResult('modify_emails', async (args) => {
             if (!allowedModifyActions.has(args.action)) {
@@ -756,46 +841,45 @@ export function buildMcpServer(service, options = {}) {
     }
     if (can('mail.read'))
         registerTool('download_attachment', {
-            description: 'Get attachment metadata and a fetchable resource link. Set inline to embed the bytes.',
+            title: 'Download attachment',
+            description: `Get metadata and a resource link for one attachment, up to ${sizeLabel(maxAttachmentBytes)}. ` +
+                'With inline, the result also includes the content. For a PDF, inline adds extracted text, and pages ' +
+                'returns the text of a page range such as 201-400.',
             inputSchema: {
-                accountId: idParam,
+                accountId: accountIdParam,
                 messageId: idParam,
                 attachmentId: attachmentIdParam,
                 inline: z.boolean().optional(),
+                pages: pageRange.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 ClientInputError('invalid_request', 'Attachment is too large to return through MCP.', {
-                    sizeBytes: content.length,
-                    maxBytes: maxAttachmentBytes,
-                });
+        }, gatedResult('download_attachment', 'mail.read', async (args, extra) => {
+            const { meta, content, accountId } = await downloadAttachment(args.accountId, args.messageId, args.attachmentId);
+            const mimeType = meta.mimeType || 'application/octet-stream';
+            const pdf = mediaType(mimeType) === 'application/pdf';
+            if (args.pages && !pdf) {
+                throw new ClientInputError('invalid_request', 'Pages apply only to PDF attachments.');
             }
+            const extracted = pdf && (args.inline || args.pages)
+                ? await pdfText(content, extra.signal, args.pages, (error) => options.logger?.warn('mcp.pdf_text_failed', 'PDF text extraction failed.', error, {
+                    productSurface: 'mcp',
+                    operation: 'download_attachment',
+                }))
+                : undefined;
             const uri = [
                 'fluxmail://attachment',
-                encodeURIComponent(args.accountId),
-                encodeURIComponent(args.messageId),
-                encodeURIComponent(args.attachmentId),
-                encodeURIComponent(meta.filename),
+                ...[accountId, args.messageId, args.attachmentId, meta.filename].map(encodeURIComponent),
             ].join('/');
+            const resourceLinks = supportsResourceLinks(extra);
             return {
                 structuredContent: { data: meta },
                 content: [
-                    { 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'),
-                                },
-                            },
-                        ]
+                    { type: 'text', text: JSON.stringify(resourceLinks ? { data: meta } : { data: meta, uri }, null, 2) },
+                    ...(resourceLinks
+                        ? [{ type: 'resource_link', name: meta.filename, uri, mimeType: meta.mimeType }]
                         : []),
+                    ...(args.inline ? [inlineContent(uri, mimeType, content)] : []),
+                    ...pdfTextContent(meta.filename, extracted),
                 ],
             };
         }));
@@ -805,11 +889,8 @@ export function buildMcpServer(service, options = {}) {
         }), { 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') }] };
+            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)] };
         });
     if (listedTools.length) {
         // The SDK's list handler declares draft-07 for output schemas, which strict clients reject.