@letoribo/mcp-graphql-enhanced 2.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Boris Besemer
+
+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/README.md

@@ -0,0 +1,106 @@
+# mcp-graphql-enhanced
+
+[![Smithery](https://smithery.ai/badge/mcp-graphql-enhanced)](https://smithery.ai/server/mcp-graphql-enhanced)
+[![Glama](https://glama.ai/mcp/servers/@letoribo/mcp-graphql-enhanced)](https://glama.ai/mcp/servers/@letoribo/mcp-graphql-enhanced)
+
+An **enhanced MCP (Model Context Protocol) server for GraphQL** that fixes real-world interoperability issues between LLMs and GraphQL APIs.
+
+> Drop-in replacement for `mcp-graphql` — with dynamic headers, robust variables parsing, and zero breaking changes.
+
+## ✨ Key Enhancements
+
+- ✅ **Dynamic headers** — pass `Authorization`, `X-API-Key`, etc., via tool arguments (no config restarts)
+- ✅ **Robust variables parsing** — fixes `“Query variables must be a null or an object”` error
+- ✅ **Full MCP compatibility** — works with **Claude Desktop**, **Cursor**, **Glama**, and **Smithery**
+- ✅ **Secure by default** — mutations disabled unless explicitly enabled
+
+## 🔍 Debug & Inspect
+
+Use the official MCP Inspector to test your server live:
+
+```bash
+npx @modelcontextprotocol/inspector \
+  -e ENDPOINT=https://api.example.com/graphql \
+  npx mcp-graphql-enhanced --debug
+```
+
+### Environment Variables (Breaking change in 1.0.0)
+
+> **Note:** As of version 1.0.0, command line arguments have been replaced with environment variables.
+
+| Environment Variable | Description | Default |
+|----------|-------------|---------|
+| `ENDPOINT` | GraphQL endpoint URL | `http://localhost:4000/graphql` |
+| `HEADERS` | JSON string containing headers for requests | `{}` |
+| `ALLOW_MUTATIONS` | Enable mutation operations (disabled by default) | `false` |
+| `NAME` | Name of the MCP server | `mcp-graphql-enhanced` |
+| `SCHEMA` | Path to a local GraphQL schema file or URL (optional) | - |
+
+### Examples
+
+```bash
+# Basic usage
+ENDPOINT=http://localhost:3000/graphql npx mcp-graphql-enhanced
+
+# With auth header
+ENDPOINT=https://api.example.com/graphql \
+HEADERS='{"Authorization":"Bearer xyz"}' \
+npx mcp-graphql-enhanced
+
+# Enable mutations
+ENDPOINT=http://localhost:3000/graphql \
+ALLOW_MUTATIONS=true \
+npx mcp-graphql-enhanced
+
+# Use local schema file
+ENDPOINT=http://localhost:3000/graphql \
+SCHEMA=./schema.graphql \
+npx mcp-graphql-enhanced
+```
+
+## Resources
+
+- **graphql-schema**: The server exposes the GraphQL schema as a resource that clients can access. This is either the local schema file, a schema file hosted at a URL, or based on an introspection query.
+
+## Available Tools
+
+The server provides two main tools:
+
+1. **introspect-schema**: This tool retrieves the GraphQL schema. Use this first if you don't have access to the schema as a resource.
+This uses either the local schema file, a schema file hosted at a URL, or an introspection query.
+
+2. **query-graphql**: Execute GraphQL queries against the endpoint. By default, mutations are disabled unless `ALLOW_MUTATIONS` is set to `true`.
+
+## Installation
+
+### Installing via Smithery
+
+To install GraphQL MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mcp-graphql-enhanced):
+
+```bash
+npx -y @smithery/cli install mcp-graphql-enhanced --client claude
+```
+
+### Installing Manually
+
+It can be manually installed to Claude:
+```json
+{
+    "mcpServers": {
+        "mcp-graphql": {
+            "command": "npx",
+            "args": ["mcp-graphql-enhanced"],
+            "env": {
+                "ENDPOINT": "https://your-api.com/graphql"
+            }
+        }
+    }
+}
+```
+
+## Security Considerations
+
+Mutations are disabled by default to prevent unintended data changes. Always validate HEADERS and SCHEMA inputs in production. Use HTTPS endpoints and short-lived tokens where possible.
+## Customize for your own server
+
+This is a very generic implementation where it allows for complete introspection and for your users to do whatever (including mutations). If you need a more specific implementation I'd suggest to just create your own MCP and lock down tool calling for clients to only input specific query fields and/or variables. You can use this as a reference.

package/dist/helpers/deprecation.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Helper module for handling deprecation warnings
+ */
+/**
+ * Check for deprecated command line arguments and output warnings
+ */
+export declare function checkDeprecatedArguments(): void;
+//# sourceMappingURL=deprecation.d.ts.map

package/dist/helpers/deprecation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deprecation.d.ts","sourceRoot":"","sources":["../../src/helpers/deprecation.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CA0B/C"}

package/dist/helpers/deprecation.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * Helper module for handling deprecation warnings
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkDeprecatedArguments = checkDeprecatedArguments;
+/**
+ * Check for deprecated command line arguments and output warnings
+ */
+function checkDeprecatedArguments() {
+    const deprecatedArgs = [
+        "--endpoint",
+        "--headers",
+        "--enable-mutations",
+        "--name",
+        "--schema",
+    ];
+    const usedDeprecatedArgs = deprecatedArgs.filter((arg) => process.argv.includes(arg));
+    if (usedDeprecatedArgs.length > 0) {
+        console.error(`WARNING: Deprecated command line arguments detected: ${usedDeprecatedArgs.join(", ")}`);
+        console.error("As of version 1.0.0, command line arguments have been replaced with environment variables.");
+        console.error("Please use environment variables instead. For example:");
+        console.error("  Instead of: npx mcp-graphql --endpoint http://example.com/graphql");
+        console.error("  Use: ENDPOINT=http://example.com/graphql npx mcp-graphql");
+        console.error("");
+    }
+}

package/dist/helpers/headers.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Parse and merge headers from various sources
+ * @param configHeaders - Default headers from configuration
+ * @param inputHeaders - Headers provided by the user (string or object)
+ * @returns Merged headers object
+ */
+export declare function parseAndMergeHeaders(configHeaders: Record<string, string>, inputHeaders?: string | Record<string, string>): Record<string, string>;
+//# sourceMappingURL=headers.d.ts.map

package/dist/helpers/headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../../src/helpers/headers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,oBAAoB,CACnC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACrC,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBxB"}

package/dist/helpers/headers.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseAndMergeHeaders = parseAndMergeHeaders;
+/**
+ * Parse and merge headers from various sources
+ * @param configHeaders - Default headers from configuration
+ * @param inputHeaders - Headers provided by the user (string or object)
+ * @returns Merged headers object
+ */
+function parseAndMergeHeaders(configHeaders, inputHeaders) {
+    // Parse headers if they're provided as a string
+    let parsedHeaders = {};
+    if (typeof inputHeaders === "string") {
+        try {
+            parsedHeaders = JSON.parse(inputHeaders);
+        }
+        catch (e) {
+            throw new Error(`Invalid headers JSON: ${e}`);
+        }
+    }
+    else if (inputHeaders) {
+        parsedHeaders = inputHeaders;
+    }
+    // Merge with config headers (config headers are overridden by input headers)
+    return { ...configHeaders, ...parsedHeaders };
+}

package/dist/helpers/introspection.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Introspect a GraphQL endpoint and return the schema as the GraphQL SDL
+ * @param endpoint - The endpoint to introspect
+ * @param headers - Optional headers to include in the request
+ * @returns The schema
+ */
+export declare function introspectEndpoint(endpoint: string, headers?: Record<string, string>): Promise<string>;
+/**
+ * Introspect a GraphQL schema file hosted at a URL and return the schema as the GraphQL SDL
+ * @param url - The URL to the schema file
+ * @returns The schema
+ */
+export declare function introspectSchemaFromUrl(url: string): Promise<string>;
+/**
+ * Introspect a local GraphQL schema file and return the schema as the GraphQL SDL
+ * @param path - The path to the local schema file
+ * @returns The schema
+ */
+export declare function introspectLocalSchema(path: string): Promise<string>;
+//# sourceMappingURL=introspection.d.ts.map

package/dist/helpers/introspection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspection.d.ts","sourceRoot":"","sources":["../../src/helpers/introspection.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACvC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,mBAuBhC;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAAC,GAAG,EAAE,MAAM,mBASxD;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,mBAGvD"}

package/dist/helpers/introspection.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.introspectEndpoint = introspectEndpoint;
+exports.introspectSchemaFromUrl = introspectSchemaFromUrl;
+exports.introspectLocalSchema = introspectLocalSchema;
+const graphql_1 = require("graphql");
+const promises_1 = require("node:fs/promises");
+/**
+ * Introspect a GraphQL endpoint and return the schema as the GraphQL SDL
+ * @param endpoint - The endpoint to introspect
+ * @param headers - Optional headers to include in the request
+ * @returns The schema
+ */
+async function introspectEndpoint(endpoint, headers) {
+    const response = await fetch(endpoint, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            ...headers,
+        },
+        body: JSON.stringify({
+            query: (0, graphql_1.getIntrospectionQuery)(),
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`GraphQL request failed: ${response.statusText}`);
+    }
+    const responseJson = await response.json();
+    // Transform to a schema object
+    const schema = (0, graphql_1.buildClientSchema)(responseJson.data);
+    // Print the schema SDL
+    return (0, graphql_1.printSchema)(schema);
+}
+/**
+ * Introspect a GraphQL schema file hosted at a URL and return the schema as the GraphQL SDL
+ * @param url - The URL to the schema file
+ * @returns The schema
+ */
+async function introspectSchemaFromUrl(url) {
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch schema from URL: ${response.statusText}`);
+    }
+    const schema = await response.text();
+    return schema;
+}
+/**
+ * Introspect a local GraphQL schema file and return the schema as the GraphQL SDL
+ * @param path - The path to the local schema file
+ * @returns The schema
+ */
+async function introspectLocalSchema(path) {
+    const schema = await (0, promises_1.readFile)(path, "utf8");
+    return schema;
+}

package/dist/helpers/package.d.ts

@@ -0,0 +1,2 @@
+export declare function getVersion(): any;
+//# sourceMappingURL=package.d.ts.map

package/dist/helpers/package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.d.ts","sourceRoot":"","sources":["../../src/helpers/package.ts"],"names":[],"mappings":"AAOA,wBAAgB,UAAU,QAEzB"}

package/dist/helpers/package.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getVersion = getVersion;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const packageJson = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(__dirname, "../../package.json"), "utf-8"));
+function getVersion() {
+    return packageJson.version;
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+declare const McpServer: any;
+declare const StdioServerTransport: any;
+declare const parse: any;
+declare const z: any;
+declare const checkDeprecatedArguments: any;
+declare const introspectEndpoint: any, introspectLocalSchema: any, introspectSchemaFromUrl: any;
+declare const getVersion: () => any;
+declare const EnvSchema: any;
+declare const env: any;
+declare const server: any;
+declare function main(): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,QAAA,MAAQ,SAAS,KAAuD,CAAC;AACzE,QAAA,MAAQ,oBAAoB,KAAyD,CAAC;AACtF,QAAA,MAAQ,KAAK,KAAgC,CAAC;AAC9C,QAAA,MAAM,CAAC,KAAyB,CAAC;AACjC,QAAA,MAAQ,wBAAwB,KAAwC,CAAC;AACzE,QAAA,MACC,kBAAkB,OAClB,qBAAqB,OACrB,uBAAuB,KACiB,CAAC;AAG1C,QAAA,MAAM,UAAU,WAIf,CAAC;AAKF,QAAA,MAAM,SAAS,KAkBb,CAAC;AAEH,QAAA,MAAM,GAAG,KAA+B,CAAC;AAEzC,QAAA,MAAM,MAAM,KAIV,CAAC;AAoMH,iBAAe,IAAI,kBAOlB"}

package/dist/index.js

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+"use strict";
+const { McpServer } = require("@modelcontextprotocol/sdk/server/mcp.js");
+const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
+const { parse } = require("graphql/language");
+const z = require("zod").default;
+const { checkDeprecatedArguments } = require("./helpers/deprecation.js");
+const { introspectEndpoint, introspectLocalSchema, introspectSchemaFromUrl, } = require("./helpers/introspection.js");
+// Simulate macro import — since "with { type: 'macro' }" is not CommonJS compatible
+const getVersion = () => {
+    // Replace with your actual version or read from package.json
+    const pkg = require("../package.json");
+    return pkg.version;
+};
+// Check for deprecated command line arguments
+checkDeprecatedArguments();
+const EnvSchema = z.object({
+    NAME: z.string().default("mcp-graphql"),
+    ENDPOINT: z.string().url().default("http://localhost:4000/graphql"),
+    ALLOW_MUTATIONS: z
+        .enum(["true", "false"])
+        .transform((value) => value === "true")
+        .default("false"),
+    HEADERS: z
+        .string()
+        .default("{}")
+        .transform((val) => {
+        try {
+            return JSON.parse(val);
+        }
+        catch (e) {
+            throw new Error("HEADERS must be a valid JSON string");
+        }
+    }),
+    SCHEMA: z.string().optional(),
+});
+const env = EnvSchema.parse(process.env);
+const server = new McpServer({
+    name: env.NAME,
+    version: getVersion(),
+    description: `GraphQL MCP server for ${env.ENDPOINT}`,
+});
+server.resource("graphql-schema", new URL(env.ENDPOINT).href, async (uri) => {
+    try {
+        let schema;
+        if (env.SCHEMA) {
+            if (env.SCHEMA.startsWith("http://") ||
+                env.SCHEMA.startsWith("https://")) {
+                schema = await introspectSchemaFromUrl(env.SCHEMA);
+            }
+            else {
+                schema = await introspectLocalSchema(env.SCHEMA);
+            }
+        }
+        else {
+            schema = await introspectEndpoint(env.ENDPOINT, env.HEADERS);
+        }
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: schema,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to get GraphQL schema: ${error}`);
+    }
+});
+server.tool("introspect-schema", "Introspect the GraphQL schema, use this tool before doing a query to get the schema information if you do not have it available as a resource already.", {
+    __ignore__: z
+        .boolean()
+        .default(false)
+        .describe("This does not do anything"),
+}, async () => {
+    try {
+        let schema;
+        if (env.SCHEMA) {
+            schema = await introspectLocalSchema(env.SCHEMA);
+        }
+        else {
+            schema = await introspectEndpoint(env.ENDPOINT, env.HEADERS);
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: schema,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to introspect schema: ${error}`,
+                },
+            ],
+        };
+    }
+});
+server.tool("query-graphql", "Query a GraphQL endpoint with the given query and variables. Optionally pass headers (e.g., for Authorization).", {
+    query: z.string(),
+    variables: z.string().optional(),
+    headers: z
+        .string()
+        .optional()
+        .describe("Optional JSON string of headers to include, e.g., {\"Authorization\": \"Bearer ...\"}"),
+}, async ({ query, variables, headers }) => {
+    try {
+        const parsedQuery = parse(query);
+        const isMutation = parsedQuery.definitions.some((def) => def.kind === "OperationDefinition" && def.operation === "mutation");
+        if (isMutation && !env.ALLOW_MUTATIONS) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: "Mutations are not allowed unless you enable them in the configuration. Please use a query operation instead.",
+                    },
+                ],
+            };
+        }
+    }
+    catch (error) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: `Invalid GraphQL query: ${error}`,
+                },
+            ],
+        };
+    }
+    try {
+        const toolHeaders = headers
+            ? JSON.parse(headers)
+            : {};
+        const allHeaders = {
+            "Content-Type": "application/json",
+            ...env.HEADERS,
+            ...toolHeaders,
+        };
+        // Parse variables if it's a string
+        let parsedVariables = null;
+        if (variables) {
+            if (typeof variables === 'string') {
+                parsedVariables = JSON.parse(variables);
+            }
+            else {
+                parsedVariables = variables;
+            }
+        }
+        const response = await fetch(env.ENDPOINT, {
+            method: "POST",
+            headers: allHeaders,
+            body: JSON.stringify({
+                query,
+                variables: parsedVariables,
+            }),
+        });
+        if (!response.ok) {
+            const responseText = await response.text();
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `GraphQL request failed: ${response.statusText}\n${responseText}`,
+                    },
+                ],
+            };
+        }
+        const rawData = await response.json();
+        // Type assertion for quick dev (replace with zod validation later)
+        const data = rawData;
+        if (data.errors && data.errors.length > 0) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `GraphQL errors: ${JSON.stringify(data.errors, null, 2)}`,
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to execute GraphQL query: ${error}`,
+                },
+            ],
+        };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`Started graphql mcp server ${env.NAME} for endpoint: ${env.ENDPOINT}`);
+}
+main().catch((error) => {
+    console.error(`Fatal error in main(): ${error}`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "@letoribo/mcp-graphql-enhanced",
+	"description": "Enhanced MCP server for GraphQL with dynamic headers and robust variables parsing — a drop-in replacement for mcp-graphql.",
+	"keywords": [
+		"mcp",
+		"graphql",
+		"llm",
+		"claude-desktop",
+		"cursor",
+		"enhanced",
+		"tool-calling"
+	],
+	"author": "letoribo",
+	"license": "MIT",
+	"repository": "github:letoribo/mcp-graphql-enhanced",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"bin": {
+		"mcp-graphql-enhanced": "./dist/index.js"
+	},
+	"files": [
+		"dist"
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"scripts": {
+		"dev": "ts-node src/index.ts",
+		"build": "tsc && chmod +x dist/index.js",
+		"start": "node dist/index.js",
+		"format": "prettier --write ."
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "1.12.0",
+		"graphql": "^16.11.0",
+		"yargs": "17.7.2",
+		"zod": "3.25.30",
+		"zod-to-json-schema": "3.24.5"
+	},
+	"devDependencies": {
+		"@graphql-tools/schema": "^10.0.23",
+		"@types/node": "^24.7.2",
+		"@types/yargs": "17.0.33",
+		"graphql-yoga": "^5.13.5",
+		"prettier": "^3.6.2",
+		"ts-node": "^10.9.2",
+		"typescript": "5.8.3"
+	},
+	"version": "2.0.5"
+}