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>
This commit is contained in:
395
specs/001-mock-gds-server/contracts/mcp-tools.md
Normal file
395
specs/001-mock-gds-server/contracts/mcp-tools.md
Normal file
@@ -0,0 +1,395 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user