Better Email MCP

Instructions

Implementation Reference

• src/tools/composite/folders.ts:21-31 (handler)

  Main handler function 'folders' that orchestrates folder listing operations. It uses a switch statement to route to the appropriate action handler (currently only 'list' is supported).

  export async function folders(accounts: AccountConfig[], input: FoldersInput): Promise<any> {
    return withErrorHandling(async () => {
      switch (input.action) {
        case 'list':
          return await handleList(accounts, input)
  
        default:
          throw createUnknownActionError(input.action, 'list')
      }
    })()
  }

• src/tools/composite/folders.ts:11-16 (schema)

  TypeScript interface 'FoldersInput' defining the input schema for the folders tool. Requires an 'action' field (currently only 'list') and optional 'account' filter.

  export interface FoldersInput {
    action: 'list'
  
    // Target account (optional - defaults to all)
    account?: string
  }

• src/tools/registry.ts:85-106 (registration)

  Tool registration defining the 'folders' tool metadata including name, description, annotations (readOnlyHint: true, idempotentHint: true), and JSON input schema with action and account properties.

    name: 'folders',
    description: 'List mailbox folders for one or all email accounts. Returns folder names, paths, and flags.',
    annotations: {
      title: 'Folders',
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: false
    },
    inputSchema: {
      type: 'object',
      properties: {
        action: {
          type: 'string',
          enum: ['list'],
          description: 'Action to perform'
        },
        account: { type: 'string', description: 'Account email filter (optional, defaults to all)' }
      },
      required: ['action']
    }
  },

• src/tools/registry.ts:250-252 (registration)

  Handler dispatch logic in the CallToolRequestSchema handler that invokes the folders function when the tool name is 'folders'.

  case 'folders':
    result = await folders(accounts, args as unknown as FoldersInput)
    break

• src/tools/helpers/imap-client.ts:442-452 (helper)

  Core helper function 'listFolders' that performs the actual IMAP folder listing operation. Connects to the email account and retrieves mailbox list with name, path, flags, and delimiter.

  export async function listFolders(account: AccountConfig): Promise<FolderInfo[]> {
    return withConnection(account, async (client) => {
      const mailboxes = await client.list()
      return mailboxes.map((mb: any) => ({
        name: mb.name,
        path: mb.path,
        flags: Array.from(mb.flags || []),
        delimiter: mb.delimiter || '/'
      }))
    })
  }