anilist-mcp-server: Instructions file for Codex

AGENTS.md

Single source of truth for working on this repository — for any model or agent. CLAUDE.md only links here (@AGENTS.md); keep all shared guidance in this file, not in CLAUDE.md. (For end-user/runtime docs, see README.md.)

Project shape

A TypeScript MCP server for the AniList GraphQL API. Reads (search/details/genres/tags/recommendations/threads/activity/public user data) call the public GraphQL endpoint directly and need no credentials. Personal-list and social tools (add/update/remove list entries, favourites, follow, posting/deleting activity or threads, update_user, get_notifications) act on the authenticated user's own AniList account and require a user access token — see docs/auth.md for the OAuth model and docs/api-references.md for AniList's API specifics (rate limits, mutation semantics, considerations) before changing the client.

src/
  index.ts        # bin entry — calls start()
  server.ts       # buildServer() + start(); registers everything
  config.ts       # env → validated Config (zod)
  version.ts      # VERSION constant, kept in sync with package.json (checked by a test)
  lib/            # http, rateLimit, cache, tokenStore, oauthLogin, errors, logger,
                  # result, graphql (the GraphQL request/error-mapping layer)
  clients/        # anilist.ts — thin AniListClient facade (auth/config/login,
                  # exposes ctx(): AniListContext); anilist/*.ts — one file per
                  # domain (activity, context, favourites, fields, list, media,
                  # misc, notification, people, recommendation, search, thread,
                  # user), matching src/tools/* (plus fuzzyDate.ts: the
                  # date-filter encoders several domains share, and
                  # deleteById.ts: the four Delete* mutations' shared call).
                  # Tool handlers call these domain functions directly
                  # (e.g. `media.getMedia(client.ctx(), ...)`) rather than through a same-named method on AniListClient.
                  # anilist/ids.ts — branded numeric-ID type aliases (MediaId,
                  # ListEntryId, etc.), one per domain concept; every domain
                  # file's exported functions take these instead of plain
                  # `number` so e.g. a MediaId can't compile where a
                  # ListEntryId is expected. Compile-time only — see the
                  # file's own comment for why it has no zod runtime import.
                  # anilist/enums.ts — single source for the AniList enums
                  # re-typed on both sides of the boundary (MediaType,
                  # MediaListStatus, FavouriteKind, birthday kinds): one
                  # `as const` array per enum, feeding z.enum() in tools/ and
                  # the derived `(typeof X)[number]` type in these domain
                  # signatures, so runtime validation and the compile-time
                  # types can't drift. Lives here (not tools/) because
                  # clients/ can't import from tools/.
  tools/          # misc.ts, activity.ts, list.ts, media.ts, notification.ts,
                  # people.ts, recommendation.ts, search.ts, thread.ts, user.ts,
                  # login.ts, guard.ts (never-throw wrapper), outputSchemas.ts
                  # (shared output-schema fragments, incl. anilistId and its
                  # per-domain branded variants — mediaId, listEntryId, etc.)
  prompts.ts      # MCP Prompts: multi-step plans that orchestrate the read tools
  __tests__/      # node:test (*.test.ts) + helpers.ts
scripts/          # run-tests.ts, check-api.ts, sync-version.ts,
                  # preversion-check.ts (npm `preversion` gate — see the `release` skill)
.agents/skills/   # reusable agent workflows for this repo (e.g. live-audit/) —
                  # plain Markdown with a YAML frontmatter name/description,
                  # not tied to any one tool's orchestration features, per
                  # this file's agent-agnostic policy; same skill name/layout
                  # as this project's sibling MCP servers (tmdb-mcp, mal-mcp,
                  # steam-games-mcp) — sync improvements both ways rather
                  # than letting them drift. `.claude/skills` is a symlink
                  # here (Codex CLI/Gemini CLI read `.agents/skills`
                  # directly, Claude Code the symlink), so no skill content
                  # is duplicated per client path.