graphql-mcp AGENTS.md

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).
• 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.