@letoribo/mcp-graphql-enhanced 3.6.0 → 3.8.0

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/prompt-registry.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Universal prompt wrapper for MCP server
+ */
+export declare function registerPrompt(server: any, name: string, description: string, template: string): void;
+//# sourceMappingURL=prompt-registry.d.ts.map

package/dist/helpers/prompt-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-registry.d.ts","sourceRoot":"","sources":["../../src/helpers/prompt-registry.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,wBAAgB,cAAc,CAC1B,MAAM,EAAE,GAAG,EACX,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,QAenB"}

package/dist/helpers/prompt-registry.js

@@ -0,0 +1,22 @@
+"use strict";
+// src/helpers/prompt-registry.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerPrompt = registerPrompt;
+/**
+ * Universal prompt wrapper for MCP server
+ */
+function registerPrompt(server, name, description, template) {
+    server.prompt(name, description, (args) => {
+        return {
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: template + (args?.focus ? ` Focus on: ${args.focus}` : "")
+                    }
+                }
+            ]
+        };
+    });
+}

package/dist/helpers/tool-registry.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Universal tool wrapper that registers tools for both MCP and HTTP Discovery.
+ * Handles Zod schema parsing to generate metadata for external clients.
+ */
+export declare function registerTool(server: any, toolHandlers: Map<string, (args: any) => Promise<any>>, registeredToolsMetadata: any[], name: string, description: string, schema: any, handler: (args: any) => Promise<any>): void;
+//# sourceMappingURL=tool-registry.d.ts.map

package/dist/helpers/tool-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../../src/helpers/tool-registry.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,YAAY,CACxB,MAAM,EAAE,GAAG,EACX,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC,EACtD,uBAAuB,EAAE,GAAG,EAAE,EAC9B,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,GAAG,EACX,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,QAwCvC"}

package/dist/helpers/tool-registry.js

@@ -0,0 +1,42 @@
+"use strict";
+// src/helpers/tool-registry.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTool = registerTool;
+/**
+ * Universal tool wrapper that registers tools for both MCP and HTTP Discovery.
+ * Handles Zod schema parsing to generate metadata for external clients.
+ */
+function registerTool(server, toolHandlers, registeredToolsMetadata, name, description, schema, handler) {
+    // 1. Official MCP Server registration
+    server.tool(name, description, schema, handler);
+    // 2. Map handler for internal HTTP routing
+    toolHandlers.set(name, handler);
+    // 3. Smart metadata generation for Discovery (HTTP list-tools)
+    registeredToolsMetadata.push({
+        name,
+        description,
+        inputSchema: {
+            type: "object",
+            properties: Object.fromEntries(Object.entries(schema).map(([key, value]) => {
+                // Recursive helper to extract type info from Zod objects
+                const getZodType = (v) => {
+                    const type = v?._def?.typeName?.replace('Zod', '').toLowerCase() || "string";
+                    if (type === 'array') {
+                        return {
+                            type: "array",
+                            items: { type: getZodType(v._def.type) }
+                        };
+                    }
+                    return { type };
+                };
+                const typeInfo = getZodType(value);
+                return [key, typeInfo];
+            })),
+            // Identify required fields by checking for ZodOptional or '?' in key
+            required: Object.keys(schema).filter(key => {
+                const val = schema[key];
+                return val?._def?.typeName !== 'ZodOptional' && !key.includes('?');
+            })
+        }
+    });
+}

package/dist/index.js

@@ -14,13 +14,15 @@ const graphql_1 = require("graphql");
 // Helper imports
 const deprecation_js_1 = require("./helpers/deprecation.js");
 const introspection_js_1 = require("./helpers/introspection.js");
+const tool_registry_js_1 = require("./helpers/tool-registry.js");
+const prompt_registry_js_1 = require("./helpers/prompt-registry.js");
 const getVersion = () => {
     try {
         const pkg = require("../package.json");
         return pkg.version;
     }
     catch {
-        return "3.2.1";
+        return "3.6.0";
     }
 };
 (0, deprecation_js_1.checkDeprecatedArguments)();
@@ -59,6 +61,11 @@ const server = new mcp_js_1.McpServer({
     name: env.NAME,
     version: getVersion(),
     description: "Start of the #mcp-graphql-enhanced channel on GraphQL server. Join here: https://discord.com/channels/622115132221685760/1348633379555184640"
+}, {
+    capabilities: {
+        prompts: {},
+        tools: {}
+    }
 });
 // --- CACHE STATE ---
 let cachedSDL = null;
@@ -67,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.
@@ -101,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;
     }
 }
 /**
@@ -168,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'}`,
@@ -182,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).`;
         }
     }
@@ -202,37 +208,6 @@ async function performUpdate(force) {
 const toolHandlers = new Map();
 // This will store schemas for our dynamic HTTP 'list-tools' response
 const registeredToolsMetadata = [];
-/**
- * Helper to register tools in both MCP Server and our local registry
- * Handles both plain objects and Zod schemas
- */
-function registerTool(name, description, schema, handler) {
-    // 1. Register in official MCP Server
-    server.tool(name, description, schema, handler);
-    // 2. Save handler for our HTTP routing
-    toolHandlers.set(name, handler);
-    // 3. Store metadata for dynamic Discovery
-    // We treat 'schema' as a plain object for the JSON output
-    registeredToolsMetadata.push({
-        name,
-        description,
-        inputSchema: {
-            type: "object",
-            properties: Object.fromEntries(Object.entries(schema).map(([key, value]) => {
-                // Detect type from Zod or default to string
-                const typeName = value?._def?.typeName
-                    ? value._def.typeName.replace('Zod', '').toLowerCase()
-                    : "string";
-                return [key, { type: typeName }];
-            })),
-            // Assume all fields in the object are required unless specified
-            required: Object.keys(schema).filter(key => {
-                const val = schema[key];
-                return val?._def?.typeName !== 'ZodOptional' && !key.includes('?');
-            })
-        }
-    });
-}
 /** * 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.
@@ -288,41 +263,59 @@ const queryGraphqlHandler = async ({ query, variables, headers }) => {
     }
 };
 toolHandlers.set("query-graphql", queryGraphqlHandler);
-registerTool("query-graphql", "Execute a GraphQL query against the endpoint", {
+(0, tool_registry_js_1.registerTool)(server, toolHandlers, registeredToolsMetadata, "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
+// --- TOOL: introspect-schema ---
 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
+    const result = await getSchema(true);
+    // Explicitly check if the result is an error string or null
+    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.`
+                }]
+        };
+    }
+    // TYPE FIX: Cast to GraphQLSchema so TS knows methods like getTypeMap exist
+    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 ---
+    const mutationType = schema.getMutationType();
+    const mutationFields = mutationType ? mutationType.getFields() : {};
+    // --- GAP ANALYSIS ---
     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];
+            return !existsAsType && !existsAsMutation;
+        });
         if (missing.length > 0) {
+            const typeKeys = Object.keys(typeMap).filter(t => !t.startsWith('__'));
+            const schemaVersion = `v${typeKeys.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(", ")}`
+                            `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(", ")}`
                     }]
             };
         }
     }
+    // 2. Generate General Manifest
     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) => {
                 const namedType = (0, graphql_1.getNamedType)(field.type);
@@ -332,32 +325,35 @@ const introspectHandler = async ({ typeNames }) => {
             });
         }
         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 typeKeys = Object.keys(typeMap).filter(t => !t.startsWith('__'));
+        const schemaVersion = `v${typeKeys.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` +
+                    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(", ")}`
                 }]
         };
     }
-    // 3. Detailed introspection for specific types
+    // 3. Detailed introspection
     const filtered = (0, introspection_js_1.introspectSpecificTypes)(schema, typeNames);
     return {
         content: [{ type: "text", text: JSON.stringify(filtered, null, 2) }]
     };
 };
 toolHandlers.set("introspect-schema", introspectHandler);
-registerTool("introspect-schema", "Introspect the GraphQL schema with optional type filtering", {
+(0, tool_registry_js_1.registerTool)(server, toolHandlers, registeredToolsMetadata, "introspect-schema", "Introspect the GraphQL schema with optional type filtering", {
     typeNames: zod_1.default.array(zod_1.default.string()).optional(),
 }, introspectHandler);
+// --- PROMPTS (The "Add from ..." buttons in Claude UI) ---
+// 1. Connection check
+(0, prompt_registry_js_1.registerPrompt)(server, "health-check", "Check if the GraphQL endpoint is alive", "Run 'query-graphql' with query '{ __typename }' to verify connection.");
+// 2. High-level overview
+(0, prompt_registry_js_1.registerPrompt)(server, "schema-overview", "List all available types", "Run 'introspect-schema' to see all types and entry points.");
+// 3. Data types analysis
+(0, prompt_registry_js_1.registerPrompt)(server, "list-scalars", "List all scalar types", "Run 'introspect-schema' and identify all scalars in the schema.");
 // --- HTTP SERVER LOGIC ---
 async function handleHttpRequest(req, res) {
     // Standard CORS headers for cross-origin compatibility
@@ -371,10 +367,18 @@ async function handleHttpRequest(req, res) {
         return;
     }
     const url = new URL(req.url || '', `http://${req.headers.host}`);
-    // Serve Web GUI (GraphiQL)
+    // Serve Web GUI (GraphiQL) - ONLY if explicitly enabled
     if (req.method === 'GET' && (url.pathname === '/' || url.pathname === '/graphiql')) {
-        res.writeHead(200, { 'Content-Type': 'text/html' });
-        return res.end((0, graphiql_js_1.renderGraphiQL)(env.ENDPOINT, env.HEADERS));
+        // Check our explicit flag
+        if (process.env.ENABLE_HTTP === 'true') {
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            return res.end((0, graphiql_js_1.renderGraphiQL)(env.ENDPOINT, env.HEADERS));
+        }
+        else {
+            // Forbidden if not explicitly enabled
+            res.writeHead(403, { 'Content-Type': 'text/plain' });
+            return res.end("Forbidden: GraphiQL UI is disabled. Start with ENABLE_HTTP=true to use it.");
+        }
     }
     // Process MCP JSON-RPC Endpoint
     if (url.pathname === '/mcp' && req.method === 'POST') {
@@ -389,7 +393,6 @@ async function handleHttpRequest(req, res) {
                 console.error(`[HTTP-RPC] Method: ${method} | ID: ${id}`);
                 // --- DYNAMIC DISCOVERY ---
                 if (method === "list-tools" || method === "tools/list") {
-                    // Просто отдаем то, что накопили в нашем реестре при регистрации
                     res.writeHead(200, { 'Content-Type': 'application/json' });
                     return res.end(JSON.stringify({
                         jsonrpc: '2.0',
@@ -446,38 +449,29 @@ async function handleHttpRequest(req, res) {
 }
 // --- STARTUP ---
 async function main() {
-    const rawEnableHttp = process.env.ENABLE_HTTP;
-    // Determine if we should open the HTTP port.
-    // 1. Check if we're not running inside the MCP Inspector.
-    // 2. Ensure the user hasn't explicitly disabled HTTP (ENABLE_HTTP="false").
     const isInspector = !!(process.env.MCP_INSPECTOR || process.env.INSPECTOR_PORT);
-    const shouldOpenPort = rawEnableHttp !== "false" && !isInspector;
-    if (shouldOpenPort) {
+    const isHttpExplicitlyEnabled = process.env.ENABLE_HTTP === "true";
+    // Open HTTP port by default for MCP SSE, unless explicitly disabled
+    if (process.env.ENABLE_HTTP !== "false" && !isInspector) {
         const serverHttp = node_http_1.default.createServer(handleHttpRequest);
-        // Error handling to prevent crashes if the port is already in use
         serverHttp.on('error', (e) => {
-            if (e.code !== 'EADDRINUSE')
-                console.error(`[HTTP-ERROR] ${e.message}`);
+            if (e.code === 'EADDRINUSE') {
+                console.error(`[HTTP-ERROR] Port ${env.MCP_PORT} is busy.`);
+            }
         });
         serverHttp.listen(env.MCP_PORT, () => {
-            // Log URLs only if HTTP is explicitly enabled
-            if (env.ENABLE_HTTP === true) {
-                console.error(`[HTTP] Server started on http://localhost:${env.MCP_PORT}`);
-                console.error(`🎨 GraphiQL IDE: http://localhost:${env.MCP_PORT}/graphiql`);
+            // All-in-one status report
+            console.error(`[SYSTEM] Server "${env.NAME}" v${getVersion()} active`);
+            console.error(`🤖 MCP SSE: http://localhost:${env.MCP_PORT}/mcp`);
+            // Show UI only if explicitly requested
+            if (isHttpExplicitlyEnabled) {
+                console.error(`🎨 GraphiQL UI: http://localhost:${env.MCP_PORT}/graphiql`);
             }
-            console.error(`🤖 MCP Endpoint: http://localhost:${env.MCP_PORT}/mcp`);
         });
     }
     const transport = new stdio_js_1.StdioServerTransport();
     await server.connect(transport);
-    // Maintain quiet mode when running inside the Inspector to avoid protocol interference
-    if (!isInspector) {
-        console.error(`[STDIO] MCP Server "${env.NAME}" v${getVersion()} started`);
-    }
-    getSchema().catch(e => {
-        if (!isInspector)
-            console.error(`[SCHEMA] Warning: ${e.message}`);
-    });
+    getSchema().catch(() => { });
 }
 process.on('SIGINT', () => process.exit(0));
 process.on('SIGTERM', () => process.exit(0));

package/package.json

@@ -50,5 +50,5 @@
 		"tsx": "^4.21.0",
 		"typescript": "5.8.3"
 	},
-	"version": "3.6.0"
+	"version": "3.8.0"
 }