@forwardemail/mcp-server 1.0.2 → 1.0.4

package/README.md

@@ -1,211 +0,0 @@
-# @forwardemail/mcp-server
-
-[Model Context Protocol](https://github.com/modelcontextprotocol/specification) (MCP) server for [Forward Email](https://forwardemail.net). Connect AI assistants to your inbox.
-
-## Overview
-
-This package provides a local MCP server that wraps the [Forward Email API](https://forwardemail.net/email-api). It lets AI agents (Claude, ChatGPT, Cursor, Windsurf, and others) send email, manage domains, and read your inbox through natural language.
-
-The server runs locally on your machine via `stdio`. Your API key never leaves your device.
-
-## Install
-
-```bash
-npm install -g @forwardemail/mcp-server
-```
-
-Or run directly with `npx`:
-
-```bash
-npx @forwardemail/mcp-server
-```
-
-## Setup
-
-### 1. Get your API key
-
-Log in at <https://forwardemail.net/my-account/security> and copy your API key.
-
-### 2. Set the environment variable
-
-```bash
-export FORWARD_EMAIL_API_KEY=your-api-key
-```
-
-### 3. Configure your AI client
-
-#### Claude Desktop
-
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "forwardemail": {
-      "command": "npx",
-      "args": ["@forwardemail/mcp-server"],
-      "env": {
-        "FORWARD_EMAIL_API_KEY": "your-api-key"
-      }
-    }
-  }
-}
-```
-
-#### Cursor
-
-Add to `.cursor/mcp.json` in your project:
-
-```json
-{
-  "mcpServers": {
-    "forwardemail": {
-      "command": "npx",
-      "args": ["@forwardemail/mcp-server"],
-      "env": {
-        "FORWARD_EMAIL_API_KEY": "your-api-key"
-      }
-    }
-  }
-}
-```
-
-## Available Tools
-
-This server exposes the complete [Forward Email API](https://forwardemail.net/email-api) as MCP tools. Every endpoint is covered.
-
-### Account
-
-* `getAccount` - Get your account details
-* `updateAccount` - Update your account
-
-### Logs
-
-* `downloadLogs` - Download email delivery logs
-
-### Contacts (CardDAV)
-
-* `listContacts` - List all contacts
-* `createContact` - Create a contact
-* `getContact` - Get a contact by ID
-* `updateContact` - Update a contact
-* `deleteContact` - Delete a contact
-
-### Calendars (CalDAV)
-
-* `listCalendars` - List all calendars
-* `createCalendar` - Create a calendar
-* `getCalendar` - Get a calendar by ID
-* `updateCalendar` - Update a calendar
-* `deleteCalendar` - Delete a calendar
-
-### Calendar Events (CalDAV)
-
-* `listCalendarEvents` - List all calendar events
-* `createCalendarEvent` - Create a calendar event
-* `getCalendarEvent` - Get a calendar event by ID
-* `updateCalendarEvent` - Update a calendar event
-* `deleteCalendarEvent` - Delete a calendar event
-
-### Domains
-
-* `listDomains` - List all domains
-* `createDomain` - Create a new domain
-* `getDomain` - Get a domain by ID or name
-* `updateDomain` - Update a domain
-* `deleteDomain` - Delete a domain
-* `verifyDomainRecords` - Verify domain DNS records
-* `verifySmtpRecords` - Verify domain SMTP records
-* `testS3Connection` - Test custom S3 connection for a domain
-
-### Domain Catch-All Passwords
-
-* `listCatchAllPasswords` - List domain-wide catch-all passwords
-* `createCatchAllPassword` - Create a domain-wide catch-all password
-* `deleteCatchAllPassword` - Remove a domain-wide catch-all password
-
-### Domain Invites
-
-* `acceptDomainInvite` - Accept a domain invite
-* `createDomainInvite` - Invite a user to a domain
-* `removeDomainInvite` - Remove a domain invite
-
-### Domain Members
-
-* `updateDomainMember` - Update a domain member role
-* `removeDomainMember` - Remove a member from a domain
-
-### Aliases
-
-* `listAliases` - List aliases for a domain
-* `createAlias` - Create a new alias
-* `getAlias` - Get an alias by ID
-* `updateAlias` - Update an alias
-* `deleteAlias` - Delete an alias
-* `generateAliasPassword` - Generate or set a password for an alias
-
-### Sieve Scripts
-
-* `listSieveScripts` - List Sieve scripts for an alias
-* `createSieveScript` - Create a Sieve script for an alias
-* `getSieveScript` - Get a Sieve script by ID
-* `updateSieveScript` - Update a Sieve script
-* `deleteSieveScript` - Delete a Sieve script
-* `activateSieveScript` - Activate a Sieve script
-
-### Sieve Scripts (Alias Auth)
-
-* `listSieveScriptsAliasAuth` - List Sieve scripts (alias auth)
-* `createSieveScriptAliasAuth` - Create a Sieve script (alias auth)
-* `getSieveScriptAliasAuth` - Get a Sieve script (alias auth)
-* `updateSieveScriptAliasAuth` - Update a Sieve script (alias auth)
-* `deleteSieveScriptAliasAuth` - Delete a Sieve script (alias auth)
-* `activateSieveScriptAliasAuth` - Activate a Sieve script (alias auth)
-
-### Emails (Outbound SMTP)
-
-* `listEmails` - List outbound SMTP emails
-* `sendEmail` - Send an email via outbound SMTP
-* `getEmailLimit` - Get outbound SMTP email sending limit
-* `getEmail` - Get an outbound SMTP email by ID
-* `deleteEmail` - Delete an outbound SMTP email
-
-### Messages (IMAP)
-
-* `listMessages` - List and search messages in a folder
-* `createMessage` - Create a new message (draft)
-* `getMessage` - Get a message by ID
-* `updateMessage` - Update a message
-* `deleteMessage` - Delete a message
-
-### Folders (IMAP)
-
-* `listFolders` - List all folders
-* `createFolder` - Create a new folder
-* `getFolder` - Get a folder by ID
-* `updateFolder` - Update a folder
-* `deleteFolder` - Delete a folder
-
-### Encrypt
-
-* `encryptRecord` - Encrypt a plaintext Forward Email TXT record
-
-## Development
-
-```bash
-git clone https://github.com/forwardemail/mcp-server.git
-cd mcp-server
-pnpm install
-pnpm test
-```
-
-## License
-
-[BUSL-1.1](LICENSE)
-
-## Links
-
-* [Forward Email](https://forwardemail.net)
-* [Forward Email API Docs](https://forwardemail.net/email-api)
-* [MCP Specification](https://github.com/modelcontextprotocol/specification)
-* [MCP Landing Page](https://forwardemail.net/mcp)

package/lib/index.d.ts

@@ -1,6 +1,8 @@
 export type McpServerOptions = {
   apiKey?: string;
   baseURL?: string;
+  aliasUser?: string;
+  aliasPassword?: string;
 };
 
 export class McpServer {

package/lib/tools.js

@@ -1,43 +1,130 @@
 const axios = require('axios');
 
 const getTools = (options = {}) => {
-  const client = axios.create({
-    baseURL: options.baseURL || 'https://api.forwardemail.net',
-    headers: {
-      Authorization: `Bearer ${options.apiKey || process.env.FORWARD_EMAIL_API_KEY}`,
-    },
+  const baseURL =
+    options.baseURL ||
+    process.env.FORWARD_EMAIL_API_URL ||
+    'https://api.forwardemail.net';
+  const apiKey = options.apiKey || process.env.FORWARD_EMAIL_API_KEY;
+
+  // Create an axios client for API-key-authenticated requests
+  // (Basic auth: apiKey as username, empty password)
+  const apiKeyClient = axios.create({
+    baseURL,
+    auth: apiKey ? {username: apiKey, password: ''} : undefined,
   });
 
+  // Create an axios client for alias-authenticated requests
+  // (Basic auth: alias email as username, generated password as password)
+  const createAliasClient = (username, password) =>
+    axios.create({
+      baseURL,
+      auth: {username, password},
+    });
+
+  // Default alias credentials from options or environment
+  const defaultAliasUser =
+    options.aliasUser || process.env.FORWARD_EMAIL_ALIAS_USER || '';
+  const defaultAliasPassword =
+    options.aliasPassword || process.env.FORWARD_EMAIL_ALIAS_PASSWORD || '';
+
+  //
+  // auth types:
+  //   'apiKey'    – uses API key via Basic auth (username=apiKey, password='')
+  //   'aliasAuth' – uses alias credentials via Basic auth
+  //                 (username=alias email, password=generated password)
+  //   'both'      – accepts either; uses alias credentials if provided,
+  //                 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 || {},
+        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.',
+            },
+          }),
+        },
       },
     },
+    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)) {
-          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];
-          }
+        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];
         }
       }
 
       const config = {params: queryArguments};
       const hasBody = Object.keys(bodyArguments).length > 0;
 
+      // Choose the right client based on auth type
+      let client;
+      switch (spec.auth) {
+        case 'aliasAuth': {
+          client = createAliasClient(aliasUser, aliasPass);
+
+          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});
+
+          break;
+        }
+
+        default: {
+          client = apiKeyClient;
+        }
+      }
+
       let response;
       if (spec.method === 'get' || spec.method === 'delete') {
         response = await client[spec.method](path, config);
@@ -55,29 +142,36 @@ const getTools = (options = {}) => {
 
   const tools = {
     //
-    // Account
+    // Account (supports both API key and alias auth)
     //
     getAccount: createTool({
       name: 'getAccount',
-      description: 'Get your account details',
+      description:
+        'Get your account details. With API key auth returns user account info. ' +
+        'With alias auth returns alias/mailbox info including storage quota.',
       method: 'get',
       path: '/v1/account',
+      auth: 'both',
     }),
     updateAccount: createTool({
       name: 'updateAccount',
-      description: 'Update your account',
+      description:
+        'Update your account. With API key auth updates user profile. ' +
+        'With alias auth updates alias-scoped settings.',
       method: 'put',
       path: '/v1/account',
+      auth: 'both',
     }),
 
     //
-    // Logs
+    // Logs (API key auth)
     //
     downloadLogs: createTool({
       name: 'downloadLogs',
       description: 'Download email delivery logs',
       method: 'get',
       path: '/v1/logs/download',
+      auth: 'apiKey',
       query: [
         'domain',
         'q',
@@ -88,115 +182,138 @@ const getTools = (options = {}) => {
     }),
 
     //
-    // Contacts (CardDAV)
+    // Contacts (CardDAV) — alias auth required
     //
     listContacts: createTool({
       name: 'listContacts',
-      description: 'List all contacts',
+      description:
+        'List all contacts for the authenticated alias. ' +
+        'Requires alias credentials (alias_username and alias_password).',
       method: 'get',
       path: '/v1/contacts',
+      auth: 'aliasAuth',
     }),
     createContact: createTool({
       name: 'createContact',
-      description: 'Create a contact',
+      description:
+        'Create a contact for the authenticated alias. Requires alias credentials.',
       method: 'post',
       path: '/v1/contacts',
+      auth: 'aliasAuth',
     }),
     getContact: createTool({
       name: 'getContact',
-      description: 'Get a contact by ID',
+      description: 'Get a contact by ID. Requires alias credentials.',
       method: 'get',
       path: '/v1/contacts/{id}',
+      auth: 'aliasAuth',
     }),
     updateContact: createTool({
       name: 'updateContact',
-      description: 'Update a contact',
+      description: 'Update a contact. Requires alias credentials.',
       method: 'put',
       path: '/v1/contacts/{id}',
+      auth: 'aliasAuth',
     }),
     deleteContact: createTool({
       name: 'deleteContact',
-      description: 'Delete a contact',
+      description: 'Delete a contact. Requires alias credentials.',
       method: 'delete',
       path: '/v1/contacts/{id}',
+      auth: 'aliasAuth',
     }),
 
     //
-    // Calendars (CalDAV)
+    // Calendars (CalDAV) — alias auth required
     //
     listCalendars: createTool({
       name: 'listCalendars',
-      description: 'List all calendars',
+      description:
+        'List all calendars for the authenticated alias. ' +
+        'Requires alias credentials (alias_username and alias_password).',
       method: 'get',
       path: '/v1/calendars',
+      auth: 'aliasAuth',
     }),
     createCalendar: createTool({
       name: 'createCalendar',
-      description: 'Create a calendar',
+      description: 'Create a calendar. Requires alias credentials.',
       method: 'post',
       path: '/v1/calendars',
+      auth: 'aliasAuth',
     }),
     getCalendar: createTool({
       name: 'getCalendar',
-      description: 'Get a calendar by ID',
+      description: 'Get a calendar by ID. Requires alias credentials.',
       method: 'get',
       path: '/v1/calendars/{id}',
+      auth: 'aliasAuth',
     }),
     updateCalendar: createTool({
       name: 'updateCalendar',
-      description: 'Update a calendar',
+      description: 'Update a calendar. Requires alias credentials.',
       method: 'put',
       path: '/v1/calendars/{id}',
+      auth: 'aliasAuth',
     }),
     deleteCalendar: createTool({
       name: 'deleteCalendar',
-      description: 'Delete a calendar',
+      description: 'Delete a calendar. Requires alias credentials.',
       method: 'delete',
       path: '/v1/calendars/{id}',
+      auth: 'aliasAuth',
     }),
 
     //
-    // Calendar Events (CalDAV)
+    // Calendar Events (CalDAV) — alias auth required
     //
     listCalendarEvents: createTool({
       name: 'listCalendarEvents',
-      description: 'List all calendar events',
+      description:
+        'List all calendar events for the authenticated alias. ' +
+        'Requires alias credentials (alias_username and alias_password).',
       method: 'get',
       path: '/v1/calendar-events',
+      auth: 'aliasAuth',
     }),
     createCalendarEvent: createTool({
       name: 'createCalendarEvent',
-      description: 'Create a calendar event',
+      description: 'Create a calendar event. Requires alias credentials.',
       method: 'post',
       path: '/v1/calendar-events',
+      auth: 'aliasAuth',
     }),
     getCalendarEvent: createTool({
       name: 'getCalendarEvent',
-      description: 'Get a calendar event by ID',
+      description: 'Get a calendar event by ID. Requires alias credentials.',
       method: 'get',
       path: '/v1/calendar-events/{id}',
+      auth: 'aliasAuth',
     }),
     updateCalendarEvent: createTool({
       name: 'updateCalendarEvent',
-      description: 'Update a calendar event',
+      description: 'Update a calendar event. Requires alias credentials.',
       method: 'put',
       path: '/v1/calendar-events/{id}',
+      auth: 'aliasAuth',
     }),
     deleteCalendarEvent: createTool({
       name: 'deleteCalendarEvent',
-      description: 'Delete a calendar event',
+      description: 'Delete a calendar event. Requires alias credentials.',
       method: 'delete',
       path: '/v1/calendar-events/{id}',
+      auth: 'aliasAuth',
     }),
 
     //
-    // Domains
+    // Domains (API key auth)
     //
     listDomains: createTool({
       name: 'listDomains',
       description: 'List all domains',
       method: 'get',
       path: '/v1/domains',
+      auth: 'apiKey',
       query: ['sort', 'page', 'limit'],
     }),
     createDomain: createTool({
@@ -204,112 +321,128 @@ const getTools = (options = {}) => {
       description: 'Create a new domain',
       method: 'post',
       path: '/v1/domains',
+      auth: 'apiKey',
     }),
     getDomain: createTool({
       name: 'getDomain',
       description: 'Get a domain by ID or name',
       method: 'get',
       path: '/v1/domains/{domain_id}',
+      auth: 'apiKey',
     }),
     updateDomain: createTool({
       name: 'updateDomain',
       description: 'Update a domain',
       method: 'put',
       path: '/v1/domains/{domain_id}',
+      auth: 'apiKey',
     }),
     deleteDomain: createTool({
       name: 'deleteDomain',
       description: 'Delete a domain',
       method: 'delete',
       path: '/v1/domains/{domain_id}',
+      auth: 'apiKey',
     }),
     verifyDomainRecords: createTool({
       name: 'verifyDomainRecords',
       description: 'Verify domain DNS records',
       method: 'get',
       path: '/v1/domains/{domain_id}/verify-records',
+      auth: 'apiKey',
     }),
     verifySmtpRecords: createTool({
       name: 'verifySmtpRecords',
       description: 'Verify domain SMTP records',
       method: 'get',
       path: '/v1/domains/{domain_id}/verify-smtp',
+      auth: 'apiKey',
     }),
     testS3Connection: createTool({
       name: 'testS3Connection',
       description: 'Test custom S3 connection for a domain',
       method: 'post',
       path: '/v1/domains/{domain_id}/test-s3-connection',
+      auth: 'apiKey',
     }),
 
     //
-    // Domain Catch-All Passwords
+    // Domain Catch-All Passwords (API key auth)
     //
     listCatchAllPasswords: createTool({
       name: 'listCatchAllPasswords',
       description: 'List domain-wide catch-all passwords',
       method: 'get',
       path: '/v1/domains/{domain_id}/catch-all-passwords',
+      auth: 'apiKey',
     }),
     createCatchAllPassword: createTool({
       name: 'createCatchAllPassword',
       description: 'Create a domain-wide catch-all password',
       method: 'post',
       path: '/v1/domains/{domain_id}/catch-all-passwords',
+      auth: 'apiKey',
     }),
     deleteCatchAllPassword: createTool({
       name: 'deleteCatchAllPassword',
       description: 'Remove a domain-wide catch-all password',
       method: 'delete',
       path: '/v1/domains/{domain_id}/catch-all-passwords/{token_id}',
+      auth: 'apiKey',
     }),
 
     //
-    // Domain Invites
+    // Domain Invites (API key auth)
     //
     acceptDomainInvite: createTool({
       name: 'acceptDomainInvite',
       description: 'Accept a domain invite',
       method: 'get',
       path: '/v1/domains/{domain_id}/invites',
+      auth: 'apiKey',
     }),
     createDomainInvite: createTool({
       name: 'createDomainInvite',
       description: 'Invite a user to a domain',
       method: 'post',
       path: '/v1/domains/{domain_id}/invites',
+      auth: 'apiKey',
     }),
     removeDomainInvite: createTool({
       name: 'removeDomainInvite',
       description: 'Remove a domain invite',
       method: 'delete',
       path: '/v1/domains/{domain_id}/invites',
+      auth: 'apiKey',
     }),
 
     //
-    // Domain Members
+    // Domain Members (API key auth)
     //
     updateDomainMember: createTool({
       name: 'updateDomainMember',
       description: 'Update a domain member role (admin or user)',
       method: 'put',
       path: '/v1/domains/{domain_id}/members/{member_id}',
+      auth: 'apiKey',
     }),
     removeDomainMember: createTool({
       name: 'removeDomainMember',
       description: 'Remove a member from a domain',
       method: 'delete',
       path: '/v1/domains/{domain_id}/members/{member_id}',
+      auth: 'apiKey',
     }),
 
     //
-    // Aliases
+    // Aliases (API key auth)
     //
     listAliases: createTool({
       name: 'listAliases',
       description: 'List aliases for a domain',
       method: 'get',
       path: '/v1/domains/{domain_id}/aliases',
+      auth: 'apiKey',
       query: ['sort', 'page', 'limit'],
     }),
     createAlias: createTool({
@@ -317,155 +450,193 @@ const getTools = (options = {}) => {
       description: 'Create a new alias',
       method: 'post',
       path: '/v1/domains/{domain_id}/aliases',
+      auth: 'apiKey',
     }),
     getAlias: createTool({
       name: 'getAlias',
       description: 'Get an alias by ID',
       method: 'get',
       path: '/v1/domains/{domain_id}/aliases/{alias_id}',
+      auth: 'apiKey',
     }),
     updateAlias: createTool({
       name: 'updateAlias',
       description: 'Update an alias',
       method: 'put',
       path: '/v1/domains/{domain_id}/aliases/{alias_id}',
+      auth: 'apiKey',
     }),
     deleteAlias: createTool({
       name: 'deleteAlias',
       description: 'Delete an alias',
       method: 'delete',
       path: '/v1/domains/{domain_id}/aliases/{alias_id}',
+      auth: 'apiKey',
     }),
     generateAliasPassword: createTool({
       name: 'generateAliasPassword',
-      description: 'Generate or set a password for an alias',
+      description:
+        'Generate or set a password for an alias. Returns the alias username ' +
+        'and password needed for alias-authenticated endpoints (messages, ' +
+        'folders, contacts, calendars, sieve scripts).',
       method: 'post',
       path: '/v1/domains/{domain_id}/aliases/{alias_id}/generate-password',
+      auth: 'apiKey',
     }),
 
     //
-    // Sieve Scripts (domain-scoped, authenticated via API key)
+    // Sieve Scripts — domain-scoped (API key auth)
     //
     listSieveScripts: createTool({
       name: 'listSieveScripts',
-      description: 'List Sieve scripts for an alias',
+      description: 'List Sieve scripts for an alias (API key auth)',
       method: 'get',
       path: '/v1/domains/{domain_id}/aliases/{alias_id}/sieve',
+      auth: 'apiKey',
     }),
     createSieveScript: createTool({
       name: 'createSieveScript',
-      description: 'Create a Sieve script for an alias',
+      description: 'Create a Sieve script for an alias (API key auth)',
       method: 'post',
       path: '/v1/domains/{domain_id}/aliases/{alias_id}/sieve',
+      auth: 'apiKey',
     }),
     getSieveScript: createTool({
       name: 'getSieveScript',
-      description: 'Get a Sieve script by ID',
+      description: 'Get a Sieve script by ID (API key auth)',
       method: 'get',
       path: '/v1/domains/{domain_id}/aliases/{alias_id}/sieve/{script_id}',
+      auth: 'apiKey',
     }),
     updateSieveScript: createTool({
       name: 'updateSieveScript',
-      description: 'Update a Sieve script',
+      description: 'Update a Sieve script (API key auth)',
       method: 'put',
       path: '/v1/domains/{domain_id}/aliases/{alias_id}/sieve/{script_id}',
+      auth: 'apiKey',
     }),
     deleteSieveScript: createTool({
       name: 'deleteSieveScript',
-      description: 'Delete a Sieve script',
+      description: 'Delete a Sieve script (API key auth)',
       method: 'delete',
       path: '/v1/domains/{domain_id}/aliases/{alias_id}/sieve/{script_id}',
+      auth: 'apiKey',
     }),
     activateSieveScript: createTool({
       name: 'activateSieveScript',
-      description: 'Activate a Sieve script',
+      description: 'Activate a Sieve script (API key auth)',
       method: 'post',
       path: '/v1/domains/{domain_id}/aliases/{alias_id}/sieve/{script_id}/activate',
+      auth: 'apiKey',
     }),
 
     //
-    // Sieve Scripts (alias auth, authenticated via alias credentials)
+    // Sieve Scripts — alias-scoped (alias auth)
     //
     listSieveScriptsAliasAuth: createTool({
       name: 'listSieveScriptsAliasAuth',
-      description: 'List Sieve scripts (alias auth)',
+      description:
+        'List Sieve scripts for the authenticated alias. ' +
+        'Requires alias credentials.',
       method: 'get',
       path: '/v1/sieve-scripts',
+      auth: 'aliasAuth',
     }),
     createSieveScriptAliasAuth: createTool({
       name: 'createSieveScriptAliasAuth',
-      description: 'Create a Sieve script (alias auth)',
+      description:
+        'Create a Sieve script for the authenticated alias. ' +
+        'Requires alias credentials.',
       method: 'post',
       path: '/v1/sieve-scripts',
+      auth: 'aliasAuth',
     }),
     getSieveScriptAliasAuth: createTool({
       name: 'getSieveScriptAliasAuth',
-      description: 'Get a Sieve script (alias auth)',
+      description:
+        'Get a Sieve script by ID (alias auth). Requires alias credentials.',
       method: 'get',
       path: '/v1/sieve-scripts/{script_id}',
+      auth: 'aliasAuth',
     }),
     updateSieveScriptAliasAuth: createTool({
       name: 'updateSieveScriptAliasAuth',
-      description: 'Update a Sieve script (alias auth)',
+      description:
+        'Update a Sieve script (alias auth). Requires alias credentials.',
       method: 'put',
       path: '/v1/sieve-scripts/{script_id}',
+      auth: 'aliasAuth',
     }),
     deleteSieveScriptAliasAuth: createTool({
       name: 'deleteSieveScriptAliasAuth',
-      description: 'Delete a Sieve script (alias auth)',
+      description:
+        'Delete a Sieve script (alias auth). Requires alias credentials.',
       method: 'delete',
       path: '/v1/sieve-scripts/{script_id}',
+      auth: 'aliasAuth',
     }),
     activateSieveScriptAliasAuth: createTool({
       name: 'activateSieveScriptAliasAuth',
-      description: 'Activate a Sieve script (alias auth)',
+      description:
+        'Activate a Sieve script (alias auth). Requires alias credentials.',
       method: 'post',
       path: '/v1/sieve-scripts/{script_id}/activate',
+      auth: 'aliasAuth',
     }),
 
     //
-    // Emails (Outbound SMTP)
+    // Emails — Outbound SMTP
     //
     listEmails: createTool({
       name: 'listEmails',
       description: 'List outbound SMTP emails',
       method: 'get',
       path: '/v1/emails',
+      auth: 'apiKey',
       query: ['q', 'domain', 'is_scheduled', 'sort', 'page', 'limit'],
     }),
     sendEmail: createTool({
       name: 'sendEmail',
-      description: 'Send an email via outbound SMTP',
+      description:
+        'Send an email via outbound SMTP. ' +
+        'Supports both API key and alias auth.',
       method: 'post',
       path: '/v1/emails',
+      auth: 'both',
     }),
     getEmailLimit: createTool({
       name: 'getEmailLimit',
       description: 'Get outbound SMTP email sending limit',
       method: 'get',
       path: '/v1/emails/limit',
+      auth: 'apiKey',
     }),
     getEmail: createTool({
       name: 'getEmail',
       description: 'Get an outbound SMTP email by ID',
       method: 'get',
       path: '/v1/emails/{id}',
+      auth: 'apiKey',
     }),
     deleteEmail: createTool({
       name: 'deleteEmail',
       description: 'Delete an outbound SMTP email',
       method: 'delete',
       path: '/v1/emails/{id}',
+      auth: 'apiKey',
     }),
 
     //
-    // Messages (IMAP)
+    // Messages — IMAP (alias auth required)
     //
     listMessages: createTool({
       name: 'listMessages',
-      description: 'List and search messages in a folder',
+      description:
+        'List and search messages in a folder. ' +
+        'Requires alias credentials (alias_username and alias_password).',
       method: 'get',
       path: '/v1/messages',
+      auth: 'aliasAuth',
       query: [
         'folder',
         'is_unread',
@@ -500,74 +671,92 @@ const getTools = (options = {}) => {
     }),
     createMessage: createTool({
       name: 'createMessage',
-      description: 'Create a new message (draft)',
+      description:
+        'Create a new message (draft) in a folder. ' +
+        'Requires alias credentials.',
       method: 'post',
       path: '/v1/messages',
+      auth: 'aliasAuth',
     }),
     getMessage: createTool({
       name: 'getMessage',
-      description: 'Get a message by ID',
+      description: 'Get a message by ID. Requires alias credentials.',
       method: 'get',
       path: '/v1/messages/{id}',
+      auth: 'aliasAuth',
       query: ['eml', 'nodemailer', 'attachments', 'raw'],
     }),
     updateMessage: createTool({
       name: 'updateMessage',
-      description: 'Update a message',
+      description:
+        'Update a message (flags, labels, move to folder). ' +
+        'Requires alias credentials.',
       method: 'put',
       path: '/v1/messages/{id}',
+      auth: 'aliasAuth',
       query: ['eml'],
     }),
     deleteMessage: createTool({
       name: 'deleteMessage',
-      description: 'Delete a message',
+      description: 'Delete a message permanently. Requires alias credentials.',
       method: 'delete',
       path: '/v1/messages/{id}',
+      auth: 'aliasAuth',
     }),
 
     //
-    // Folders (IMAP)
+    // Folders — IMAP (alias auth required)
     //
     listFolders: createTool({
       name: 'listFolders',
-      description: 'List all folders',
+      description:
+        'List all IMAP folders. ' +
+        'Requires alias credentials (alias_username and alias_password).',
       method: 'get',
       path: '/v1/folders',
+      auth: 'aliasAuth',
       query: ['subscribed'],
     }),
     createFolder: createTool({
       name: 'createFolder',
-      description: 'Create a new folder',
+      description: 'Create a new IMAP folder. Requires alias credentials.',
       method: 'post',
       path: '/v1/folders',
+      auth: 'aliasAuth',
     }),
     getFolder: createTool({
       name: 'getFolder',
-      description: 'Get a folder by ID',
+      description: 'Get a folder by ID or path. Requires alias credentials.',
       method: 'get',
       path: '/v1/folders/{id}',
+      auth: 'aliasAuth',
     }),
     updateFolder: createTool({
       name: 'updateFolder',
-      description: 'Update a folder',
+      description: 'Rename a folder. Requires alias credentials.',
       method: 'put',
       path: '/v1/folders/{id}',
+      auth: 'aliasAuth',
     }),
     deleteFolder: createTool({
       name: 'deleteFolder',
-      description: 'Delete a folder',
+      description:
+        'Delete a folder and all messages in it. ' +
+        'Requires alias credentials.',
       method: 'delete',
       path: '/v1/folders/{id}',
+      auth: 'aliasAuth',
     }),
 
     //
-    // Encrypt
+    // Encrypt (no auth required)
     //
     encryptRecord: createTool({
       name: 'encryptRecord',
       description: 'Encrypt a plaintext Forward Email TXT record',
       method: 'post',
       path: '/v1/encrypt',
+      auth: 'none',
     }),
   };
 

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.2",
+  "version": "1.0.4",
   "author": "Forward Email LLC <support@forwardemail.net> (https://forwardemail.net)",
   "bin": {
     "mcp-server": "bin/mcp-server.js"
@@ -59,6 +59,9 @@
     "tabWidth": 2,
     "singleQuote": true
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/forwardemail/mcp-server.git"
@@ -70,7 +73,13 @@
     "rules": {
       "unicorn/prefer-module": "off",
       "import-x/extensions": "off",
-      "n/prefer-global/process": "off"
+      "n/prefer-global/process": "off",
+      "camelcase": [
+        "error",
+        {
+          "properties": "never"
+        }
+      ]
     }
   },
   "scripts": {