qbit_manage-mcp: Instructions file for Codex

AGENTS.md — qbit_manage-mcp

MCP server exposing qbit_manage's Web API (REST, read + write) as tools so an LLM can read and manage a qbit_manage instance: run maintenance commands against its qBittorrent torrents, manage config files, the scheduler, logs, security settings, and system state. Uses FastMCP, uv for deps.

Exposed as 6 resource-scoped portmanteau tools, not one tool per endpoint — see "Portmanteau registration" below. The API is small (23 endpoints), but it is still grouped from the very first commit per the fleet standard: tool-per-endpoint is only tolerated for tracearr-mcp (it predates the standard and sits under the ceiling), never for a server built today.

Testing

• Offline suite: make test (or uv run pytest)
• Live integration (needs QBIT_MANAGE_URL/QBIT_MANAGE_API_KEY): make test-integration
  • GET endpoints run against the live instance.
  • POST/PUT/DELETE only run when QBIT_MANAGE_WRITE_TESTS=1 (safe create→validate→delete cycle against a scratch config file, then cleanup). Never point write tests at a production instance you care about.

Tool registry and the qbit_manage source

• _TOOL_REGISTRY in qbit_manage_mcp.py lists every JSON-producing qbit_manage endpoint under /api. qbit_manage publishes no vendored OpenAPI spec (its FastAPI /openapi.json is served at runtime but the routes are registered dynamically on a sub-router), so this table is hand-maintained against modules/web_api.py in the qbit_manage repo (currently develop HEAD). Each entry carries name/method/path/path-params/query-params/body-kind/doc.
• Response caveats: /api/docs returns text/markdown — _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.
• get_documentation's file query param is required (no default): its registry entry marks it required: true and _tool_source renders it without a default. The op_to_args test helper supplies sentinel values for required query params the same way it does for path params.
• To refresh coverage after a qbit_manage update, diff modules/web_api.py's api_router route registrations 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): qbit_manage_<verb>_<resource> derived from path + method (e.g. qbit_manage_list_configs, qbit_manage_update_config, qbit_manage_run_command, qbit_manage_health_check).