xer-mcp/.specify/memory/constitution.md

XER MCP Server Constitution

Core Principles

I. Test-First Development (NON-NEGOTIABLE)

Test-Driven Development is mandatory for all feature implementation. Tests MUST be written and verified to fail before any implementation code is written.

Requirements:

• Red-Green-Refactor cycle strictly enforced
• Tests MUST fail before implementation begins
• No feature is complete until tests pass
• Contract tests required for all MCP tool endpoints
• Integration tests required for XER parsing workflows

Rationale: TDD ensures correctness, documents behavior, and prevents regressions. For an MCP server handling complex XER data, test coverage is essential to maintain reliability.

II. Extensibility Architecture

The system MUST be designed for extension through well-defined interfaces and plugin points. Future capabilities MUST be addable without modifying core components.

Requirements:

• Core parsing logic separated from MCP transport layer
• XER table handlers MUST be pluggable
• New MCP tools MUST be addable without core changes
• Configuration MUST support extension points
• Abstract base classes MUST define extension contracts

Rationale: XER files contain many table types, and the MCP protocol evolves. Extensibility ensures the server can grow to handle new requirements without architectural rewrites.

III. MCP Protocol Compliance

All MCP server implementations MUST strictly comply with the Model Context Protocol specification. Non-compliant behavior is a blocking defect.

Requirements:

• All tool definitions MUST include complete JSON schemas
• Error responses MUST follow MCP error format
• Resource URIs MUST follow MCP conventions
• Transport layer MUST handle all MCP message types
• Capability negotiation MUST be implemented correctly

Rationale: MCP clients expect compliant servers. Protocol deviations cause integration failures and break the fundamental contract with AI assistants.

IV. XER Format Fidelity

XER file parsing MUST preserve data integrity and accurately represent Primavera P6 project data. No data loss or corruption is acceptable.

Requirements:

• All standard XER table types MUST be recognized
• Field mappings MUST match P6 export specifications
• Date/time values MUST preserve timezone information
• Numeric precision MUST be maintained
• Unknown tables MUST be preserved, not discarded

Rationale: XER files represent critical project schedules. Data loss or misinterpretation can have serious business consequences for construction and engineering projects.

V. Semantic Versioning

All releases MUST follow Semantic Versioning (MAJOR.MINOR.PATCH). Breaking changes MUST increment MAJOR version and include migration guidance.

Requirements:

• MAJOR: Breaking API changes, removed MCP tools, incompatible schema changes
• MINOR: New features, new MCP tools, backward-compatible additions
• PATCH: Bug fixes, documentation, non-functional improvements
• Breaking changes MUST be documented with migration paths
• Deprecations MUST be announced one MINOR version before removal

Rationale: Consumers of MCP servers need predictable upgrade paths. SemVer provides clear expectations about compatibility and change impact.

Technical Standards

Language: Python 3.14 Type Checking: Type hints MUST be used throughout; mypy or equivalent MUST pass Formatting: Code MUST conform to project linter/formatter (e.g., ruff, black) Dependencies: MUST be pinned to specific versions in requirements files Logging: Console logging for debugging; structured format preferred

Development Workflow

Branch Strategy: Feature branches MUST be created for all non-trivial changes Code Review: All changes MUST be reviewed before merge to main Testing Gates:

• Unit tests MUST pass
• Contract tests MUST pass for MCP tools
• Integration tests MUST pass for XER parsing

Documentation:

• Public APIs MUST have docstrings
• MCP tools MUST have usage examples
• Breaking changes MUST update migration docs

Governance

This constitution supersedes all other development practices for the XER MCP Server project. When conflicts arise, this document takes precedence.

Amendment Process:

1. Proposed amendments MUST be documented with rationale
2. Amendments MUST be reviewed and approved
3. Version MUST be incremented according to change type:
   • MAJOR: Principle removal or fundamental redefinition
   • MINOR: New principle or significant expansion
   • PATCH: Clarifications and wording improvements
4. All dependent templates MUST be reviewed for consistency

Compliance Review:

• All PRs MUST verify compliance with core principles
• TDD violations are blocking defects
• MCP protocol deviations are blocking defects
• Constitution Check in plan.md MUST be completed before implementation

Version: 1.0.1 | Ratified: 2026-01-06 | Last Amended: 2026-01-06