verint.com/gds-mock-mcp
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: create constitution v1.0.0 for Mock GDS MCP server

Browse Source 
Initial constitution defining core principles:
- MCP protocol compliance (non-negotiable)
- Mock data realism with GDS standards
- Safety guarantees (no real transactions)
- Tool-based architecture
- Stateful session management
- Observability and debugging

Includes governance, amendment process, and compliance review requirements.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Peter Morton
2026-04-07 11:04:05 -05:00
parent ec40d91bec
commit 5d7d888c80
1 changed files with 142 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

177
.specify/memory/constitution.md
View File

@@ -1,50 +1,157 @@
# [PROJECT_NAME] Constitution
<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
<!--
Sync Impact Report:
Version: UNVERSIONED → 1.0.0
Change Type: Initial constitution creation (MAJOR)
Modified Principles: N/A (initial creation)
Added Sections:
- Core Principles (6 principles)
- Mock Data Safety (critical constraint)
- Development Standards (quality gates)
Templates Requiring Updates:
✅ spec-template.md - aligned with MCP protocol and mock data principles
✅ plan-template.md - constitution check section ready for validation
✅ tasks-template.md - task categorization supports MCP server development
Follow-up TODOs: None - all placeholders filled
-->
# Mock GDS MCP Server Constitution
## Core Principles
### [PRINCIPLE_1_NAME]
<!-- Example: I. Library-First -->
[PRINCIPLE_1_DESCRIPTION]
<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
### I. MCP Protocol Compliance (NON-NEGOTIABLE)
### [PRINCIPLE_2_NAME]
<!-- Example: II. CLI Interface -->
[PRINCIPLE_2_DESCRIPTION]
<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
**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
### [PRINCIPLE_3_NAME]
<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
[PRINCIPLE_3_DESCRIPTION]
<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
**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.
### [PRINCIPLE_4_NAME]
<!-- Example: IV. Integration Testing -->
[PRINCIPLE_4_DESCRIPTION]
<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
### II. Mock Data Realism
### [PRINCIPLE_5_NAME]
<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
[PRINCIPLE_5_DESCRIPTION]
<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
**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)
## [SECTION_2_NAME]
<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
**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.
[SECTION_2_CONTENT]
<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
### III. No Real Transactions (Safety Guarantee)
## [SECTION_3_NAME]
<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
**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)
[SECTION_3_CONTENT]
<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
**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
<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
[GOVERNANCE_RULES]
<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
### Amendment Process
**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
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