gds-mock-mcp/specs/001-mock-gds-server/spec.md

# 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"

## Clarifications

### Session 2026-04-07

- Q: Authentication implementation approach for remote connections → A: Don't implement authentication at this time (authentication deferred to future version, remote access will be open/unauthenticated for initial implementation)
- Q: Remote transport protocol selection → A: HTTP/2 with streaming (modern HTTP version with multiplexed streams for efficient concurrent request handling)
- Q: Session expiry and PNR lifecycle behavior → A: Global with TTL - PNRs are globally retrievable for a configurable time period (e.g., 1 hour) after creation, regardless of which session created them, allowing cross-session retrieval for testing flexibility
- Q: CORS policy configuration for web clients → A: Allow all origins (*) - Permissive wildcard CORS policy allowing any web client to connect, suitable for open development/testing environments
- Q: Rate limiting identifier without authentication → A: Client IP address - Track request rates per source IP address to prevent abuse while supporting unauthenticated access

### Session 2026-04-08

- Q: MCP transport protocol implementation - correct specification compliance → A: Implement MCP Streamable HTTP spec (HTTP/1.1 + SSE) - Follow the official MCP 2025-11-25 specification: HTTP/1.1 with Server-Sent Events, single /mcp endpoint with POST/GET/DELETE methods, event IDs for resumability, MCP-Protocol-Version header handling. Optional Nginx reverse proxy can upgrade to HTTP/2 for clients while proxying HTTP/1.1 to the application.
- Q: SSE connection management strategy for resource efficiency → A: Implement SSE polling pattern with connection closure - Server sends initial event with ID and empty data to prime reconnection, then MAY close the HTTP connection (not stream) after sending responses to reduce resource usage. Clients reconnect using Last-Event-ID header to resume. Server sends retry field before closing connections per MCP 2025-11-25 specification.
- Q: MCP-Protocol-Version header validation behavior → A: Require MCP-Protocol-Version header on all requests - Reject requests without the header with 400 Bad Request immediately, forcing all clients to send version explicitly with no backward compatibility fallback.

## 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 6 - Remote Access for Distributed Teams (Priority: P2)

A distributed development team needs to access the mock GDS server from different locations without setting up local instances. Remote developers connect to a centrally hosted mock server over the internet and execute booking workflows from their local development environments or web-based tools. The remote server handles multiple concurrent connections while maintaining session isolation.

**Why this priority**: Enables distributed teams to share a single mock server instance, reducing setup overhead and ensuring consistency across team members. Remote access supports cloud-based development environments, CI/CD pipelines running in the cloud, and web-based MCP clients that cannot use local stdio connections.

**Independent Test**: Can be tested by deploying the server to a public endpoint, connecting from multiple external clients, executing parallel booking workflows, and verifying that each session maintains proper isolation and receives correct responses. Confirms remote multi-user capability.

**Acceptance Scenarios**:

1. **Given** a remote MCP client, **When** the client connects to the server's public endpoint, **Then** the system establishes a connection and responds to MCP tool calls with the same functionality as stdio mode
2. **Given** web-based MCP clients from different origins, **When** clients connect to the server, **Then** the system allows connections and handles cross-origin requests appropriately
3. **Given** multiple remote clients connected simultaneously, **When** each executes independent booking workflows, **Then** the system maintains separate session contexts and prevents data leakage between remote sessions
4. **Given** monitoring tools checking server availability, **When** health check endpoints are queried, **Then** the system returns status information indicating operational readiness

---

### 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**: PNRs remain globally retrievable for a configurable time period (default 1 hour) after creation, regardless of which session created them or whether that session is still active. After the TTL expires, PNR retrieval returns "PNR not found or expired" error. This allows testing scenarios where bookings need to be retrieved across different sessions or after reconnection.

- **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).

### Remote Access Edge Cases

- **Rapid Connection Attempts**: What happens when a client attempts to connect 20 times in quick succession (potential connection retry loop)? System should handle connection rate limiting separately from request rate limiting, allowing reasonable reconnection attempts but preventing connection floods.

- **CORS Preflight Failures**: What happens when a web-based client from an allowed origin sends preflight OPTIONS requests? System must respond correctly to preflight requests to enable web clients to complete connection establishment.

- **Concurrent Requests from Same Remote Session**: What happens when a remote client sends 10 simultaneous booking requests in parallel using the same session? System should handle concurrent requests within a session appropriately - either process them in parallel maintaining consistency, or serialize them with appropriate queuing.

- **Health Check During High Load**: What happens when health check endpoint is queried while server is processing maximum concurrent connections? Health check should remain responsive (sub-second response) even under load, possibly with degraded status if resource utilization is high.

- **Rate Limit Edge Conditions**: What happens when a client makes exactly the limit number of requests at the boundary of a time window? System should handle edge cases consistently (requests at exactly the limit boundary should either all succeed or clearly fail with limit message, not random behavior).

- **Connection Cleanup on Client Crash**: What happens when a remote client crashes or loses network connectivity without gracefully closing the connection? System should detect inactive connections (no requests for N minutes) and clean up associated resources, freeing session data for garbage collection.

- **Invalid Origin Headers**: What happens when a remote client sends requests with spoofed or missing Origin headers? System should validate CORS based on request characteristics and either allow (if origin validation passes) or deny with appropriate CORS error.

## 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 PNR in format TEST-{6-character alphanumeric} (e.g., TEST-A1B2C3)

- **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 with configurable TTL (default 1 hour) - bookings remain globally retrievable from any session until TTL expiration, after which they return "not found" errors

- **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

### Remote Access Functional Requirements

- **FR-021**: System MUST support both stdio transport (for local MCP clients) and remote transport (for internet-accessible MCP clients), with transport mode configurable via environment settings

- **FR-022**: System MUST implement MCP Streamable HTTP transport per specification 2025-11-25: HTTP/1.1 with Server-Sent Events (SSE), single /mcp endpoint supporting POST (client-to-server messages with SSE response), GET (server-to-client message stream), and DELETE (session termination) methods, event IDs for stream resumability, MCP-Protocol-Version header handling, and MCP-Session-Id header for session management. The application uses HTTP/1.1 + SSE; optional reverse proxy (Nginx/Caddy) may upgrade client connections to HTTP/2 while proxying HTTP/1.1 to the application.

- **FR-022a**: System MUST implement SSE polling pattern for resource efficiency: send initial event with ID and empty data field to prime client reconnection, MAY close HTTP connection (not stream) after sending responses to reduce resource usage, clients reconnect using Last-Event-ID header to resume stream, and server MUST send retry field (milliseconds) before closing connections to guide client reconnection timing per MCP specification.

- **FR-022b**: System MUST require MCP-Protocol-Version header on all remote HTTP requests and reject requests without this header with HTTP 400 Bad Request and error message indicating the missing required header. System MUST validate the header value and support protocol version 2025-11-25, rejecting unsupported versions with HTTP 400 Bad Request.

- **FR-023**: System MAY implement authentication for remote connections in future versions, but initial implementation allows unauthenticated access suitable for trusted development/testing environments

- **FR-024**: System MUST support cross-origin requests from web-based MCP clients using permissive CORS policy (Allow-Origin: *), enabling browser-based tools and applications from any domain to connect to the remote server

- **FR-025**: System MUST enforce rate limiting on remote connections based on client IP address to prevent abuse, with configurable limits for requests per IP per time period (e.g., 100 requests per minute per IP address)

- **FR-026**: System MUST validate all input data from remote connections with security checks protecting against malicious payloads or injection attacks

- **FR-027**: System MUST provide health check endpoints that return operational status without requiring authentication, enabling monitoring systems and load balancers to verify server availability

- **FR-028**: System MUST maintain session isolation for remote clients identical to stdio sessions - each remote connection receives a unique session identifier with complete data isolation from other remote and local sessions

- **FR-029**: System MUST handle multiple concurrent remote client connections (minimum 50 simultaneous remote sessions) while maintaining performance and isolation guarantees

- **FR-030**: System MUST support secure connections using standard encryption for remote transport, protecting data in transit from client to server

- **FR-031**: System MUST log connection events and rate limit violations for remote connections in addition to standard operation logging, supporting operational monitoring

- **FR-032**: System MUST allow transport mode to be selected at server startup (stdio-only, remote-only, or both) to support different deployment scenarios from local development to public cloud hosting

- **FR-033**: System MUST gracefully handle remote client disconnections, cleaning up session resources and maintaining data consistency even when clients disconnect unexpectedly

- **FR-034**: System MUST provide the same MCP tool functionality and response format for both stdio and remote connections, ensuring consistent behavior regardless of transport method

### 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, expiration timestamp (creation time + configurable TTL, default 1 hour), list of all service segments (flights, hotels, cars), passenger/guest details, total price summary, payment method placeholder, and originating session identifier for logging purposes. PNRs are globally retrievable from any session until TTL expiration.

- **Session**: Represents an MCP connection session with unique session ID, creation timestamp, session expiry time, and isolation boundary ensuring no cross-session data access during operation. Sessions track which PNRs were created during the session for logging but do not restrict retrieval - PNRs remain accessible globally based on their own TTL.

- **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

- **Remote Connection**: Represents an active remote client connection with connection identifier, remote client IP address (for logging and rate limiting), connection start timestamp, last activity timestamp, transport protocol details, and associated session identifier

- **Rate Limit Record**: Tracks request rates per client IP address with IP address identifier, time window start, request count in current window, limit threshold, and next reset timestamp, enabling enforcement of usage limits to prevent abuse from individual source addresses

- **Health Status**: Represents server operational status with overall health state (healthy/degraded/unhealthy), active connection counts (stdio and remote), resource utilization metrics, uptime duration, and any current issues or warnings

## 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

### Remote Access Success Criteria

- **SC-011**: Remote developers can connect to a deployed server instance from any location with internet access and complete booking workflows with the same sub-30-second performance as local stdio connections

- **SC-012**: System handles 50 concurrent remote clients executing independent booking workflows simultaneously while maintaining sub-2-second response times and complete session isolation

- **SC-013**: Web-based MCP clients from different domains can successfully connect and execute MCP tools without CORS-related failures, enabling browser-based development tools

- **SC-014**: Rate limiting prevents abuse while allowing legitimate usage - clients can execute at least 100 requests per minute under normal operation, with clear error messages when limits are exceeded

- **SC-015**: Health check endpoints respond within 500ms and accurately reflect server operational status, enabling effective monitoring and automated health checks by deployment platforms

- **SC-016**: Distributed teams can share a single remote server instance without coordination overhead - each developer receives isolated session data regardless of how many other team members are connected

- **SC-017**: Remote connections survive typical network interruptions - temporary disconnections of under 30 seconds result in automatic reconnection without data loss or session corruption

- **SC-018**: Transport mode configuration is clear and validated at startup - invalid configuration (missing required settings, contradictory options) results in immediate startup failure with specific error messages indicating the configuration problem

## 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 metadata may be cleaned up, but PNRs created during that session remain retrievable globally based on their own TTL (default 1 hour from creation). This allows test scenarios to create bookings in one session and verify them in another.

- **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.

### Remote Access Assumptions

- **Network Environment**: Remote deployments assume standard cloud hosting environments with public internet access and no unusual firewall restrictions. Complex enterprise network configurations (corporate proxies, VPNs, non-standard ports) may require additional configuration.

- **MCP Transport Protocol**: System implements MCP Streamable HTTP transport per specification 2025-11-25 using HTTP/1.1 with Server-Sent Events (SSE). Optional reverse proxy (Nginx, Caddy) may be deployed to upgrade client connections to HTTP/2 while proxying HTTP/1.1 to the application, but this is an infrastructure enhancement not required for MCP specification compliance.

- **No Authentication (Initial Version)**: Initial implementation provides open/unauthenticated remote access suitable for trusted development/testing environments. Authentication may be added in future versions when deployment to less trusted environments is required.

- **Rate Limiting Scope**: Rate limits are designed to prevent abuse and accidental infinite loops, not to implement billing tiers or usage tracking. Limits are set at reasonable levels for development usage (hundreds of requests per minute) and may be adjusted based on deployment capacity. Rate limiting may be based on client IP address or connection identifier rather than authenticated credentials.

- **Security Posture**: Remote access is appropriate for development/testing environments with trusted team members on trusted networks. Initial version without authentication is NOT designed for public internet exposure to untrusted users. Deployment should use network-level access controls (firewalls, VPNs, private networks) to limit access to authorized development teams.

- **CORS Configuration**: CORS support uses permissive wildcard policy (Access-Control-Allow-Origin: *) allowing connections from any web origin. This maximizes development flexibility - web-based tools, browser extensions, and client applications from any domain can connect without CORS configuration. Suitable for trusted development/testing networks where access control is managed at the network layer (firewalls, VPNs) rather than application layer.

- **Connection Persistence**: Remote connections are expected to be relatively short-lived (minutes to hours, not days). Long-lived connections are supported but may be subject to cleanup on server restart or maintenance. No connection migration or state persistence across server restarts.

- **Health Check Usage**: Health checks are designed for basic operational monitoring and load balancer integration. They report simple up/down status and basic metrics, not comprehensive performance monitoring or detailed diagnostics.

- **Transport Coexistence**: When both stdio and remote transport are enabled simultaneously, they share the same mock data and session isolation boundaries but operate independently. No cross-transport session sharing or migration.

- **Deployment Model**: Remote deployments assume container-based hosting (Docker) or similar cloud deployment models. The system does not include installation packages, system service configurations, or traditional server deployment tooling.

- **SSL/TLS Termination**: Secure connections assume standard SSL/TLS termination at the server or load balancer level. The mock server itself focuses on application-level functionality and relies on deployment infrastructure for transport security.

- **Monitoring Integration**: Basic health endpoints are provided, but comprehensive monitoring (metrics collection, distributed tracing, log aggregation) relies on standard deployment infrastructure and observability tools, not custom mock server monitoring features.