FlixBridge AGENTS.md

AGENTS.md – How We Build Here

This document defines engineering principles, architectural constraints, and contribution patterns for this MCP server. It is intentionally focused on how we build (process, quality bar, patterns) rather than what we build. Keep it short, boring, and repeatable.

---

0. Core Constraints

1. Total handwritten runtime TypeScript LOC (excluding config, README, this file) MUST stay ≤ 700 lines, but the entire project can be more than that, any core service is exempt from this rule, but it should be kept as small as possible.
2. Zero heavy frameworks. Prefer the platform (Node 20+ LTS, native fetch / undici).
3. Minimal dependencies (target set):
   • typescript@^5.9.x
   • zod (runtime validation, narrow usage)
   • @biomejs/biome (formatter + linter; replaces ESLint/Prettier)
   • tsx (optional dev runner) OR plain node as appropriate
4. No class hierarchies unless polymorphism cannot be expressed more simply (object literals + functions preferred).
5. Strict TypeScript ("strict": true, include noUncheckedIndexedAccess, useUnknownInCatchVariables).
6. All external I/O (HTTP) funneled through one tiny helper to enforce:
   • Timeouts
   • Error normalization
   • Consistent logging hooks (single choke point)
7. The repository should always be in a shippable state (main = releasable).
8. Public surface area (exported symbols) stays tiny; internal refactors remain cheap.

---

1. High-Level Architecture

/src
  index.ts                 -> MCP server bootstrap + tool registration
  core.ts                  -> shared fetch wrapper (retry + timeout)
  debug.ts                 -> debug logging system (Phase 3)
  metrics.ts               -> observability & metrics collection (Phase 3)
  services/
    base.ts                -> shared service & operation type contracts
    shared.ts              -> BaseArrService implementation
    registry.ts            -> service registry: serviceName -> adapter
    arr/
      sonarr.ts            -> Sonarr adapter (conforms to shared contract)
      radarr.ts            -> Radarr adapter (conforms to shared contract)
    downloaders/
      sabnzbd.ts           -> SABnzbd downloader integration (Phase 2)