@letoribo/mcp-graphql-enhanced 3.7.0 → 3.8.1

package/LICENSE

@@ -1,7 +1,7 @@
 MIT License
 
-Copyright (c) 2024 Boris Besemer (Original Work)
-Copyright (c) 2025-2026 [letoribo] (Enhanced Architecture, NPM Refactoring & Discord Graph Infrastructure)
+Copyright (c) 2024 Boris Besemer
+Copyright (c) 2025-2026 letoribo
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -19,19 +19,4 @@ 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.
-
----
-PROJECT EVOLUTION & SOVEREIGNTY NOTE:
-As of mid-2025, this project has undergone a fundamental architectural shift. 
-The legacy Bun-based implementation has been decommissioned and replaced with 
-a surgical, production-ready NPM/Node.js core for maximum stability.
-
-This "Enhanced" version was battle-tested as the architectural engine for the 
-"Neo4j Discord-as-a-Database" project (mcp-neo4j-discord.vercel.app), handling 
-large-scale graph datasets. 
-
-While active real-time data ingestion is currently throttled due to persistent 
-infrastructure challenges and blackouts in Odesa, the codebase remains the 
-sovereign standard for high-performance GraphRAG, 3D visualization interface, 
-and resilient AI intent parsing. Developed under pressure in Odesa, Ukraine.
+SOFTWARE.

package/dist/helpers/introspection.d.ts

@@ -8,8 +8,9 @@ export declare function introspectEndpoint(endpoint: string, headers?: Record<st
  */
 export declare function introspectLocalSchema(path: string): Promise<string>;
 /**
- * Extract and filter specific types from a schema object.
- * Prevents "No result received" errors by only sending requested parts of the graph.
+ * Extract and filter specific types or root fields from a GraphQL schema.
+ * This prevents "No result received" errors by only sending the requested
+ * parts of the graph to the agent, maintaining a stable context window.
  */
 export declare function introspectSpecificTypes(schema: GraphQLSchema, typeNames: string[]): Record<string, any>;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"introspection.d.ts","sourceRoot":"","sources":["../../src/helpers/introspection.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,aAAa,EAQd,MAAM,SAAS,CAAC;AAGjB;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,mBAiBjC;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,mBAEvD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,EAAE,uBAmEjF;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,YAAK,EACpC,SAAS,EAAE,MAAM,EAAE,mBAYpB"}
+{"version":3,"file":"introspection.d.ts","sourceRoot":"","sources":["../../src/helpers/introspection.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,aAAa,EAQd,MAAM,SAAS,CAAC;AAGjB;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,mBAiBjC;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,mBAEvD;AAED;;;;GAIG;AAEH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,EAAE,uBAgGjF;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,YAAK,EACpC,SAAS,EAAE,MAAM,EAAE,mBAYpB"}

package/dist/helpers/introspection.js

@@ -31,12 +31,39 @@ async function introspectLocalSchema(path) {
     return await (0, promises_1.readFile)(path, "utf8");
 }
 /**
- * Extract and filter specific types from a schema object.
- * Prevents "No result received" errors by only sending requested parts of the graph.
+ * Extract and filter specific types or root fields from a GraphQL schema.
+ * This prevents "No result received" errors by only sending the requested
+ * parts of the graph to the agent, maintaining a stable context window.
  */
 function introspectSpecificTypes(schema, typeNames) {
     const result = {};
+    // Cache root field maps to avoid repeated lookups during the loop
+    const queryType = schema.getQueryType();
+    const queryFields = queryType ? queryType.getFields() : {};
+    const mutationType = schema.getMutationType();
+    const mutationFields = mutationType ? mutationType.getFields() : {};
     for (const name of typeNames) {
+        // --- ROOT FIELD RESOLUTION ---
+        // Check if the name refers to a root field (Query or Mutation) 
+        // rather than a named Type.
+        const rootField = queryFields[name] || mutationFields[name];
+        if (rootField) {
+            result[name] = {
+                kind: queryFields[name] ? "QUERY_FIELD" : "MUTATION_FIELD",
+                description: rootField.description,
+                type: rootField.type.toString(),
+                args: rootField.args
+                    .filter(arg => !arg.deprecationReason)
+                    .map(arg => ({
+                    name: arg.name,
+                    type: arg.type.toString(),
+                    description: arg.description,
+                }))
+            };
+            continue; // Field found, move to next requested name
+        }
+        // --- NAMED TYPE RESOLUTION ---
+        // Fallback to standard type introspection if no root field matches
         const type = schema.getType(name);
         if (!type)
             continue;

package/dist/index.js

@@ -74,7 +74,6 @@ let schemaLoadError = null;
 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.
@@ -108,15 +107,13 @@ async function getSchema(force = false, requestedTypes) {
     updatePromise = performUpdate(force);
     try {
         if (force || !cachedSDL) {
-            return await updatePromise;
-        }
-        else {
-            updatePromise.catch(err => console.error("[SCHEMA] Background update failed:", err));
-            return cachedSDL;
+            await updatePromise; // Wait for update to complete
+            return cachedSchemaObject;
         }
+        return cachedSchemaObject;
     }
     finally {
-        // Promise reference is cleared inside performUpdate's 'finally' block
+        updatePromise = null;
     }
 }
 /**
@@ -175,11 +172,12 @@ async function performUpdate(force) {
         // Maintain state for "Gap Analysis"
         lastKnownTypeCount = businessTypes.length;
         const currentSDL = printSchema(tempSchema);
-        const duration = ((Date.now() - startTime) / 1000).toFixed(2);
         // --- CACHE & NOTIFICATION ---
+        // Always update the live object if we successfully built it
+        cachedSchemaObject = tempSchema;
         if (currentSDL !== cachedSDL) {
             cachedSDL = currentSDL;
-            cachedSchemaObject = tempSchema; // Store the live Schema object for tool execution
+            const duration = ((Date.now() - startTime) / 1000).toFixed(2);
             return [
                 `✨ SCHEMA EVOLVED (${duration}s)`,
                 `📊 Source: ${env.SCHEMA ? 'Local/Remote SDL' : 'Live Endpoint'}`,
@@ -189,6 +187,7 @@ async function performUpdate(force) {
             ].join('\n');
         }
         else {
+            // Even if SDL string is the same, we've ensured cachedSchemaObject is set above
             return `✅ Status: Schema stable (${lastKnownTypeCount} labels).`;
         }
     }
@@ -269,62 +268,89 @@ toolHandlers.set("query-graphql", queryGraphqlHandler);
     variables: zod_1.default.string().optional(),
     headers: zod_1.default.string().optional(),
 }, queryGraphqlHandler);
-// Tool: introspect-schema
+/**
+ * Tool: introspect-schema
+ * Main handler for the introspection tool.
+ * Implements "Agent Recovery" logic to guide the LLM when entities are missing.
+ */
 const introspectHandler = async ({ typeNames }) => {
-    // 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;
+    // 1. Fetch the schema directly from the source
+    const result = await getSchema(true);
+    // Explicitly check if the result is a valid GraphQLSchema object
+    if (!result || typeof result === 'string') {
+        return {
+            content: [{
+                    type: "text",
+                    text: `❌ SCHEMA_ERROR: ${typeof result === 'string' ? result : 'GraphQL schema is not initialized yet.'}\n` +
+                        `ACTION: Please wait 5-10 seconds for the backend endpoint to respond.`
+                }]
+        };
+    }
+    // --- 1. INITIALIZE MAPPINGS ---
+    const schema = result;
     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 ---
+    // Cache Root Type fields for rapid gap analysis
+    const queryType = schema.getQueryType();
+    const queryFields = queryType ? queryType.getFields() : {};
+    const mutationType = schema.getMutationType();
+    const mutationFields = mutationType ? mutationType.getFields() : {};
+    // --- 2. GAP ANALYSIS & SELF-HEALING LOOP ---
+    // If specific types were requested, verify their existence in the current schema
     if (typeNames && typeNames.length > 0) {
-        const missing = typeNames.filter(name => !typeMap[name]);
+        const missing = typeNames.filter(name => {
+            const existsAsType = !!typeMap[name];
+            const existsAsMutation = !!mutationFields[name];
+            const existsAsQueryField = !!queryFields[name];
+            return !existsAsType && !existsAsMutation && !existsAsQueryField;
+        });
+        // If some requested entities are missing, provide the agent with a recovery map
         if (missing.length > 0) {
+            // Filter out internal GraphQL types to reduce noise for the agent
+            const internalTypes = ['Query', 'Mutation', 'Subscription'];
+            const availableEntities = Object.keys(typeMap).filter(t => !t.startsWith('__') && !internalTypes.includes(t));
+            // Generate a pseudo-version ID based on schema state and time
+            const schemaVersion = `v${availableEntities.length}.${Math.floor(Date.now() / 10000) % 1000}`;
             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(", ")}`
+                        text: `❌ PARTIAL RESULTS [Schema ID: ${schemaVersion}]\n\n` +
+                            `MISSING ENTITIES: ${missing.join(", ")}\n` +
+                            `REASON: These specific types or fields were not found in the current schema.\n` +
+                            `ACTION: Re-examine the available entities below and correct your query intent.\n\n` +
+                            `AVAILABLE_ENTITIES: ${availableEntities.join(", ")}`
                     }]
             };
         }
     }
+    // --- 3. GENERAL MANIFEST GENERATION ---
+    // If no typeNames provided, return a high-level overview of the entry points
     if (!typeNames || typeNames.length === 0) {
-        const queryType = schema.getQueryType();
         const discoveredEntities = new Set();
         if (queryType) {
-            const queryFields = queryType.getFields();
-            Object.values(queryFields).forEach((field) => {
+            // Map Query fields to their underlying Object Types
+            const fields = queryType.getFields();
+            Object.values(fields).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();
-        const communityHeader = [
-            `🌐 Community Channel: #mcp-graphql-enhanced`,
-            `🔗 Join the discussion: https://discord.com/channels/625400653321076807/1480510460339159184`,
-            `---`
-        ].join('\n');
+        const entryPoints = Array.from(discoveredEntities).sort();
+        const allTypes = Object.keys(typeMap).filter(t => !t.startsWith('__'));
+        const schemaVersion = `v${allTypes.length}.${Math.floor(Date.now() / 10000) % 1000}`;
         return {
             content: [{
                     type: "text",
-                    text: `${communityHeader}\n${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(", ")}`
+                    text: `GraphQL Schema Manifest [ID: ${schemaVersion}]\n\n` +
+                        `ENTRY_POINT_ENTITIES: ${entryPoints.join(", ") || "None"}\n` +
+                        `TOTAL_SCHEMA_TYPES: ${allTypes.length}\n\n` +
+                        `ALL_AVAILABLE_TYPES: ${allTypes.join(", ")}`
                 }]
         };
     }
-    // 3. Detailed introspection for specific types
+    // --- 4. DETAILED INTROSPECTION ---
+    // Return filtered schema metadata for the requested types or root fields
     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.7.0"
+	"version": "3.8.1"
 }