verint.com/gds-mock-mcp
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
35a98c6d4bd5f0173729cf1295621cd9b46a4dae
gds-mock-mcp/specs/001-mock-gds-server/contracts/mcp-tools.md
Peter.Morton 35a98c6d4b feat: complete implementation plan for Mock GDS MCP server 
Phase 0 (Research):
- Selected MCP SDK (@modelcontextprotocol/sdk) for protocol compliance
- Chose ioredis for Valkey client (Redis-compatible)
- Minimal dependencies: Pino logging, native test runner
- Docker buildx bake for multi-platform builds
- Embedded mock data with deterministic generation
- PNR format: TEST-{BASE32} for safety

Phase 1 (Design):
- Data model: 8 core entities (Session, PNR, FlightSegment, etc.)
- MCP contracts: 8 tools with JSON schemas
- Quickstart guide with complete workflow examples
- Constitution compliance verified

Technical stack:
- Node.js 20 LTS
- Valkey 8.0+ for persistence
- Docker containers (amd64/arm64)
- Performance: <2s search, 50+ concurrent sessions

Ready for task generation with /speckit.tasks

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-04-07 11:27:53 -05:00

8.1 KiB
Raw Blame History

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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
Reference in New Issue View Git Blame Copy Permalink