@letoribo/mcp-graphql-enhanced 3.3.0 → 3.4.0

package/README.md

@@ -11,6 +11,19 @@ An **enhanced MCP (Model Context Protocol) server for GraphQL** that fixes real-
 * ✅ **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)

package/dist/index.js

@@ -10,6 +10,7 @@ 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");
@@ -62,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 {
-        const { buildClientSchema, getIntrospectionQuery, printSchema, buildASTSchema, parse: gqlParse } = require("graphql");
-        let sdl;
+        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, 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 {
@@ -121,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) {
@@ -138,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) }]
     };

package/package.json

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