@forwardemail/mcp-server 1.0.5 → 1.0.7

package/lib/index.js

@@ -18,9 +18,12 @@ class McpServer {
       tools: Object.values(this.tools).map((tool) => ({
         name: tool.toolSpec.name,
         description: tool.toolSpec.description,
+        annotations: tool.toolSpec.annotations,
+        _meta: tool.toolSpec._meta,
         inputSchema: {
           type: 'object',
           properties: tool.toolSpec.input?.properties ?? {},
+          required: tool.toolSpec.input?.required ?? [],
         },
       })),
     }));

package/lib/tools.js

@@ -37,108 +37,347 @@ const getTools = (options = {}) => {
   //                 otherwise falls back to API key
   //   'none'      – no authentication required
   //
-  const createTool = (spec) => ({
-    toolSpec: {
-      name: spec.name,
-      description: spec.description,
-      input: {
-        type: 'object',
-        properties: {
-          ...spec.inputs,
-          // Inject alias credential inputs for alias-auth and both-auth tools
-
-          ...((spec.auth === 'aliasAuth' || spec.auth === 'both') && {
-            alias_username: {
-              type: 'string',
-              description:
-                'Alias email address for authentication (e.g. user@example.com). ' +
-                'Required for alias-authenticated endpoints. ' +
-                'Falls back to FORWARD_EMAIL_ALIAS_USER env var.',
-            },
-            alias_password: {
-              type: 'string',
-              description:
-                'Generated alias password for authentication. ' +
-                'Required for alias-authenticated endpoints. ' +
-                'Falls back to FORWARD_EMAIL_ALIAS_PASSWORD env var. ' +
-                'Generate one with the generateAliasPassword tool.',
+  // Descriptions for well-known path parameters
+  const pathParameterDescriptions = {
+    domain_id: 'Domain ID or fully qualified domain name (e.g. "example.com")',
+    alias_id: 'Alias ID',
+    id: 'Resource ID',
+    token_id: 'Token ID for the catch-all password',
+    member_id: 'Member ID',
+    script_id: 'Sieve script ID',
+  };
+
+  // Descriptions for well-known query parameters
+  const queryParameterDescriptions = {
+    sort: 'Sort field and direction (e.g. "created_at" or "-created_at" for descending)',
+    page: 'Page number for pagination (1-based)',
+    limit: 'Number of results per page',
+    q: 'Search query string',
+    domain: 'Domain name to filter by',
+    bounce_category: 'Filter by bounce category',
+    response_code: 'Filter by SMTP response code',
+    always_send_email:
+      'Whether to always send the log download via email (boolean)',
+    is_scheduled: 'Filter by scheduled status (boolean)',
+    folder: 'IMAP folder name (e.g. "INBOX", "Sent", "Drafts")',
+    is_unread: 'Filter by unread status (boolean)',
+    is_flagged: 'Filter by flagged status (boolean)',
+    is_deleted: 'Filter by deleted status (boolean)',
+    is_draft: 'Filter by draft status (boolean)',
+    is_junk: 'Filter by junk/spam status (boolean)',
+    is_copied: 'Filter by copied status (boolean)',
+    is_encrypted: 'Filter by encrypted status (boolean)',
+    is_searchable: 'Filter by searchable status (boolean)',
+    is_expired: 'Filter by expired status (boolean)',
+    has_attachments: 'Filter messages with attachments (boolean)',
+    has_attachment: 'Filter messages with attachments (boolean)',
+    subject: 'Filter by message subject',
+    body: 'Search within message body',
+    text: 'Full text search query',
+    headers: 'Search within message headers',
+    message_id: 'Filter by Message-ID header',
+    search: 'IMAP SEARCH query string',
+    since: 'Filter messages after this date (ISO 8601)',
+    before: 'Filter messages before this date (ISO 8601)',
+    min_size: 'Minimum message size in bytes',
+    max_size: 'Maximum message size in bytes',
+    from: 'Filter by sender address',
+    to: 'Filter by recipient address',
+    cc: 'Filter by CC address',
+    bcc: 'Filter by BCC address',
+    date: 'Filter by message date',
+    'reply-to': 'Filter by Reply-To address',
+    eml: 'Return raw EML format (boolean)',
+    nodemailer: 'Return in Nodemailer-compatible format (boolean)',
+    attachments: 'Include attachments in response (boolean)',
+    raw: 'Return raw message source (boolean)',
+    subscribed: 'Filter by subscription status (boolean)',
+  };
+
+  const LIST_MESSAGES_MAX_RESULT_SIZE_CHARS = 500_000;
+  const LIST_MESSAGES_METADATA_FIELDS = [
+    'id',
+    'uid',
+    'subject',
+    'from',
+    'to',
+    'date',
+    'size',
+    'has_attachment',
+    'has_attachments',
+    'flags',
+    'folder',
+  ];
+  const LIST_MESSAGES_COLLECTION_KEYS = [
+    'results',
+    'messages',
+    'items',
+    'data',
+  ];
+
+  const isTruthyBoolean = (value) => {
+    if (typeof value === 'boolean') return value;
+    if (typeof value === 'number') return value === 1;
+    if (typeof value !== 'string') return false;
+
+    return ['1', 'true', 'yes', 'on'].includes(value.toLowerCase());
+  };
+
+  const getListMessagesCollection = (result) => {
+    if (Array.isArray(result)) {
+      return {key: null, items: result};
+    }
+
+    if (!result || typeof result !== 'object') return null;
+
+    for (const key of LIST_MESSAGES_COLLECTION_KEYS) {
+      if (Array.isArray(result[key])) {
+        return {key, items: result[key]};
+      }
+    }
+
+    return null;
+  };
+
+  const toListMessageMetadata = (message) => {
+    if (!message || typeof message !== 'object' || Array.isArray(message)) {
+      return message;
+    }
+
+    const metadata = {};
+    for (const field of LIST_MESSAGES_METADATA_FIELDS) {
+      if (message[field] !== undefined) metadata[field] = message[field];
+    }
+
+    return Object.keys(metadata).length > 0 ? metadata : message;
+  };
+
+  const replaceListMessagesCollection = (
+    originalResult,
+    collection,
+    items,
+    extraProperties = {},
+  ) => {
+    if (!collection) return originalResult;
+    if (collection.key === null) return items;
+
+    return {
+      ...originalResult,
+      ...extraProperties,
+      [collection.key]: items,
+    };
+  };
+
+  const toMetadataOnlyListMessagesResult = (result) => {
+    const collection = getListMessagesCollection(result);
+    if (!collection) return result;
+
+    return replaceListMessagesCollection(
+      result,
+      collection,
+      collection.items.map((item) => toListMessageMetadata(item)),
+    );
+  };
+
+  const fitListMessagesResultToMaxSize = (
+    result,
+    maxChars = LIST_MESSAGES_MAX_RESULT_SIZE_CHARS,
+  ) => {
+    const metadataResult = toMetadataOnlyListMessagesResult(result);
+    if (JSON.stringify(metadataResult).length <= maxChars) {
+      return metadataResult;
+    }
+
+    const collection = getListMessagesCollection(metadataResult);
+    if (!collection) return metadataResult;
+
+    const extraProperties =
+      collection.key === null
+        ? {}
+        : {
+            notice:
+              'Result truncated to stay within the MCP result-size limit. ' +
+              'Use narrower filters or call getMessage for full message content.',
+            truncated: true,
+            total_count: collection.items.length,
+          };
+
+    const keptItems = [];
+    for (const item of collection.items) {
+      const candidateItems = [...keptItems, item];
+      const candidateResult = replaceListMessagesCollection(
+        metadataResult,
+        collection,
+        candidateItems,
+        collection.key === null
+          ? {}
+          : {
+              ...extraProperties,
+              returned_count: candidateItems.length,
             },
-          }),
+      );
+
+      if (JSON.stringify(candidateResult).length > maxChars) break;
+      keptItems.push(item);
+    }
+
+    return replaceListMessagesCollection(
+      metadataResult,
+      collection,
+      keptItems,
+      collection.key === null
+        ? {}
+        : {
+            ...extraProperties,
+            returned_count: keptItems.length,
+          },
+    );
+  };
+
+  const createTool = (spec) => {
+    // Auto-extract path parameter names from the URL template
+    const pathParameters = (spec.path.match(/{(\w+)}/g) || []).map((match) =>
+      match.slice(1, -1),
+    );
+
+    // Auto-generate property definitions for path parameters
+    const pathProperties = {};
+    for (const parameter of pathParameters) {
+      pathProperties[parameter] = {
+        type: 'string',
+        description:
+          pathParameterDescriptions[parameter] ||
+          `${parameter.replaceAll('_', ' ')}`,
+      };
+    }
+
+    // Auto-generate property definitions for query parameters
+    const queryProperties = {};
+    if (spec.query) {
+      for (const parameter of spec.query) {
+        queryProperties[parameter] = {
+          type: 'string',
+          description:
+            queryParameterDescriptions[parameter] ||
+            `${parameter.replaceAll('_', ' ')}`,
+        };
+      }
+    }
+
+    return {
+      toolSpec: {
+        name: spec.name,
+        description: spec.description,
+        annotations: spec.annotations,
+        _meta: spec._meta,
+        input: {
+          type: 'object',
+          properties: {
+            // Path parameters first
+            ...pathProperties,
+            // Query parameters next
+            ...queryProperties,
+            // Explicit inputs override auto-generated ones
+            ...spec.inputs,
+            // Inject alias credential inputs for alias-auth and both-auth tools
+
+            ...((spec.auth === 'aliasAuth' || spec.auth === 'both') && {
+              alias_username: {
+                type: 'string',
+                description:
+                  'Alias email address for authentication (e.g. user@example.com). ' +
+                  'Required for alias-authenticated endpoints. ' +
+                  'Falls back to FORWARD_EMAIL_ALIAS_USER env var.',
+              },
+              alias_password: {
+                type: 'string',
+                description:
+                  'Generated alias password for authentication. ' +
+                  'Required for alias-authenticated endpoints. ' +
+                  'Falls back to FORWARD_EMAIL_ALIAS_PASSWORD env var. ' +
+                  'Generate one with the generateAliasPassword tool.',
+              },
+            }),
+          },
+          // Path parameters are always required; merge with explicit requiredInputs
+          required: [...pathParameters, ...(spec.requiredInputs || [])],
         },
       },
-    },
-    auth: spec.auth || 'apiKey',
-    async invoke(arguments_) {
-      let {path} = spec;
-      const pathParameters = path.match(/{(\w+)}/g) || [];
-      const queryArguments = {};
-      const bodyArguments = {};
-
-      // Extract alias credentials from arguments (don't send them to the API)
-      const aliasUser = arguments_.alias_username || defaultAliasUser;
-      const aliasPass = arguments_.alias_password || defaultAliasPassword;
-
-      for (const key in arguments_) {
-        if (!Object.hasOwn(arguments_, key)) continue;
-        // Skip credential fields
-        if (key === 'alias_username' || key === 'alias_password') continue;
-
-        if (pathParameters.includes(`{${key}}`)) {
-          path = path.replace(`{${key}}`, arguments_[key]);
-        } else if (spec.query && spec.query.includes(key)) {
-          queryArguments[key] = arguments_[key];
-        } else {
-          bodyArguments[key] = arguments_[key];
-        }
-      }
+      auth: spec.auth || 'apiKey',
+      async invoke(arguments_) {
+        let {path} = spec;
+        const pathParameters = path.match(/{(\w+)}/g) || [];
+        const queryArguments = {};
+        const bodyArguments = {};
 
-      const config = {params: queryArguments};
-      const hasBody = Object.keys(bodyArguments).length > 0;
+        // Extract alias credentials from arguments (don't send them to the API)
+        const aliasUser = arguments_.alias_username || defaultAliasUser;
+        const aliasPass = arguments_.alias_password || defaultAliasPassword;
 
-      // Choose the right client based on auth type
-      let client;
-      switch (spec.auth) {
-        case 'aliasAuth': {
-          client = createAliasClient(aliasUser, aliasPass);
+        for (const key in arguments_) {
+          if (!Object.hasOwn(arguments_, key)) continue;
+          // Skip credential fields
+          if (key === 'alias_username' || key === 'alias_password') continue;
 
-          break;
+          if (pathParameters.includes(`{${key}}`)) {
+            path = path.replace(`{${key}}`, arguments_[key]);
+          } else if (spec.query && spec.query.includes(key)) {
+            queryArguments[key] = arguments_[key];
+          } else {
+            bodyArguments[key] = arguments_[key];
+          }
         }
 
-        case 'both': {
-          // Use alias credentials if provided, otherwise fall back to API key
-          client =
-            aliasUser && aliasPass
-              ? createAliasClient(aliasUser, aliasPass)
-              : apiKeyClient;
+        const config = {params: queryArguments};
+        const hasBody = Object.keys(bodyArguments).length > 0;
 
-          break;
-        }
+        // Choose the right client based on auth type
+        let client;
+        switch (spec.auth) {
+          case 'aliasAuth': {
+            client = createAliasClient(aliasUser, aliasPass);
 
-        case 'none': {
-          client = axios.create({baseURL});
+            break;
+          }
 
-          break;
-        }
+          case 'both': {
+            // Use alias credentials if provided, otherwise fall back to API key
+            client =
+              aliasUser && aliasPass
+                ? createAliasClient(aliasUser, aliasPass)
+                : apiKeyClient;
+
+            break;
+          }
+
+          case 'none': {
+            client = axios.create({baseURL});
 
-        default: {
-          client = apiKeyClient;
+            break;
+          }
+
+          default: {
+            client = apiKeyClient;
+          }
         }
-      }
 
-      let response;
-      if (spec.method === 'get' || spec.method === 'delete') {
-        response = await client[spec.method](path, config);
-      } else {
-        response = await client[spec.method](
-          path,
-          hasBody ? bodyArguments : undefined,
-          config,
-        );
-      }
+        let response;
+        if (spec.method === 'get' || spec.method === 'delete') {
+          response = await client[spec.method](path, config);
+        } else {
+          response = await client[spec.method](
+            path,
+            hasBody ? bodyArguments : undefined,
+            config,
+          );
+        }
 
-      return response.data;
-    },
-  });
+        return typeof spec.transformResponse === 'function'
+          ? spec.transformResponse(response.data, arguments_)
+          : response.data;
+      },
+    };
+  };
 
   const tools = {
     //
@@ -161,6 +400,24 @@ const getTools = (options = {}) => {
       method: 'put',
       path: '/v1/account',
       auth: 'both',
+      inputs: {
+        email: {
+          type: 'string',
+          description: 'Email address to update on the account',
+        },
+        given_name: {
+          type: 'string',
+          description: 'First name',
+        },
+        family_name: {
+          type: 'string',
+          description: 'Last name',
+        },
+        avatar_url: {
+          type: 'string',
+          description: 'Link to avatar image (URL)',
+        },
+      },
     }),
 
     //
@@ -322,6 +579,61 @@ const getTools = (options = {}) => {
       method: 'post',
       path: '/v1/domains',
       auth: 'apiKey',
+      inputs: {
+        domain: {
+          type: 'string',
+          description:
+            'Fully qualified domain name or IP address (e.g. "example.com")',
+        },
+        plan: {
+          type: 'string',
+          description: 'Plan type: "free", "enhanced_protection", or "team"',
+        },
+        catchall: {
+          type: 'string',
+          description:
+            'Create a default catch-all alias (email address or "true" for default)',
+        },
+        has_adult_content_protection: {
+          type: 'boolean',
+          description: 'Enable Spam Scanner adult content protection',
+        },
+        has_phishing_protection: {
+          type: 'boolean',
+          description: 'Enable Spam Scanner phishing protection',
+        },
+        has_executable_protection: {
+          type: 'boolean',
+          description: 'Enable Spam Scanner executable protection',
+        },
+        has_virus_protection: {
+          type: 'boolean',
+          description: 'Enable Spam Scanner virus protection',
+        },
+        has_recipient_verification: {
+          type: 'boolean',
+          description:
+            'Require alias recipients to click email verification link',
+        },
+        ignore_mx_check: {
+          type: 'boolean',
+          description: 'Ignore MX record check on the domain',
+        },
+        retention_days: {
+          type: 'number',
+          description:
+            'Number of days to retain emails (integer between 0 and 30)',
+        },
+        bounce_webhook: {
+          type: 'string',
+          description: 'Webhook URL for bounce notifications',
+        },
+        max_quota_per_alias: {
+          type: 'string',
+          description: 'Maximum storage quota per alias (e.g. "1GB")',
+        },
+      },
+      requiredInputs: ['domain'],
     }),
     getDomain: createTool({
       name: 'getDomain',
@@ -336,6 +648,50 @@ const getTools = (options = {}) => {
       method: 'put',
       path: '/v1/domains/{domain_id}',
       auth: 'apiKey',
+      inputs: {
+        smtp_port: {
+          type: 'string',
+          description: 'Custom SMTP forwarding port number',
+        },
+        has_adult_content_protection: {
+          type: 'boolean',
+          description: 'Enable Spam Scanner adult content protection',
+        },
+        has_phishing_protection: {
+          type: 'boolean',
+          description: 'Enable Spam Scanner phishing protection',
+        },
+        has_executable_protection: {
+          type: 'boolean',
+          description: 'Enable Spam Scanner executable protection',
+        },
+        has_virus_protection: {
+          type: 'boolean',
+          description: 'Enable Spam Scanner virus protection',
+        },
+        has_recipient_verification: {
+          type: 'boolean',
+          description:
+            'Require alias recipients to click email verification link',
+        },
+        ignore_mx_check: {
+          type: 'boolean',
+          description: 'Ignore MX record check on the domain',
+        },
+        retention_days: {
+          type: 'number',
+          description:
+            'Number of days to retain emails (integer between 0 and 30)',
+        },
+        bounce_webhook: {
+          type: 'string',
+          description: 'Webhook URL for bounce notifications',
+        },
+        max_quota_per_alias: {
+          type: 'string',
+          description: 'Maximum storage quota per alias (e.g. "1GB")',
+        },
+      },
     }),
     deleteDomain: createTool({
       name: 'deleteDomain',
@@ -364,6 +720,7 @@ const getTools = (options = {}) => {
       method: 'post',
       path: '/v1/domains/{domain_id}/test-s3-connection',
       auth: 'apiKey',
+      inputs: {},
     }),
 
     //
@@ -382,6 +739,17 @@ const getTools = (options = {}) => {
       method: 'post',
       path: '/v1/domains/{domain_id}/catch-all-passwords',
       auth: 'apiKey',
+      inputs: {
+        new_password: {
+          type: 'string',
+          description:
+            'Custom password to set (leave empty for auto-generated password)',
+        },
+        description: {
+          type: 'string',
+          description: 'Description for organizing this password',
+        },
+      },
     }),
     deleteCatchAllPassword: createTool({
       name: 'deleteCatchAllPassword',
@@ -407,6 +775,18 @@ const getTools = (options = {}) => {
       method: 'post',
       path: '/v1/domains/{domain_id}/invites',
       auth: 'apiKey',
+      inputs: {
+        email: {
+          type: 'string',
+          description: 'Email address of the user to invite',
+        },
+        group: {
+          type: 'string',
+          description:
+            'Group assignment for the invited user: "admin" or "user"',
+        },
+      },
+      requiredInputs: ['email', 'group'],
     }),
     removeDomainInvite: createTool({
       name: 'removeDomainInvite',
@@ -425,6 +805,13 @@ const getTools = (options = {}) => {
       method: 'put',
       path: '/v1/domains/{domain_id}/members/{member_id}',
       auth: 'apiKey',
+      inputs: {
+        group: {
+          type: 'string',
+          description: 'Group assignment: "admin" or "user"',
+        },
+      },
+      requiredInputs: ['group'],
     }),
     removeDomainMember: createTool({
       name: 'removeDomainMember',
@@ -451,6 +838,76 @@ const getTools = (options = {}) => {
       method: 'post',
       path: '/v1/domains/{domain_id}/aliases',
       auth: 'apiKey',
+      inputs: {
+        name: {
+          type: 'string',
+          description:
+            'Alias name (the part before @). Random if not provided.',
+        },
+        recipients: {
+          type: 'string',
+          description:
+            'Comma or newline separated email addresses to forward to',
+        },
+        description: {
+          type: 'string',
+          description: 'Alias description',
+        },
+        labels: {
+          type: 'string',
+          description: 'Comma separated list of labels',
+        },
+        has_recipient_verification: {
+          type: 'boolean',
+          description: 'Require recipients to click an email verification link',
+        },
+        is_enabled: {
+          type: 'boolean',
+          description: 'Whether the alias is enabled for email routing',
+        },
+        error_code_if_disabled: {
+          type: 'number',
+          description:
+            'SMTP error code when alias is disabled: 250, 421, or 550',
+        },
+        has_imap: {
+          type: 'boolean',
+          description: 'Enable or disable IMAP storage for the alias',
+        },
+        has_pgp: {
+          type: 'boolean',
+          description: 'Enable OpenPGP encryption for IMAP/POP3 storage',
+        },
+        public_key: {
+          type: 'string',
+          description: 'OpenPGP public key in ASCII Armor format',
+        },
+        max_quota: {
+          type: 'string',
+          description: 'Maximum storage quota for this alias (e.g. "1GB")',
+        },
+        vacation_responder_is_enabled: {
+          type: 'boolean',
+          description: 'Enable automatic vacation responder',
+        },
+        vacation_responder_start_date: {
+          type: 'string',
+          description:
+            'Vacation responder start date (MM/DD/YYYY or YYYY-MM-DD)',
+        },
+        vacation_responder_end_date: {
+          type: 'string',
+          description: 'Vacation responder end date (MM/DD/YYYY or YYYY-MM-DD)',
+        },
+        vacation_responder_subject: {
+          type: 'string',
+          description: 'Subject line for the vacation responder (plaintext)',
+        },
+        vacation_responder_message: {
+          type: 'string',
+          description: 'Message body for the vacation responder (plaintext)',
+        },
+      },
     }),
     getAlias: createTool({
       name: 'getAlias',
@@ -465,6 +922,75 @@ const getTools = (options = {}) => {
       method: 'put',
       path: '/v1/domains/{domain_id}/aliases/{alias_id}',
       auth: 'apiKey',
+      inputs: {
+        name: {
+          type: 'string',
+          description: 'Alias name (the part before @)',
+        },
+        recipients: {
+          type: 'string',
+          description:
+            'Comma or newline separated email addresses to forward to',
+        },
+        description: {
+          type: 'string',
+          description: 'Alias description',
+        },
+        labels: {
+          type: 'string',
+          description: 'Comma separated list of labels',
+        },
+        has_recipient_verification: {
+          type: 'boolean',
+          description: 'Require recipients to click an email verification link',
+        },
+        is_enabled: {
+          type: 'boolean',
+          description: 'Whether the alias is enabled for email routing',
+        },
+        error_code_if_disabled: {
+          type: 'number',
+          description:
+            'SMTP error code when alias is disabled: 250, 421, or 550',
+        },
+        has_imap: {
+          type: 'boolean',
+          description: 'Enable or disable IMAP storage for the alias',
+        },
+        has_pgp: {
+          type: 'boolean',
+          description: 'Enable OpenPGP encryption for IMAP/POP3 storage',
+        },
+        public_key: {
+          type: 'string',
+          description: 'OpenPGP public key in ASCII Armor format',
+        },
+        max_quota: {
+          type: 'string',
+          description: 'Maximum storage quota for this alias (e.g. "1GB")',
+        },
+        vacation_responder_is_enabled: {
+          type: 'boolean',
+          description: 'Enable automatic vacation responder',
+        },
+        vacation_responder_start_date: {
+          type: 'string',
+          description:
+            'Vacation responder start date (MM/DD/YYYY or YYYY-MM-DD)',
+        },
+        vacation_responder_end_date: {
+          type: 'string',
+          description: 'Vacation responder end date (MM/DD/YYYY or YYYY-MM-DD)',
+        },
+        vacation_responder_subject: {
+          type: 'string',
+          description: 'Subject line for the vacation responder (plaintext)',
+        },
+        vacation_responder_message: {
+          type: 'string',
+          description: 'Message body for the vacation responder (plaintext)',
+        },
+      },
     }),
     deleteAlias: createTool({
       name: 'deleteAlias',
@@ -482,6 +1008,28 @@ const getTools = (options = {}) => {
       method: 'post',
       path: '/v1/domains/{domain_id}/aliases/{alias_id}/generate-password',
       auth: 'apiKey',
+      inputs: {
+        new_password: {
+          type: 'string',
+          description:
+            'Custom password to set (leave empty for auto-generated password)',
+        },
+        password: {
+          type: 'string',
+          description:
+            'Existing password to change without deleting IMAP storage',
+        },
+        is_override: {
+          type: 'boolean',
+          description:
+            'Override existing password and delete associated IMAP storage',
+        },
+        emailed_instructions: {
+          type: 'string',
+          description:
+            'Email address to send the password and setup instructions to',
+        },
+      },
     }),
 
     //
@@ -603,6 +1151,74 @@ const getTools = (options = {}) => {
       method: 'post',
       path: '/v1/emails',
       auth: 'both',
+      inputs: {
+        from: {
+          type: 'string',
+          description: 'Sender email address',
+        },
+        to: {
+          type: 'string',
+          description: 'Comma separated list of recipient email addresses',
+        },
+        cc: {
+          type: 'string',
+          description: 'Comma separated list of CC recipient email addresses',
+        },
+        bcc: {
+          type: 'string',
+          description: 'Comma separated list of BCC recipient email addresses',
+        },
+        subject: {
+          type: 'string',
+          description: 'Email subject line',
+        },
+        text: {
+          type: 'string',
+          description: 'Plaintext version of the email body',
+        },
+        html: {
+          type: 'string',
+          description: 'HTML version of the email body',
+        },
+        attachments: {
+          type: 'string',
+          description:
+            'JSON array of attachment objects with filename, content, and encoding',
+        },
+        sender: {
+          type: 'string',
+          description: 'Email address for the Sender header',
+        },
+        replyTo: {
+          type: 'string',
+          description: 'Email address for the Reply-To header',
+        },
+        inReplyTo: {
+          type: 'string',
+          description: 'Message-ID that this email is replying to',
+        },
+        references: {
+          type: 'string',
+          description:
+            'Space separated list of Message-IDs in the reference chain',
+        },
+        priority: {
+          type: 'string',
+          description: 'Email priority: "high", "normal" (default), or "low"',
+        },
+        messageId: {
+          type: 'string',
+          description: 'Custom Message-ID value for the email header',
+        },
+        date: {
+          type: 'string',
+          description: 'Date value for the email Date header (ISO 8601)',
+        },
+        raw: {
+          type: 'string',
+          description: 'Custom RFC822 formatted message to send as raw email',
+        },
+      },
     }),
     getEmailLimit: createTool({
       name: 'getEmailLimit',
@@ -632,11 +1248,41 @@ const getTools = (options = {}) => {
     listMessages: createTool({
       name: 'listMessages',
       description:
-        'List and search messages in a folder. ' +
-        'Requires alias credentials (alias_username and alias_password).',
+        'List and search messages in a folder. Supports metadata_only to ' +
+        'return envelope fields only and automatically trims oversized ' +
+        'results so the tool remains usable in Anthropic clients. Requires ' +
+        'alias credentials (alias_username and alias_password).',
       method: 'get',
       path: '/v1/messages',
       auth: 'aliasAuth',
+      _meta: {
+        'anthropic/maxResultSizeChars': LIST_MESSAGES_MAX_RESULT_SIZE_CHARS,
+      },
+      inputs: {
+        metadata_only: {
+          type: 'boolean',
+          description:
+            'If true, only return lightweight message metadata (id, uid, ' +
+            'subject, from, to, date, size, attachment flags, flags, and ' +
+            'folder). Use getMessage to fetch full content for a specific ' +
+            'message.',
+        },
+      },
+      transformResponse(result, arguments_) {
+        if (isTruthyBoolean(arguments_.metadata_only)) {
+          return fitListMessagesResultToMaxSize(
+            toMetadataOnlyListMessagesResult(result),
+          );
+        }
+
+        if (
+          JSON.stringify(result).length <= LIST_MESSAGES_MAX_RESULT_SIZE_CHARS
+        ) {
+          return result;
+        }
+
+        return fitListMessagesResultToMaxSize(result);
+      },
       query: [
         'folder',
         'is_unread',
@@ -757,6 +1403,14 @@ const getTools = (options = {}) => {
       method: 'post',
       path: '/v1/encrypt',
       auth: 'none',
+      inputs: {
+        input: {
+          type: 'string',
+          description:
+            'Any valid Forward Email plaintext DNS TXT record value to encrypt',
+        },
+      },
+      requiredInputs: ['input'],
     }),
   };
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@forwardemail/mcp-server",
   "description": "Model Context Protocol (MCP) server for Forward Email. Connect AI to your inbox.",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "author": "Forward Email LLC <support@forwardemail.net> (https://forwardemail.net)",
   "bin": {
     "mcp-server": "bin/mcp-server.js"
@@ -36,6 +36,7 @@
     }
   },
   "files": [
+    "server.json",
     "lib/",
     "bin/",
     "README.md",
@@ -55,7 +56,7 @@
   ],
   "license": "BUSL-1.1",
   "main": "lib/index.js",
-  "packageManager": "pnpm@9.0.0",
+  "mcpName": "net.forwardemail/mcp-server",
   "prettier": {
     "useTabs": false,
     "tabWidth": 2,
@@ -68,13 +69,6 @@
     "type": "git",
     "url": "git+https://github.com/forwardemail/mcp-server.git"
   },
-  "scripts": {
-    "lint": "fixpack && remark . -qfo && xo --fix",
-    "pre-commit": "lint-staged",
-    "prepare": "husky",
-    "pretest": "pnpm run lint",
-    "test": "c8 --reporter=text --reporter=html node --test"
-  },
   "types": "lib/index.d.ts",
   "xo": {
     "space": 2,
@@ -90,5 +84,11 @@
         }
       ]
     }
+  },
+  "scripts": {
+    "lint": "fixpack && remark . -qfo && xo --fix",
+    "pre-commit": "lint-staged",
+    "pretest": "pnpm run lint",
+    "test": "c8 --reporter=text --reporter=html node --test"
   }
-}
+}

package/server.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "net.forwardemail/mcp-server",
+  "title": "Forward Email",
+  "description": "Privacy-focused email: domains, DNS verification, aliases, SMTP sending, mailboxes and calendars.",
+  "websiteUrl": "https://forwardemail.net/en/blog/docs/mcp",
+  "repository": {
+    "url": "https://github.com/forwardemail/mcp-server",
+    "source": "github"
+  },
+  "version": "1.0.7",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@forwardemail/mcp-server",
+      "version": "1.0.7",
+      "transport": { "type": "stdio" },
+      "environmentVariables": [
+        {
+          "name": "FORWARD_EMAIL_API_KEY",
+          "description": "API key from https://forwardemail.net/my-account/security",
+          "isRequired": true,
+          "isSecret": true,
+          "format": "string"
+        },
+        {
+          "name": "FORWARD_EMAIL_ALIAS_USER",
+          "description": "Alias address for the mailbox, calendar and contact tools",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "FORWARD_EMAIL_ALIAS_PASSWORD",
+          "description": "Generated password for that alias",
+          "isRequired": false,
+          "isSecret": true,
+          "format": "string"
+        }
+      ]
+    }
+  ]
+}