# MCP Tool Contracts: Mock GDS MCP Server

**Branch**: `001-mock-gds-server` | **Date**: 2026-04-07

## Overview

This document defines the MCP tool schemas exposed by the Mock GDS MCP server. All tools follow the MCP JSON-RPC 2.0 protocol and include comprehensive JSON Schema validation.

## Tool Categories

1. **Flight Operations**: searchFlights, bookFlight
2. **Hotel Operations**: searchHotels, bookHotel
3. **Car Rental Operations**: searchCars, bookCar
4. **Booking Management**: retrieveBooking, cancelBooking, listBookings

---

## Flight Operations

### searchFlights

Search for available flight options.

**Tool Name**: `searchFlights`

**Description**: Search for flights between two airports on a specific date. Returns mock flight options with realistic pricing, schedules, and availability.

**Input Schema**:
```json
{
  "type": "object",
  "properties": {
    "origin": {
      "type": "string",
      "pattern": "^[A-Z]{3}$",
      "description": "Origin airport IATA code (3 letters, e.g., 'JFK')"
    },
    "destination": {
      "type": "string",
      "pattern": "^[A-Z]{3}$",
      "description": "Destination airport IATA code (3 letters, e.g., 'LAX')"
    },
    "departureDate": {
      "type": "string",
      "format": "date",
      "description": "Departure date in ISO 8601 format (YYYY-MM-DD)"
    },
    "passengers": {
      "type": "object",
      "properties": {
        "adults": {
          "type": "integer",
          "minimum": 1,
          "maximum": 9,
          "default": 1
        },
        "children": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9,
          "default": 0
        },
        "infants": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9,
          "default": 0
        }
      },
      "required": ["adults"]
    },
    "cabin": {
      "type": "string",
      "enum": ["economy", "premium_economy", "business", "first"],
      "default": "economy"
    }
  },
  "required": ["origin", "destination", "departureDate"]
}
```

**Example Request**:
```json
{
  "origin": "JFK",
  "destination": "LAX",
  "departureDate": "2026-06-15",
  "passengers": { "adults": 2 },
  "cabin": "economy"
}
```

---

### bookFlight

Create a flight booking.

**Tool Name**: `bookFlight`

**Description**: Book one or more flight segments with passenger details. Creates a PNR (Passenger Name Record) with TEST- prefix.

**Input Schema**:
```json
{
  "type": "object",
  "properties": {
    "flightIds": {
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1,
      "description": "Array of flight IDs from search results"
    },
    "passengers": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": ["adult", "child", "infant"]
          },
          "firstName": { "type": "string", "minLength": 1, "maxLength": 50 },
          "lastName": { "type": "string", "minLength": 1, "maxLength": 50 },
          "dateOfBirth": { "type": "string", "format": "date" },
          "email": { "type": "string", "format": "email" },
          "phone": { "type": "string" },
          "frequentFlyerNumber": { "type": "string" }
        },
        "required": ["type", "firstName", "lastName"]
      }
    },
    "contactEmail": {
      "type": "string",
      "format": "email",
      "description": "Primary contact email"
    },
    "contactPhone": {
      "type": "string",
      "description": "Primary contact phone"
    }
  },
  "required": ["flightIds", "passengers"],
  "anyOf": [
    { "required": ["contactEmail"] },
    { "required": ["contactPhone"] }
  ]
}
```

---

## Hotel Operations

### searchHotels

**Tool Name**: `searchHotels`

**Description**: Search for hotel properties in a city with check-in/check-out dates.

**Input Schema**:
```json
{
  "type": "object",
  "properties": {
    "cityCode": {
      "type": "string",
      "pattern": "^[A-Z]{3}$",
      "description": "City IATA code (3 letters, e.g., 'LAX')"
    },
    "checkInDate": {
      "type": "string",
      "format": "date"
    },
    "checkOutDate": {
      "type": "string",
      "format": "date"
    },
    "guests": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "default": 1
    },
    "starRating": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5,
      "description": "Minimum star rating filter (optional)"
    }
  },
  "required": ["cityCode", "checkInDate", "checkOutDate"]
}
```

---

### bookHotel

**Tool Name**: `bookHotel`

**Description**: Book a hotel reservation. Can create a new PNR or add to an existing flight booking.

**Input Schema**:
```json
{
  "type": "object",
  "properties": {
    "hotelId": { "type": "string" },
    "existingPnr": {
      "type": "string",
      "pattern": "^TEST-[A-Z0-9]{6}$",
      "description": "Optional: Add hotel to existing booking"
    },
    "guests": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "firstName": { "type": "string" },
          "lastName": { "type": "string" },
          "email": { "type": "string", "format": "email" }
        },
        "required": ["firstName", "lastName"]
      }
    },
    "specialRequests": { "type": "string" }
  },
  "required": ["hotelId", "guests"]
}
```

---

## Car Rental Operations

### searchCars

**Tool Name**: `searchCars`

**Description**: Search for car rental options at an airport or city location.

**Input Schema**:
```json
{
  "type": "object",
  "properties": {
    "pickupLocationCode": {
      "type": "string",
      "pattern": "^[A-Z]{3}$"
    },
    "dropoffLocationCode": {
      "type": "string",
      "pattern": "^[A-Z]{3}$",
      "description": "Defaults to pickup location if not specified"
    },
    "pickupDate": {
      "type": "string",
      "format": "date-time"
    },
    "dropoffDate": {
      "type": "string",
      "format": "date-time"
    },
    "driverAge": {
      "type": "integer",
      "minimum": 21,
      "maximum": 99,
      "default": 30
    }
  },
  "required": ["pickupLocationCode", "pickupDate", "dropoffDate"]
}
```

---

### bookCar

**Tool Name**: `bookCar`

**Description**: Book a car rental. Can create a new PNR or add to an existing booking.

---

## Booking Management Operations

### retrieveBooking

**Tool Name**: `retrieveBooking`

**Description**: Fetch complete booking details including all segments.

**Input Schema**:
```json
{
  "type": "object",
  "properties": {
    "pnr": {
      "type": "string",
      "pattern": "^TEST-[A-Z0-9]{6}$"
    }
  },
  "required": ["pnr"]
}
```

---

### cancelBooking

**Tool Name**: `cancelBooking`

**Description**: Cancel a confirmed booking.

**Input Schema**:
```json
{
  "type": "object",
  "properties": {
    "pnr": {
      "type": "string",
      "pattern": "^TEST-[A-Z0-9]{6}$"
    },
    "reason": { "type": "string" }
  },
  "required": ["pnr"]
}
```

---

### listBookings

**Tool Name**: `listBookings`

**Description**: Retrieve a list of all PNRs created in the current MCP session.

**Input Schema**:
```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": ["all", "confirmed", "cancelled"],
      "default": "all"
    }
  }
}
```

---

## Error Responses

All tools return standard MCP errors:

- **-32602**: Invalid params (validation failure)
- **-32603**: Internal error (server error)
- **-32001**: Resource not found (invalid PNR, airport code, etc.)
- **-32002**: Business logic error (cancelled booking, date in past, etc.)

**Error Format**:
```json
{
  "code": -32602,
  "message": "Invalid airport code 'XYZ': must be a valid 3-letter IATA code",
  "data": {
    "field": "origin",
    "value": "XYZ"
  }
}
```

---

## MCP Resource Endpoints

- `gds://session/current` - Current session metadata
- `gds://session/bookings` - List of all bookings
- `gds://mock-data/airports` - Mock airport data
- `gds://mock-data/airlines` - Mock airline data

---

## Protocol Notes

- All tools use JSON-RPC 2.0 over stdio (default) or SSE
- Tool schemas validated before execution
- Timestamps use ISO 8601 format
- Prices in USD cents (integer)
- All PNRs prefixed with "TEST-" for safety