get_recent_emails

Instructions

Implementation Reference

• src/mcp-server.ts:281-285 (handler)

  The MCP server handler for the 'get_recent_emails' tool. It extracts limit/mailboxName/offset args, calls client.getRecentEmails(), and returns the result as JSON.

  case 'get_recent_emails': {
    const { limit = 10, mailboxName = 'inbox', offset = 0 } = args as any;
    const emails = await client.getRecentEmails(limit, mailboxName, offset);
    return { content: [{ type: 'text', text: JSON.stringify(emails, null, 2) }] };
  }

• src/jmap-client.ts:620-643 (helper)

  The JMAP client method 'getRecentEmails' that resolves the mailbox by name, then calls queryEmails with the mailbox filter and desired properties.

  async getRecentEmails(
    limit: number = 10,
    mailboxName: string = 'inbox',
    offset: number = 0,
  ): Promise<PaginatedResult<any>> {
    // Find the specified mailbox (default to inbox)
    const mailboxes = await this.getMailboxes();
    const targetMailbox = mailboxes.find(mb => 
      mb.role === mailboxName.toLowerCase() || 
      mb.name.toLowerCase().includes(mailboxName.toLowerCase())
    );
    
    if (!targetMailbox) {
      throw new Error(`Could not find mailbox: ${mailboxName}`);
    }
  
    return this.queryEmails({
      filter: { inMailbox: targetMailbox.id },
      properties: ['id', 'subject', 'from', 'to', 'receivedAt', 'preview', 'hasAttachment', 'keywords'],
      limit,
      offset,
      defaultLimit: 10,
    });
  }

• src/tool-definitions.ts:403-431 (schema)

  The tool definition (schema) for 'get_recent_emails' including title, description, and input schema with limit, mailboxName, and offset properties.

  readTool(
    'get_recent_emails',
    'Get Recent Emails',
    description(
      'Get the newest email summaries from a Fastmail mailbox, defaulting to Inbox, in paginated form.',
      'Use when the user says "check email", "read my inbox", "show recent emails", or asks what just arrived.',
      'Returns items, total, has_more, and next_offset so the caller can keep paging only when needed.',
      'Use mailboxName to target another mailbox. Do not use when you need full message content for a known emailId (use get_email) or when you need filtered search results (use search_emails or advanced_search).',
    ),
    {
      type: 'object',
      properties: {
        limit: {
          ...numberLikeSchema,
          description: 'Number of recent emails to retrieve (default: 10, max: 50)',
          default: 10,
        },
        mailboxName: {
          type: 'string',
          description: 'Mailbox to search (default: inbox)',
          default: 'inbox',
        },
        offset: {
          ...numberLikeSchema,
          description: 'Zero-based offset for pagination. Use next_offset from the previous response to fetch the next page.',
          default: 0,
        },
      },
    },

• src/mcp-server.ts:160-162 (registration)

  Tool registration: TOOL_DEFINITIONS are passed to ListToolsRequestSchema handler, and the 'get_recent_emails' case is handled in the CallToolRequestSchema switch.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOL_DEFINITIONS }));
  
  server.setRequestHandler(CallToolRequestSchema, async (request) => {