# Mock GDS MCP Server Constitution ## Core Principles ### I. MCP Protocol Compliance (NON-NEGOTIABLE) **Rules**: - All server implementations MUST conform to the Model Context Protocol specification - Every tool/resource MUST follow MCP's JSON-RPC 2.0 message format - Server capabilities MUST be declared correctly in initialization handshake - Error responses MUST use standard MCP error codes and structures **Rationale**: MCP protocol compliance ensures interoperability with any MCP-compatible client. Non-standard implementations break the ecosystem and defeat the purpose of using MCP. This is not negotiable because the entire value proposition depends on protocol conformance. ### II. Mock Data Realism **Rules**: - Mock data MUST reflect real GDS data structures (SABRE, Amadeus, Galileo formats) - Flight numbers, airport codes, and airline identifiers MUST use valid IATA/ICAO standards - Pricing and availability data MUST be realistic and internally consistent - Sample itineraries MUST respect real-world constraints (flight times, connections, geography) - Mock responses SHOULD include realistic edge cases (sold out flights, price changes, connection misses) **Rationale**: The mock server's purpose is testing and demonstration. Unrealistic data reduces testing value and creates false confidence. Users expect to test against data that resembles production GDS responses, including edge cases that expose bugs in client code. ### III. No Real Transactions (Safety Guarantee) **Rules**: - The server MUST NOT connect to any real GDS system or booking platform - All booking/reservation operations MUST be simulated only - Mock confirmations MUST include clear indicators that they are test data (e.g., `TEST-` prefix on PNRs) - Documentation MUST prominently state "FOR TESTING AND DEMO PURPOSES ONLY" - Configuration MUST prevent accidental production use (no production API keys accepted) **Rationale**: Safety is paramount. Even in test/demo scenarios, any possibility of real bookings creates liability, financial risk, and user confusion. Clear boundaries prevent catastrophic mistakes. ### IV. Tool-Based Architecture **Rules**: - Each GDS operation MUST be exposed as an MCP tool (search, book, retrieve, cancel) - Tool schemas MUST be self-documenting with clear descriptions and parameter validation - Tools MUST be independently testable without dependencies on other tools - Tool responses MUST be deterministic for the same inputs (unless explicitly testing randomness) - Resource exposure (e.g., cached itineraries) SHOULD supplement tools where read-only access patterns benefit clients **Rationale**: MCP's tool-based model enables AI agents and clients to discover and use capabilities programmatically. Well-designed tools with clear contracts reduce integration friction and enable reliable automation. ### V. Stateful Session Management **Rules**: - Server MUST maintain session state for ongoing booking workflows - Each session MUST isolate user contexts (separate PNRs, searches, bookings) - State transitions MUST be explicit and auditable (search → price → book → confirm) - Session cleanup MUST be automatic or configurable to prevent memory leaks - State persistence SHOULD be optional and configurable (in-memory vs. file-based) **Rationale**: Real GDS systems are stateful. Mock servers need to simulate multi-step workflows (search, then book, then modify). Statelessness would force clients to manage complex state externally, reducing the realism and utility of the mock. ### VI. Observable and Debuggable **Rules**: - All operations MUST log structured events (operation type, parameters, result summary) - Logs MUST distinguish between client errors (4xx-style), server errors (5xx-style), and successful operations - Logging verbosity MUST be configurable (silent, normal, verbose, trace) - Error messages MUST include actionable guidance (e.g., "Invalid airport code 'XYZ': must be 3-letter IATA code") - Mock server SHOULD support inspection endpoints (e.g., list all active sessions, view session history) **Rationale**: Developers using the mock server for testing need visibility into what's happening. Clear logs accelerate debugging. Structured logging enables automated testing and analysis. Helpful error messages reduce support burden. ## Mock Data Safety **Critical Constraints**: - MUST NOT accept real GDS credentials or API keys in any configuration - MUST reject requests containing production-like authentication tokens - MUST include "MOCK" or "TEST" markers in all response headers - MUST NOT store any real user PII (names, payment info, passport details) - MUST document data safety guarantees prominently in README and tool descriptions **Enforcement**: - Configuration validation at server startup fails if production patterns detected - Response serialization automatically injects safety markers - Code review checklist includes explicit mock data safety verification ## Development Standards ### Code Quality - All tools MUST have JSON schema validation for inputs and outputs - Public functions MUST include type hints (TypeScript/Python) or equivalent - Critical paths MUST include unit tests (especially tool handlers and state transitions) - Integration tests SHOULD cover end-to-end workflows (search → book → confirm) ### Documentation Requirements - Each MCP tool MUST document parameters, return types, and error conditions - README MUST include quickstart guide with example MCP client integration - API contracts (tool schemas) MUST be versioned and documented - Architecture decisions MUST be captured in ADR format when introducing new patterns ### Testing Philosophy - Unit tests focus on individual tool handlers and state management - Integration tests verify multi-step workflows - Contract tests ensure MCP protocol compliance - Mock data fixtures SHOULD cover common scenarios and known edge cases - Testing is RECOMMENDED but not mandatory (balance speed with safety based on project phase) ## Governance ### Amendment Process This constitution may be amended when: - MCP protocol evolves and requires updates - New GDS data requirements emerge from user feedback - Safety or compliance issues are identified Amendments require: 1. Documented rationale for the change 2. Impact analysis on existing tools and contracts 3. Version bump following semantic versioning (MAJOR for breaking principle changes, MINOR for additions, PATCH for clarifications) 4. Sync update to dependent templates (spec, plan, tasks) ### Compliance Review - All feature specifications MUST demonstrate alignment with Core Principles - Implementation plans MUST include constitution compliance checklist - Pull requests SHOULD reference relevant principles where applicable - Violations of NON-NEGOTIABLE principles require explicit justification and alternative safety measures ### Versioning Policy **Constitution versions follow semantic versioning**: - **MAJOR**: Removal or redefinition of core principles, backward-incompatible governance changes - **MINOR**: New principles added, material expansions to guidance, new sections - **PATCH**: Clarifications, wording improvements, typo fixes, non-semantic refinements ### Living Document This constitution is the authoritative source for project values and constraints. When conflicts arise between this document and other guidance, the constitution takes precedence. Practical implementation patterns should reference constitutional principles for legitimacy. **Version**: 1.0.0 | **Ratified**: 2026-04-07 | **Last Amended**: 2026-04-07