@cubicecho/graphql-mcp 0.1.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Van Treese
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/executor.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The two built-in {@link GraphqlExecutor}s — the seam that decides *where* a
+ * tool's GraphQL operation runs.
+ *
+ * - {@link createLocalExecutor} runs it in-process against the schema you already
+ *   have (the simplest "side-by-side" setup: mount the MCP handler on a route in
+ *   the same app as your GraphQL endpoint).
+ * - {@link createHttpExecutor} forwards it to a separate GraphQL HTTP endpoint —
+ *   for when the MCP server runs as its own process next to the GraphQL server.
+ */
+import { type GraphQLSchema } from 'graphql';
+import type { GraphqlExecutor } from './types.ts';
+/** Options for {@link createLocalExecutor}. */
+export interface LocalExecutorOptions {
+    /** Default `rootValue` for execution (e.g. a resolver root for `buildSchema` schemas). */
+    rootValue?: unknown;
+    /** Fallback `contextValue` used when a call provides no per-request `context`. */
+    contextValue?: unknown;
+}
+/**
+ * An executor that runs operations in-process against `schema` via graphql-js's
+ * `execute`. The per-call `context` (from the `context` server option) is passed
+ * as the GraphQL `contextValue`, falling back to `options.contextValue`.
+ *
+ * @param schema - The executable schema to run against.
+ * @param options - Default root/context values.
+ */
+export declare function createLocalExecutor(schema: GraphQLSchema, options?: LocalExecutorOptions): GraphqlExecutor;
+/** Options for {@link createHttpExecutor}. */
+export interface HttpExecutorOptions {
+    /**
+     * Extra request headers. Either a static record or a function of the per-call
+     * `context` — use the function form to forward auth derived from the MCP
+     * request (e.g. `(ctx) => ({ authorization: ctx.token })`).
+     */
+    headers?: Record<string, string> | ((context: unknown) => Record<string, string>);
+    /** Override the `fetch` implementation (defaults to the global `fetch`). */
+    fetch?: typeof fetch;
+}
+/**
+ * An executor that POSTs operations to a GraphQL HTTP `endpoint` (the standard
+ * `{ query, variables, operationName }` body) and returns the parsed JSON.
+ *
+ * @param endpoint - The GraphQL endpoint URL.
+ * @param options - Header and `fetch` overrides.
+ */
+export declare function createHttpExecutor(endpoint: string, options?: HttpExecutorOptions): GraphqlExecutor;

package/dist/executor.js

@@ -0,0 +1,58 @@
+/**
+ * The two built-in {@link GraphqlExecutor}s — the seam that decides *where* a
+ * tool's GraphQL operation runs.
+ *
+ * - {@link createLocalExecutor} runs it in-process against the schema you already
+ *   have (the simplest "side-by-side" setup: mount the MCP handler on a route in
+ *   the same app as your GraphQL endpoint).
+ * - {@link createHttpExecutor} forwards it to a separate GraphQL HTTP endpoint —
+ *   for when the MCP server runs as its own process next to the GraphQL server.
+ */
+import { execute, parse } from 'graphql';
+/**
+ * An executor that runs operations in-process against `schema` via graphql-js's
+ * `execute`. The per-call `context` (from the `context` server option) is passed
+ * as the GraphQL `contextValue`, falling back to `options.contextValue`.
+ *
+ * @param schema - The executable schema to run against.
+ * @param options - Default root/context values.
+ */
+export function createLocalExecutor(schema, options = {}) {
+    return async ({ query, variables, operationName, context }) => {
+        const result = await execute({
+            schema,
+            document: parse(query),
+            variableValues: variables,
+            operationName,
+            rootValue: options.rootValue,
+            contextValue: context ?? options.contextValue,
+        });
+        return result;
+    };
+}
+/**
+ * An executor that POSTs operations to a GraphQL HTTP `endpoint` (the standard
+ * `{ query, variables, operationName }` body) and returns the parsed JSON.
+ *
+ * @param endpoint - The GraphQL endpoint URL.
+ * @param options - Header and `fetch` overrides.
+ */
+export function createHttpExecutor(endpoint, options = {}) {
+    const doFetch = options.fetch ?? globalThis.fetch;
+    return async ({ query, variables, operationName, context }) => {
+        const extra = typeof options.headers === 'function' ? options.headers(context) : options.headers;
+        const response = await doFetch(endpoint, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', accept: 'application/json', ...extra },
+            body: JSON.stringify({ query, variables, operationName }),
+        });
+        if (!response.ok) {
+            return {
+                errors: [
+                    { message: `GraphQL endpoint responded ${response.status} ${response.statusText}` },
+                ],
+            };
+        }
+        return (await response.json());
+    };
+}

package/dist/http.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The HTTP glue for running the MCP server "side-by-side" with your GraphQL
+ * server: {@link createHttpHandler} returns a plain `(req, res)` handler you
+ * mount on a route (e.g. `app.post('/mcp', handler)` in Express).
+ *
+ * It uses the MCP SDK's Streamable HTTP transport in stateless JSON mode and
+ * creates a fresh `McpServer` + transport per request — the transport owns a
+ * single connection, so per-request isolation is what keeps concurrent calls
+ * from clobbering each other.
+ *
+ * Express is assumed for the MVP, but nothing here imports it: any framework
+ * works as long as it hands the handler a Node `IncomingMessage` whose parsed
+ * JSON body is on `req.body` (Express's `express.json()` does this) and a Node
+ * `ServerResponse`. Adapting other servers is tracked in TODO.md.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type CreateMcpServerOptions } from './server.ts';
+/** A request with its parsed JSON body attached (as `express.json()` provides). */
+export type McpHttpRequest = IncomingMessage & {
+    body?: unknown;
+};
+/** An Express/Node-compatible request handler for MCP-over-HTTP. */
+export type McpHttpHandler = (req: McpHttpRequest, res: ServerResponse) => Promise<void>;
+/** Options for {@link createHttpHandler}. */
+export interface HttpHandlerOptions extends CreateMcpServerOptions {
+    /**
+     * Derive per-request GraphQL context from the HTTP request (e.g. read an auth
+     * header). Takes precedence over the `context` option for HTTP calls and lets
+     * you key context off the real request rather than the MCP `extra`.
+     */
+    contextFromRequest?: (req: McpHttpRequest) => unknown | Promise<unknown>;
+}
+/**
+ * Creates an HTTP handler that serves the schema's tools over the MCP Streamable
+ * HTTP transport. Tool descriptors are built once; each request gets a fresh
+ * server and transport.
+ *
+ * @param options - The same options as {@link createMcpServer}, plus
+ *   `contextFromRequest` for request-derived GraphQL context.
+ * @returns A `(req, res)` handler to mount on a route.
+ * @example
+ * ```ts
+ * const handler = createHttpHandler({ schema });
+ * app.post('/mcp', handler); // run beside app.post('/graphql', ...)
+ * ```
+ */
+export declare function createHttpHandler(options: HttpHandlerOptions): McpHttpHandler;

package/dist/http.js

@@ -0,0 +1,50 @@
+/**
+ * The HTTP glue for running the MCP server "side-by-side" with your GraphQL
+ * server: {@link createHttpHandler} returns a plain `(req, res)` handler you
+ * mount on a route (e.g. `app.post('/mcp', handler)` in Express).
+ *
+ * It uses the MCP SDK's Streamable HTTP transport in stateless JSON mode and
+ * creates a fresh `McpServer` + transport per request — the transport owns a
+ * single connection, so per-request isolation is what keeps concurrent calls
+ * from clobbering each other.
+ *
+ * Express is assumed for the MVP, but nothing here imports it: any framework
+ * works as long as it hands the handler a Node `IncomingMessage` whose parsed
+ * JSON body is on `req.body` (Express's `express.json()` does this) and a Node
+ * `ServerResponse`. Adapting other servers is tracked in TODO.md.
+ */
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createServerFactory } from "./server.js";
+/**
+ * Creates an HTTP handler that serves the schema's tools over the MCP Streamable
+ * HTTP transport. Tool descriptors are built once; each request gets a fresh
+ * server and transport.
+ *
+ * @param options - The same options as {@link createMcpServer}, plus
+ *   `contextFromRequest` for request-derived GraphQL context.
+ * @returns A `(req, res)` handler to mount on a route.
+ * @example
+ * ```ts
+ * const handler = createHttpHandler({ schema });
+ * app.post('/mcp', handler); // run beside app.post('/graphql', ...)
+ * ```
+ */
+export function createHttpHandler(options) {
+    const { contextFromRequest, ...serverOptions } = options;
+    const makeServer = createServerFactory(serverOptions);
+    return async (req, res) => {
+        // Per-request context derived from the real HTTP request wins over a static
+        // `context`; otherwise fall back to whatever `serverOptions.context` holds.
+        const server = makeServer(contextFromRequest ? () => contextFromRequest(req) : undefined);
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+            enableJsonResponse: true,
+        });
+        res.on('close', () => {
+            transport.close();
+            server.close();
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * graphql-mcp — turn a GraphQL schema into an MCP server.
+ *
+ * Point it at a `GraphQLSchema` and every `Query`/`Mutation` root field becomes
+ * a Model Context Protocol tool, described from the SDL (field and argument
+ * descriptions, types) so an AI can discover and call your API. It's a thin
+ * wrapper meant to run *beside* 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 endpoint.
+ *
+ * Quick start:
+ * ```ts
+ * import express from 'express';
+ * import { createHttpHandler } from '@cubicecho/graphql-mcp';
+ * import { schema } from './schema.js';
+ *
+ * const app = express();
+ * app.use(express.json());
+ * app.post('/mcp', createHttpHandler({ schema })); // beside app.post('/graphql', …)
+ * app.listen(4000);
+ * ```
+ *
+ * Modules:
+ * - `types` — `GraphqlExecutor`/`GraphqlRequest`/`GraphqlResult`, the execution seam
+ * - `zodSchema` — GraphQL args → Zod input schema (`argsToZodShape`)
+ * - `selection` — auto-built selection sets (`buildSelectionSet`)
+ * - `operation` — per-field operation documents (`buildOperation`)
+ * - `tools` — schema → `ToolDescriptor`s (`buildTools`)
+ * - `executor` — `createLocalExecutor` (in-process) / `createHttpExecutor` (forwarding)
+ * - `server` — `createMcpServer` / `createServerFactory` / `registerGraphqlTools` (+ custom tools)
+ * - `http` — `createHttpHandler` for the Streamable HTTP transport
+ *
+ * @packageDocumentation
+ */
+export type { HttpExecutorOptions, LocalExecutorOptions } from './executor.ts';
+export { createHttpExecutor, createLocalExecutor } from './executor.ts';
+export type { HttpHandlerOptions, McpHttpHandler, McpHttpRequest } from './http.ts';
+export { createHttpHandler } from './http.ts';
+export type { BuiltOperation } from './operation.ts';
+export { buildOperation } from './operation.ts';
+export { buildSelectionSet } from './selection.ts';
+export type { ContextFactory, CreateMcpServerOptions, CustomTool, ServerFactory, ToolHandler, } from './server.ts';
+export { createMcpServer, createServerFactory, registerGraphqlTools, } from './server.ts';
+export type { BuildToolsOptions, ToolDescriptor } from './tools.ts';
+export { buildTools } from './tools.ts';
+export type { GraphqlError, GraphqlExecutor, GraphqlRequest, GraphqlResult, OperationKind, ToolAnnotations, } from './types.ts';
+export { argsToZodShape } from './zodSchema.ts';

package/dist/index.js

@@ -0,0 +1,41 @@
+/**
+ * graphql-mcp — turn a GraphQL schema into an MCP server.
+ *
+ * Point it at a `GraphQLSchema` and every `Query`/`Mutation` root field becomes
+ * a Model Context Protocol tool, described from the SDL (field and argument
+ * descriptions, types) so an AI can discover and call your API. It's a thin
+ * wrapper meant to run *beside* 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 endpoint.
+ *
+ * Quick start:
+ * ```ts
+ * import express from 'express';
+ * import { createHttpHandler } from '@cubicecho/graphql-mcp';
+ * import { schema } from './schema.js';
+ *
+ * const app = express();
+ * app.use(express.json());
+ * app.post('/mcp', createHttpHandler({ schema })); // beside app.post('/graphql', …)
+ * app.listen(4000);
+ * ```
+ *
+ * Modules:
+ * - `types` — `GraphqlExecutor`/`GraphqlRequest`/`GraphqlResult`, the execution seam
+ * - `zodSchema` — GraphQL args → Zod input schema (`argsToZodShape`)
+ * - `selection` — auto-built selection sets (`buildSelectionSet`)
+ * - `operation` — per-field operation documents (`buildOperation`)
+ * - `tools` — schema → `ToolDescriptor`s (`buildTools`)
+ * - `executor` — `createLocalExecutor` (in-process) / `createHttpExecutor` (forwarding)
+ * - `server` — `createMcpServer` / `createServerFactory` / `registerGraphqlTools` (+ custom tools)
+ * - `http` — `createHttpHandler` for the Streamable HTTP transport
+ *
+ * @packageDocumentation
+ */
+export { createHttpExecutor, createLocalExecutor } from "./executor.js";
+export { createHttpHandler } from "./http.js";
+export { buildOperation } from "./operation.js";
+export { buildSelectionSet } from "./selection.js";
+export { createMcpServer, createServerFactory, registerGraphqlTools, } from "./server.js";
+export { buildTools } from "./tools.js";
+export { argsToZodShape } from "./zodSchema.js";

package/dist/operation.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Assembles a complete, named GraphQL operation document for a single root
+ * field, passing every argument as a variable (so values are never inlined into
+ * the query string — the executor's variable layer handles escaping/coercion).
+ *
+ * Example output for a `Mutation.createTodo(input: CreateTodoInput!)` field:
+ *
+ * ```graphql
+ * mutation createTodo($input: CreateTodoInput!) {
+ *   createTodo(input: $input) { id completed __typename }
+ * }
+ * ```
+ */
+import type { GraphQLField } from 'graphql';
+import type { OperationKind } from './types.ts';
+/** A built operation: the document plus the metadata needed to invoke it. */
+export interface BuiltOperation {
+    /** The operation document string. */
+    query: string;
+    /** The operation name (equal to the field name). */
+    operationName: string;
+    /** The field's argument names, in declared order. */
+    argNames: string[];
+}
+/**
+ * Builds the operation document for a root `field` of the given `kind`.
+ *
+ * @param kind - `'query'` or `'mutation'` — becomes the operation keyword.
+ * @param field - The root field to wrap.
+ * @param selectionDepth - Passed through to {@link buildSelectionSet} (default `2`).
+ * @returns The {@link BuiltOperation}.
+ */
+export declare function buildOperation(kind: OperationKind, field: GraphQLField<any, any>, selectionDepth?: number): BuiltOperation;

package/dist/operation.js

@@ -0,0 +1,34 @@
+/**
+ * Assembles a complete, named GraphQL operation document for a single root
+ * field, passing every argument as a variable (so values are never inlined into
+ * the query string — the executor's variable layer handles escaping/coercion).
+ *
+ * Example output for a `Mutation.createTodo(input: CreateTodoInput!)` field:
+ *
+ * ```graphql
+ * mutation createTodo($input: CreateTodoInput!) {
+ *   createTodo(input: $input) { id completed __typename }
+ * }
+ * ```
+ */
+import { buildSelectionSet } from "./selection.js";
+/**
+ * Builds the operation document for a root `field` of the given `kind`.
+ *
+ * @param kind - `'query'` or `'mutation'` — becomes the operation keyword.
+ * @param field - The root field to wrap.
+ * @param selectionDepth - Passed through to {@link buildSelectionSet} (default `2`).
+ * @returns The {@link BuiltOperation}.
+ */
+export function buildOperation(kind, 
+// biome-ignore lint/suspicious/noExplicitAny: a root field's source/context types are irrelevant here
+field, selectionDepth = 2) {
+    const variableDefs = field.args.map((arg) => `$${arg.name}: ${arg.type.toString()}`);
+    const argPassings = field.args.map((arg) => `${arg.name}: $${arg.name}`);
+    const varBlock = variableDefs.length ? `(${variableDefs.join(', ')})` : '';
+    const argBlock = argPassings.length ? `(${argPassings.join(', ')})` : '';
+    const selection = buildSelectionSet(field.type, selectionDepth);
+    const selectionBlock = selection ? ` ${selection}` : '';
+    const query = `${kind} ${field.name}${varBlock} {\n  ${field.name}${argBlock}${selectionBlock}\n}`;
+    return { query, operationName: field.name, argNames: field.args.map((arg) => arg.name) };
+}

package/dist/selection.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Auto-generates a GraphQL selection set for a field's return type.
+ *
+ * A tool call has no way to ask the AI "which fields do you want back?", so we
+ * select a sensible default: every scalar/enum leaf at each level, descending
+ * into nested object/interface/union types up to `maxDepth`. `__typename` is
+ * always included so the result is self-describing (and never an empty, invalid
+ * selection set).
+ *
+ * Two things are deliberately skipped (see TODO.md): fields that require
+ * arguments (we can't invent argument values) and types already on the current
+ * path (cycle guard).
+ */
+import { type GraphQLOutputType } from 'graphql';
+/**
+ * Builds a selection set string (e.g. `{ id name author { id __typename } }`)
+ * for a field's return `type`. Returns `''` when the type is a scalar/enum leaf
+ * (such a field takes no selection set).
+ *
+ * @param type - The field's return type (wrappers are unwrapped automatically).
+ * @param maxDepth - How many object levels deep to select. `1` = leaf fields of
+ *   the return type only; `2` (default) also expands one level of nested objects.
+ * @returns The selection set string, or `''` for a leaf return type.
+ */
+export declare function buildSelectionSet(type: GraphQLOutputType, maxDepth?: number): string;

package/dist/selection.js

@@ -0,0 +1,70 @@
+/**
+ * Auto-generates a GraphQL selection set for a field's return type.
+ *
+ * A tool call has no way to ask the AI "which fields do you want back?", so we
+ * select a sensible default: every scalar/enum leaf at each level, descending
+ * into nested object/interface/union types up to `maxDepth`. `__typename` is
+ * always included so the result is self-describing (and never an empty, invalid
+ * selection set).
+ *
+ * Two things are deliberately skipped (see TODO.md): fields that require
+ * arguments (we can't invent argument values) and types already on the current
+ * path (cycle guard).
+ */
+import { getNamedType, isEnumType, isInterfaceType, isNonNullType, isObjectType, isScalarType, isUnionType, } from 'graphql';
+/**
+ * Builds a selection set string (e.g. `{ id name author { id __typename } }`)
+ * for a field's return `type`. Returns `''` when the type is a scalar/enum leaf
+ * (such a field takes no selection set).
+ *
+ * @param type - The field's return type (wrappers are unwrapped automatically).
+ * @param maxDepth - How many object levels deep to select. `1` = leaf fields of
+ *   the return type only; `2` (default) also expands one level of nested objects.
+ * @returns The selection set string, or `''` for a leaf return type.
+ */
+export function buildSelectionSet(type, maxDepth = 2) {
+    return selectionFor(getNamedType(type), maxDepth, new Set());
+}
+/** Returns a `{ ... }` block for a composite type, or `''` for a leaf. */
+function selectionFor(named, depth, path) {
+    if (isScalarType(named) || isEnumType(named)) {
+        return '';
+    }
+    if (isUnionType(named)) {
+        const parts = ['__typename'];
+        for (const member of named.getTypes()) {
+            parts.push(`... on ${member.name} { ${compositeFields(member, depth, path)} }`);
+        }
+        return `{ ${parts.join(' ')} }`;
+    }
+    if (isObjectType(named) || isInterfaceType(named)) {
+        return `{ ${compositeFields(named, depth, path)} }`;
+    }
+    return '';
+}
+/** Joins the selectable fields of an object/interface type, always ending with `__typename`. */
+function compositeFields(type, depth, path) {
+    const selected = [];
+    const nextPath = new Set(path).add(type.name);
+    for (const [name, field] of Object.entries(type.getFields())) {
+        // Can't auto-select a field that requires arguments we don't have.
+        if (field.args.some((arg) => isNonNullType(arg.type) && arg.defaultValue === undefined)) {
+            continue;
+        }
+        const named = getNamedType(field.type);
+        if (isScalarType(named) || isEnumType(named)) {
+            selected.push(name);
+            continue;
+        }
+        // A composite field: only descend if we have depth left and aren't cycling.
+        if (depth <= 1 || path.has(named.name)) {
+            continue;
+        }
+        const sub = selectionFor(named, depth - 1, nextPath);
+        if (sub) {
+            selected.push(`${name} ${sub}`);
+        }
+    }
+    selected.push('__typename');
+    return selected.join(' ');
+}

package/dist/server.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Wires schema-derived {@link ToolDescriptor}s onto an `McpServer`, binding each
+ * to a {@link GraphqlExecutor}, and lets callers register custom tools that add
+ * to — or override, by name — the generated ones.
+ *
+ * Two entry points:
+ * - {@link createMcpServer} — a ready `McpServer` (use directly for stdio or a
+ *   single long-lived connection).
+ * - {@link createServerFactory} — builds the (pure) descriptors once and returns
+ *   a `() => McpServer` that mints a fresh server per call. The HTTP layer uses
+ *   this so each stateless request gets its own server+transport.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { GraphQLSchema } from 'graphql';
+import type { ZodRawShape } from 'zod';
+import { type BuildToolsOptions, type ToolDescriptor } from './tools.ts';
+import type { GraphqlExecutor, ToolAnnotations } from './types.ts';
+/** The handler signature for a custom tool: validated args plus the MCP `extra`. */
+export type ToolHandler = (args: Record<string, unknown>, extra: unknown) => CallToolResult | Promise<CallToolResult>;
+/**
+ * A user-supplied tool. If its `name` matches a generated tool, it replaces that
+ * tool; otherwise it's added. Omit `inputSchema` for a no-argument tool.
+ */
+export interface CustomTool {
+    name: string;
+    title?: string;
+    description: string;
+    inputSchema?: ZodRawShape;
+    annotations?: ToolAnnotations;
+    handler: ToolHandler;
+}
+/** Derives the per-call GraphQL context from the MCP request's `extra`. */
+export type ContextFactory = (extra: unknown) => unknown | Promise<unknown>;
+/** Options for {@link createMcpServer} / {@link createServerFactory}. */
+export interface CreateMcpServerOptions extends BuildToolsOptions {
+    /** The GraphQL schema to expose. */
+    schema: GraphQLSchema;
+    /** MCP server name advertised to clients. Default `'graphql-mcp-server'`. */
+    name?: string;
+    /** MCP server version. Default `'0.1.0'`. */
+    version?: string;
+    /**
+     * Where tool operations run. Default: {@link createLocalExecutor} against
+     * `schema`. Swap in {@link createHttpExecutor} to forward to a separate server.
+     */
+    executor?: GraphqlExecutor;
+    /**
+     * Per-call GraphQL context. A static value, or a factory of the MCP `extra`
+     * (which carries request/auth info under HTTP transport) — use the factory to
+     * derive auth context per request.
+     */
+    context?: unknown | ContextFactory;
+    /** Custom tools to add or override generated ones by name. */
+    tools?: CustomTool[];
+}
+/**
+ * Builds a single `McpServer` with all generated and custom tools registered.
+ *
+ * For stateless HTTP, prefer {@link createHttpHandler} (which gives each request
+ * its own server). Use this directly for stdio or a single persistent session.
+ *
+ * @param options - Schema, executor, context, and tool options.
+ */
+export declare function createMcpServer(options: CreateMcpServerOptions): McpServer;
+/** A factory minting fresh `McpServer`s; an optional arg overrides the call context. */
+export type ServerFactory = (contextOverride?: unknown | ContextFactory) => McpServer;
+/**
+ * Builds the tool descriptors once and returns a factory that mints a fresh
+ * `McpServer` (with those tools registered) on each call. The factory accepts an
+ * optional context override so per-request callers (e.g. the HTTP handler) can
+ * supply request-derived context without rebuilding the descriptors.
+ *
+ * @param options - Schema, executor, context, and tool options.
+ * @returns A {@link ServerFactory}.
+ */
+export declare function createServerFactory(options: CreateMcpServerOptions): ServerFactory;
+/**
+ * Registers schema-derived `descriptors` onto an existing `server`, binding each
+ * to `executor`. The lower-level building block behind {@link createMcpServer};
+ * use it when you manage the `McpServer` lifecycle yourself.
+ *
+ * @param server - The MCP server to register tools on.
+ * @param descriptors - Tool descriptors (from `buildTools`).
+ * @param executor - Where the tools' operations run.
+ * @param context - Per-call GraphQL context (value or factory of MCP `extra`).
+ */
+export declare function registerGraphqlTools(server: McpServer, descriptors: ToolDescriptor[], executor: GraphqlExecutor, context?: unknown | ContextFactory): void;

package/dist/server.js

@@ -0,0 +1,116 @@
+/**
+ * Wires schema-derived {@link ToolDescriptor}s onto an `McpServer`, binding each
+ * to a {@link GraphqlExecutor}, and lets callers register custom tools that add
+ * to — or override, by name — the generated ones.
+ *
+ * Two entry points:
+ * - {@link createMcpServer} — a ready `McpServer` (use directly for stdio or a
+ *   single long-lived connection).
+ * - {@link createServerFactory} — builds the (pure) descriptors once and returns
+ *   a `() => McpServer` that mints a fresh server per call. The HTTP layer uses
+ *   this so each stateless request gets its own server+transport.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { createLocalExecutor } from "./executor.js";
+import { buildTools } from "./tools.js";
+/**
+ * Builds a single `McpServer` with all generated and custom tools registered.
+ *
+ * For stateless HTTP, prefer {@link createHttpHandler} (which gives each request
+ * its own server). Use this directly for stdio or a single persistent session.
+ *
+ * @param options - Schema, executor, context, and tool options.
+ */
+export function createMcpServer(options) {
+    return createServerFactory(options)();
+}
+/**
+ * Builds the tool descriptors once and returns a factory that mints a fresh
+ * `McpServer` (with those tools registered) on each call. The factory accepts an
+ * optional context override so per-request callers (e.g. the HTTP handler) can
+ * supply request-derived context without rebuilding the descriptors.
+ *
+ * @param options - Schema, executor, context, and tool options.
+ * @returns A {@link ServerFactory}.
+ */
+export function createServerFactory(options) {
+    const descriptors = buildTools(options.schema, options);
+    const executor = options.executor ?? createLocalExecutor(options.schema);
+    const customTools = options.tools ?? [];
+    const overridden = new Set(customTools.map((tool) => tool.name));
+    return (contextOverride) => {
+        const context = contextOverride ?? options.context;
+        const server = new McpServer({
+            name: options.name ?? 'graphql-mcp-server',
+            version: options.version ?? '0.1.0',
+        });
+        for (const descriptor of descriptors) {
+            if (overridden.has(descriptor.name))
+                continue;
+            registerGeneratedTool(server, descriptor, executor, context);
+        }
+        for (const tool of customTools) {
+            registerCustomTool(server, tool);
+        }
+        return server;
+    };
+}
+/**
+ * Registers schema-derived `descriptors` onto an existing `server`, binding each
+ * to `executor`. The lower-level building block behind {@link createMcpServer};
+ * use it when you manage the `McpServer` lifecycle yourself.
+ *
+ * @param server - The MCP server to register tools on.
+ * @param descriptors - Tool descriptors (from `buildTools`).
+ * @param executor - Where the tools' operations run.
+ * @param context - Per-call GraphQL context (value or factory of MCP `extra`).
+ */
+export function registerGraphqlTools(server, descriptors, executor, context) {
+    for (const descriptor of descriptors) {
+        registerGeneratedTool(server, descriptor, executor, context);
+    }
+}
+function registerGeneratedTool(server, descriptor, executor, context) {
+    server.registerTool(descriptor.name, {
+        title: descriptor.title,
+        description: descriptor.description,
+        inputSchema: descriptor.inputSchema,
+        annotations: descriptor.annotations,
+    }, async (args, extra) => {
+        const variables = {};
+        for (const argName of descriptor.argNames) {
+            if (args[argName] !== undefined)
+                variables[argName] = args[argName];
+        }
+        const resolvedContext = await resolveContext(context, extra);
+        const result = await executor({
+            query: descriptor.query,
+            variables,
+            operationName: descriptor.name,
+            context: resolvedContext,
+        });
+        return toCallToolResult(result);
+    });
+}
+function registerCustomTool(server, tool) {
+    // The SDK's overloads differ by whether `inputSchema` is present; cast the
+    // config/handler at this boundary so callers get a single clean `CustomTool`.
+    const config = {
+        title: tool.title,
+        description: tool.description,
+        annotations: tool.annotations,
+        ...(tool.inputSchema ? { inputSchema: tool.inputSchema } : {}),
+    };
+    // biome-ignore lint/suspicious/noExplicitAny: bridging our uniform CustomTool to the SDK's split overloads
+    server.registerTool(tool.name, config, tool.handler);
+}
+async function resolveContext(context, extra) {
+    return typeof context === 'function' ? await context(extra) : context;
+}
+/** Wraps a GraphQL result as an MCP tool result; flags GraphQL errors as `isError`. */
+function toCallToolResult(result) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        isError: Boolean(result.errors?.length),
+    };
+}

package/dist/tools.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Turns a `GraphQLSchema` into a flat list of {@link ToolDescriptor}s — one per
+ * `Query`/`Mutation` root field. This is the heart of the wrapper: it reads the
+ * SDL (field + argument descriptions, types) and projects each operation into an
+ * MCP tool whose name, description, and input schema mirror the GraphQL surface
+ * one-to-one.
+ *
+ * Descriptors are pure data (no SDK, no executor). `registerGraphqlTools` binds
+ * them to an executor and an `McpServer`.
+ */
+import type { GraphQLField, GraphQLSchema } from 'graphql';
+import type { ZodRawShape } from 'zod';
+import type { OperationKind, ToolAnnotations } from './types.ts';
+/** A schema-derived MCP tool, prior to being bound to an executor/server. */
+export interface ToolDescriptor {
+    /** Tool name (the GraphQL field name, unless remapped via `toolName`). */
+    name: string;
+    /** Whether this came from `Query` or `Mutation`. */
+    kind: OperationKind;
+    /** Human-friendly title (e.g. `Create Todo`). */
+    title: string;
+    /** Full tool description, derived from the SDL. */
+    description: string;
+    /** Zod raw shape for the field's arguments (the tool `inputSchema`). */
+    inputSchema: ZodRawShape;
+    /** MCP behaviour hints, defaulted from the operation kind. */
+    annotations: ToolAnnotations;
+    /** The pre-built operation document this tool runs. */
+    query: string;
+    /** The field's argument names (used to pluck variables from validated input). */
+    argNames: string[];
+}
+/** Options controlling which fields become tools and how they're named. */
+export interface BuildToolsOptions {
+    /** Wrap `Query` fields as tools. Default `true`. */
+    includeQueries?: boolean;
+    /** Wrap `Mutation` fields as tools. Default `true`. */
+    includeMutations?: boolean;
+    /** Selection-set depth for return types (see `buildSelectionSet`). Default `2`. */
+    selectionDepth?: number;
+    /** Keep a field only when this returns `true`. Receives the field and its kind. */
+    filter?: (field: GraphQLField<any, any>, kind: OperationKind) => boolean;
+    /** Map a field to a custom tool name. Default: the field name verbatim. */
+    toolName?: (field: GraphQLField<any, any>, kind: OperationKind) => string;
+}
+/**
+ * Builds the {@link ToolDescriptor}s for a schema's root fields.
+ *
+ * @param schema - The GraphQL schema to wrap.
+ * @param options - Inclusion, depth, filtering, and naming options.
+ * @returns One descriptor per included root field.
+ * @throws If two included fields map to the same tool name (e.g. a query and a
+ *   mutation share a name) — resolve the clash with `toolName` or `filter`.
+ */
+export declare function buildTools(schema: GraphQLSchema, options?: BuildToolsOptions): ToolDescriptor[];

package/dist/tools.js

@@ -0,0 +1,98 @@
+/**
+ * Turns a `GraphQLSchema` into a flat list of {@link ToolDescriptor}s — one per
+ * `Query`/`Mutation` root field. This is the heart of the wrapper: it reads the
+ * SDL (field + argument descriptions, types) and projects each operation into an
+ * MCP tool whose name, description, and input schema mirror the GraphQL surface
+ * one-to-one.
+ *
+ * Descriptors are pure data (no SDK, no executor). `registerGraphqlTools` binds
+ * them to an executor and an `McpServer`.
+ */
+import { buildOperation } from "./operation.js";
+import { argsToZodShape } from "./zodSchema.js";
+/**
+ * Builds the {@link ToolDescriptor}s for a schema's root fields.
+ *
+ * @param schema - The GraphQL schema to wrap.
+ * @param options - Inclusion, depth, filtering, and naming options.
+ * @returns One descriptor per included root field.
+ * @throws If two included fields map to the same tool name (e.g. a query and a
+ *   mutation share a name) — resolve the clash with `toolName` or `filter`.
+ */
+export function buildTools(schema, options = {}) {
+    const { includeQueries = true, includeMutations = true } = options;
+    const descriptors = [];
+    const seen = new Set();
+    const collect = (root, kind) => {
+        if (!root)
+            return;
+        for (const field of Object.values(root.getFields())) {
+            if (options.filter && !options.filter(field, kind))
+                continue;
+            const name = options.toolName ? options.toolName(field, kind) : field.name;
+            if (seen.has(name)) {
+                throw new Error(`graphql-mcp: duplicate tool name '${name}'. A query and mutation field likely ` +
+                    'collide — disambiguate with the `toolName` or `filter` option.');
+            }
+            seen.add(name);
+            descriptors.push(toDescriptor(name, field, kind, options.selectionDepth));
+        }
+    };
+    if (includeQueries)
+        collect(schema.getQueryType(), 'query');
+    if (includeMutations)
+        collect(schema.getMutationType(), 'mutation');
+    return descriptors;
+}
+function toDescriptor(name, 
+// biome-ignore lint/suspicious/noExplicitAny: a root field's source/context types are irrelevant here
+field, kind, selectionDepth) {
+    const { query, argNames } = buildOperation(kind, field, selectionDepth);
+    return {
+        name,
+        kind,
+        title: humanize(field.name),
+        description: buildDescription(field, kind),
+        inputSchema: argsToZodShape(field.args),
+        annotations: annotationsFor(kind, humanize(field.name)),
+        query,
+        argNames,
+    };
+}
+/** Composes a tool description from the field's SDL: docstring, signature, and args. */
+// biome-ignore lint/suspicious/noExplicitAny: a root field's source/context types are irrelevant here
+function buildDescription(field, kind) {
+    const lines = [];
+    lines.push(field.description?.trim() || `The \`${field.name}\` ${kind}.`);
+    lines.push('');
+    lines.push(`GraphQL ${kind}: \`${field.name}\` → \`${field.type.toString()}\``);
+    if (field.args.length) {
+        lines.push('');
+        lines.push('Arguments:');
+        for (const arg of field.args) {
+            const desc = arg.description ? ` — ${arg.description.trim()}` : '';
+            lines.push(`- \`${arg.name}\`: \`${arg.type.toString()}\`${desc}`);
+        }
+    }
+    return lines.join('\n');
+}
+/** Default MCP annotations: queries are read-only/idempotent, mutations are writes. */
+function annotationsFor(kind, title) {
+    const isQuery = kind === 'query';
+    return {
+        title,
+        readOnlyHint: isQuery,
+        destructiveHint: !isQuery,
+        idempotentHint: isQuery,
+        // Tools reach a GraphQL backend, whose data lives outside this server.
+        openWorldHint: true,
+    };
+}
+/** `createTodo` → `Create Todo`; `me` → `Me`. */
+function humanize(fieldName) {
+    const spaced = fieldName
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/[_-]+/g, ' ')
+        .trim();
+    return spaced.replace(/\b\w/g, (char) => char.toUpperCase());
+}

package/dist/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Core shared types. Pure types — no runtime, no internal dependencies.
+ *
+ * The central abstraction is {@link GraphqlExecutor}: the single seam between a
+ * generated MCP tool and "where GraphQL actually runs". The default executor
+ * (`createLocalExecutor`) runs the operation against the in-process schema, but
+ * a tool never knows the difference — swap in `createHttpExecutor` to forward to
+ * a separate GraphQL server running side-by-side instead.
+ */
+/** Whether a root field originates from the schema's `Query` or `Mutation` type. */
+export type OperationKind = 'query' | 'mutation';
+/** A single GraphQL error, mirroring the spec's error shape. */
+export interface GraphqlError {
+    message: string;
+    path?: ReadonlyArray<string | number>;
+    [key: string]: any;
+}
+/** A GraphQL execution result, mirroring the spec's `{ data, errors }` envelope. */
+export interface GraphqlResult {
+    data?: Record<string, unknown> | null;
+    errors?: ReadonlyArray<GraphqlError>;
+}
+/** A GraphQL request as produced from a tool call: a document plus its variables. */
+export interface GraphqlRequest {
+    /** The operation document — a `query`/`mutation` string. */
+    query: string;
+    /** Variables keyed by the root field's argument names. */
+    variables: Record<string, unknown>;
+    /** The operation name (equal to the tool / root-field name). */
+    operationName: string;
+    /**
+     * Per-call context, opaque to the tool layer. Forwarded as the GraphQL
+     * `contextValue` (local executor) or used to derive request headers (HTTP
+     * executor). Typically derived from the MCP request via the `context` option.
+     */
+    context?: unknown;
+}
+/**
+ * Runs a GraphQL operation and returns its `{ data, errors }` result.
+ *
+ * This is the one place the library is decoupled from execution: implement it
+ * (or use {@link createLocalExecutor} / {@link createHttpExecutor}) to run tools
+ * against an in-process schema, a remote endpoint, or anything else.
+ */
+export type GraphqlExecutor = (request: GraphqlRequest) => Promise<GraphqlResult>;
+/**
+ * MCP tool behaviour hints. Mirrors the SDK's `ToolAnnotations` (kept local so
+ * the type helpers don't depend on SDK internals); all fields are optional.
+ */
+export interface ToolAnnotations {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}

package/dist/types.js

@@ -0,0 +1,10 @@
+/**
+ * Core shared types. Pure types — no runtime, no internal dependencies.
+ *
+ * The central abstraction is {@link GraphqlExecutor}: the single seam between a
+ * generated MCP tool and "where GraphQL actually runs". The default executor
+ * (`createLocalExecutor`) runs the operation against the in-process schema, but
+ * a tool never knows the difference — swap in `createHttpExecutor` to forward to
+ * a separate GraphQL server running side-by-side instead.
+ */
+export {};

package/dist/zodSchema.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Converts a GraphQL field's arguments into a Zod "raw shape" — the input-schema
+ * form the MCP SDK's `registerTool` expects. Written by hand (rather than pulling
+ * in a graphql-to-zod dependency) because the mapping is small and we want full
+ * control over nullability, descriptions, and custom-scalar fallbacks.
+ *
+ * Mapping rules:
+ * - `NonNull` → required (no `.nullish()`); a nullable arg/field becomes `.nullish()`
+ * - `List` → `z.array(element)`
+ * - built-in scalars → `Int`/`Float` ⇒ number, `String`/`ID` ⇒ string, `Boolean` ⇒ boolean
+ * - custom scalars → `z.any()` (the server still validates them) tagged with the scalar name
+ * - enums → `z.enum([...names])` (enum *names*, the form passed as GraphQL variables)
+ * - input objects → `z.object({...})`, recursively; a recursive input type falls back
+ *   to `z.any()` once revisited (a pragmatic MVP guard — see TODO.md)
+ */
+import { type GraphQLArgument } from 'graphql';
+import { type ZodRawShape } from 'zod';
+/**
+ * Builds a Zod raw shape (`{ argName: ZodType }`) from a GraphQL field's
+ * arguments, ready to pass as a tool's `inputSchema`. Non-null args are required;
+ * nullable args are optional. Each arg's GraphQL description is carried onto its
+ * Zod type so it shows up in the tool's generated JSON Schema.
+ *
+ * @param args - The field's arguments (`field.args`).
+ * @returns A Zod raw shape; empty (`{}`) for a field with no arguments.
+ */
+export declare function argsToZodShape(args: ReadonlyArray<GraphQLArgument>): ZodRawShape;

package/dist/zodSchema.js

@@ -0,0 +1,80 @@
+/**
+ * Converts a GraphQL field's arguments into a Zod "raw shape" — the input-schema
+ * form the MCP SDK's `registerTool` expects. Written by hand (rather than pulling
+ * in a graphql-to-zod dependency) because the mapping is small and we want full
+ * control over nullability, descriptions, and custom-scalar fallbacks.
+ *
+ * Mapping rules:
+ * - `NonNull` → required (no `.nullish()`); a nullable arg/field becomes `.nullish()`
+ * - `List` → `z.array(element)`
+ * - built-in scalars → `Int`/`Float` ⇒ number, `String`/`ID` ⇒ string, `Boolean` ⇒ boolean
+ * - custom scalars → `z.any()` (the server still validates them) tagged with the scalar name
+ * - enums → `z.enum([...names])` (enum *names*, the form passed as GraphQL variables)
+ * - input objects → `z.object({...})`, recursively; a recursive input type falls back
+ *   to `z.any()` once revisited (a pragmatic MVP guard — see TODO.md)
+ */
+import { isEnumType, isInputObjectType, isListType, isNonNullType, isScalarType, } from 'graphql';
+import { z } from 'zod';
+const SCALAR_BUILDERS = {
+    Int: () => z.number().int(),
+    Float: () => z.number(),
+    String: () => z.string(),
+    Boolean: () => z.boolean(),
+    ID: () => z.string(),
+};
+/** Applies an element/field type's nullability: required for `NonNull`, else `.nullish()`. */
+function fieldToZod(type, seen) {
+    if (isNonNullType(type)) {
+        return baseToZod(type.ofType, seen);
+    }
+    return baseToZod(type, seen).nullish();
+}
+/** Builds the Zod type for a (already nullability-stripped) list/named GraphQL type. */
+function baseToZod(type, seen) {
+    if (isListType(type)) {
+        return z.array(fieldToZod(type.ofType, seen));
+    }
+    if (isScalarType(type)) {
+        const builder = SCALAR_BUILDERS[type.name];
+        return builder ? builder() : z.any().describe(`Custom scalar ${type.name}`);
+    }
+    if (isEnumType(type)) {
+        const names = type.getValues().map((value) => value.name);
+        // An enum with no values can't happen in a valid schema, but guard the cast.
+        return names.length ? z.enum(names) : z.string();
+    }
+    if (isInputObjectType(type)) {
+        // Recursive input types (e.g. nested filter inputs) would recurse forever;
+        // once a type reappears on the current path, fall back to an opaque value.
+        if (seen.has(type.name)) {
+            return z.any().describe(`Recursive input ${type.name}`);
+        }
+        const next = new Set(seen).add(type.name);
+        const shape = {};
+        for (const [name, field] of Object.entries(type.getFields())) {
+            shape[name] = describe(fieldToZod(field.type, next), field.description);
+        }
+        return z.object(shape);
+    }
+    // Unreachable for valid input types; keep type-checking happy and fail soft.
+    return z.any();
+}
+function describe(schema, description) {
+    return description ? schema.describe(description) : schema;
+}
+/**
+ * Builds a Zod raw shape (`{ argName: ZodType }`) from a GraphQL field's
+ * arguments, ready to pass as a tool's `inputSchema`. Non-null args are required;
+ * nullable args are optional. Each arg's GraphQL description is carried onto its
+ * Zod type so it shows up in the tool's generated JSON Schema.
+ *
+ * @param args - The field's arguments (`field.args`).
+ * @returns A Zod raw shape; empty (`{}`) for a field with no arguments.
+ */
+export function argsToZodShape(args) {
+    const shape = {};
+    for (const arg of args) {
+        shape[arg.name] = describe(fieldToZod(arg.type, new Set()), arg.description);
+    }
+    return shape;
+}

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@cubicecho/graphql-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Turn a GraphQL schema into a Model Context Protocol (MCP) server: each query/mutation becomes a tool, runnable side-by-side with your GraphQL server.",
+  "license": "MIT",
+  "author": "Benjamin Van Treese",
   "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cubicecho/graphql-mcp.git"
@@ -24,7 +29,8 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
     "typecheck": "tsc --noEmit",
     "typecheck:tests": "tsc -p tsconfig.tests.json",
     "test": "node --test --experimental-strip-types \"src/**/*.test.ts\"",