Better Email MCP

Instructions

Implementation Reference

• src/tools/composite/attachments.ts:26-55 (handler)

  Main handler function for the 'attachments' tool. Validates input, dispatches to handleList or handleDownload based on action, and wraps execution with error handling.

  export async function attachments(accounts: AccountConfig[], input: AttachmentsInput): Promise<any> {
    return withErrorHandling(async () => {
      if (!input.account) {
        throw new EmailMCPError(
          'account is required for attachment operations',
          'VALIDATION_ERROR',
          'Provide the account email address'
        )
      }
  
      if (!input.uid) {
        throw new EmailMCPError(
          'uid is required for attachment operations',
          'VALIDATION_ERROR',
          'Provide the email UID from search/read'
        )
      }
  
      switch (input.action) {
        case 'list':
          return await handleList(accounts, input)
  
        case 'download':
          return await handleDownload(accounts, input)
  
        default:
          throw createUnknownActionError(input.action, 'list, download')
      }
    })()
  }

• src/tools/composite/attachments.ts:11-21 (schema)

  TypeScript interface defining the input schema for the attachments tool, including action type ('list' or 'download'), required fields (account, uid), and optional fields (folder, filename).

  export interface AttachmentsInput {
    action: 'list' | 'download'
  
    // Required
    account: string
    uid: number
  
    // Optional
    folder?: string
    filename?: string
  }

• src/tools/composite/attachments.ts:60-75 (handler)

  handleList function - lists all attachments for a specific email by reading the email and returning attachment metadata (filename, content_type, size, content_id).

  async function handleList(accounts: AccountConfig[], input: AttachmentsInput): Promise<any> {
    const account = resolveSingleAccount(accounts, input.account)
    const folder = input.folder || 'INBOX'
  
    const email = await readEmail(account, input.uid, folder)
  
    return {
      action: 'list',
      account: account.email,
      uid: input.uid,
      folder,
      subject: email.subject,
      total: email.attachments.length,
      attachments: email.attachments
    }
  }

• src/tools/composite/attachments.ts:80-101 (handler)

  handleDownload function - downloads a specific attachment by filename, returning base64-encoded content along with metadata.

  async function handleDownload(accounts: AccountConfig[], input: AttachmentsInput): Promise<any> {
    if (!input.filename) {
      throw new EmailMCPError(
        'filename is required for download action',
        'VALIDATION_ERROR',
        'Use attachments list action first to see available filenames'
      )
    }
  
    const account = resolveSingleAccount(accounts, input.account)
    const folder = input.folder || 'INBOX'
  
    const attachment = await getAttachment(account, input.uid, folder, input.filename)
  
    return {
      action: 'download',
      account: account.email,
      uid: input.uid,
      folder,
      ...attachment
    }
  }

• src/tools/registry.ts:107-133 (registration)

  Tool registration for 'attachments' in the registry, defining the tool name, description, annotations, and JSON Schema input schema including action enum, required fields, and optional parameters.

  {
    name: 'attachments',
    description:
      'Email attachments: list, download. List shows all attachments for an email. Download returns base64-encoded content.',
    annotations: {
      title: 'Attachments',
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: false
    },
    inputSchema: {
      type: 'object',
      properties: {
        action: {
          type: 'string',
          enum: ['list', 'download'],
          description: 'Action to perform'
        },
        account: { type: 'string', description: 'Account email (required)' },
        uid: { type: 'number', description: 'Email UID (required)' },
        folder: { type: 'string', description: 'Mailbox folder (default: INBOX)' },
        filename: { type: 'string', description: 'Attachment filename (required for download)' }
      },
      required: ['action', 'account', 'uid']
    }
  },