lidarr-mcp: Instructions file for Codex

AGENTS.md — lidarr-mcp

MCP server exposing Lidarr's v1 REST API (OpenAPI 3.0.4) as tools so an LLM can read and manage a Lidarr instance: artists, albums, tracks, track files, queue, wanted, history, indexers, import lists, metadata profiles, 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 one-tool-per-endpoint version of this API would register 221 endpoints individually, blowing the MCP context budget (~221 tools × ~250 tokens ≈ 55k tokens just for this one server); the grouped version costs roughly a tenth of that.

Testing

• Offline suite: make test (or uv run pytest)
• Live integration (needs LIDARR_URL/LIDARR_API_KEY): make test-integration
  • GET endpoints run against the live instance.
  • POST/PUT/DELETE only run when LIDARR_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 lidarr_mcp.py is generated from the vendored spec at tests/data/lidarr_openapi.json (pinned to Lidarr develop HEAD d88cbcec050c04b3064c9f36221edac152e241e2). It lists every JSON-producing endpoint under /api/v1 plus GET /ping.
• Excluded on purpose: /login, /logout, static web routes, the .ics calendar feed, and binary/text endpoints (media covers, raw log files) — _req JSON-decodes every response. /ping is kept.
• 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): lidarr_<verb>_<resource> derived from path + method (e.g. lidarr_list_artist, lidarr_add_album, lidarr_delete_trackfile, lidarr_run_command). Overrides for flagship/action endpoints live in the authoring script.