steam-games-mcp: Instructions file for Codex

AGENTS.md

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

Project shape

A TypeScript MCP server for Steam. Hybrid backend, mirroring the mal-mcp/tmdb-mcp pattern: store/game reads go through the Steam Storefront API (store.steampowered.com/api/*) which needs no key, while player data (profiles, libraries, achievements, friends) uses the official Steam Web API (api.steampowered.com) which needs a free key. Design rationale (why two clients, the keyless caveat, why no SteamDB/price-history, API references, template reuse) lives in docs/architecture.md.

src/
  index.ts        # bin entry — calls start()
  server.ts       # buildServer() + start(); registers everything
  config.ts       # env → validated Config (zod)
  version.ts      # VERSION/USER_AGENT, kept in sync with package.json by a test
  format/         # raw Steam payloads → trimmed, agent-facing shapes: storefront.ts,
                  #   web.ts + webAchievements.ts (official Web API: player data /
                  #   achievement lists), store.ts (keyless store-service summarizers:
                  #   SearchSuggestions/GetItems/Query/wishlist/recommendations) over
                  #   storeCard.ts (their
                  #   shared StoreItem/tag/compat/card/filter toolkit), shared.ts (helpers),
                  #   charts.ts (keyless chart services: top sellers / most played /
                  #   Steam Deck most played / live concurrent players, for get_charts).
                  #   Each shaper has a co-located *.schemas.ts (schema-first: the shaper
                  #   builds its return value via `schema.parse({...})`, see Conventions);
                  #   storeCard.ts shares store.schemas.ts with store.ts
  lib/            # GENERIC carcass: http, rateLimit, cache, concurrency, errors,
                  #   logger, result
  clients/        # storefront.ts (keyless store; takes storeService as a
                  #   PurchasePriceSource, because Storefront prices are wrong —
                  #   see docs/architecture.md), web.ts (official Web API; key
                  #   optional; builds storeService.ts, exposed via `.store` for
                  #   tools/webStore.ts; also the one place that talks to
                  #   steamcommunity.com, to resolve a vanity STEAM_ID without a
                  #   key), storeService.ts (modern store-browse/
                  #   query/wishlist-sorted card services)
  tools/          # storefront.ts, webStore.ts (keyless-capable Web API tools),
                  #   webPlayer.ts (key-gated player tools), webShared.ts (steamid
                  #   schema, steamIdTool helper and requireKey, shared by the two),
                  #   common.ts (shared param schemas, toCompatFilters + reply
                  #   wrapper across storefront+web), guard.ts, prompts.ts (MCP
                  #   Prompts)
  __tests__/      # node:test (*.test.ts) + helpers.ts
scripts/          # run-tests.ts, sync-version.ts (generic), check-api.ts
                  #   (domain), preversion-check.ts (CHANGELOG gate) — plain
                  #   .ts run directly by Node's type stripping, no build step
.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. Same
                  #   skill name/layout as this project's sibling MCP servers
                  #   (tmdb-mcp, mal-mcp, anilist-mcp-server) — 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)