@letoribo/mcp-graphql-enhanced 3.8.0 → 3.8.1

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

@@ -268,76 +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 ---
+/**
+ * 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. Fetch the schema directly
+    // 1. Fetch the schema directly from the source
     const result = await getSchema(true);
-    // Explicitly check if the result is an error string or null
+    // 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 Neo4j endpoint to respond.`
+                        `ACTION: Please wait 5-10 seconds for the backend endpoint to respond.`
                 }]
         };
     }
-    // TYPE FIX: Cast to GraphQLSchema so TS knows methods like getTypeMap exist
+    // --- 1. INITIALIZE MAPPINGS ---
     const schema = result;
     const typeMap = schema.getTypeMap();
+    // 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() : {};
-    // --- GAP ANALYSIS ---
+    // --- 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 => {
             const existsAsType = !!typeMap[name];
             const existsAsMutation = !!mutationFields[name];
-            return !existsAsType && !existsAsMutation;
+            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) {
-            const typeKeys = Object.keys(typeMap).filter(t => !t.startsWith('__'));
-            const schemaVersion = `v${typeKeys.length}.${Math.floor(Date.now() / 10000) % 1000}`;
+            // 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` +
+                        text: `❌ PARTIAL RESULTS [Schema ID: ${schemaVersion}]\n\n` +
                             `MISSING ENTITIES: ${missing.join(", ")}\n` +
-                            `REASON: These specific types or mutations were not found in the current schema map.\n` +
-                            `ACTION: Ensure the names match your Neo4j labels exactly.\n\n` +
-                            `AVAILABLE_ENTITIES: ${typeKeys.filter(t => !['Query', 'Mutation', 'Report'].includes(t)).join(", ")}`
+                            `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(", ")}`
                     }]
             };
         }
     }
-    // 2. Generate General Manifest
+    // --- 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) {
-            // TYPE FIX: Cast fields to Record<string, GraphQLField<any, any>>
-            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 typeKeys = Object.keys(typeMap).filter(t => !t.startsWith('__'));
-        const schemaVersion = `v${typeKeys.length}.${Math.floor(Date.now() / 10000) % 1000}`;
+        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: `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(", ")}`
+                        `ENTRY_POINT_ENTITIES: ${entryPoints.join(", ") || "None"}\n` +
+                        `TOTAL_SCHEMA_TYPES: ${allTypes.length}\n\n` +
+                        `ALL_AVAILABLE_TYPES: ${allTypes.join(", ")}`
                 }]
         };
     }
-    // 3. Detailed introspection
+    // --- 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.8.0"
+	"version": "3.8.1"
 }