DSP Booking MCP Server

Instructions

Implementation Reference

• src/mcp/tools/input-schema.ts:71-82 (schema)

  Input schema definition for the create_cart tool using Zod for validation of session token and airBoundIds.

  export const CreateCartSchema = z.object({
    'session-token': z.string()
      .min(1)
      .describe('Required authentication token obtained from the initialize_booking_session step. This token maintains the booking session context and must be included to create a cart. The token is returned in the response headers of the initialization call (look for "Session-Token" header).'),
    requestBody: z.object({
      airBoundIds: z.array(AirBoundId)
        .min(1)
        .max(10)
        .describe('List of selected flight bound identifiers to add to the shopping cart. These IDs come from the flight search results returned by search_flights. Each ID represents a flight segment the customer wants to book. For a one-way trip, include 1 airBoundId. For a round-trip, include 2 airBoundIds (outbound + return). For multi-city trips, include multiple airBoundIds in the order of travel. IMPORTANT: Only use airBoundIds that were returned in the most recent search_flights response for this session.'),
    }).describe('Cart creation request containing the selected flight options the customer wants to purchase.'),
  }).describe('STEP 3: Create a shopping cart with selected flights. After searching for flights using search_flights, use this endpoint to add the customer\'s chosen flight options to a cart. The cart creation validates the selections and prepares them for booking. This step is required before proceeding to passenger details and payment.');

• src/mcp/tools/tools.ts:219-283 (registration)

  Registration of the create_cart tool in the MCP tools Map, defining name, description, input schema, HTTP endpoint (/carts POST), parameters, security, and custom response serializer.

  [
    'create_cart',
    {
      name: 'create_cart',
      description: `Create a shopping cart with selected flight options. PREREQUISITES: Must call 'initialize_booking_session' first, then 'search_flights' to get available flight options. This endpoint adds the customer's selected flights (identified by airBoundIds from search results) to a cart for booking. The cart validates selections, checks availability, and calculates final pricing. WORKFLOW POSITION: Step 3 of the booking flow (after initialization and search, before passenger details and payment). RESPONSE: Returns a cartId which is required for subsequent booking operations. IMPORTANT: All airBoundIds must come from the most recent search_flights response within the same session.`,
      inputSchema: CreateCartSchema,
      method: 'post',
      pathTemplate: '/carts',
      executionParameters: [
        {
          name: 'session-token',
          in: 'header',
        },
      ],
      requestBodyContentType: 'application/json',
      securityRequirements: [
        {
          HeaderApiToken: [],
          HeaderApimSubscriptionKey: [],
          HeaderApiVersion: [],
        },
      ],
      serializer: (response: AxiosResponse<{
        data: {
          cartId: string;
        };
        warnings?: Warning[];
        errors?: ErrorDetail[];
      }>): string => {
        const { data } = response;
  
        let output = 'CART CREATION RESULT\n';
        output += '='.repeat(80) + '\n\n';
  
        if (data.errors && data.errors.length > 0) {
          output += 'ERRORS:\n';
          data.errors.forEach((error) => {
            output += `  - [${error.code}] ${error.message}\n`;
            if (error.details) {
              output += `    Details: ${JSON.stringify(error.details)}\n`;
            }
          });
          return output;
        }
  
        output += `Cart created successfully!\n\n`;
        output += `Cart ID: ${data.data.cartId}\n\n`;
  
        if (data.warnings && data.warnings.length > 0) {
          output += 'WARNINGS:\n';
          data.warnings.forEach((warning) => {
            output += `  - [${warning.code}] ${warning.message}\n`;
          });
          output += '\n';
        }
  
        output += 'Next steps:\n';
        output += '  1. Add passenger details\n';
        output += '  2. Select ancillary services (baggage, meals, etc.)\n';
        output += '  3. Proceed to payment\n';
  
        return output;
      },
    },
  ],

• src/mcp/tools/types.d.ts:86-92 (schema)

  TypeScript interface defining the expected response structure for the create_cart tool.

  export interface CreateCartResponse {
    data: {
      cartId: string;
    };
    warnings?: Warning[];
    errors?: ErrorDetail[];
  }

• src/mcp/tools/tools.ts:241-282 (handler)

  Custom serializer function acting as the response handler for the create_cart tool, formatting API response into user-friendly output.

    serializer: (response: AxiosResponse<{
      data: {
        cartId: string;
      };
      warnings?: Warning[];
      errors?: ErrorDetail[];
    }>): string => {
      const { data } = response;
  
      let output = 'CART CREATION RESULT\n';
      output += '='.repeat(80) + '\n\n';
  
      if (data.errors && data.errors.length > 0) {
        output += 'ERRORS:\n';
        data.errors.forEach((error) => {
          output += `  - [${error.code}] ${error.message}\n`;
          if (error.details) {
            output += `    Details: ${JSON.stringify(error.details)}\n`;
          }
        });
        return output;
      }
  
      output += `Cart created successfully!\n\n`;
      output += `Cart ID: ${data.data.cartId}\n\n`;
  
      if (data.warnings && data.warnings.length > 0) {
        output += 'WARNINGS:\n';
        data.warnings.forEach((warning) => {
          output += `  - [${warning.code}] ${warning.message}\n`;
        });
        output += '\n';
      }
  
      output += 'Next steps:\n';
      output += '  1. Add passenger details\n';
      output += '  2. Select ancillary services (baggage, meals, etc.)\n';
      output += '  3. Proceed to payment\n';
  
      return output;
    },
  },