mcp-server-template: Instructions file for Codex

AGENTS.md

Single source of truth for working on this repository — for any model or agent (Claude, and others). CLAUDE.md only references this file; keep all shared guidance here.

This repository is a template for building TypeScript MCP servers. See TEMPLATE.md for the step-by-step checklist to spin up a new server.

Architecture

A standard stdio MCP server. The design separates a reusable carcass from a thin domain layer, so a new server only rewrites the domain layer.

src/
  index.ts        # bin entry — calls start()
  server.ts       # buildServer() + start(); wires clients/tools/prompts   [domain wiring]
  config.ts       # env → validated Config (zod)                          [domain]
  lib/            # GENERIC carcass — reuse as-is:
    http.ts       #   fetch wrapper: timeout, retries, backoff, UA, error mapping
    rateLimit.ts  #   min-interval + sliding-window limiter (e.g. N/s and M/min)
    cache.ts      #   in-memory TTL cache
    tokenStore.ts #   OAuth refresh-token persistence (use only if your API needs it)
    errors.ts     #   ApiError + status classification + secret redaction
    logger.ts     #   leveled stderr logger (redacts secrets)
    result.ts     #   MCP tool-result builders (jsonResult/errorResult/apiErrorToResult)
  clients/        # one client per upstream API, fetch+cache ONLY — no shaping [domain]
  format/         # raw upstream payloads → trimmed, agent-facing shapes, one
                  #   *.ts per client plus a co-located *.schemas.ts           [domain]
  tools/
    guard.ts      #   GENERIC — wraps a tool body, turns errors into results
    *.ts          #   tool registrations                                  [domain]
  prompts.ts      # optional MCP prompts                                  [domain]
  __tests__/      # node:test; helpers.ts is generic infra
scripts/          # build-tests.mjs, run-tests.mjs (generic), check-api.mjs (domain)

Reuse model: copy this template (GitHub "Use this template") and rewrite only the [domain] parts: config.ts, clients/, format/, domain tools/, prompts.ts, check-api.mjs, the manifest tool list, and the docs. The lib/ carcass, build tooling, tests infra and CI come for free. Extract lib/ into a shared package only once duplication across servers actually hurts (YAGNI) — not before.