autobrr-mcp: Instructions file for Codex

AGENTS.md — autobrr-mcp

MCP server exposing autobrr's REST API (read + write) as tools so an LLM can read and manage a full autobrr instance: filters, indexers, IRC networks, RSS/Torznab feeds, download clients, actions, the release queue and its stats, import lists, notifications, API keys, proxies, config, health, and update checks. Uses FastMCP, uv for deps.

Exposed as 13 resource-scoped portmanteau tools, not one tool per endpoint — see "Portmanteau registration" below. autobrr's API has no OpenAPI spec, so the endpoint table is hand-written from autobrr's Go source rather than generated from a vendored spec.

Testing

• Offline suite: make test (or uv run pytest)
• Live integration (needs AUTOBRR_URL/AUTOBRR_API_KEY): make test-integration
  • GET endpoints run against the live instance.
  • POST/PUT/PATCH/DELETE only run when AUTOBRR_WRITE_TESTS=1 (safe create→update→delete cycles against a scratch filter and a scratch API key, then cleanup). Never point write tests at a production instance you care about.

Tool registry and the autobrr source

• _TOOL_REGISTRY in autobrr_mcp.py lists every JSON-producing autobrr endpoint. autobrr publishes no OpenAPI spec (docs/ holds only man pages), so this table is maintained by hand against autobrr's internal/http/<resource>.go handler Routes methods (currently pinned to develop HEAD). Each entry carries name/method/path/path-params/query-params/body-kind/doc.
• Excluded on purpose: /api/auth (session/OIDC, not usable over an API token), /api/events (SSE stream, not JSON), the inbound /api/webhook list-trigger routes (same job as /api/lists/refresh), and /api/logs/files/{logFile} (raw text download).
• Response caveats: healthz endpoints return text/plain ("OK") and /api/feeds/{id}/latest returns a raw string body — _req falls back to r.text for non-JSON 2xx bodies and returns {} for empty bodies, and dispatch is typed JSONVal | str accordingly. Keep that union widened; a too-narrow return type breaks structured-content validation at runtime.
• To refresh coverage after an autobrr update, diff internal/http/*.go Routes methods and update _TOOL_REGISTRY + _GROUPS by hand. Do not hand-edit generated per-endpoint functions; register_tools() regenerates them from the registry.
• Endpoint function naming (internal, not an MCP tool name): autobrr_<verb>_<resource> derived from path + method (e.g. autobrr_list_filters, autobrr_create_filter, autobrr_delete_releases, autobrr_retry_release_action).