@letoribo/mcp-graphql-enhanced 3.2.0 → 3.2.1

package/README.md

@@ -17,13 +17,16 @@ An **enhanced MCP (Model Context Protocol) server for GraphQL** that fixes real-
 
 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.
+This allows external systems, web applications, and direct `curl` commands to access the server's tools with **live request logging** in your terminal (`[HTTP-RPC]` logs).
 
 | **Endpoint** | **Method** | **Description** |
 | :--- | :--- | :--- |
-| `/mcp` | `POST` | The main JSON-RPC endpoint for tool execution. |
+| `/mcp` | `POST` | The main JSON-RPC 2.0 endpoint for tool execution. |
 | `/health` | `GET` | Simple health check, returns `{ status: 'ok' }`. |
 
+### Automatic Port Selection
+The server defaults to port `6274`. If you encounter an `EADDRINUSE` error, the server will automatically find the next available port. **Check the server logs for the final bound port** (e.g., `[HTTP] Started server on http://localhost:6275`).
+
 ### Resolving Port Conflicts (EADDRINUSE) and Automatic Port Selection
 
 The server defaults to port `6274`. If you encounter an `EADDRINUSE: address already in use :::6274` error (common in local development due to stale processes), the server will automatically find the next available port (up to 10 attempts, not spawning multiple servers).
@@ -62,9 +65,10 @@ npx @modelcontextprotocol/inspector \
 | `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) | - |
+| `SCHEMA` | Path to a local GraphQL schema file or URL | - |
 | `MCP_PORT` | Port for the HTTP/JSON-RPC server. | `6274` |
 | `ENABLE_HTTP` | Enable HTTP transport: `auto` (default), `true`, or `false` | `auto` |
+| `DEBUG` | Set to `mcp:*` for detailed SDK logs | - |
 **Note on `ENABLE_HTTP`:** 
 - `auto` (default): Automatically enables HTTP only when running in MCP Inspector...
 - `true`: Always enable HTTP server

package/dist/index.js

@@ -5,25 +5,31 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const node_http_1 = __importDefault(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, introspectSpecificTypes, } = require("./helpers/introspection.js");
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const language_1 = require("graphql/language");
+const zod_1 = __importDefault(require("zod"));
+// Helper imports
+const deprecation_js_1 = require("./helpers/deprecation.js");
+const introspection_js_1 = require("./helpers/introspection.js");
 const getVersion = () => {
-    const pkg = require("../package.json");
-    return pkg.version;
+    try {
+        const pkg = require("../package.json");
+        return pkg.version;
+    }
+    catch {
+        return "3.2.1";
+    }
 };
-checkDeprecatedArguments();
-const EnvSchema = z.object({
-    NAME: z.string().default("mcp-graphql-enhanced"),
-    ENDPOINT: z.preprocess((val) => (typeof val === 'string' ? val.trim() : val), z.string().url("ENDPOINT must be a valid URL (e.g., https://example.com/graphql)")).default("https://mcp-neo4j-discord.vercel.app/api/graphiql"),
-    ALLOW_MUTATIONS: z
+(0, deprecation_js_1.checkDeprecatedArguments)();
+const EnvSchema = zod_1.default.object({
+    NAME: zod_1.default.string().default("mcp-graphql-enhanced"),
+    ENDPOINT: zod_1.default.preprocess((val) => (typeof val === 'string' ? val.trim() : val), zod_1.default.string().url()).default("https://mcp-neo4j-discord.vercel.app/api/graphiql"),
+    ALLOW_MUTATIONS: zod_1.default
         .enum(["true", "false"])
         .transform((value) => value === "true")
         .default("false"),
-    HEADERS: z
+    HEADERS: zod_1.default
         .string()
         .default("{}")
         .transform((val) => {
@@ -34,32 +40,27 @@ const EnvSchema = z.object({
             throw new Error("HEADERS must be a valid JSON string");
         }
     }),
-    SCHEMA: z.string().optional(),
-    MCP_PORT: z.preprocess((val) => (val ? parseInt(val) : 6274), z.number().int().min(1024).max(65535)).default(6274),
-    ENABLE_HTTP: z
+    SCHEMA: zod_1.default.string().optional(),
+    MCP_PORT: zod_1.default.preprocess((val) => (val ? parseInt(val) : 6274), zod_1.default.number().int().min(1024).max(65535)).default(6274),
+    ENABLE_HTTP: zod_1.default
         .enum(["true", "false", "auto"])
         .transform((value) => {
         if (value === "auto") {
-            return !!(process.env.MCP_INSPECTOR || process.env.INSPECTOR_PORT);
+            return !!(process.env.MCP_INSPECTOR || process.env.INSPECTOR_PORT || process.env.MCP_PORT);
         }
         return value === "true";
     })
         .default("auto"),
 });
 const env = EnvSchema.parse(process.env);
-const server = new McpServer({
+const server = new mcp_js_1.McpServer({
     name: env.NAME,
     version: getVersion(),
-    description: `GraphQL MCP server for ${env.ENDPOINT}`,
 });
 // --- CACHE STATE ---
 let cachedSDL = null;
 let cachedSchemaObject = null;
 let schemaLoadError = null;
-/**
- * Loads the schema into memory.
- * Populates both cachedSDL (string) and cachedSchemaObject (GraphQLSchema object).
- */
 async function getSchema() {
     if (cachedSDL)
         return cachedSDL;
@@ -69,17 +70,18 @@ async function getSchema() {
         const { buildClientSchema, getIntrospectionQuery, printSchema, buildASTSchema, parse: gqlParse } = require("graphql");
         let sdl;
         if (env.SCHEMA) {
+            // Check if it's a URL or local path
             if (env.SCHEMA.startsWith("http")) {
-                sdl = await introspectSchemaFromUrl(env.SCHEMA);
+                const response = await fetch(env.SCHEMA);
+                sdl = await response.text();
             }
             else {
-                sdl = await introspectLocalSchema(env.SCHEMA);
+                sdl = await (0, introspection_js_1.introspectLocalSchema)(env.SCHEMA);
             }
             cachedSchemaObject = buildASTSchema(gqlParse(sdl));
             cachedSDL = sdl;
         }
         else {
-            // Live Introspection
             const response = await fetch(env.ENDPOINT, {
                 method: "POST",
                 headers: { "Content-Type": "application/json", ...env.HEADERS },
@@ -99,93 +101,15 @@ async function getSchema() {
         throw schemaLoadError;
     }
 }
-// --- RESOURCES ---
-server.resource("graphql-schema", new URL(env.ENDPOINT).href, async (uri) => {
-    try {
-        const sdl = await getSchema();
-        return { contents: [{ uri: uri.href, text: sdl }] };
-    }
-    catch (error) {
-        throw error;
-    }
-});
 // --- TOOL HANDLERS ---
 const toolHandlers = new Map();
-const introspectSchemaHandler = async ({ typeNames }) => {
-    try {
-        // Ensure cache is populated
-        await getSchema();
-        // Safety: If no specific types requested, return the 'Map' of types to prevent bridge crash
-        if (!typeNames || typeNames.length === 0) {
-            const allTypeNames = Object.keys(cachedSchemaObject.getTypeMap())
-                .filter(t => !t.startsWith('__'));
-            return {
-                content: [{
-                        type: "text",
-                        text: `Schema is large. Please request specific types for full details.\n\nAvailable types: ${allTypeNames.join(", ")}`
-                    }]
-            };
-        }
-        // Use the new filtering logic from helpers/introspection.js
-        const filteredResult = introspectSpecificTypes(cachedSchemaObject, typeNames);
-        return {
-            content: [{
-                    type: "text",
-                    text: JSON.stringify(filteredResult, null, 2)
-                }]
-        };
-    }
-    catch (error) {
-        throw new Error(`Introspection failed: ${error.message}`);
-    }
-};
-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("A list of specific type names to filter (e.g. ['User', 'Post'])."),
-}, async ({ typeNames }) => {
-    try {
-        console.error(`[TOOL] Introspect called with types: ${JSON.stringify(typeNames || "NONE")}`);
-        // 1. Ensure the schema is loaded into the cache
-        await getSchema();
-        // 2. THE GATEKEEPER: If no types requested, send ONLY names.
-        if (!typeNames || typeNames.length === 0) {
-            const allTypeNames = Object.keys(cachedSchemaObject.getTypeMap())
-                .filter(t => !t.startsWith('__'));
-            console.error(`[TOOL] Sending summary list of ${allTypeNames.length} types.`);
-            return {
-                content: [{
-                        type: "text",
-                        text: `Schema is large. Please request specific types for details.\n\nAvailable types: ${allTypeNames.join(", ")}`
-                    }]
-            };
-        }
-        // 3. DRILL DOWN: If Claude asks for specific types, use the helper.
-        console.error(`[TOOL] Filtering for: ${typeNames.join(", ")}`);
-        const filteredResult = introspectSpecificTypes(cachedSchemaObject, typeNames);
-        return {
-            content: [{
-                    type: "text",
-                    text: JSON.stringify(filteredResult, null, 2)
-                }]
-        };
-    }
-    catch (error) {
-        console.error(`[TOOL ERROR] ${error.message}`);
-        throw new Error(`Introspection failed: ${error.message}`);
-    }
-});
+// Tool: query-graphql
 const queryGraphqlHandler = async ({ query, variables, headers }) => {
     try {
-        const parsedQuery = parse(query);
+        const parsedQuery = (0, language_1.parse)(query);
         const isMutation = parsedQuery.definitions.some((def) => def.kind === "OperationDefinition" && def.operation === "mutation");
-        if (isMutation && !env.ALLOW_MUTATIONS) {
-            throw new Error("Mutations are not allowed. Enable ALLOW_MUTATIONS in config.");
-        }
-    }
-    catch (error) {
-        throw new Error(`Invalid GraphQL query: ${error}`);
-    }
-    try {
+        if (isMutation && !env.ALLOW_MUTATIONS)
+            throw new Error("Mutations are not allowed.");
         const toolHeaders = headers ? JSON.parse(headers) : {};
         const allHeaders = { "Content-Type": "application/json", ...env.HEADERS, ...toolHeaders };
         let parsedVariables = variables;
@@ -196,124 +120,97 @@ const queryGraphqlHandler = async ({ query, variables, headers }) => {
             headers: allHeaders,
             body: JSON.stringify({ query, variables: parsedVariables }),
         });
-        if (!response.ok) {
-            const responseText = await response.text();
-            throw new Error(`GraphQL request failed: ${response.statusText}\n${responseText}`);
-        }
         const data = await response.json();
-        if (data.errors && data.errors.length > 0) {
-            throw new Error(`GraphQL errors: ${JSON.stringify(data.errors, null, 2)}`);
-        }
         return {
-            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
         };
     }
     catch (error) {
-        throw new Error(`Failed to execute GraphQL query: ${error}`);
+        throw new Error(`Execution failed: ${error.message}`);
     }
 };
 toolHandlers.set("query-graphql", queryGraphqlHandler);
-server.tool("query-graphql", "Query a GraphQL endpoint with the given query and variables.", {
-    query: z.string(),
-    variables: z.string().optional(),
-    headers: z.string().optional().describe("Optional JSON string of headers"),
+server.tool("query-graphql", "Execute a GraphQL query against the endpoint", {
+    query: zod_1.default.string(),
+    variables: zod_1.default.string().optional(),
+    headers: zod_1.default.string().optional(),
 }, queryGraphqlHandler);
+// Tool: introspect-schema
+const introspectHandler = async ({ typeNames }) => {
+    await getSchema();
+    if (!typeNames || typeNames.length === 0) {
+        const allTypeNames = Object.keys(cachedSchemaObject.getTypeMap()).filter(t => !t.startsWith('__'));
+        return {
+            content: [{ type: "text", text: `Schema is large. Available types: ${allTypeNames.join(", ")}` }]
+        };
+    }
+    const filtered = (0, introspection_js_1.introspectSpecificTypes)(cachedSchemaObject, typeNames);
+    return {
+        content: [{ type: "text", text: JSON.stringify(filtered, null, 2) }]
+    };
+};
+toolHandlers.set("introspect-schema", introspectHandler);
+server.tool("introspect-schema", "Introspect the GraphQL schema with optional type filtering", {
+    typeNames: zod_1.default.array(zod_1.default.string()).optional(),
+}, introspectHandler);
 // --- HTTP SERVER LOGIC ---
-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-Methods', 'POST, GET, 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;
-    }
+    const url = new URL(req.url || '', `http://${req.headers.host}`);
     if (url.pathname === '/mcp' && req.method === 'POST') {
-        try {
-            const rawBody = await readBody(req);
-            const { method, params, id } = JSON.parse(rawBody);
-            const handler = toolHandlers.get(method);
-            if (!handler) {
-                res.writeHead(404);
-                res.end(JSON.stringify({ jsonrpc: '2.0', id, error: { code: -32601, message: 'Method not found' } }));
-                return;
+        let body = '';
+        req.on('data', chunk => { body += chunk; });
+        req.on('end', async () => {
+            try {
+                const { method, params, id } = JSON.parse(body);
+                console.error(`[HTTP-RPC] Method: ${method} | ID: ${id}`);
+                const handler = toolHandlers.get(method);
+                if (!handler) {
+                    res.writeHead(404);
+                    return res.end(JSON.stringify({ jsonrpc: '2.0', id, error: { code: -32601, message: "Method not found" } }));
+                }
+                const result = await handler(params);
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ jsonrpc: '2.0', id, result }));
             }
-            const result = await handler(params);
-            res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ jsonrpc: '2.0', id, result }));
-        }
-        catch (error) {
-            res.writeHead(500);
-            res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32603, message: 'Internal error' } }));
-        }
+            catch (e) {
+                console.error(`[HTTP-ERROR] ${e.message}`);
+                res.writeHead(500);
+                res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32603, message: "Internal Error" } }));
+            }
+        });
         return;
     }
+    if (url.pathname === '/health') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        return res.end(JSON.stringify({ status: "ok", server: env.NAME }));
+    }
     res.writeHead(404);
-    res.end('Not Found');
-}
-let httpServer = null;
-async function startHttpServer(initialPort) {
-    return new Promise((resolve, reject) => {
-        let port = initialPort;
-        const server = node_http_1.default.createServer(handleHttpRequest);
-        server.once('error', (err) => {
-            if (err.code === 'EADDRINUSE') {
-                server.close();
-                resolve(startHttpServer(port + 1));
-            }
-            else
-                reject(err);
-        });
-        server.listen(port, () => {
-            httpServer = server;
-            resolve(port);
-        });
-    });
+    res.end("Not Found");
 }
 // --- STARTUP ---
 async function main() {
-    console.error(`[SCHEMA] Pre-loading GraphQL schema...`);
-    const schemaPromise = getSchema().catch(error => {
-        console.error(`[SCHEMA] Warning: Failed to pre-load schema: ${error}`);
-    });
-    const stdioTransport = new StdioServerTransport();
-    await server.connect(stdioTransport);
-    console.error(`[STDIO] Started GraphQL MCP server ${env.NAME}`);
     if (env.ENABLE_HTTP) {
-        try {
-            const port = await startHttpServer(env.MCP_PORT);
-            console.error(`[HTTP] Server started on http://localhost:${port}`);
-        }
-        catch (error) {
-            console.error(`[HTTP] Failed to start: ${error}`);
-        }
+        const serverHttp = node_http_1.default.createServer(handleHttpRequest);
+        serverHttp.listen(env.MCP_PORT, () => {
+            console.error(`[HTTP] Server started on http://localhost:${env.MCP_PORT}`);
+        });
     }
-    await schemaPromise;
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error(`[STDIO] MCP Server "${env.NAME}" v${getVersion()} started`);
+    getSchema().catch(e => console.error(`[SCHEMA] Warning: Preload failed: ${e.message}`));
 }
-// Graceful exit
-const shutdown = () => {
-    if (httpServer)
-        httpServer.close(() => process.exit(0));
-    else
-        process.exit(0);
-};
-process.on('SIGINT', shutdown);
-process.on('SIGTERM', shutdown);
+process.on('SIGINT', () => process.exit(0));
+process.on('SIGTERM', () => process.exit(0));
 main().catch(error => {
-    console.error(`Fatal error: ${error}`);
+    console.error(`[FATAL] ${error}`);
     process.exit(1);
 });

package/package.json

@@ -29,7 +29,7 @@
 		"node": ">=18"
 	},
 	"scripts": {
-		"dev": "ts-node src/index.ts",
+		"dev": "tsx --watch src/index.ts",
 		"build": "tsc && chmod +x dist/index.js",
 		"start": "node dist/index.js",
 		"format": "prettier --write ."
@@ -47,7 +47,8 @@
 		"@types/yargs": "17.0.33",
 		"prettier": "^3.6.2",
 		"ts-node": "^10.9.2",
+		"tsx": "^4.21.0",
 		"typescript": "5.8.3"
 	},
-	"version": "3.2.0"
+	"version": "3.2.1"
 }