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

Technical Research: Mock GDS MCP Server

Branch: 001-mock-gds-server | Date: 2026-04-07

Phase 0: Technology Decisions

Decision 1: MCP SDK and Protocol Implementation

Decision: Use @modelcontextprotocol/sdk official Node.js SDK

Rationale:

• Official SDK ensures MCP protocol compliance (Constitution Principle I)
• Handles JSON-RPC 2.0 message format automatically
• Provides TypeScript types for type safety
• Active maintenance by Anthropic
• Simplified tool registration and schema management

Alternatives Considered:

• Custom MCP implementation: Rejected - high risk of protocol non-compliance, significant development effort
• Python MCP SDK: Rejected - requirement specifies Node.js with minimal dependencies

Implementation Notes:

• SDK provides Server class for initialization
• Tool handlers registered via server.setRequestHandler
• Automatic capability negotiation during handshake
• Built-in error handling with standard MCP error codes

Decision 2: Valkey Client Library

Decision: Use ioredis v5.x as Valkey client

Rationale:

• Valkey is Redis protocol-compatible, ioredis is the most mature Node.js Redis client
• Full support for Redis/Valkey commands (GET, SET, HSET, EXPIRE, etc.)
• Connection pooling and automatic reconnection
• Cluster and sentinel support (for future scaling)
• Pipeline and transaction support
• Active maintenance and TypeScript support

Alternatives Considered:

• node-redis: Rejected - ioredis has better TypeScript support and more features
• Custom Valkey protocol: Rejected - unnecessarily complex
• No persistence (memory-only): Rejected - requirement specifies Valkey for persistence

Implementation Notes:

• Use Redis-compatible commands only (avoid Redis-specific extensions)
• Session data stored with TTL (e.g., 1 hour default)
• Key naming: gds:session:{sessionId}:bookings:{pnr}
• Use hash structures for complex objects (bookings, searches)
• Enable Valkey RDB/AOF persistence via docker-compose configuration

Decision 3: Minimal Dependencies Strategy

Decision: Limit external dependencies to essentials only

Core Dependencies (production):

1. @modelcontextprotocol/sdk - MCP protocol (required)
2. ioredis - Valkey client (required for persistence)
3. pino - Structured logging (minimal, fast, constitution requires observability)

Development Dependencies:

• Node.js native test runner (node:test) - no jest/mocha overhead
• c8 - code coverage (lightweight)

Rationale:

• Aligns with "minimal libraries" requirement
• Reduces attack surface and dependency maintenance burden
• Faster container builds and smaller images
• Native Node.js features (test runner, assert) are mature and sufficient

Explicitly Avoided:

• ❌ Express/Fastify/Koa - MCP uses stdio/SSE, no HTTP server needed
• ❌ TypeORM/Prisma - direct Valkey commands sufficient for key-value storage
• ❌ Jest/Mocha - native test runner adequate
• ❌ Lodash/Ramda - native JS methods sufficient
• ❌ Moment.js/date-fns - native Date and Temporal API (when available)

Decision 4: Docker Build Strategy

Decision: Use Docker Buildx with docker-bake.hcl for multi-platform builds

Rationale:

• docker buildx bake supports complex build configurations
• Multi-platform builds (linux/amd64, linux/arm64) in single command
• Build matrix for multiple tags (latest, version, dev)
• Better caching and parallelization than traditional Dockerfile
• Aligns with requirement specification

Build Configuration:

# docker-bake.hcl
target "default" {
  dockerfile = "docker/Dockerfile"
  tags = ["gds-mock-mcp:latest"]
  platforms = ["linux/amd64", "linux/arm64"]
  cache-from = ["type=registry,ref=gds-mock-mcp:buildcache"]
  cache-to = ["type=registry,ref=gds-mock-mcp:buildcache,mode=max"]
}

Dockerfile Strategy:

• Multi-stage build: builder → production
• Builder stage: install dependencies, run tests
• Production stage: copy only production deps and source
• Use Node.js 20 Alpine for minimal image size
• Non-root user for security
• Health check via MCP ping or valkey connection test

Alternatives Considered:

• Traditional Dockerfile only: Rejected - buildx bake provides better DX and multi-platform support
• Docker Compose build: Rejected - less flexible than buildx, no multi-platform
• Podman: Rejected - Docker specified in requirements

Decision 5: Mock Data Architecture

Decision: Embed realistic GDS data in JavaScript modules with deterministic generation

Data Structure:

• Airports: ~100 major airports with IATA codes (JFK, LAX, ORD, etc.)
• Airlines: Major carriers with IATA codes (AA, DL, UA, BA, etc.)
• Hotels: 50+ chains/properties across major cities
• Car Rentals: Major companies (Hertz, Avis, Enterprise) with vehicle types
• Flight Routes: Pre-defined routes with realistic times and prices
• Pricing Tiers: Economy ($200-$600 domestic), Business ($800-$2000), First Class ($2500+)

Generation Strategy:

• Deterministic: Same search inputs produce same results (for testing reproducibility)
• Controlled Randomness: Optional seed parameter for demo variety
• Rule-Based Pricing: Distance-based pricing with time-of-day adjustments
• Availability Simulation: Random sold-out scenarios (10% of flights)

Rationale:

• Embedded data = no external dependencies (fast startup)
• Deterministic = reliable integration tests
• Realistic codes = constitution compliance (Principle II)
• Pre-computed routes = sub-2s response times

Alternatives Considered:

• External API (Skyscanner, etc.): Rejected - violates "no external connections" (Constitution Principle III)
• Database seeding: Rejected - overhead, embedded data sufficient for mock scope
• Fully random data: Rejected - testing requires deterministic outputs

Decision 6: Testing Strategy

Decision: Use Node.js native test runner with three-tier test structure

Test Tiers:

1. Unit Tests: Individual tool handlers, data generators, validators

   • Fast (<100ms total), isolated, no external dependencies
   • Mock Valkey client for session tests

2. Integration Tests: Full MCP workflows with real Valkey (test container)

   • End-to-end booking flows (search → book → retrieve → cancel)
   • Multi-service workflows (flight + hotel + car)
   • Concurrent session isolation tests
   • Use docker-compose test profile for Valkey

3. Contract Tests: MCP protocol compliance validation

   • Verify JSON-RPC 2.0 format
   • Tool schema validation
   • Error response structure

Test Execution:

npm test              # All tests
npm run test:unit     # Fast unit tests only
npm run test:integration  # Requires Valkey
npm run test:coverage     # Coverage report with c8

Rationale:

• Native test runner = minimal dependencies
• Three tiers = appropriate test coverage
• Docker test containers = realistic integration tests
• Fast unit tests = quick feedback loop

Decision 7: Configuration Management

Decision: Environment variables with secure defaults

Configuration Variables:

# MCP Server
MCP_TRANSPORT=stdio           # stdio or sse
MCP_SESSION_TIMEOUT=3600      # 1 hour session TTL

# Valkey
VALKEY_HOST=localhost
VALKEY_PORT=6379
VALKEY_PASSWORD=                # Empty for dev, required for prod
VALKEY_DB=0
VALKEY_KEY_PREFIX=gds:

# Logging
LOG_LEVEL=info                  # silent, error, warn, info, debug, trace
LOG_PRETTY=false                # Pretty print for dev

# Mock Data
MOCK_DATA_SEED=fixed            # fixed or random
MOCK_RESPONSE_DELAY=0           # Artificial delay (ms) for demo purposes

Security Defaults:

• No production credentials in code or .env.example
• Configuration validation on startup
• Reject production-like patterns (Constitution Principle III)

Rationale:

• Standard practice for containerized apps
• Easy to override in docker-compose
• Secure defaults prevent accidents

Decision 8: PNR Generation Strategy

Decision: Deterministic PNR generation with TEST prefix

Format: TEST-{BASE32} where BASE32 is 6 characters

Example: TEST-A1B2C3

Generation Algorithm:

1. Generate session-scoped sequence number
2. Combine with booking timestamp
3. Hash with SHA-256
4. Take first 6 characters of base32 encoding
5. Prefix with "TEST-"

Rationale:

• "TEST-" prefix = clear mock indicator (Constitution Principle III)
• Base32 = human-readable, unambiguous (no 0/O, 1/I confusion)
• 6 characters = 1 billion unique combinations (sufficient for testing)
• Deterministic = reproducible test scenarios
• Session-scoped = prevents conflicts

Alternatives Considered:

• Random UUID: Rejected - too long, not human-friendly
• Sequential numbers: Rejected - predictable, not realistic
• No prefix: Rejected - violates safety requirement

Technology Stack Summary

Component	Technology	Version	Rationale
Runtime	Node.js	20 LTS	Current stable, long-term support
MCP SDK	@modelcontextprotocol/sdk	Latest	Official SDK, protocol compliance
Persistence	Valkey	8.0+	Redis-compatible, requirement specified
Valkey Client	ioredis	5.x	Mature, feature-rich, TypeScript support
Logging	Pino	Latest	Fast, structured, minimal overhead
Testing	node:test	Built-in	Native, zero dependencies
Coverage	c8	Latest	V8 coverage, lightweight
Container	Docker	24+	Buildx support, multi-platform
Orchestration	docker-compose	2.x	Development environment

Performance Considerations

Expected Performance Profile

• Search Operations: <500ms (data generation + Valkey lookup)
• Booking Operations: <200ms (validation + Valkey write)
• Retrieval Operations: <100ms (Valkey read)
• Concurrent Sessions: 50+ (limited by Valkey and Node.js event loop)
• Memory Footprint: <100MB per server instance
• Container Image Size: <50MB (Alpine-based)

Optimization Strategies

1. Caching: Pre-compute common search results in Valkey
2. Connection Pooling: ioredis maintains persistent Valkey connections
3. Lazy Loading: Load mock data modules on-demand
4. Batch Operations: Use Valkey pipelines for multi-key operations

Security Considerations

Mock Data Safety

• ✅ No real API keys or credentials stored
• ✅ Configuration validation rejects production patterns
• ✅ All PNRs prefixed with "TEST-"
• ✅ No external network calls (except to local Valkey)
• ✅ Non-root container user

Docker Security

• Use official Node.js Alpine base images
• Run as non-root user (node:node)
• Minimal attack surface (no shell, no dev tools in prod image)
• Regular security updates via base image updates

Open Questions (Resolved)

All technical unknowns from initial planning have been resolved through research above. No blocking issues identified.

Next Steps

Proceed to Phase 1: Design & Contracts

• Create data-model.md (data structures)
• Define MCP tool contracts in contracts/
• Generate quickstart.md with usage examples
• Update agent context with technology decisions