infrahub-mcp: Instructions file for Codex

Infrahub MCP Server

Connects AI assistants to Infrahub over the open MCP standard, so agents can read and (optionally) change infrastructure state through a consistent, audited, human-approved interface.

Tech Stack

• Runtime: Python 3.13, FastMCP, Infrahub SDK, Pydantic 2, Starlette
• Testing: pytest, pytest-asyncio
• Linting: ruff, mypy, pylint, yamllint
• Docs: Docusaurus (.mdx in docs/docs/), rumdl for markdown linting
• Package Manager: uv

File Structure

• src/infrahub_mcp/ — Library source code
  • tools/ — MCP tool implementations (gql, nodes, schema, session, write)
  • resources/ — MCP resources (branches, schema)
  • prompts/ — MCP prompt templates
  • middleware.py — Full middleware stack (logging, caching, auth, rate limiting, audit)
  • server.py — FastMCP server construction and ASGI app
  • config.py — ServerConfig via pydantic-settings
  • auth.py — OIDC provider factory and identity helpers
• tests/ — Test suite
• docs/ — User-facing documentation (Docusaurus)
• dev/ — Internal developer documentation — see dev/README.md
• .agents/ — AI agent commands and skills
• .specify/ — Speckit scaffolding (templates, workflows, extensions)

Commands

uv sync                          # Install dependencies

uv run pytest                    # Run full test suite

uv run invoke format             # Auto-format with ruff
uv run invoke lint               # All linters (yaml, ruff, pylint, mypy)
uv run invoke lint-ruff          # Ruff only
uv run invoke lint-pylint        # Pylint only
uv run invoke lint-mypy          # MyPy type checking only
uv run invoke lint-yaml          # Yamllint only

uv run rumdl check docs/docs/    # Check markdown linting
uv run rumdl fmt docs/docs/      # Auto-fix markdown formatting
cd docs && npm run build         # Test documentation build

uv run pre-commit run            # Ruff + rumdl on staged files, Mypy on src/
uv run pre-commit install        # Optional: run those same hooks on every commit