fixing jsonSchema validation by using zod

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

@@ -5,6 +5,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)
@@ -72,6 +88,23 @@ A QA team runs automated integration tests that execute multiple booking scenari
 
 ---
 
+### 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.
@@ -94,7 +127,7 @@ A sales team demonstrates travel booking software to potential customers. They n
 
 - **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.
+- **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").
 
@@ -106,6 +139,22 @@ A sales team demonstrates travel booking software to potential customers. They n
 
 - **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
@@ -142,7 +191,7 @@ A sales team demonstrates travel booking software to potential customers. They n
 
 - **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-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
 
@@ -150,6 +199,40 @@ A sales team demonstrates travel booking software to potential customers. They n
 
 - **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
@@ -160,14 +243,20 @@ A sales team demonstrates travel booking software to potential customers. They n
 
 - **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
+- **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, list of active PNRs created in this session, session expiry time, and isolation boundary ensuring no cross-session data access
+- **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
@@ -192,6 +281,24 @@ A sales team demonstrates travel booking software to potential customers. They n
 
 - **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.
@@ -200,7 +307,7 @@ A sales team demonstrates travel booking software to potential customers. They n
 
 - **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.
+- **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.
 
@@ -217,3 +324,29 @@ A sales team demonstrates travel booking software to potential customers. They n
 - **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.