rocannon: Instructions file for Codex

AGENTS.md

Instructions for AI coding agents working on this repo (Claude Code, Cursor, Bob, Codex, etc.). Humans, start with README.md.

What Rocannon is

An MCP server that registers every installed Ansible module as a typed MCP tool. One server, every module auto-discovered from ansible-doc at startup. There is no plugin abstraction: Ansible is the engine. Module discovery and tool registration live in src/rocannon/ansible.py; cross-cutting concerns (middleware, profile switching, save/replay) live in src/rocannon/server.py.

Setup

uv sync                     # all dev deps including the `ansible` extra
./tests/check.sh            # ruff format + ruff check + mypy + pytest

uv is required. Do not use pip, python -m venv, pipx, or conda. If uv is missing, install it (brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh) before doing anything else.

Quality gates

Every change must pass ./tests/check.sh before commit. The script runs four steps and exits on the first failure:

1. ruff format --check
2. ruff check
3. mypy --strict (against src/ and tests/)
4. pytest -x -q (unit tests only; integration suite is opt-in)

Auto-fix mode: ./tests/check.sh --fix (format and lint auto-fix; type and test errors still surface).

Mypy runs in strict mode. The codebase has targeted # type: ignore[<code>] comments where the static and dynamic type systems meet (FastMCP dynamic signatures, the rare untyped third-party import). Do not broaden these to bare # type: ignore and do not add new ignores without a specific error code.

Architecture

src/rocannon/
├── cli.py              Typer entrypoint. Subcommands: mcp serve|doctor,
│                       repl, run, doctor, doc, search, ls, playbook.
├── config.py           Pydantic Config model + YAML profile loader.
│                       Resolves profile-relative paths against the profile
│                       file's parent, not the process CWD.
├── profiles.py         .rocannon/profiles/ discovery, ProfileRegistry,
│                       RuntimeContext for runtime profile switching.
├── ansible.py          register_ansible_modules(): reads ansible-doc,
│                       registers one typed MCP tool per module, plus the
│                       rocannon://inventory and rocannon://module/<fqcn>
│                       resources.
├── server.py           create_server(). Wires middleware, calls
│                       register_ansible_modules, registers save_playbook +
│                       commit_session + rocannon_{list,current,use}_profile.
├── schema.py           ansible-doc parsing, module expansion, type mapping.
├── executor.py         ansible-runner Python-API wrapper + result parsing.
├── playbook.py         Playbook model {tool, args}. Persisted as YAML,
│                       loaded as MCP prompts.
├── repl.py             Operator REPL: same in-process MCP server, prompt
│                       toolkit shell, history, .save, optional .ai mode.
├── inventory.py        ansible-inventory subprocess wrapper.
├── history.py          In-memory ring buffer feeding save_playbook.
├── correlation.py      Request correlation IDs for the audit log.
└── redaction.py        Secrets redaction in audit records.