Code Standards and Constitution
Relevant source files
The following files were used as context for generating this wiki page:
The Infrahub MCP Server project operates under a strict set of architectural principles, coding guidelines, and governance rules. These standards ensure that the server remains a reliable, secure, and interoperable bridge between AI assistants and critical infrastructure data. The project follows the Context Nuggets pattern, organizing documentation into focused files within the dev/ directory to facilitate both human and AI contribution efficiency.
This documentation defines the mandatory quality gates, technical requirements, and development workflows. It serves as the authoritative reference for all contributors, superseding informal practices and ad-hoc decisions. Developers must adhere to these standards to maintain the integrity of the MCP protocol compliance and the safety of infrastructure mutations.
Sources: dev/constitution.md:1-12, dev/adr/0001-context-nuggets-pattern.md:14-25, dev/README.md:1-15
Core Principles
The project identifies seven core principles that guide all design and implementation efforts.
I. MCP Protocol Compliance and SDK Integration
All tools, resources, and prompts must conform to the Model Context Protocol (MCP) specification. The server utilizes the infrahub-sdk exclusively for all Infrahub operations. Direct HTTP calls to the Infrahub API are forbidden to ensure consistent authentication, retry logic, and branch awareness.
Sources: dev/constitution.md:37-65, GPT.md:88-90
II. Branch-Safe Operations
The server enforces isolation for all write operations. By default, write tools target session branches rather than the main infrastructure branch. The ReadOnlyMiddleware blocks all tools tagged with "write" when the server operates in read-only mode.
Sources: dev/constitution.md:67-78, GPT.md:91
III. Type Safety and Explicit Contracts
The project mandates strict type safety using Python 3.13+ annotations and Pydantic models. All public interfaces must avoid the Any type, and configuration is validated at the system boundary during startup using pydantic-settings.
Sources: dev/constitution.md:80-92, dev/guidelines/python.md:14-22
IV. Security and Performance
Security is enforced at the boundaries. Credentials must never be hardcoded and are managed via environment variables. The server employs a 17-layer middleware stack composed once at startup to ensure high performance and strict observability.
Sources: dev/constitution.md:109-145, GPT.md:78-83
Development Workflow and Quality Gates
The development process follows a structured lifecycle: idea → ADR or spec → knowledge/ or guidelines/. Every contribution must pass specific quality gates before being merged into the stable branch.
Mandatory Quality Gates
- Dependencies:
uv syncensures the lock file is up to date. - Linting: Zero errors from
ruff,mypy, andpylint. - Tests: All tests must pass via
uv run pytest. - Documentation: Markdown linting via
rumdl.
Sources: dev/README.md:28-30, dev/constitution.md:151-160, GPT.md:33-45
Git and Branching Strategy
The project uses stable as the production branch. Feature branches use the feat/<name> convention. Force-pushing to stable is strictly prohibited. AI agents must identify themselves in all commits and PRs.
Sources: dev/constitution.md:162-171, GPT.md:95
The Documentation Ecosystem
The project organizes internal documentation by purpose to optimize AI context loading and human readability.
| Category | Path | Description |
|---|---|---|
| Constitution | dev/constitution.md | Core principles, quality gates, and governance. |
| ADRs | dev/adr/ | Architecture Decision Records explaining why choices were made. |
| Guidelines | dev/guidelines/ | Prescriptive rules on how code should be written. |
| Knowledge | dev/knowledge/ | Descriptive reference on how the system works. |
Sources: dev/README.md:17-25, dev/adr/0001-context-nuggets-pattern.md:34-40
Technical Standards
Python Implementation Guidelines
The project adheres to specific implementation patterns for the FastMCP framework and standard Python development.
The diagram shows the lifecycle from tool definition to execution, highlighting the mandatory tagging and middleware composition steps.
Sources: dev/guidelines/python.md:28-40, dev/constitution.md:37-43
Python Tooling and Configuration
The project uses pyproject.toml as the single source of truth for tool configuration.
| Tool | Usage | Key Configuration |
|---|---|---|
| Ruff | Formatting & Linting | Line length 150, double quotes, ALL rules selected. |
| Mypy | Type Checking | Strict mode, explicit error codes for ignores. |
| Pytest | Testing | asyncio_mode = "auto", unit/integration separation. |
| Towncrier | Changelog | Fragment-based assembly, stored in changelog/. |
| uv | Package Management | Lockfile maintenance, fast dependency sync. |
Sources: pyproject.toml:1-260, dev/guidelines/python.md:7-12
Middleware Stack Management
Middleware must be composed once at startup via configure_middleware(). It is forbidden to scatter middleware attachments across individual tool modules. This centralized approach ensures consistent application of logging, authentication, and rate-limiting policies.
Sources: GPT.md:78-83, dev/guidelines/python.md:33-35
Testing Discipline
Every feature requires corresponding tests, including happy paths and edge cases. Tests must mirror the source structure, where tests/test_feature.py corresponds to src/infrahub_mcp/feature.py.
- Atomic Tests: Each test must target exactly one behavior.
- Async Testing: Use
pytest-asynciofor all async tool implementations. - Mocking: Use
# type: ignore[attr-defined]for MCP result objects in tests to avoid brittle type assertions. - Integration: Integration tests are opt-in and marked with
@pytest.mark.integration, requiring a real Infrahub container viainfrahub-testcontainers.
Sources: dev/constitution.md:94-107, dev/guidelines/python.md:65-76, pyproject.toml:26-34
Summary
The Code Standards and Constitution define the Infrahub MCP Server as a high-integrity component. By mandating MCP protocol compliance, SDK-exclusive interaction, and branch-safe operations, the project protects infrastructure state. The rigorous quality gates—spanning type safety, linting, and comprehensive testing—ensure that every contribution meets production standards before reaching the stable branch.
Sources: dev/constitution.md:188-193, GPT.md:104-106