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

Implementation Plan: Mock GDS MCP Server

Branch: 001-mock-gds-server | Date: 2026-04-07 | Spec: spec.md Input: Feature specification from /specs/001-mock-gds-server/spec.md

Summary

Build a Mock MCP server that simulates Global Distribution System (GDS) functionality for testing and demonstration. The server exposes GDS operations (search, book, retrieve, cancel) as MCP tools, maintains stateful session management for multi-step workflows, uses Valkey for persistence, and packages as a Docker container for easy deployment.

Technical Context

Language/Version: Node.js 20 LTS (current stable)
Primary Dependencies: Minimal libraries - MCP SDK (@modelcontextprotocol/sdk), Valkey client (ioredis), Docker buildx for multi-platform builds
Storage: Valkey 8.0+ (Redis-compatible in-memory store with persistence)
Testing: Node.js native test runner (node:test) with minimal external dependencies
Target Platform: Docker containers (Linux amd64/arm64), deployable via docker-compose
Project Type: MCP server (daemon/service)
Performance Goals: <2s search response time, 50+ concurrent sessions, <500ms booking operations
Constraints: Minimal dependencies (avoid framework bloat), stateless server design (state in Valkey), zero external API calls
Scale/Scope: Single-server deployment, 1000+ bookings/session, 100+ concurrent MCP connections

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

Principle I: MCP Protocol Compliance (NON-NEGOTIABLE)

• ✅ Conformance: Using official @modelcontextprotocol/sdk ensures protocol compliance
• ✅ JSON-RPC 2.0: SDK handles message format automatically
• ✅ Capability Declaration: Server will declare tools during initialization handshake
• ✅ Error Codes: SDK provides standard MCP error structures

Status: PASS - Using official SDK guarantees protocol compliance

Principle II: Mock Data Realism

• ✅ GDS Structures: Will implement SABRE/Amadeus/Galileo-style response formats
• ✅ Valid IATA/ICAO Codes: Mock data will use real airport (JFK, LAX) and airline (AA, DL, UA) codes
• ✅ Realistic Pricing: Price ranges match market expectations ($200-$800 domestic flights)
• ✅ Real-World Constraints: Flight times, connection logic, geography respected
• ✅ Edge Cases: Will include sold-out flights, price variations, booking errors

Status: PASS - Spec requirements align with realism principle

Principle III: No Real Transactions (Safety Guarantee)

• ✅ Zero External Connections: No real GDS APIs called (all data from Valkey/memory)
• ✅ Simulated Operations: All bookings are mock data only
• ✅ TEST Markers: PNRs will have "TEST-" prefix (e.g., TEST-ABC123)
• ✅ Documentation: README will include prominent "FOR TESTING AND DEMO PURPOSES ONLY" disclaimer
• ✅ Configuration Safety: No production API key acceptance (configuration validates against production patterns)

Status: PASS - Safety guarantees built into design

Principle IV: Tool-Based Architecture

• ✅ MCP Tools: Each operation exposed as tool (searchFlights, bookFlight, retrieveBooking, cancelBooking, searchHotels, bookHotel, searchCars, bookCar)
• ✅ Self-Documenting: JSON schemas with descriptions and validation
• ✅ Independent Tools: Each tool callable without dependencies
• ✅ Deterministic: Same inputs produce same outputs (controlled randomness for demo variety)
• ✅ Resources: Will expose resources for session state inspection

Status: PASS - Tool-based design matches MCP patterns

Principle V: Stateful Session Management

• ✅ Session State: Valkey stores session data (searches, bookings, PNRs)
• ✅ Isolation: Session ID scopes all data (no cross-session leakage)
• ✅ Explicit Transitions: search → price → book → confirm flow tracked
• ✅ Cleanup: TTL on session keys for automatic expiry
• ✅ Optional Persistence: Valkey persistence configurable (RDB/AOF)

Status: PASS - Valkey provides robust session management

Principle VI: Observable and Debuggable

• ✅ Structured Logging: Pino logger with operation type, parameters, results
• ✅ Error Classification: Client errors (4xx), server errors (5xx), success (2xx)
• ✅ Configurable Verbosity: LOG_LEVEL env var (silent, error, warn, info, debug, trace)
• ✅ Actionable Errors: Clear messages ("Invalid airport code 'XYZ': must be 3-letter IATA")
• ✅ Inspection: MCP resource endpoints for session list, booking history

Status: PASS - Logging and observability built in

Overall Gate Status: ✅ PASS

All constitution principles satisfied. Proceed with Phase 0 research.

Project Structure

Documentation (this feature)

specs/[###-feature]/
├── plan.md              # This file (/speckit.plan command output)
├── research.md          # Phase 0 output (/speckit.plan command)
├── data-model.md        # Phase 1 output (/speckit.plan command)
├── quickstart.md        # Phase 1 output (/speckit.plan command)
├── contracts/           # Phase 1 output (/speckit.plan command)
└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)

Source Code (repository root)

src/
├── index.js              # MCP server entry point
├── server.js             # MCP server initialization
├── tools/                # MCP tool handlers
│   ├── flights.js        # searchFlights, bookFlight
│   ├── hotels.js         # searchHotels, bookHotel
│   ├── cars.js           # searchCars, bookCar
│   └── bookings.js       # retrieveBooking, cancelBooking
├── data/                 # Mock data generators
│   ├── airports.js       # IATA airport codes and data
│   ├── airlines.js       # Airline codes and metadata
│   ├── hotels.js         # Hotel chains and properties
│   ├── cars.js           # Car rental companies and types
│   └── pnr.js            # PNR generation utilities
├── session/              # Session management
│   ├── manager.js        # Session lifecycle
│   └── storage.js        # Valkey client wrapper
├── validation/           # Input validation
│   ├── schemas.js        # JSON schemas for tools
│   └── validators.js     # Validation logic
└── utils/                # Shared utilities
    ├── logger.js         # Pino logger setup
    └── errors.js         # Error handling

tests/
├── integration/          # End-to-end MCP workflows
│   ├── flight-booking.test.js
│   ├── multi-service.test.js
│   └── concurrent-sessions.test.js
├── unit/                 # Tool and data tests
│   ├── tools/
│   ├── data/
│   └── session/
└── fixtures/             # Test data

docker/
├── Dockerfile            # Multi-stage build
└── docker-bake.hcl       # Buildx bake configuration

docker-compose.yaml       # Local dev/test environment
package.json              # Dependencies and scripts
.dockerignore             # Build exclusions
README.md                 # Setup and usage

Structure Decision: Single project layout selected. The Mock GDS MCP server is a standalone daemon with embedded mock data. All source code in src/, organized by functional concerns (tools, data, session, validation, utils). Docker configuration in docker/ directory with multi-stage Dockerfile and buildx bake configuration. Tests organized by type (unit, integration) with shared fixtures.

Phase 0: Research & Technology Decisions (COMPLETED)

Status: ✅ Complete
Output: research.md
Completion Date: 2026-04-07

All technical unknowns resolved:

• MCP SDK selection (@modelcontextprotocol/sdk)
• Valkey client library (ioredis)
• Minimal dependencies strategy (Pino for logging, native test runner)
• Docker buildx bake configuration
• Mock data architecture (embedded, deterministic generation)
• PNR generation strategy (TEST- prefix with base32)
• Configuration management (environment variables)
• Testing strategy (3-tier: unit, integration, contract)

Phase 1: Design & Contracts (COMPLETED)

Status: ✅ Complete
Output: data-model.md, contracts/mcp-tools.md, quickstart.md
Completion Date: 2026-04-07

Design artifacts created:

• Data Model: 8 core entities (Session, Passenger, FlightSegment, HotelReservation, CarRental, PNR, SearchQuery, MockDataRecord)
• MCP Tool Contracts: 8 tools defined with JSON schemas (searchFlights, bookFlight, searchHotels, bookHotel, searchCars, bookCar, retrieveBooking, cancelBooking, listBookings)
• Quick Start Guide: Complete usage examples for all workflows
• Agent Context: Updated Copilot context with Node.js, MCP SDK, Valkey stack

Post-Design Constitution Re-Check

All principles remain satisfied after detailed design:

• ✅ Principle I (MCP Protocol): Tool schemas follow JSON-RPC 2.0 specification
• ✅ Principle II (Mock Data Realism): Data model includes valid IATA codes, realistic pricing tiers
• ✅ Principle III (No Real Transactions): PNR format enforces TEST- prefix, no external APIs
• ✅ Principle IV (Tool Architecture): 8 independent tools with clear schemas
• ✅ Principle V (Session Management): Valkey key naming and TTL strategy defined
• ✅ Principle VI (Observability): Error codes, logging strategy, inspection resources specified

Final Gate Status: ✅ PASS - Ready for task generation

Complexity Tracking

Fill ONLY if Constitution Check has violations that must be justified

Violation	Why Needed	Simpler Alternative Rejected Because
[e.g., 4th project]	[current need]	[why 3 projects insufficient]
[e.g., Repository pattern]	[specific problem]	[why direct DB access insufficient]