DSP Booking MCP Server

Instructions

Implementation Reference

• src/mcp/tools/input-schema.ts:54-57 (schema)

  Zod input schema for the initialize_booking_session tool, which requires a requestBody matching FlightSearchBodySchema.

  export const InitializeBookingSchema = z.object({
    requestBody: FlightSearchBodySchema
      .describe('Initial flight search parameters to validate and establish booking session. This creates the foundation for subsequent flight searches.'),
  }).describe('REQUIRED FIRST STEP: Initialize booking session with airline system. Call this endpoint first to receive a session token, then use that token for actual flight searches. The session token will be returned in the response headers and must be captured for the next step.');

• src/mcp/tools/tools.ts:9-43 (registration)

  Definition and registration of the initialize_booking_session tool in the tools Map, specifying HTTP POST to '/initialisation', input schema, security requirements, and custom response serializer that extracts session token from headers.

  [
    'initialize_booking_session',
    {
      name: 'initialize_booking_session',
      description: 'Initialize a new booking session.',
      inputSchema: InitializeBookingSchema,
      method: 'post',
      pathTemplate: '/initialisation',
      executionParameters: [],
      requestBodyContentType: 'application/json',
      securityRequirements: [
        {
          HeaderApiToken: [],
          HeaderApimSubscriptionKey: [],
          HeaderApiVersion: [],
        },
      ],
      serializer: (response: AxiosResponse): string => {
        const sessionToken = response.headers['session-token'];
  
        let output = 'BOOKING SESSION INITIALIZED\n';
        output += '='.repeat(80) + '\n\n';
  
        if (sessionToken) {
          output += `Session Token: ${sessionToken}\n`;
          output += '(Token has been captured and will be used automatically for subsequent requests)\n\n';
        }
  
        output += 'Status: Ready\n';
        output += 'Next step: Use search_flights tool to find available flights\n';
  
        return output;
      },
    },
  ],

• src/mcp/tools/index.ts:9-51 (registration)

  MCP server registration of all tools from the tools map, handling list_tools and call_tool requests by retrieving tool definition and executing via executeApiTool.

  export function registerTools(server: Server): void {
    server.setRequestHandler(ListToolsRequestSchema, async () => {
      const toolsForClient: Tool[] = [];
      for (const def of Array.from(tools.values())) {
        toolsForClient.push({
          name: def.name,
          description: def.description,
          inputSchema: zodToMcpJsonSchema(def.inputSchema),
        });
      }
      return {
        tools: toolsForClient,
      };
    });
  
    server.setRequestHandler(
      CallToolRequestSchema,
      async (request: CallToolRequest): Promise<CallToolResult> => {
        const { name: toolName, arguments: toolArgs } = request.params;
        console.info(`Attempt to use custom tool: ${toolName}`);
  
        const toolDefinition = tools.get(toolName);
  
        if (!toolDefinition) {
          return {
            content: [
              {
                type: 'text',
                text: `Error: Unknown tool requested: ${toolName}`,
              },
            ],
          };
        }
  
        return await executeApiTool(
          toolName,
          toolDefinition,
          toolArgs ?? {},
          securitySchemes,
        );
      },
    );
  }

• src/mcp/tools/executor.ts:320-377 (handler)

  Generic handler function that executes API tools: validates inputs with schema, builds HTTP request from tool definition (method, path, params, body), applies security, makes axios call to booking API, and formats response using the tool's custom serializer.

  export async function executeApiTool(
    toolName: string,
    definition: McpToolDefinition,
    toolArgs: Record<string, unknown>,
    securityRequirementDictionaries: Record<string, SecurityScheme>,
  ): Promise<CallToolResult> {
    // 1. Validate arguments
    const validation = validateToolArguments(toolName, definition, toolArgs);
    if (!validation.success) {
      return validation.result;
    }
  
    try {
      // 2. Build request configuration
      const baseUrl = DSP_BOOKING_BASE_URL;
      const requestConfig = buildRequestConfig(definition, validation.data);
  
      // 3. Validate and apply security
      const securityContext = validateSecurity(definition, securityRequirementDictionaries);
      if (!securityContext.isValid) {
        console.warn(`Tool '${toolName}' ${securityContext.errorMessage}`);
        return {
          content: [
            {
              type: 'text',
              text: `Internal error during tool setup: '${toolName}'`,
            },
          ],
        };
      }
  
      if (securityContext.appliedSecurity) {
        await applySecurity(
          requestConfig.headers,
          securityContext.appliedSecurity,
          securityRequirementDictionaries,
        );
      }
  
      // 4. Create axios configuration
      const axiosConfig: AxiosRequestConfig = {
        method: definition.method.toUpperCase(),
        url: baseUrl + requestConfig.urlPath,
        params: requestConfig.queryParams,
        headers: requestConfig.headers,
        ...(requestConfig.requestBodyData !== undefined && { data: requestConfig.requestBodyData }),
      };
  
      // 5. Execute request
      console.info(`Executing tool "${toolName}": ${axiosConfig.method} ${axiosConfig.url}`);
      const response = await axios(axiosConfig);
  
      // 6. Format and return response - pass definition instead of toolName
      return formatResponse(response, definition);
    } catch (error) {
      return formatError(toolName, error);
    }
  }