mcp-arr-lite AGENTS.md

AGENTS.md

Compact guide for OpenCode sessions working in this repo.

Toolchain

• Node >= 20, ES modules ("type": "module"), module/moduleResolution: NodeNext. Use .js extensions in relative imports (required at runtime under NodeNext).
• No ESLint/Prettier — npm run lint and npm run typecheck are both tsc --noEmit. Do not look for a separate linter config.
• npm run build compiles src/ -> dist/ (rootDir: src, outDir: dist); tests/ is excluded from tsconfig.json but included in tsconfig.test.json.

Commands

• Dev: npm run dev (tsx watch on src/index.ts).
• Build: npm run build; run built: npm start (stdio) or npm run start:stdio / npm run start:http.
• Tests: npm test (vitest run). Coverage: npm run test:coverage.
• Single test: npx vitest run tests/tools.test.ts or npx vitest run -t "pattern".
• Run both npm run typecheck and npm run typecheck:tests before pushing.

Tests

• vitest.config.ts sets globals: true and environment: 'node'; tests live in tests/**/*.test.ts.
• tests/setup.ts stubs env vars (RADARR_URL, RADARR_API_KEY, SONARR_URL, SONARR_API_KEY, MCP_TRANSPORT=http, LOG_LEVEL=error) for the whole suite via beforeAll. Don't assume a real Radarr/Sonarr is reachable.
• Tests mock ArrClient / global fetch — no integration services required.

Architecture

• Entry: src/index.ts (bin dist/index.js). Loads config, builds ArrClient instances for configured apps, creates the MCP McpServer, then selects transport from MCP_TRANSPORT.
• src/config.ts owns all env loading and validation; validateHttpConfig requires MCP_AUTH_TOKEN when MCP_TRANSPORT=http. Radarr/Sonarr config is optional.
• src/server.ts registers tools from buildTools() into the MCP McpServer and wraps handlers with safe-error normalization.
• Transport: src/transport/stdio.ts and src/transport/http.ts. HTTP transport adds bearer auth, rate limiting (60 req/min/IP), and 1 MB body limit; defaults HOST=127.0.0.1.
• Tools live in src/tools/handlers/ and are aggregated in src/tools/registry.ts (buildTools()). Adding a tool = create handler file + append it in buildTools(); server.ts picks the rest up automatically.
• src/arr/client.ts is the only Arr API surface (X-Api-Key auth); src/arr/radarr.ts / src/arr/sonarr.ts wrap resource-specific calls and default-resolution (quality profile, root folder); src/arr/indexer.ts has the preferred-indexer logic (lowest numeric priority among enabled).
• Search tools default to the preferred indexer; pass a specific indexer id to force an alternative. Read-only tools (*_lookup, list_indexers) are safe to auto-approve; mutations (*_add, *_search_releases, *_grab) should require HITL.