@letoribo/mcp-graphql-enhanced 2.1.7 → 2.2.1

package/README.md

@@ -2,12 +2,39 @@
 [![Glama](https://glama.ai/mcp/servers/@letoribo/mcp-graphql-enhanced/badge)](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
-- ✅ **Filtered introspection** — request only specific types (e.g., `typeNames: ["Query", "User"]`) to reduce LLM context noise
-- ✅ **Full MCP compatibility** — works with **Claude Desktop**, **Cursor**, **Glama**
-- ✅ **Secure by default** — mutations disabled unless explicitly enabled
+* ✅ **Dual Transport** — Supports both **STDIO** (for local CLI/client tools) and **HTTP/JSON-RPC** (for external/browser clients).
+* ✅ **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
+* ✅ **Filtered introspection** — request only specific types (e.g., `typeNames: ["Query", "User"]`) to reduce LLM context noise
+* ✅ **Full MCP compatibility** — works with **Claude Desktop**, **Cursor**, **Glama**
+* ✅ **Secure by default** — mutations disabled unless explicitly enabled
+
+---
+
+## 💻 HTTP / Dual Transport
+
+This server now runs in **dual transport mode**, supporting both the standard **STDIO** communication (used by most MCP clients) and a new **HTTP JSON-RPC** endpoint on port `6274`.
+
+This allows external systems, web applications, and direct `curl` commands to access the server's tools.
+
+| **Endpoint** | **Method** | **Description** |
+| :--- | :--- | :--- |
+| `/mcp` | `POST` | The main JSON-RPC endpoint for tool execution. |
+| `/health` | `GET` | Simple health check, returns `{ status: 'ok' }`. |
+
+### Testing the HTTP Endpoint
+
+You can test the endpoint using `curl` as long as the server is running (e.g., via `npm run dev`):
+
+```bash
+# Test the health check
+curl http://localhost:6274/health
+
+# Test the query tool via JSON-RPC
+curl -X POST http://localhost:6274/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"query-graphql","params":{"query":"query { __typename }"},"id":1}'
+
 ## 🔍 Filtered Introspection (New!)
 Avoid 50k-line schema dumps. Ask for only what you need:
 ```@introspect-schema typeNames ["Query", "User"]```
@@ -28,6 +55,7 @@ npx @modelcontextprotocol/inspector \
 | `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) | - |
+| `MCP_PORT` | Port for the HTTP/JSON-RPC server. | `6274` |
 ### Examples
 ```bash
 # Basic usage
@@ -44,6 +72,8 @@ npx @letoribo/mcp-graphql-enhanced
 ENDPOINT=http://localhost:3000/graphql \
 SCHEMA=./schema.graphql \
 npx @letoribo/mcp-graphql-enhanced
+# Change the HTTP port
+MCP_PORT=8080 npx @letoribo/mcp-graphql-enhanced
 ```
 ### 🖥️ Claude Desktop Configuration Examples
 You can connect Claude Desktop to your GraphQL API using either the npx package (recommended for simplicity) or the Docker image (ideal for reproducibility and isolation).

package/dist/index.d.ts

@@ -1,18 +1,3 @@
 #!/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, introspectTypes: any;
-declare const getVersion: () => any;
-declare const EnvSchema: any;
-declare const env: any;
-declare const server: any;
-interface IntrospectSchemaArgs {
-    typeNames?: string[];
-    descriptions?: boolean;
-    directives?: boolean;
-}
-declare function main(): Promise<void>;
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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,OACvB,eAAe,KACyB,CAAC;AAG1C,QAAA,MAAM,UAAU,WAIf,CAAC;AAKF,QAAA,MAAM,SAAS,KAqBb,CAAC;AAEH,QAAA,MAAM,GAAG,KAA+B,CAAC;AAEzC,QAAA,MAAM,MAAM,KAIV,CAAC;AA+BH,UAAU,oBAAoB;IAC5B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAsKD,iBAAe,IAAI,kBAOlB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -1,18 +1,17 @@
 #!/usr/bin/env node
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const http = require("node:http");
 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, introspectTypes, } = require("./helpers/introspection.js");
-// Simulate macro import — since "with { type: 'macro' }" is not CommonJS compatible
+const { checkDeprecatedArguments } = require("./helpers/deprecation.ts");
+const { introspectEndpoint, introspectLocalSchema, introspectSchemaFromUrl, introspectTypes, } = require("./helpers/introspection.ts");
 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-enhanced"),
@@ -33,6 +32,7 @@ const EnvSchema = z.object({
         }
     }),
     SCHEMA: z.string().optional(),
+    MCP_PORT: z.preprocess((val) => (val ? parseInt(val) : 6274), z.number().int().min(1024).max(65535)).default(6274),
 });
 const env = EnvSchema.parse(process.env);
 const server = new McpServer({
@@ -68,21 +68,14 @@ server.resource("graphql-schema", new URL(env.ENDPOINT).href, async (uri) => {
         throw new Error(`Failed to get GraphQL schema: ${error}`);
     }
 });
-server.tool("introspect-schema", "Introspect the GraphQL schema. Optionally filter to specific types.", {
-    typeNames: z.array(z.string()).optional().describe("e.g., [\"Query\", \"User\"]"),
-    endpoint: z.string().optional(),
-    headers: z.string().optional(),
-    descriptions: z.boolean().optional().default(true),
-    directives: z.boolean().optional().default(true),
-}, async ({ typeNames, descriptions = true, directives = true }) => {
+const toolHandlers = new Map();
+const introspectSchemaHandler = async ({ typeNames, descriptions = true, directives = true }) => {
     try {
         if (typeNames && typeNames.length > 0) {
-            // ✅ Use your existing introspectTypes helper
             const filtered = await introspectTypes(env.ENDPOINT, env.HEADERS, typeNames);
             return { content: [{ type: "text", text: filtered }] };
         }
         else {
-            // Fallback to full schema
             let schema;
             if (env.SCHEMA) {
                 if (env.SCHEMA.startsWith("http://") || env.SCHEMA.startsWith("https://")) {
@@ -104,15 +97,14 @@ server.tool("introspect-schema", "Introspect the GraphQL schema. Optionally filt
             content: [{ type: "text", text: `Introspection failed: ${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 }) => {
+};
+toolHandlers.set("introspect-schema", introspectSchemaHandler);
+server.tool("introspect-schema", "Introspect the GraphQL schema. Optionally filter to specific types.", {
+    typeNames: z.array(z.string()).optional().describe("e.g., [\"Query\", \"User\"]"),
+    descriptions: z.boolean().optional().default(true),
+    directives: z.boolean().optional().default(true),
+}, introspectSchemaHandler);
+const queryGraphqlHandler = async ({ query, variables, headers }) => {
     try {
         const parsedQuery = parse(query);
         const isMutation = parsedQuery.definitions.some((def) => def.kind === "OperationDefinition" && def.operation === "mutation");
@@ -148,7 +140,6 @@ server.tool("query-graphql", "Query a GraphQL endpoint with the given query and
             ...env.HEADERS,
             ...toolHeaders,
         };
-        // Parse variables if it's a string
         let parsedVariables = null;
         if (variables) {
             if (typeof variables === 'string') {
@@ -179,7 +170,6 @@ server.tool("query-graphql", "Query a GraphQL endpoint with the given query and
             };
         }
         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 {
@@ -212,11 +202,114 @@ server.tool("query-graphql", "Query a GraphQL endpoint with the given query and
             ],
         };
     }
-});
+};
+toolHandlers.set("query-graphql", queryGraphqlHandler);
+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 ...\"}"),
+}, queryGraphqlHandler);
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let body = '';
+        req.on('data', (chunk) => {
+            body += chunk.toString();
+        });
+        req.on('end', () => {
+            resolve(body);
+        });
+        req.on('error', reject);
+    });
+}
+async function handleHttpRequest(req, res) {
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+    if (req.method === 'OPTIONS') {
+        res.writeHead(204);
+        res.end();
+        return;
+    }
+    const url = new URL(req.url, `http://${req.headers.host}`);
+    if (url.pathname === '/health' && req.method === 'GET') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ status: 'ok', server: env.NAME }));
+        return;
+    }
+    if (url.pathname === '/mcp' && req.method === 'POST') {
+        let rawBody;
+        let request;
+        try {
+            rawBody = await readBody(req);
+            request = JSON.parse(rawBody);
+        }
+        catch (e) {
+            console.error("HTTP MCP Parse Error:", e);
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                jsonrpc: '2.0',
+                id: null,
+                error: { code: -32700, message: 'Parse Error: Invalid JSON received in request body.' }
+            }));
+            return;
+        }
+        try {
+            const { method, params, id } = request;
+            if (!method || typeof id === 'undefined') {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: id || null,
+                    error: { code: -32600, message: 'Invalid JSON-RPC Request structure (missing method or id).' }
+                }));
+                return;
+            }
+            const handler = toolHandlers.get(method);
+            if (!handler) {
+                res.writeHead(404, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: id,
+                    error: { code: -32601, message: `Method not found: ${method}` }
+                }));
+                return;
+            }
+            const result = await handler(params);
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                jsonrpc: '2.0',
+                id: id,
+                result: result
+            }));
+        }
+        catch (error) {
+            console.error("HTTP MCP Execution Error:", error);
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                jsonrpc: '2.0',
+                id: request?.id || null,
+                error: { code: -32603, message: 'Internal server error during tool execution.' }
+            }));
+        }
+        return;
+    }
+    res.writeHead(404, { 'Content-Type': 'text/plain' });
+    res.end('Not Found. Use POST /mcp for JSON-RPC or GET /health.');
+}
+function startHttpTransport() {
+    const server = http.createServer(handleHttpRequest);
+    server.listen(env.MCP_PORT, () => {
+        console.error(`[HTTP] Started server on http://localhost:${env.MCP_PORT}. Listening for POST /mcp requests.`);
+    });
+}
 async function main() {
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    console.error(`Started graphql mcp server ${env.NAME} for endpoint: ${env.ENDPOINT}`);
+    const stdioTransport = new StdioServerTransport();
+    await server.connect(stdioTransport);
+    startHttpTransport();
+    console.error(`[STDIO] Started graphql mcp server ${env.NAME} for endpoint: ${env.ENDPOINT}`);
 }
 main().catch((error) => {
     console.error(`Fatal error in main(): ${error}`);

package/package.json

@@ -50,5 +50,5 @@
 		"ts-node": "^10.9.2",
 		"typescript": "5.8.3"
 	},
-	"version": "2.1.7"
+	"version": "2.2.1"
 }