fluxmail 0.15.0 → 0.17.0

package/dist/mcp/buildServer.js

@@ -2,16 +2,16 @@ import { VERSION } from '../version.js';
 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 { isInitializeRequest, LATEST_PROTOCOL_VERSION, ListToolsRequestSchema, SUPPORTED_PROTOCOL_VERSIONS, } from '@modelcontextprotocol/sdk/types.js';
-import { EmailError, isEmailError, mergeEmailQueries, parseEmailSearch, parseSingleAddress, } from '@fluxmail/core';
+import { CLIENT_INFO_META_KEY, PROTOCOL_VERSION_META_KEY, McpServer, ResourceTemplate, } from '@modelcontextprotocol/server';
+import { isEmailError, mergeEmailQueries, parseEmailSearch, parseSingleAddress, } from '@fluxmail/core';
 import { batchFailureCause } 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 { ClientInputError, MissingCapabilityError, publicError } from '../service/publicErrors.js';
+import { attachmentTooLarge, ClientInputError, isAttachmentSizeError, MissingCapabilityError, publicError, } from '../service/publicErrors.js';
 import { outputSchemas } from './outputSchemas.js';
+import { mcpClientProperties, trackMcpInitialization } from './clientTelemetry.js';
 import { attachmentContents, inlineContent, mediaType, pageRange, pdfText, pdfTextContent, } from './attachmentContent.js';
 const MAX_BODY_CHARS = 50_000;
 const BYTES_PER_MEGABYTE = 1024 * 1024;
@@ -33,6 +33,25 @@ function toolJsonSchema(shape, pipeStrategy) {
         delete schema.$schema;
     return schema;
 }
+// Retain the existing validators, transforms and JSON Schemas at the SDK boundary.
+// The rest of the server also uses Zod 3; the SDK consumes only Standard Schema here.
+function mcpSchema(shape) {
+    const schema = z.object(shape);
+    return {
+        '~standard': {
+            version: 1,
+            vendor: 'fluxmail',
+            validate: async (value) => {
+                const result = await schema.safeParseAsync(value);
+                return result.success ? { value: result.data } : { issues: result.error.issues };
+            },
+            jsonSchema: {
+                input: () => toolJsonSchema(shape, 'input'),
+                output: () => toolJsonSchema(shape, 'output'),
+            },
+        },
+    };
+}
 function nullableOptionalInputs(shape) {
     return Object.fromEntries(Object.entries(shape).map(([name, schema]) => {
         if (!(schema instanceof z.ZodOptional))
@@ -210,6 +229,9 @@ function toolError(err, requestId) {
     return { isError: true, content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
 }
 function toolFeatureProperties(tool, args) {
+    const modifyAction = MODIFY_ACTION_BY_TOOL.get(tool);
+    if (modifyAction)
+        return { action: modifyAction };
     if (!args || typeof args !== 'object')
         return {};
     const input = args;
@@ -224,8 +246,6 @@ function toolFeatureProperties(tool, args) {
             };
         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: input.inline === true ? 'inline' : typeof input.pages === 'string' ? 'pdf_pages' : 'resource',
@@ -234,6 +254,12 @@ function toolFeatureProperties(tool, args) {
             return {};
     }
 }
+function toolTelemetryProperties(tool, args, options) {
+    return {
+        ...toolFeatureProperties(tool, args[0]),
+        ...options.clientProperties?.(args[1]),
+    };
+}
 function handleResult(tool, fn, gate, options = {}) {
     return async (...args) => {
         const finishActivity = options.telemetry?.beginActivity?.();
@@ -255,7 +281,7 @@ function handleResult(tool, fn, gate, options = {}) {
                     : {}),
                 durationMs: performance.now() - startedAt,
                 transport: options.transport ?? 'unknown',
-                properties: toolFeatureProperties(tool, args[0]),
+                properties: toolTelemetryProperties(tool, args, options),
             });
             return result;
         }
@@ -275,7 +301,7 @@ function handleResult(tool, fn, gate, options = {}) {
                 error: err,
                 durationMs: performance.now() - startedAt,
                 transport: options.transport ?? 'unknown',
-                properties: toolFeatureProperties(tool, args[0]),
+                properties: toolTelemetryProperties(tool, args, options),
             });
             return toolError(err, requestId);
         }
@@ -310,24 +336,103 @@ function emailQuery(args) {
         'rawProviderQuery',
     ];
     const q = {};
-    for (const key of keys)
-        if (args[key] !== undefined)
-            q[key] = args[key];
+    for (const key of keys) {
+        const value = args[key];
+        // Agents often fill filters they mean to leave out with blank strings.
+        if (value === undefined || (typeof value === 'string' && value.trim() === ''))
+            continue;
+        q[key] = value;
+    }
     return q;
 }
-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',
+/** One MCP tool per modify action, all served by the same implementation. */
+export const MODIFY_TOOLS = {
+    markRead: {
+        name: 'mark_emails_read',
+        title: 'Mark emails read',
+        description: 'Mark messages as read.',
+        capability: 'mail.organize',
+        destructive: false,
+    },
+    markUnread: {
+        name: 'mark_emails_unread',
+        title: 'Mark emails unread',
+        description: 'Mark messages as unread.',
+        capability: 'mail.organize',
+        destructive: false,
+    },
+    star: {
+        name: 'star_emails',
+        title: 'Star emails',
+        description: 'Star messages.',
+        capability: 'mail.organize',
+        destructive: false,
+    },
+    unstar: {
+        name: 'unstar_emails',
+        title: 'Unstar emails',
+        description: 'Remove the star from messages.',
+        capability: 'mail.organize',
+        destructive: false,
+    },
+    archive: {
+        name: 'archive_emails',
+        title: 'Archive emails',
+        description: 'Move messages out of the inbox into the archive.',
+        capability: 'mail.organize',
+        destructive: false,
+    },
+    // Spam and Junk folders delete their mail after a while, so a move can lose it.
+    move: {
+        name: 'move_emails',
+        title: 'Move emails',
+        description: 'Move messages to a folder other than the archive or trash.',
+        capability: 'mail.organize',
+        destructive: true,
+        input: 'folder',
+    },
+    addLabels: {
+        name: 'add_labels',
+        title: 'Add labels',
+        description: 'Add labels, or Outlook categories, to messages.',
+        capability: 'mail.organize',
+        destructive: false,
+        input: 'labels',
+    },
+    removeLabels: {
+        name: 'remove_labels',
+        title: 'Remove labels',
+        description: 'Remove labels, or Outlook categories, from messages.',
+        capability: 'mail.organize',
+        destructive: false,
+        input: 'labels',
+    },
+    // Providers empty the trash automatically, so trashed mail is eventually gone.
+    trash: {
+        name: 'trash_emails',
+        title: 'Move emails to trash',
+        description: 'Move messages to the trash, where they can be restored until the provider empties it.',
+        capability: 'mail.trash',
+        destructive: true,
+    },
+    untrash: {
+        name: 'restore_emails',
+        title: 'Restore emails from trash',
+        description: 'Move messages out of the trash.',
+        capability: 'mail.trash',
+        destructive: false,
+    },
+    delete: {
+        name: 'delete_emails',
+        title: 'Delete emails permanently',
+        description: "Permanently delete messages. This cannot be undone. Gmail accounts connected through Fluxmail's built-in " +
+            'Google app cannot delete permanently; move their messages to the trash instead.',
+        capability: 'mail.delete',
+        destructive: true,
+    },
 };
+const MODIFY_TOOL_ENTRIES = Object.entries(MODIFY_TOOLS);
+const MODIFY_ACTION_BY_TOOL = new Map(MODIFY_TOOL_ENTRIES.map(([action, tool]) => [tool.name, action]));
 const PROTECTED_MOVE_DESTINATIONS = new Set(['archive', 'trash']);
 function disabledCapabilitiesInstructions(permissions, source) {
     const disabled = MCP_CAPABILITIES.filter((capability) => !hasCapability(permissions, capability));
@@ -348,7 +453,6 @@ export function buildMcpServer(service, options = {}) {
     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) {
@@ -357,28 +461,42 @@ export function buildMcpServer(service, options = {}) {
         }
     };
     const downloadAttachment = async (accountId, messageId, attachmentId) => {
-        const attachment = await service.getAttachment(accountId, messageId, attachmentId, maxAttachmentBytes);
+        const attachment = await service
+            .getAttachment(accountId, messageId, attachmentId, maxAttachmentBytes)
+            .catch((error) => {
+            if (!isAttachmentSizeError(error))
+                throw error;
+            const sizeBytes = error.data?.sizeBytes;
+            throw attachmentTooLarge('MCP', maxAttachmentBytes, typeof sizeBytes === 'number' ? sizeBytes : undefined);
+        });
         if (attachment.content.length > maxAttachmentBytes) {
-            throw new ClientInputError('invalid_request', 'Attachment is too large to return through MCP.', {
-                sizeBytes: attachment.content.length,
-                maxBytes: maxAttachmentBytes,
-            });
+            throw attachmentTooLarge('MCP', maxAttachmentBytes, attachment.content.length);
         }
         return attachment;
     };
+    // Modern requests carry the client in their envelope; legacy stdio keeps it from initialization.
+    const toolOptions = {
+        ...options,
+        clientProperties: (ctx) => {
+            const context = ctx;
+            // The SDK types the lifted envelope as empty, but it holds the reserved _meta keys.
+            const envelope = context?.mcpReq.envelope;
+            return mcpClientProperties(envelope?.[CLIENT_INFO_META_KEY] ?? server.server.getClientVersion(), envelope?.[PROTOCOL_VERSION_META_KEY] ?? (context ? protocolVersionOf(context) : undefined));
+        },
+    };
     // Every tool except get_status (the diagnostic way out) enforces the plan quota.
     const gated = (tool, capability, fn) => handle(tool, async (...args) => {
         requireCapabilities([capability]);
         return fn(...args);
-    }, () => service.enforceQuota(), options);
+    }, () => service.enforceQuota(), toolOptions);
     const allowed = (tool, capability, fn) => handle(tool, async (...args) => {
         requireCapabilities([capability]);
         return fn(...args);
-    }, undefined, options);
+    }, undefined, toolOptions);
     const gatedResult = (tool, capability, fn) => handleResult(tool, async (...args) => {
         requireCapabilities([capability]);
         return fn(...args);
-    }, () => service.enforceQuota(), options);
+    }, () => service.enforceQuota(), toolOptions);
     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. " +
             'Tool results are structured for you, not for display. Message ids, thread ids, draft ids, and ' +
@@ -388,40 +506,26 @@ export function buildMcpServer(service, options = {}) {
             '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;
+    // Observe successful handshakes/discovery without interpreting protocol negotiation ourselves.
     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);
-            };
+            if (options.telemetry && (options.transport === 'stdio' || options.transport === 'http')) {
+                trackMcpInitialization(transport, options.telemetry, options.transport);
+            }
             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 protocolVersionOf = (ctx) => ctx.http?.req?.headers.get('mcp-protocol-version') ?? server.server.getNegotiatedProtocolVersion();
+    const supportsResourceLinks = (ctx) => (protocolVersionOf(ctx) ?? '2025-03-26') >= '2025-06-18';
     const listedTools = [];
-    const registerTool = ((name, config, callback) => {
+    const registerTool = (name, config, callback) => {
         const outputSchema = outputSchemas[name];
         const inputShape = config.inputSchema;
         const inputSchema = inputShape ? nullableOptionalInputs(inputShape) : undefined;
-        const registered = server.registerTool(name, { ...config, ...(inputSchema ? { inputSchema } : {}), outputSchema }, callback);
+        const registered = server.registerTool(name, { ...config, inputSchema: mcpSchema(inputSchema ?? {}), outputSchema: mcpSchema(outputSchema) }, callback);
         listedTools.push({
             name,
             title: config.title,
@@ -430,10 +534,9 @@ export function buildMcpServer(service, options = {}) {
             outputSchema: toolJsonSchema(outputSchema, 'output'),
             annotations: config.annotations,
             execution: { taskSupport: 'forbidden' },
-            _meta: config._meta,
         });
         return registered;
-    });
+    };
     if (can('mail.read'))
         registerTool('list_accounts', {
             title: 'List accounts',
@@ -733,7 +836,7 @@ export function buildMcpServer(service, options = {}) {
             return deliveryResult(await (sendAt !== undefined
                 ? service.scheduleDelivery(args.accountId, toSendRequest(sendArgs), sendAt, idempotencyKey)
                 : service.deliver(args.accountId, toSendRequest(sendArgs), idempotencyKey)));
-        }, () => service.enforceQuota(), options));
+        }, () => service.enforceQuota(), toolOptions));
     if (can('mail.read'))
         registerTool('list_scheduled_emails', {
             title: 'List scheduled emails',
@@ -792,59 +895,61 @@ export function buildMcpServer(service, options = {}) {
                 ...(args.includeAttachments !== undefined ? { includeAttachments: args.includeAttachments } : {}),
                 ...(args.from !== undefined ? { from: args.from } : {}),
             }, args.idempotencyKey));
-        }, () => service.enforceQuota(), options));
-    const modifyActions = Object.keys(MODIFY_CAPABILITIES).filter((action) => can(MODIFY_CAPABILITIES[action]));
-    if (modifyActions.length) {
-        const allowedModifyActions = new Set(modifyActions);
-        registerTool('modify_emails', {
-            title: 'Modify emails',
-            description: 'Batch-modify emails using the actions allowed for this connection. Moving requires folder; labels require labels.',
+        }, () => service.enforceQuota(), toolOptions));
+    const modifyEmails = async (action, args) => {
+        requireCapabilities([MODIFY_TOOLS[action].capability]);
+        let modifyAction;
+        if (action === 'move') {
+            if (!args.folder)
+                throw new ClientInputError('invalid_request', 'Moving messages requires "folder"');
+            if (PROTECTED_MOVE_DESTINATIONS.has(args.folder.trim().toLowerCase())) {
+                throw new ClientInputError('invalid_request', 'Archive or trash these messages instead of moving them to this folder.');
+            }
+            modifyAction = { move: args.folder };
+        }
+        else if (action === 'addLabels' || action === 'removeLabels') {
+            if (!args.labels?.length)
+                throw new ClientInputError('invalid_request', `${action} requires "labels"`);
+            modifyAction = action === 'addLabels' ? { addLabels: args.labels } : { removeLabels: args.labels };
+        }
+        else {
+            modifyAction = action;
+        }
+        const result = await service.modify(args.accountId, args.messageIds, modifyAction);
+        const response = ok({ ...result, action });
+        if (result.failed.length || result.uncertainIds.length) {
+            response.isError = true;
+            response[TELEMETRY_ERROR] = true;
+        }
+        return response;
+    };
+    const messageIdsParam = z
+        .array(idParam)
+        .min(1)
+        .refine((ids) => new Set(ids).size <= 100, 'At most 100 distinct message IDs are allowed.')
+        .describe('Messages to change, up to 100 distinct IDs');
+    const modifyInputs = {
+        folder: { folder: z.string().min(1).describe('Destination folder name or role') },
+        labels: { labels: z.array(z.string().min(1)).min(1).max(100).describe('Gmail labels or Outlook categories') },
+    };
+    for (const [action, tool] of MODIFY_TOOL_ENTRIES) {
+        if (!can(tool.capability))
+            continue;
+        registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
             inputSchema: {
                 accountId: accountIdParam,
-                messageIds: z
-                    .array(idParam)
-                    .min(1)
-                    .refine((ids) => new Set(ids).size <= 100, 'At most 100 distinct message IDs are allowed.'),
-                action: z.enum(modifyActions),
-                folder: z.string().min(1).optional().describe('Target folder for action=move'),
-                labels: z.array(z.string().min(1)).max(100).optional().describe('Labels for addLabels/removeLabels'),
+                messageIds: messageIdsParam,
+                ...(tool.input ? modifyInputs[tool.input] : {}),
             },
             annotations: {
                 readOnlyHint: false,
-                destructiveHint: canAny(['mail.trash', 'mail.delete']),
+                destructiveHint: tool.destructive,
                 idempotentHint: true,
+                openWorldHint: false,
             },
-        }, handleResult('modify_emails', async (args) => {
-            if (!allowedModifyActions.has(args.action)) {
-                throw new EmailError('permission_denied', `This MCP connection does not allow action=${args.action}.`);
-            }
-            requireCapabilities([MODIFY_CAPABILITIES[args.action]]);
-            let action;
-            if (args.action === 'move') {
-                if (!args.folder)
-                    throw new ClientInputError('invalid_request', 'action=move requires "folder"');
-                if (PROTECTED_MOVE_DESTINATIONS.has(args.folder.trim().toLowerCase())) {
-                    throw new ClientInputError('invalid_request', 'Use the dedicated archive or trash action for this folder');
-                }
-                action = { move: args.folder };
-            }
-            else if (args.action === 'addLabels' || args.action === 'removeLabels') {
-                if (!args.labels?.length) {
-                    throw new ClientInputError('invalid_request', `action=${args.action} requires "labels"`);
-                }
-                action = args.action === 'addLabels' ? { addLabels: args.labels } : { removeLabels: args.labels };
-            }
-            else {
-                action = args.action;
-            }
-            const result = await service.modify(args.accountId, args.messageIds, action);
-            const response = ok({ ...result, action: args.action });
-            if (result.failed.length || result.uncertainIds.length) {
-                response.isError = true;
-                response[TELEMETRY_ERROR] = true;
-            }
-            return response;
-        }, () => service.enforceQuota(), options));
+        }, handleResult(tool.name, async (args) => modifyEmails(action, args), () => service.enforceQuota(), toolOptions));
     }
     if (can('mail.read'))
         registerTool('download_attachment', {
@@ -868,7 +973,7 @@ export function buildMcpServer(service, options = {}) {
                 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, {
+                ? await pdfText(content, extra.mcpReq.signal, args.pages, (error) => options.logger?.warn('mcp.pdf_text_failed', 'PDF text extraction failed.', error, {
                     productSurface: 'mcp',
                     operation: 'download_attachment',
                 }))
@@ -899,9 +1004,12 @@ export function buildMcpServer(service, options = {}) {
             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 (can('mail.read'))
+        server.server.registerCapabilities({ resources: { listChanged: false } });
     if (listedTools.length) {
-        // The SDK's list handler declares draft-07 for output schemas, which strict clients reject.
-        server.server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: listedTools }));
+        server.server.registerCapabilities({ tools: { listChanged: false } });
+        // Preserve the advertised schemas, including empty inputs and output schema dialects.
+        server.server.setRequestHandler('tools/list', () => ({ tools: listedTools }));
     }
     return server;
 }