mcp-arrstack: Instructions file for Codex

MCP ARR Stack — Agent Instructions

Purpose

MCP (Model Context Protocol) server providing LLM tools for ARR Stack media automation services: Sonarr, Radarr, Lidarr, Prowlarr, Readarr, Seerr, Tautulli, Plex.

Directory Structure

src/
  server.py          # Main entry point — tool definitions, dispatch table, MCP server factory
  config.py          # Dataclass configs per service; load_config() reads env vars
  client.py          # Async HTTP clients: BaseARRClient (v3 API), SeerrClient (v1), TautulliClient (/api/v2), PlexClient
  http_server.py     # ASGI app: Starlette + StreamableHTTPSessionManager, API key auth middleware, CORS
  utils.py           # In-memory cache, rate limiter, safe_execute helper
  tools/
    sonarr_tools.py
    radarr_tools.py
    lidarr_tools.py
    prowlarr_tools.py
    readarr_tools.py   # Exists as config but no tool file yet — add src/tools/readarr_tools.py when needed
    seerr_tools.py
    tautulli_tools.py
    plex_tools.py
tests/               # pytest tests (conftest has env-var isolation + mock fixtures)

Build, Test, Lint Commands

Важно: Python не установлен на хост-машине. Все команды должны выполняться внутри Docker-контейнера.

# Install deps (editable) — inside container
docker compose exec mcp-arr-stack pip install -e ".[dev]"

# Run tests — inside container
docker compose exec mcp-arr-stack pytest tests/ -v
docker compose exec mcp-arr-stack pytest tests/ -v --cov=src --cov-report=term-missing

# Format — inside container
docker compose exec mcp-arr-stack black src/ tests/
docker compose exec mcp-arr-stack ruff check src/ tests/
docker compose exec mcp-arr-stack ruff check src/ tests/ --fix

Быстрый запуск тестов

# Все тесты
docker compose exec mcp-arr-stack pytest tests/ -v

# Один файл
docker compose exec mcp-arr-stack pytest tests/test_sonarr_tools.py -v

# С покрытием
docker compose exec mcp-arr-stack pytest tests/ -v --cov=src --cov-report=term-missing

# Только упавшие (last failures)
docker compose exec mcp-arr-stack pytest tests/ -v --lf