graphql-mcp: Instructions file for Codex

AGENTS.md

Project

@cubicecho/graphql-mcp — middleware that turns a GraphQL schema into a Model Context Protocol server. Each Query/Mutation root field is projected into an MCP tool, described from the SDL (field and argument descriptions, types) so an AI can discover and call your API. It is designed to run side-by-side with your GraphQL server: mount the returned HTTP handler on a route in the same app, or run it as its own process and forward to a remote GraphQL endpoint.

Stack

• Language: TypeScript 5.7+, strict mode, ESM only, "erasable syntax only" (no enums/namespaces/parameter-properties) so the source runs unbuilt under Node's type stripping.
• Runtime/build: Source uses .ts import specifiers. Run it directly with node --experimental-strip-types; tsc (with rewriteRelativeImportExtensions) rewrites the specifiers to .js and emits dist/. Requires Node ≥ 22 and TypeScript ≥ 5.7.
• Tests: Node's built-in test runner (node --test) with type stripping — no test framework dependency. Test files are src/**/*.test.ts.
• Formatting/linting: Biome (npm run check). Every if/loop body is a braced block (useBlockStatements), and a logic check is negated with === false, not ! (no-negation.grit; ! stays for null guards).
• File names: kebab-case (zod-schema.ts, event-store.ts). A new module goes in the folder whose phrase below covers it, never in a utils or helpers folder.
• Comments: every function and method has a TSDoc block: a description of at most four sentences, a blank line, then @param name - … for each parameter (@param [name] - … when optional) and @returns … unless it returns nothing. No {type} annotations. A comment in a function body is at most two lines. Keep the one fact that stops a reader undoing a decision; the longer history goes in this file or the commit message.
• Dependencies: @graphql-tools/schema (schema merging for the extend option) is the only runtime dependency. @modelcontextprotocol/sdk (>=1.12), graphql (>=16) and zod (^3.25 || ^4.0) are peer deps — zod because the SDK validates against the caller's copy, and a second one in our own tree makes instanceof checks fail across the boundary. Express is not a dependency — the HTTP handler is framework-agnostic. createFetchHandler needs SDK ≥ 1.25 and loads that transport lazily so the floor stays at 1.12 for everyone else.
• Guiding constraint: avoid adding libraries unless writing it ourselves isn't worth the effort (e.g. the GraphQL→Zod mapping is hand-written). The scalars option is a plain Record<string, AnyZodType> for the same reason — it's structurally identical to what generators emit (e.g. defaultScalarMap from @vantreeseba/graphql-zod), so interop needs no adapter or dependency.