sonarr-mcp: Instructions file for Codex

AGENTS.md — sonarr-mcp

MCP server exposing Sonarr's v3 REST API (OpenAPI 3.0.0) as tools so an LLM can read and manage a Sonarr instance: series, episodes, episode files, queue, history, indexers, import lists, custom formats, tags, commands, system status, and more. Full surface — reads and writes. Uses FastMCP, uv for deps.

Exposed as 15 resource-scoped portmanteau tools, not one tool per endpoint — see "Tool registry and the spec" below. A prior version registered all 223 endpoints individually; that blew the MCP context budget (~223 tools × ~250 tokens ≈ 56k tokens just for this one server) and has been retired.

Testing

• Offline suite: make test (or uv run pytest)
• Live integration (needs SONARR_URL/SONARR_API_KEY): make test-integration
  • GET endpoints run against the live instance.
  • POST/PUT/DELETE only run when SONARR_WRITE_TESTS=1 (safe create→update→delete cycles against a scratch tag, then cleanup). Never point write tests at a production library.

Tool registry and the spec

• _TOOL_REGISTRY in sonarr_mcp.py is generated from the vendored spec at tests/data/sonarr_openapi.json (pinned to Sonarr develop HEAD e7caf8fbaa8e7b9dff48ce26b476ebcad7fd7324). It lists every JSON-producing endpoint under /api/v3 plus GET /ping.
• Excluded on purpose: /login, /logout, /ping (kept), static web routes, the .ics calendar feed, and binary/text endpoints (media covers, raw log files) — _req JSON-decodes every response.
• To add a tool or refresh coverage, regenerate the registry from a newer openapi.json (same algorithm as the authoring script) and re-run the tests. Do not hand-edit the registry.
• Endpoint function naming (internal, no longer an MCP tool name): sonarr_<verb>_<resource> derived from path + method (e.g. sonarr_list_series, sonarr_add_series, sonarr_delete_series, sonarr_run_command). Overrides for flagship/action endpoints live in the authoring script.

Portmanteau registration — do not go back to one tool per endpoint

• _GROUPS buckets every _TOOL_REGISTRY name into one of 15 resource groups (sonarr_media_library, sonarr_queue, sonarr_config, ...). register_tools() registers exactly one MCP tool per group via _register_group, which wraps the group's endpoint functions in a single dispatch(operation, arguments) closure. The endpoint functions themselves are unchanged — they're plain callables looked up by name, not separately-registered tools.
• operation is typed Literal[<the group's endpoint names>], so FastMCP/pydantic validates it against the real endpoint list before dispatch ever runs — an invalid operation never reaches the group tool's body.
• Adding a new endpoint: add its entry to _TOOL_REGISTRY as before, then add its name to exactly one group in _GROUPS. tests/test_tools.py::test_all_registry_names_grouped fails if you forget.
• New resource area big enough to need its own group (rare): add a new _GROUPS key. Keep the total group count at or under ~15 — that ceiling is the entire point of this pattern.
• If you're tempted to add a per-endpoint @mcp.tool or an extra mcp.add_tool call outside _register_group, don't — every endpoint must be reachable only via its group's operation enum. A 223-tool server (one per endpoint) previously cost ~56k tokens of system-prompt budget on every session start; the 15-tool grouped version costs roughly a tenth of that.