# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Commands

```bash
# Install dependencies
uv sync

# Run the MCP server
python src/jellyfin_mcp/server.py

# Run tests
pytest

# Run a single test
pytest tests/test_server.py::test_search_items_tool
```

## Architecture

This is a Python MCP server that wraps the Jellyfin media server REST API using the `FastMCP` framework.

**Two-layer design:**

- [`src/jellyfin_mcp/client.py`](src/jellyfin_mcp/client.py) — `JellyfinClient`: low-level async HTTP client using `httpx`. Handles auth via `MediaBrowser Token` header, constructs URLs, and maps Jellyfin API responses to Python types.
- [`src/jellyfin_mcp/server.py`](src/jellyfin_mcp/server.py) — MCP tool definitions via `@mcp.tool()` decorators. Each tool calls `JellyfinClient` methods and formats results as plain strings for AI consumption. The `client` instance is a module-level singleton initialized at import time from env vars.

**Configuration:** `JELLYFIN_URL` and `JELLYFIN_API_KEY` must be set (via `.env` file or environment). The server raises `ValueError` at startup if either is missing.

**Testing:** Tests mock `jellyfin_mcp.server.client` at the module level and patch individual `JellyfinClient` methods with `AsyncMock`. The `mock_env` fixture is `autouse=True` so env vars are always set during tests.