mal-mcp: 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. Hybrid backend: read tools call the free Tenrai API (no auth; an unofficial MyAnimeList mirror). Personal-list tools call the official MyAnimeList API (user token). Eleven read tools (search/top/seasonal/recommendations/details/anime statistics) additionally fall back to the official API via just a Client ID — see ReadFallback in clients/readFallback.ts and the rationale/scope in docs/api-references.md before changing a client. docs/auth.md lays out what each credential tier (none / Client ID / OAuth token) unlocks — read that before changing auth-gating logic or docs that describe it.

Upstream API docs (rate limits, endpoints, OAuth, audit notes) are collected in docs/api-references.md — check there before changing a client.

src/
  index.ts        # bin entry — calls start()
  server.ts       # buildServer() + start(); registers everything
  config.ts       # env → validated Config (zod)
  version.ts      # VERSION/USER_AGENT string, kept in sync with package.json (version.test.ts)
  lib/            # http, rateLimit, cache, tokenStore, oauthLogin, errors, logger,
                  # result, format(+formatOfficial for the fallback's response shaping)
                  # format.schemas.ts: Zod schemas mirroring every format.ts/formatOfficial.ts
                  # shaper, PLUS clients/mal.ts's trimList()/deleteMy*ListItem() outputs
                  # (myListSchema, deleteAnimeItemSchema, deleteMangaItemSchema — shaped/
                  # client-synthesized output, not raw upstream passthrough, so they live
                  # here rather than in mal.ts); each tool's outputSchema, AND (schema-first)
                  # the paired shaper itself calls schema.parse() on its own result before
                  # returning
  clients/        # tenrai.ts (reads) + tenraiEnums.ts (every enum-shaped query param Tenrai
                  # accepts, as `as const` arrays — the single source of truth read.ts's
                  # z.enum(...) calls build from) + tenraiParams.ts (TenraiClient's param
                  # interfaces, split out once tenrai.ts grew too large to scan) +
                  # readFallback.ts (retry policy), mal.ts (personal-list CRUD — MyUserInfoSchema/
                  # MalListResponseSchema/ListStatusUpdateResponseSchema stay here as
                  # z.looseObject(), see below) + malEnums.ts (mal.ts's own enum arrays, same
                  # reasoning/pattern as tenraiEnums.ts, shared with tools/mylist.ts) +
                  # malAuth.ts (MalAuthManager: OAuth token refresh + the login_mal/
                  # submit_mal_redirect PKCE flow, composed into MalClient — split out because
                  # token lifecycle and personal-list CRUD are genuinely different concerns, not
                  # because of anime/manga: unlike tenrai.ts's split, there's no anime/manga axis
                  # here worth separating further, since #getMyList/#updateStatus/#deleteItem are
                  # correctly DRY, resource-parameterized helpers, not a merged-domain mistake),
                  # officialReads.ts (Client-ID-only public reads, the fallback's data source),
                  # httpClients.ts (shared HttpClient factory for the official API, +
                  # withThrottle(), the rate-limit wiring shared with tenrai.ts too, +
                  # formBody() form-encoder shared by mal.ts and malAuth.ts)
  tools/          # read.ts, mylist.ts, login.ts (login_mal), guard.ts, spec.ts (defineTool/
                  # registerTools + ToolSpec — the per-tool registration abstraction all three
                  # register*Tools() callers flow through)
  prompts.ts      # registerPrompts(server, tenrai) — clients get threaded in as needed,
                  # e.g. for completable() autocomplete on recommend_similar's title
  __tests__/      # node:test (*.test.ts) + helpers.ts
scripts/          # build-tests.mjs, run-tests.mjs, check-api.mjs, sync-version.mjs,
                  # preversion-check.mjs (npm version gate — see .agents/skills/release/SKILL.md),
                  # check-changelog-coverage.mjs (see docs-consistency-check skill),
                  # check-chainable-optional-fields.mjs (see tool-description-check 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,
                  # steam-games-mcp, anilist-mcp-server) — sync improvements
                  # both ways rather than letting them drift. Codex CLI and
                  # Gemini CLI read `.agents/skills` directly and Claude Code
                  # via the `.claude/skills` symlink, so every skill is picked
                  # up without duplicating content per client path.