mcp: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents working in this repository.

Project overview

sphinx-mcp is a Sphinx extension (src/sphinx_mcp/) that documents MCP (Model Context Protocol) servers — their tools, prompts, resources and resource templates — by connecting to a configured server via fastmcp and rendering its metadata as RST/docutils sections at build time.

• src/sphinx_mcp/common.py — Sphinx event handlers and MCP client setup.
• src/sphinx_mcp/mcpdocs.py — the MCPDocsDomain that renders collected tools/prompts/resources/resource templates into documentation sections.
• src/sphinx_mcp/utils.py — shared helpers.
• docs/ — the extension's own Sphinx documentation (built with itself, against example MCP servers under docs/conf.py's mcp_config).
• tests/ — pytest suite; tests/test_mcpdocs.py builds Sphinx docs against a local fixture MCP server (tests/servers/fixture_server.py) and asserts on the generated docutils tree.

Tooling

This project uses uv for dependency and environment management, and just as the task runner. Run just --list to see all recipes. Common ones:

just install-all   # install all dependency groups (dev, docs, test)
just format        # format code (ruff format, via pre-commit)
just lint           # run all pre-commit hooks against all files
just test            # run the pytest suite
just docs-html      # build the HTML docs
just docs-pdf        # build the PDF docs and copy to the project root

Prefer just recipes over ad hoc uv run ... invocations so behaviour stays consistent with CI and CONTRIBUTING.md.

Code style

• Formatting and linting are enforced by ruff (via the ruff-pre-commit hook pinned in .pre-commit-config.yaml) — run just format / just lint rather than hand-formatting.
• Follow the "no unnecessary comments" / "no speculative abstraction" conventions already used throughout src/sphinx_mcp/: prefer clear naming over comments, and only comment on non-obvious why, not what.
• Python 3.12+ only (see requires-python in pyproject.toml).