@letoribo/mcp-graphql-enhanced 3.2.1 → 3.4.0

package/README.md

@@ -4,14 +4,33 @@ An **enhanced MCP (Model Context Protocol) server for GraphQL** that fixes real-
 > Drop-in replacement for `mcp-graphql` — with dynamic headers, robust variables parsing, and zero breaking changes.
 
 ## ✨ Key Enhancements
+* ✅ **Built-in GraphiQL IDE** — Visual playground at http://localhost:MCP_PORT/ (or /graphiql) with pre-configured headers.
 * ✅ **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
+* ✅ **Dynamic Schema Evolution** — Smart diagnostics and gap analysis for servers that regenerate GraphQL types on-the-fly (like Neo4j).
+* ✅ **Deep Observability** — Automatic Cypher extraction and cleaning from GraphQL extensions.
+
+## 🔍 Advanced Observability & Cypher
+The bridge provides deep insights into how the LLM interacts with your graph database. 
+
+### 🕸️ Automated Cypher Extraction
+For GraphQL server implementations that return query execution plans (like `@neo4j/graphql`), the bridge automatically:
+1. **Detects** `extensions.cypher` in the response.
+2. **Sanitizes** the output by stripping internal headers (like `CYPHER 5` or empty `PARAMS`).
+3. **Injects** a clean Cypher block directly into the tool's output for the AI to analyze.
+
+> **Note:** This feature requires your GraphQL server to be configured to include debug information in the response extensions.
 
 ---
+## 🎨 Visual Command Center (GraphiQL)
+Unlike standard MCP servers, this one provides a visual interface for humans. When running with `ENABLE_HTTP=true`, you can open a full-featured **GraphiQL IDE** in your browser.
+
+* **Endpoint:** `http://localhost:6274/` (or `/graphiql`)
+* **Header Sync:** Any headers set in your environment (like GitHub tokens) are automatically injected into the GraphiQL "Headers" tab for immediate testing.
 
 ## 💻 HTTP / Dual Transport
 
@@ -21,6 +40,7 @@ This allows external systems, web applications, and direct `curl` commands to ac
 
 | **Endpoint** | **Method** | **Description** |
 | :--- | :--- | :--- |
+| `/graphiql` | `GET` | Human Interface: The visual GraphQL IDE. |
 | `/mcp` | `POST` | The main JSON-RPC 2.0 endpoint for tool execution. |
 | `/health` | `GET` | Simple health check, returns `{ status: 'ok' }`. |
 
@@ -46,21 +66,21 @@ curl http://localhost:6274/health
 # Example: Test the query tool via JSON-RPC (using port 6275 if 6274 was busy)
 curl -X POST http://localhost:6275/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"query-graphql","params":{"query":"query { __typename }"},"id":1}'
 
-## 🔍 Filtered Introspection (New!)
+## 🔍 Filtered Introspection
 Avoid 50k-line schema dumps. Ask for only what you need:
-```@introspect-schema typeNames ["Query", "User"]```
+`@introspect-schema typeNames ["Query", "User"]`
 ## 🔍 Debug & Inspect
 Use the official MCP Inspector to test your server live:
 ```bash
 npx @modelcontextprotocol/inspector \
   -e ENDPOINT=https://api.example.com/graphql \
-  npx @letoribo/mcp-graphql-enhanced --debug
+  npx @letoribo/mcp-graphql-enhanced
 ```
 ### 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 | `https://mcp-neo4j-discord.vercel.app/api/graphiql` |
 | `HEADERS` | JSON string containing headers for requests | `{}` |
 | `ALLOW_MUTATIONS` | Enable mutation operations (disabled by default) | `false` |
@@ -93,6 +113,13 @@ npx @letoribo/mcp-graphql-enhanced
 MCP_PORT=8080 npx @letoribo/mcp-graphql-enhanced
 # Disable HTTP transport (fastest, recommended for Claude Desktop)
 ENABLE_HTTP=false npx @letoribo/mcp-graphql-enhanced
+# Test the surgical precision and the IDE immediately:
+ENDPOINT=https://api.github.com/graphql \
+HEADERS='{"Authorization":"Bearer YOUR_GITHUB_TOKEN"}' \
+ENABLE_HTTP=true \
+npx @letoribo/mcp-graphql-enhanced
+
+# Then visit http://localhost:6274/graphiql
 ```
 ### 🖥️ 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/helpers/graphiql.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Renders the GraphiQL IDE template with visible headers
+ * @param endpoint The GraphQL API endpoint to connect to
+ * @param headers Optional default headers to inject into the editor
+ */
+export declare function renderGraphiQL(endpoint: string, headers?: object): string;
+//# sourceMappingURL=graphiql.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graphiql.d.ts","sourceRoot":"","sources":["../../src/helpers/graphiql.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,MAAW,GAAG,MAAM,CAoE7E"}

package/dist/helpers/graphiql.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderGraphiQL = renderGraphiQL;
+/**
+ * Renders the GraphiQL IDE template with visible headers
+ * @param endpoint The GraphQL API endpoint to connect to
+ * @param headers Optional default headers to inject into the editor
+ */
+function renderGraphiQL(endpoint, headers = {}) {
+    // Stringify headers for the injection into the script
+    const stringifiedHeaders = JSON.stringify(headers, null, 2);
+    return `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>GraphiQL Explorer | Surgical MCP</title>
+    <link href="https://unpkg.com/graphiql@3.8.2/graphiql.min.css" rel="stylesheet" />
+    <style>
+        body { 
+            margin: 0; 
+            height: 100vh; 
+            width: 100vw; 
+            overflow: hidden; 
+            background: #0b1016; 
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+        }
+        #graphiql { height: 100vh; }
+        .loading-screen { 
+            color: white; 
+            display: flex; 
+            justify-content: center; 
+            align-items: center; 
+            height: 100%; 
+            font-size: 1.2rem;
+        }
+    </style>
+</head>
+<body>
+    <div id="graphiql">
+        <div class="loading-screen">Initializing Surgical GraphiQL...</div>
+    </div>
+
+    <script src="https://unpkg.com/react@18.2.0/umd/react.production.min.js" crossorigin referrerpolicy="no-referrer"></script>
+    <script src="https://unpkg.com/react-dom@18.2.0/umd/react-dom.production.min.js" crossorigin referrerpolicy="no-referrer"></script>
+    <script src="https://unpkg.com/graphiql@3.8.2/graphiql.min.js" crossorigin referrerpolicy="no-referrer"></script>
+
+    <script>
+        window.addEventListener('load', function() {
+            if (typeof GraphiQL !== 'undefined') {
+                const fetcher = GraphiQL.createFetcher({ 
+                    url: '${endpoint}'
+                });
+                
+                const root = ReactDOM.createRoot(document.getElementById('graphiql'));
+                root.render(
+                    React.createElement(GraphiQL, { 
+                        fetcher: fetcher,
+                        headerEditorEnabled: true,
+                        shouldPersistHeaders: true,
+                        // This makes the headers visible in the UI tab
+                        defaultHeaders: \`${stringifiedHeaders}\`,
+                        theme: 'dark',
+                        defaultEditorToolsVisibility: true
+                    })
+                );
+            } else {
+                document.getElementById('graphiql').innerHTML = 
+                    '<div class="loading-screen" style="color: #ff4d4d">Error: GraphiQL SDK failed to load.</div>';
+            }
+        });
+    </script>
+</body>
+</html>`;
+}

package/dist/index.js

@@ -9,6 +9,8 @@ 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"));
+const graphiql_js_1 = require("./helpers/graphiql.js");
+const graphql_1 = require("graphql");
 // Helper imports
 const deprecation_js_1 = require("./helpers/deprecation.js");
 const introspection_js_1 = require("./helpers/introspection.js");
@@ -61,48 +63,147 @@ const server = new mcp_js_1.McpServer({
 let cachedSDL = null;
 let cachedSchemaObject = null;
 let schemaLoadError = null;
-async function getSchema() {
-    if (cachedSDL)
+let isUpdating = false;
+let updatePromise = null;
+let lastKnownTypeCount = 0;
+let expectEmptySchema = false; // Intent flag for intentional purges
+/**
+ * Smart Hybrid Schema Fetcher (Zero-Error Version)
+ * @param force If true, blocks and waits for the new schema evolution.
+ * If false, returns cache immediately and updates in background.
+ */
+async function getSchema(force = false, requestedTypes) {
+    // 1. Hook into existing update if in progress
+    if (isUpdating && updatePromise) {
+        if (force || !cachedSDL)
+            return await updatePromise;
         return cachedSDL;
+    }
+    // 2. Return cache if valid and not forcing
+    if (cachedSDL && !force) {
+        // Validation check: If user wants specific types but they aren't in the cache
+        if (requestedTypes && cachedSchemaObject) {
+            const typeMap = cachedSchemaObject.getTypeMap();
+            const missing = requestedTypes.filter(t => !typeMap[t]);
+            if (missing.length > 0) {
+                // Force a refresh if requested types are missing from current cache
+                return await (updatePromise = performUpdate(true));
+            }
+        }
+        return cachedSDL;
+    }
+    if (force)
+        schemaLoadError = null;
     if (schemaLoadError)
         throw schemaLoadError;
+    // 3. Trigger update
+    updatePromise = performUpdate(force);
+    try {
+        if (force || !cachedSDL) {
+            return await updatePromise;
+        }
+        else {
+            updatePromise.catch(err => console.error("[SCHEMA] Background update failed:", err));
+            return cachedSDL;
+        }
+    }
+    finally {
+        // Promise reference is cleared inside performUpdate's 'finally' block
+    }
+}
+/**
+ * Internal logic for schema introspection and building.
+ * This version uses universal business-type tracking and provides
+ * detailed diagnostic reports instead of generic error messages.
+ */
+async function performUpdate(force) {
+    isUpdating = true;
+    const startTime = Date.now();
     try {
-        const { buildClientSchema, getIntrospectionQuery, printSchema, buildASTSchema, parse: gqlParse } = require("graphql");
-        let sdl;
+        const { buildClientSchema, getIntrospectionQuery, printSchema, buildASTSchema, parse: gqlParse, isObjectType } = require("graphql");
+        let tempSchema;
+        // --- FETCHING LOGIC (Unified Source) ---
         if (env.SCHEMA) {
-            // Check if it's a URL or local path
+            let sdl;
             if (env.SCHEMA.startsWith("http")) {
+                // Remote SDL File: Fetch via HTTP
                 const response = await fetch(env.SCHEMA);
+                if (!response.ok)
+                    throw new Error(`Remote_SDL_Fetch_Failed: ${response.statusText}`);
                 sdl = await response.text();
             }
             else {
+                // Local SDL File: Use your custom helper (readFile inside)
                 sdl = await (0, introspection_js_1.introspectLocalSchema)(env.SCHEMA);
             }
-            cachedSchemaObject = buildASTSchema(gqlParse(sdl));
-            cachedSDL = sdl;
+            // Direct path: Convert raw SDL string to GraphQLSchema object
+            tempSchema = buildASTSchema(gqlParse(sdl));
         }
         else {
+            // Standard Path: Execute Introspection Query against live ENDPOINT
             const response = await fetch(env.ENDPOINT, {
                 method: "POST",
                 headers: { "Content-Type": "application/json", ...env.HEADERS },
                 body: JSON.stringify({ query: getIntrospectionQuery() }),
             });
             if (!response.ok)
-                throw new Error(`Fetch failed: ${response.statusText}`);
+                throw new Error(`HTTP_${response.status}: ${response.statusText}`);
             const result = await response.json();
-            cachedSchemaObject = buildClientSchema(result.data);
-            cachedSDL = printSchema(cachedSchemaObject);
+            if (!result.data)
+                throw new Error("Invalid GraphQL response: Missing 'data' field.");
+            // Build Schema object from introspection JSON
+            tempSchema = buildClientSchema(result.data);
+        }
+        // --- UNIFIED STRUCTURAL ANALYSIS (For AI Report) ---
+        const typeMap = tempSchema.getTypeMap();
+        // Filter "Business Labels" (Nodes) while ignoring internal scalars/system types
+        const businessTypes = Object.keys(typeMap).filter(typeName => {
+            const type = typeMap[typeName];
+            return (!typeName.startsWith('__') &&
+                !['Query', 'Mutation', 'Subscription'].includes(typeName) &&
+                !['String', 'Int', 'Float', 'Boolean', 'ID', 'BigInt', 'DateTime'].includes(typeName) &&
+                isObjectType(type));
+        });
+        // Maintain state for "Gap Analysis"
+        lastKnownTypeCount = businessTypes.length;
+        const currentSDL = printSchema(tempSchema);
+        const duration = ((Date.now() - startTime) / 1000).toFixed(2);
+        // --- CACHE & NOTIFICATION ---
+        if (currentSDL !== cachedSDL) {
+            cachedSDL = currentSDL;
+            cachedSchemaObject = tempSchema; // Store the live Schema object for tool execution
+            return [
+                `✨ SCHEMA EVOLVED (${duration}s)`,
+                `📊 Source: ${env.SCHEMA ? 'Local/Remote SDL' : 'Live Endpoint'}`,
+                `🧬 Labels: ${businessTypes.join(', ') || 'None'}`,
+                `---`,
+                `The bridge has updated the graph model. New types are now queryable.`
+            ].join('\n');
+        }
+        else {
+            return `✅ Status: Schema stable (${lastKnownTypeCount} labels).`;
         }
-        console.error(`[SCHEMA] Successfully loaded and cached GraphQL schema`);
-        return cachedSDL;
     }
     catch (error) {
-        schemaLoadError = error instanceof Error ? error : new Error(String(error));
-        throw schemaLoadError;
+        // Informative error report to prevent "AI confusion"
+        return [
+            `❌ SCHEMA SYNC FAILED`,
+            `🔍 Reason: ${error.message}`,
+            `🛠️ Action: Verify your ${env.SCHEMA ? 'file path' : 'endpoint connection'} and retry.`
+        ].join('\n');
+    }
+    finally {
+        isUpdating = false;
+        updatePromise = null;
     }
 }
 // --- TOOL HANDLERS ---
 const toolHandlers = new Map();
+/** * executionLogs stores the last 5 GraphQL operations.
+ * This allows the AI to "inspect" its own generated queries and the raw data
+ * for debugging or bridging to 3D visualization tools.
+ */
+let executionLogs = [];
 // Tool: query-graphql
 const queryGraphqlHandler = async ({ query, variables, headers }) => {
     try {
@@ -120,9 +221,32 @@ const queryGraphqlHandler = async ({ query, variables, headers }) => {
             headers: allHeaders,
             body: JSON.stringify({ query, variables: parsedVariables }),
         });
-        const data = await response.json();
+        const data = (await response.json());
+        // 1. Extract and sanitize Cypher if present in extensions
+        const rawCypher = data.extensions?.cypher || [];
+        const cleanCypher = rawCypher.map((c) => c.replace(/^CYPHER: /, '')
+            .replace(/^CYPHER 5\n/, '')
+            .replace(/\nPARAMS: \{\}$/, ''));
+        // 2. Update execution history for internal server state
+        executionLogs.push({
+            query,
+            variables: parsedVariables,
+            response: data,
+            timestamp: new Date().toISOString()
+        });
+        if (executionLogs.length > 5)
+            executionLogs.shift();
+        // 3. Prepare optimized response for Claude
+        const responseForClaude = {
+            result: data.data,
+            // Only add the cypher field if there's actual data to show
+            ...(cleanCypher.length > 0 ? { cypher: cleanCypher } : {})
+        };
         return {
-            content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(responseForClaude, null, 2)
+                }]
         };
     }
     catch (error) {
@@ -137,14 +261,56 @@ server.tool("query-graphql", "Execute a GraphQL query against the endpoint", {
 }, queryGraphqlHandler);
 // Tool: introspect-schema
 const introspectHandler = async ({ typeNames }) => {
-    await getSchema();
+    // 1. Always pull the latest schema state
+    // The report from performUpdate is captured to show evolution details
+    const evolutionSummary = await getSchema(true);
+    const schema = cachedSchemaObject;
+    const typeMap = schema.getTypeMap();
+    // 2. Generate a structural fingerprint
+    const typeKeys = Object.keys(typeMap).filter(t => !t.startsWith('__'));
+    const schemaVersion = `v${typeKeys.length}.${Math.floor(Date.now() / 10000) % 1000}`;
+    // --- GAP ANALYSIS: Check if requested types are actually in the map ---
+    if (typeNames && typeNames.length > 0) {
+        const missing = typeNames.filter(name => !typeMap[name]);
+        if (missing.length > 0) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `❌ PARTIAL RESULTS [ID: ${schemaVersion}]\n\n` +
+                            `MISSING TYPES: ${missing.join(", ")}\n` +
+                            `REASON: The database has been updated, but the GraphQL Schema is still regenerating these specific types.\n` +
+                            `ACTION: Please wait 3 seconds and retry 'introspect-schema' to see the full graph.\n\n` +
+                            `CURRENTLY AVAILABLE: ${typeKeys.filter(t => !['Query', 'Mutation', 'Report'].includes(t)).join(", ")}`
+                    }]
+            };
+        }
+    }
     if (!typeNames || typeNames.length === 0) {
-        const allTypeNames = Object.keys(cachedSchemaObject.getTypeMap()).filter(t => !t.startsWith('__'));
+        const queryType = schema.getQueryType();
+        const discoveredEntities = new Set();
+        if (queryType) {
+            const queryFields = queryType.getFields();
+            Object.values(queryFields).forEach((field) => {
+                const namedType = (0, graphql_1.getNamedType)(field.type);
+                if ((0, graphql_1.isObjectType)(namedType) && !namedType.name.startsWith('__')) {
+                    discoveredEntities.add(namedType.name);
+                }
+            });
+        }
+        const coreEntities = Array.from(discoveredEntities).sort();
         return {
-            content: [{ type: "text", text: `Schema is large. Available types: ${allTypeNames.join(", ")}` }]
+            content: [{
+                    type: "text",
+                    text: `${evolutionSummary}\n\n` + // Include the report from performUpdate
+                        `GraphQL Schema Manifest [ID: ${schemaVersion}]\n\n` +
+                        `ENTRY_POINT_ENTITIES: ${coreEntities.join(", ") || "None"}\n` +
+                        `TOTAL_SCHEMA_TYPES: ${typeKeys.length}\n\n` +
+                        `ALL_AVAILABLE_TYPES: ${typeKeys.join(", ")}`
+                }]
         };
     }
-    const filtered = (0, introspection_js_1.introspectSpecificTypes)(cachedSchemaObject, typeNames);
+    // 3. Detailed introspection for specific types
+    const filtered = (0, introspection_js_1.introspectSpecificTypes)(schema, typeNames);
     return {
         content: [{ type: "text", text: JSON.stringify(filtered, null, 2) }]
     };
@@ -164,6 +330,12 @@ async function handleHttpRequest(req, res) {
         return;
     }
     const url = new URL(req.url || '', `http://${req.headers.host}`);
+    // NEW FEATURE: Web GUI for Humans
+    if (req.method === 'GET' && (url.pathname === '/' || url.pathname === '/graphiql')) {
+        res.writeHead(200, { 'Content-Type': 'text/html' });
+        // Pass env.HEADERS to the explorer
+        return res.end((0, graphiql_js_1.renderGraphiQL)(env.ENDPOINT, env.HEADERS));
+    }
     if (url.pathname === '/mcp' && req.method === 'POST') {
         let body = '';
         req.on('data', chunk => { body += chunk; });
@@ -201,6 +373,8 @@ async function main() {
         const serverHttp = node_http_1.default.createServer(handleHttpRequest);
         serverHttp.listen(env.MCP_PORT, () => {
             console.error(`[HTTP] Server started on http://localhost:${env.MCP_PORT}`);
+            console.error(`🎨 GraphiQL IDE: http://localhost:${env.MCP_PORT}/graphiql`);
+            console.error(`🤖 MCP Endpoint: http://localhost:${env.MCP_PORT}/mcp\n`);
         });
     }
     const transport = new stdio_js_1.StdioServerTransport();

package/package.json

@@ -50,5 +50,5 @@
 		"tsx": "^4.21.0",
 		"typescript": "5.8.3"
 	},
-	"version": "3.2.1"
+	"version": "3.4.0"
 }