seerr-mcp-server AGENTS.md

Developer Protocol

Server: seerr-mcp-server Version: 0.1.3 Framework: @cyanheads/mcp-ts-core ^0.12.3 Engines: Bun ≥1.3.0, Node ≥24.0.0 MCP SDK: @modelcontextprotocol/server ^2.0.0 Zod: ^4.4.3

Read the framework docs first: node_modules/@cyanheads/mcp-ts-core/CLAUDE.md contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.

---

What This Server Does

A workflow MCP server over a self-hosted Jellyseerr/Overseerr instance: search → confirm the TMDB-backed title → check availability/request state → create a guarded request that Radarr/Sonarr act on. Jellyseerr owns permissions, quotas, routing, and status; this server never touches Radarr/Sonarr directly. Read + guarded-request only — admin-scope endpoints (approve/decline, retry, edit/delete, media/file deletion, user/settings/sync) are excluded by design.

Surface: six tools (seerr_search_media, seerr_get_media, seerr_list_requests, seerr_request_media, seerr_request_status, seerr_service_options) + one resource (seerr://request/{requestId}). No prompts.

Two invariants that must never regress:

1. Guarded write. seerr_request_media is the only mutation. It defaults to mode: preview (resolve + validate, no POST); the real write fires only on mode: request and only once the handler is re-entered with a schema-valid acceptance on ctx.inputs, with destructiveHint: true surfacing the risk in client-side approval flows. There is no branch that proceeds without an acceptance — a client that never answers leaves the write un-run. Capability validation (4K/seasons/partial) runs locally against cached settings before any POST. MCP_SESSION_MODE must resolve to stateful: the round trip needs a live session for 2025-era clients, and stateless refuses it.
2. PII/infra redaction. Every raw Jellyseerr payload is projected through src/services/seerr/normalizers.ts — the single choke point — before output. It allow-lists fields: User → { id, displayName }, and drops operator email, Plex/Jellyfin tokens, serviceUrl, vapidPublic, and filesystem paths (gated behind includePaths). The base URL and API key live only in config and never appear in output. Redaction lives in normalizers, not format(), so both structuredContent and content[] are clean. ctx.log is a third output surface — it is dual-sink as of mcp-ts-core 0.12.0, mirroring every call to the client as notifications/message — so log only classified reasons and the caller's own inputs, never a raw upstream or network message.