Fastmail MCP Server

Instructions

Implementation Reference

• src/index.ts:1094-1112 (handler)

  MCP tool handler case for 'bulk_move': validates input parameters (emailIds array and targetMailboxId), initializes JMAP client, calls client.bulkMove(), and returns success response with count of moved emails.

  case 'bulk_move': {
    const { emailIds, targetMailboxId } = args as any;
    if (!emailIds || !Array.isArray(emailIds) || emailIds.length === 0) {
      throw new McpError(ErrorCode.InvalidParams, 'emailIds array is required and must not be empty');
    }
    if (!targetMailboxId) {
      throw new McpError(ErrorCode.InvalidParams, 'targetMailboxId is required');
    }
    const client = initializeClient();
    await client.bulkMove(emailIds, targetMailboxId);
    return {
      content: [
        {
          type: 'text',
          text: `${emailIds.length} emails moved successfully`,
        },
      ],
    };
  }

• src/index.ts:590-607 (registration)

  Registration of the 'bulk_move' tool in the tools array passed to server.setTools(), including name, description, and input schema defining emailIds (string array) and targetMailboxId (string).

    name: 'bulk_move',
    description: 'Move multiple emails to a mailbox',
    inputSchema: {
      type: 'object',
      properties: {
        emailIds: {
          type: 'array',
          items: { type: 'string' },
          description: 'Array of email IDs to move',
        },
        targetMailboxId: {
          type: 'string',
          description: 'ID of target mailbox',
        },
      },
      required: ['emailIds', 'targetMailboxId'],
    },
  },

• src/jmap-client.ts:698-725 (helper)

  JmapClient helper method bulkMove that constructs and sends Email/set JMAP request to update mailboxIds for multiple emailIds to the targetMailboxId, checks for notUpdated errors.

  async bulkMove(emailIds: string[], targetMailboxId: string): Promise<void> {
    const session = await this.getSession();
  
    const targetMailboxIds: Record<string, boolean> = {};
    targetMailboxIds[targetMailboxId] = true;
  
    const updates: Record<string, any> = {};
    emailIds.forEach(id => {
      updates[id] = { mailboxIds: targetMailboxIds };
    });
  
    const request: JmapRequest = {
      using: ['urn:ietf:params:jmap:core', 'urn:ietf:params:jmap:mail'],
      methodCalls: [
        ['Email/set', {
          accountId: session.accountId,
          update: updates
        }, 'bulkMove']
      ]
    };
  
    const response = await this.makeRequest(request);
    const result = response.methodResponses[0][1];
    
    if (result.notUpdated && Object.keys(result.notUpdated).length > 0) {
      throw new Error('Failed to move some emails.');
    }
  }