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:
194
specs/001-mock-gds-server/plan.md
Normal file
194
specs/001-mock-gds-server/plan.md
Normal file
@@ -0,0 +1,194 @@
|
||||
# Implementation Plan: Mock GDS MCP Server
|
||||
|
||||
**Branch**: `001-mock-gds-server` | **Date**: 2026-04-07 | **Spec**: [spec.md](./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)
|
||||
|
||||
```text
|
||||
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)
|
||||
|
||||
```text
|
||||
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] |
|
||||
Reference in New Issue
Block a user