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:
219
specs/001-mock-gds-server/spec.md
Normal file
219
specs/001-mock-gds-server/spec.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# Feature Specification: Mock GDS MCP Server
|
||||
|
||||
**Feature Branch**: `001-mock-gds-server`
|
||||
**Created**: 2025-01-22
|
||||
**Status**: Draft
|
||||
**Input**: User description: "Build a Mock GDS MCP Server"
|
||||
|
||||
## User Scenarios & Testing *(mandatory)*
|
||||
|
||||
### User Story 1 - Flight Search and Booking (Priority: P1)
|
||||
|
||||
A developer building a travel application needs to test flight search and booking functionality. They initiate a flight search for a specific route and date, receive mock availability results with realistic pricing, select a flight, and complete a booking that returns a PNR (Passenger Name Record). The mock server provides immediate responses with consistent data, allowing the developer to verify their application's search UI, results display, booking form, and confirmation workflow.
|
||||
|
||||
**Why this priority**: Flight booking is the core GDS capability and most commonly used. Without this, the mock server delivers no meaningful value. This represents the essential MVP - a working flight search and book operation demonstrates the server is functional.
|
||||
|
||||
**Independent Test**: Can be fully tested by executing a flight search request through MCP, receiving mock flight results, submitting a booking request with passenger details, and receiving a valid PNR. Delivers immediate value for testing basic travel app workflows without requiring any other travel service types.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** a developer requests flights from JFK to LAX on a future date, **When** the search executes, **Then** the system returns 3-5 mock flight options with different times, airlines (using valid IATA codes like AA, DL, UA), realistic prices ($200-$800), and available seats
|
||||
2. **Given** search results are displayed, **When** the developer selects a specific flight and provides passenger details (name, contact info), **Then** the system creates a booking and returns a 6-character alphanumeric PNR (e.g., ABC123)
|
||||
3. **Given** a valid PNR exists, **When** the developer retrieves the booking, **Then** the system returns complete booking details including passenger information, flight details, booking status, and total price
|
||||
4. **Given** a confirmed booking with PNR, **When** the developer requests cancellation, **Then** the system marks the booking as cancelled and confirms the cancellation
|
||||
|
||||
---
|
||||
|
||||
### User Story 2 - Hotel Search and Multi-Service Bundling (Priority: P2)
|
||||
|
||||
A developer needs to test a travel package feature that combines flights and hotels. They search for hotels in the destination city for specific dates, view available properties with realistic amenities and pricing, add a hotel to an existing flight booking to create a multi-service itinerary, and retrieve the combined booking showing both flight and hotel details under one PNR.
|
||||
|
||||
**Why this priority**: Multi-service bookings are a common real-world scenario and differentiate GDS from simple flight APIs. This adds significant testing value but flight-only booking (P1) must work first. Can be developed after P1 is stable.
|
||||
|
||||
**Independent Test**: Can be tested by performing hotel searches independently, creating hotel-only bookings, and then testing the bundling workflow by adding hotels to existing flight bookings. Demonstrates the server can handle multiple service types and maintain complex booking state.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** a destination city code (e.g., LAX) and date range, **When** the developer searches for hotels, **Then** the system returns 5-10 mock properties with names, star ratings (2-5 stars), nightly rates ($80-$400), amenities lists, and availability
|
||||
2. **Given** an existing flight booking PNR, **When** the developer adds a hotel to the itinerary with check-in/check-out dates matching travel dates, **Then** the system updates the PNR to include both flight and hotel segments
|
||||
3. **Given** a multi-service booking, **When** the developer retrieves the PNR, **Then** the system returns a complete itinerary showing flight departure/arrival times, hotel check-in/check-out dates, total price breakdown by service type, and overall booking status
|
||||
|
||||
---
|
||||
|
||||
### User Story 3 - Car Rental and Complete Travel Package (Priority: P3)
|
||||
|
||||
A developer testing a comprehensive travel platform needs to create complete travel packages including flights, hotels, and car rentals. They search for rental cars at the destination airport, view available vehicle classes with daily rates, add a car rental to an existing multi-service booking, and manage a complete end-to-end travel itinerary under one PNR.
|
||||
|
||||
**Why this priority**: Car rentals complete the full travel package offering but are less commonly used than flights and hotels. This is valuable for comprehensive testing but not essential for initial MVP. Requires P1 and P2 to be working first.
|
||||
|
||||
**Independent Test**: Can be tested by performing car rental searches independently, creating car-only bookings, and integrating with flight+hotel bookings. Demonstrates full GDS capability coverage and complex multi-segment itinerary management.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** an airport code (e.g., LAX) and rental dates, **When** the developer searches for cars, **Then** the system returns 4-6 vehicle options (economy, compact, SUV, luxury) with daily rates ($35-$150), rental companies (using valid codes like Hertz, Avis, Enterprise), and availability
|
||||
2. **Given** an existing flight+hotel booking, **When** the developer adds a car rental with pickup/dropoff dates matching the travel period, **Then** the system updates the PNR to include flight, hotel, and car segments in chronological order
|
||||
3. **Given** a complete travel package, **When** the developer requests the itinerary, **Then** the system returns a structured view showing the full trip timeline: flight arrival, car pickup, hotel check-in, hotel check-out, car dropoff, and return flight
|
||||
|
||||
---
|
||||
|
||||
### User Story 4 - Session Management for Concurrent Testing (Priority: P2)
|
||||
|
||||
A QA team runs automated integration tests that execute multiple booking scenarios simultaneously. Each test session needs isolated booking state so concurrent tests don't interfere with each other. The mock server assigns unique session identifiers, maintains separate booking contexts per session, and ensures that searches, bookings, and retrievals in one session are completely isolated from other sessions.
|
||||
|
||||
**Why this priority**: Essential for realistic testing environments where multiple developers or automated tests run in parallel. Without session isolation, the mock server can only handle one user at a time, severely limiting its usefulness. This is critical for CI/CD integration.
|
||||
|
||||
**Independent Test**: Can be tested by initiating 5-10 concurrent MCP sessions, performing different booking operations in each (different routes, dates, passenger names), and verifying that retrieving a PNR in one session never returns data from another session. Confirms multi-user readiness.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** two developers start separate MCP sessions, **When** each performs a flight search with different criteria (different cities and dates), **Then** each receives results matching their search only, with no data leakage between sessions
|
||||
2. **Given** concurrent test automation runs 10 booking flows simultaneously, **When** each creates a booking with unique passenger names, **Then** the system generates 10 distinct PNRs and each can be retrieved with correct passenger information in its originating session
|
||||
3. **Given** a session with multiple active bookings, **When** the developer ends the session, **Then** the system maintains booking data for retrieval operations but prevents new modifications, allowing tests to verify final state
|
||||
|
||||
---
|
||||
|
||||
### User Story 5 - Realistic Test Data for Demonstrations (Priority: P3)
|
||||
|
||||
A sales team demonstrates travel booking software to potential customers. They need realistic, professional-looking mock data that appears authentic during presentations - valid airline names and codes, recognizable hotel chains, realistic pricing that matches market expectations, and diverse route options covering major travel markets (domestic US, transatlantic, Asia-Pacific). The mock server provides curated demonstration scenarios with high-quality data suitable for live demos.
|
||||
|
||||
**Why this priority**: Important for sales and training but not for development testing. Demo quality data enhances presentations but basic valid mock data (covered in P1) suffices for testing. This is a polish feature that improves adoption but isn't technically essential.
|
||||
|
||||
**Independent Test**: Can be tested by reviewing the mock data catalog, executing searches for major routes (NYC-LAX, NYC-LON, LAX-TYO), verifying that returned data includes recognizable brands (United, Marriott, Hertz), realistic prices (not $1 or $999999), and appropriate travel times/durations. Success means demo-ready output requiring no explanation or apology.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** a demo scenario for domestic US travel, **When** the sales person searches JFK to LAX, **Then** the system returns flights on American, Delta, and United with prices between $250-$600, realistic departure times (6am, 9am, 2pm, 5pm), and 5.5-6 hour flight durations
|
||||
2. **Given** a demo scenario for international travel, **When** the sales person searches NYC to London, **Then** the system returns overnight flights on major carriers (BA, AA, Virgin Atlantic) with prices $800-$1500, premium cabin options (economy, business, first class), and realistic 7-8 hour flight times
|
||||
3. **Given** a demo for hotel bookings, **When** searching major cities (New York, London, Tokyo), **Then** the system returns recognizable hotel brands (Marriott, Hilton, Hyatt) with appropriate pricing tiers ($150-$300 mid-range, $400-$800 luxury) and realistic amenities (WiFi, breakfast, gym, pool)
|
||||
|
||||
---
|
||||
|
||||
### Edge Cases
|
||||
|
||||
- **Empty Search Results**: What happens when a search request uses invalid codes (non-existent airport ZZZZ, impossible date like Feb 30)? System should return user-friendly error messages with specific reasons ("Airport code ZZZZ not recognized in mock database", "Invalid date format") rather than crashing.
|
||||
|
||||
- **Booking Modifications**: How does the system handle attempts to modify an already-cancelled booking? System must reject modification requests and return clear error indicating booking is in cancelled state and cannot be changed.
|
||||
|
||||
- **Session Expiry**: What happens when a developer retrieves a PNR after the session expires or in a different session? System should handle this gracefully - either maintain PNRs across sessions (making them globally retrievable) or return clear error "PNR not found in current session" if session-scoped.
|
||||
|
||||
- **Incomplete Booking Data**: How does system respond when booking request is missing required fields (no passenger name, no contact info)? System must validate required fields and return specific validation errors ("Missing required field: passenger.lastName", "Missing required field: contact.email").
|
||||
|
||||
- **Concurrent Booking Same Flight**: What happens when two sessions simultaneously book the last seat on a mock flight? System should handle this realistically - either both succeed (infinite mock inventory), or implement basic availability tracking and one booking succeeds while other receives "No availability" response.
|
||||
|
||||
- **Invalid PNR Format**: How does retrieval handle malformed PNRs (wrong length, invalid characters like "A@B!C1")? System should validate PNR format and return "Invalid PNR format" error rather than attempting database lookup.
|
||||
|
||||
- **Date Logic**: What happens when hotel check-out date is before check-in date, or car dropoff is before pickup? System must validate date sequences and return errors like "Check-out date must be after check-in date".
|
||||
|
||||
- **Multi-Service Timing Conflicts**: What happens when developer tries to add a hotel with dates that don't overlap with the flight dates in the same booking (flight on June 10, hotel June 20-22)? System should either warn about date mismatch or enforce logical consistency (hotel dates must overlap with travel period).
|
||||
|
||||
## Requirements *(mandatory)*
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
- **FR-001**: System MUST expose all travel search and booking capabilities as MCP tools with clearly defined input parameters and output schemas
|
||||
|
||||
- **FR-002**: System MUST support flight search with parameters: origin airport code (3-letter IATA), destination airport code, departure date, optional return date, and passenger count, returning a list of available flights with times, airlines, prices, and seat availability
|
||||
|
||||
- **FR-003**: System MUST support hotel search with parameters: city or airport code, check-in date, check-out date, and guest count, returning a list of available properties with names, ratings, nightly rates, total prices, and amenities
|
||||
|
||||
- **FR-004**: System MUST support car rental search with parameters: pickup location (airport code), pickup date/time, dropoff location, dropoff date/time, returning available vehicle classes with daily rates, rental companies, and vehicle specifications
|
||||
|
||||
- **FR-005**: System MUST support booking creation for any travel service (flight, hotel, car) with passenger/guest details, payment method placeholder (no actual processing), and return a unique 6-character alphanumeric PNR
|
||||
|
||||
- **FR-006**: System MUST allow multiple service types (flight + hotel + car) to be combined under a single PNR, maintaining all segment details in one unified booking record
|
||||
|
||||
- **FR-007**: System MUST support PNR retrieval by PNR code, returning complete booking details including all service segments, passenger information, prices, booking status, and creation timestamp
|
||||
|
||||
- **FR-008**: System MUST support booking cancellation by PNR, updating booking status to "cancelled" and returning cancellation confirmation with timestamp
|
||||
|
||||
- **FR-009**: System MUST maintain session isolation - each MCP session receives a unique session identifier and all bookings, searches, and state are isolated per session with no data leakage between concurrent sessions
|
||||
|
||||
- **FR-010**: System MUST include realistic mock data covering at minimum: 20+ major airports (US domestic and international hubs), 15+ airlines with valid IATA codes, 30+ hotels across major cities, and 5+ car rental companies
|
||||
|
||||
- **FR-011**: System MUST use only valid IATA/ICAO codes for airports and airlines - no fictional codes that would confuse users testing against real GDS documentation
|
||||
|
||||
- **FR-012**: System MUST clearly mark all data as mock/test data in responses (via metadata field like "data_source": "mock") to prevent any confusion with production systems
|
||||
|
||||
- **FR-013**: System MUST log all operations (search, book, retrieve, cancel) with timestamps, session IDs, and operation parameters to support debugging and test verification
|
||||
|
||||
- **FR-014**: System MUST return structured error responses with error codes and human-readable messages for all error conditions (invalid input, not found, validation failures)
|
||||
|
||||
- **FR-015**: System MUST support common GDS workflows including: price verification (confirm price before booking), seat/room availability checks, and multi-step booking processes (search → select → confirm)
|
||||
|
||||
- **FR-016**: System MUST generate realistic pricing based on route distance, service class, and time factors - no arbitrary prices like $1 or $999999
|
||||
|
||||
- **FR-017**: System MUST maintain booking state persistence within a session - bookings created during a session remain retrievable for the session duration
|
||||
|
||||
- **FR-018**: System MUST validate all input parameters (date formats YYYY-MM-DD, valid airport codes, positive passenger counts, logical date sequences) and reject invalid requests with specific error messages
|
||||
|
||||
- **FR-019**: System MUST support date/time handling for different time zones - flight times in local airport time, with UTC timestamps in responses for unambiguous time tracking
|
||||
|
||||
- **FR-020**: System MUST prevent any connection attempts to real booking systems, payment processors, or external GDS providers - all operations are fully self-contained mock operations
|
||||
|
||||
### Key Entities
|
||||
|
||||
- **Flight Segment**: Represents one flight leg with departure/arrival airports (IATA codes), departure/arrival times (local time + UTC), airline code, flight number, aircraft type, duration, available fare classes (economy/business/first), pricing per class, and seat availability counts
|
||||
|
||||
- **Hotel Reservation**: Represents accommodation booking with property name, location (city/address), star rating (1-5), check-in/check-out dates, room type (single/double/suite), nightly rate, total price, amenities list (WiFi, parking, breakfast, gym, pool), and cancellation policy
|
||||
|
||||
- **Car Rental**: Represents vehicle rental with pickup/dropoff locations (airport codes or city), pickup/dropoff date-times, rental company name and code, vehicle class (economy/compact/SUV/luxury), daily rate, total price, vehicle specifications (make/model/seats), and mileage policy (unlimited/limited)
|
||||
|
||||
- **Passenger/Guest**: Represents traveler information with full name (first/middle/last), date of birth, contact details (email, phone), loyalty program numbers (frequent flyer, hotel rewards), and special requests/needs (meal preferences, accessibility requirements, seat preferences)
|
||||
|
||||
- **PNR (Passenger Name Record)**: Core booking entity containing unique 6-character alphanumeric identifier, booking status (confirmed/cancelled/pending), creation timestamp, list of all service segments (flights, hotels, cars), passenger/guest details, total price summary, payment method placeholder, and session identifier
|
||||
|
||||
- **Session**: Represents an MCP connection session with unique session ID, creation timestamp, list of active PNRs created in this session, session expiry time, and isolation boundary ensuring no cross-session data access
|
||||
|
||||
- **Search Query**: Represents search parameters for any service type with service type (flight/hotel/car), origin/destination or location, dates, passenger/guest counts, optional filters (price range, star rating, airline preference), and returns matching results list
|
||||
|
||||
- **Mock Data Record**: Represents static test data entries for airports (code, city, country, timezone), airlines (code, name, country), hotels (name, location, rating, base rates), and rental companies (name, code, vehicle inventory), all marked with "mock: true" flag
|
||||
|
||||
## Success Criteria *(mandatory)*
|
||||
|
||||
### Measurable Outcomes
|
||||
|
||||
- **SC-001**: Developers can complete a full flight search and booking workflow (search → select → book → retrieve) in under 30 seconds with clear, understandable responses at each step
|
||||
|
||||
- **SC-002**: System handles 50 concurrent MCP sessions executing independent booking workflows simultaneously without response degradation, data corruption, or cross-session data leakage
|
||||
|
||||
- **SC-003**: All search operations (flight, hotel, car) return results in under 2 seconds with realistic data, enabling developers to build responsive user interfaces without waiting for slow mock responses
|
||||
|
||||
- **SC-004**: 100% of mock data uses valid IATA/ICAO codes and realistic pricing within market ranges (flights $100-$2000, hotels $50-$800/night, cars $25-$200/day) so developers don't need to question data authenticity
|
||||
|
||||
- **SC-005**: Integration tests using the mock server can verify end-to-end booking workflows without manual intervention, achieving 95% test automation coverage for travel app booking features
|
||||
|
||||
- **SC-006**: Sales demonstrations using the mock server require zero data explanation or disclaimer - all returned data appears professional and realistic enough to represent production-quality responses
|
||||
|
||||
- **SC-007**: New developers unfamiliar with GDS concepts can understand booking workflows by examining mock server responses within 15 minutes, using the clear response structure and realistic data as learning material
|
||||
|
||||
- **SC-008**: System logs provide sufficient detail that 90% of failed test cases can be debugged by examining logs alone, without needing to instrument additional debugging code
|
||||
|
||||
- **SC-009**: Zero production system connections or external API calls are made during any operation - 100% self-contained mock operation with no risk of accidental real bookings
|
||||
|
||||
- **SC-010**: Error messages enable developers to fix invalid requests on first attempt - each validation error specifies the exact field, expected format, and current invalid value
|
||||
|
||||
## Assumptions
|
||||
|
||||
- **Mock Data Scope**: The mock database will include major US airports, international hubs (London, Paris, Tokyo, Dubai), and popular tourist destinations, but will not attempt to be comprehensive (all 40,000+ airports worldwide). Coverage focuses on common testing scenarios.
|
||||
|
||||
- **Pricing Realism**: Mock prices will be realistic based on current market ranges but will not update for inflation, seasonal changes, or market conditions. Fixed pricing tiers will be maintained for consistency across tests and demos.
|
||||
|
||||
- **No Payment Processing**: All payment operations are placeholders - the system accepts payment method information (credit card type, last 4 digits) for workflow testing but performs no validation, tokenization, or processing of any kind.
|
||||
|
||||
- **Session Duration**: Sessions remain active for the duration of the MCP connection. When the connection closes, session data may be cleaned up. For persistent testing scenarios, developers should maintain their MCP connection or implement session rehydration in their test framework.
|
||||
|
||||
- **Infinite Inventory**: Mock availability is effectively unlimited - any search returns available results, and any booking succeeds (unless specifically testing error scenarios). No real inventory tracking or "sold out" conditions unless explicitly requested in test scenario.
|
||||
|
||||
- **Simplified Fare Rules**: Complex GDS fare rules (change fees, blackout dates, minimum stay requirements) are simplified or omitted. The focus is on basic booking workflows, not exhaustive fare rule validation.
|
||||
|
||||
- **English Language Only**: All mock data (airport names, hotel names, city names) will be in English with standard Latin character encoding (UTF-8). International character support is out of scope for v1.
|
||||
|
||||
- **No Real-Time Updates**: Prices and availability are static mock data. There are no real-time updates, dynamic pricing, or availability changes based on time or demand. Each search returns consistent results for the same parameters.
|
||||
|
||||
- **MCP Protocol Version**: System assumes MCP version 1.0 protocol standards for tool definition, parameter passing, and response formatting. Compatibility with future MCP versions may require updates.
|
||||
|
||||
- **Target Users**: Primary users are software developers and QA engineers familiar with travel industry concepts (IATA codes, PNR terminology). The system is not designed for end-user consumer access.
|
||||
|
||||
- **No Authentication**: Session isolation is based on MCP connection identity, not user authentication. There is no login system, user accounts, or permission management. All sessions have equal access to all mock operations.
|
||||
|
||||
- **Development Environment**: The mock server is designed for development, testing, and demonstration environments. It is not intended for production use, load testing beyond moderate concurrency (50-100 sessions), or as a production GDS proxy.
|
||||
Reference in New Issue
Block a user