@letoribo/mcp-graphql-enhanced 3.8.0 → 3.9.0

package/README.md

@@ -23,6 +23,31 @@ This is the best place to share your feedback, report issues, or suggest new "en
 * ✅ **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.
 
+## 🚀 Multi-Endpoint Broadcast (Experimental in v3.9.0+)
+Starting from **v3.9.0**, the server supports querying multiple GraphQL endpoints simultaneously. This was originally designed to synchronize mutations across different environments (e.g., Node.js and Python backends), but it opens up powerful possibilities for data aggregation.
+
+*   **Zero Breaking Changes**: If you provide a single URL in `ENDPOINT`, the server behaves exactly as before.
+*   **Smart Aggregation**: When multiple comma-separated URLs are provided, the server broadcasts the query to all of them and **merges the resulting arrays**.
+*   **Bypass Free Tier Limits**: Perfect for users of "Free Tier" cloud databases (like Neo4j Aura). You can split your data across multiple free instances and use this bridge to query them as a **single unified graph**, effectively bypassing entity count limitations.
+*   **Deduplication**: The bridge automatically removes duplicate objects based on their unique fields to keep the AI's context window clean.
+
+> **⚠️ Use at your own risk:** This feature assumes all endpoints share the same (or very similar) GraphQL schema. The introspection is performed against the **first** endpoint in the list.
+
+#### 💡 Use Case: Bridging WSL and Windows (PowerShell)
+A common challenge for Windows developers is the network isolation between the Windows Subsystem for Linux (WSL) and the host OS. This feature allows you to bridge these two worlds into a "Unified Nervous System".  
+
+Example configuration for Claude Desktop:
+```bash
+{
+  "ENDPOINT": "http://DESKTOP-NAME.local:2311/graphql,http://127.0.0.1:4000/graphql"
+}
+```
+*   **Hybrid Ecosystem**: Seamlessly query and aggregate data across Windows-native processes (PowerShell) and Linux-based environments (WSL).  
+
+*   **mDNS Support**: By using .local addresses, the bridge automatically resolves the host machine's IP from within the WSL environment.  
+
+*   **Transparent Aggregation**: The AI assistant interacts with a single unified schema, unaware that the data is being fetched from different operating systems simultaneously.
+
 ## 🔍 Advanced Observability & Cypher
 The bridge provides deep insights into how the LLM interacts with your graph database. 
 

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

@@ -16,19 +16,31 @@ 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");
+/**
+ * Retrieves the current version from package.json
+ */
 const getVersion = () => {
     try {
         const pkg = require("../package.json");
         return pkg.version;
     }
     catch {
-        return "3.6.0";
+        return "3.9.0";
     }
 };
 (0, deprecation_js_1.checkDeprecatedArguments)();
+/**
+ * Environment configuration schema
+ */
 const EnvSchema = zod_1.default.object({
     NAME: zod_1.default.string().default("mcp-graphql-enhanced"),
-    ENDPOINT: zod_1.default.preprocess((val) => (typeof val === 'string' ? val.trim() : val), zod_1.default.string().url()).default("https://mcp-neo4j-discord.vercel.app/api/graphiql"),
+    ENDPOINT: zod_1.default.preprocess((val) => {
+        if (typeof val === 'string') {
+            // Support for multiple endpoints via comma-separated string
+            return val.trim();
+        }
+        return val;
+    }, zod_1.default.string().min(1)).default("https://mcp-neo4j-discord.vercel.app/api/graphiql"),
     ALLOW_MUTATIONS: zod_1.default
         .enum(["true", "false"])
         .transform((value) => value === "true")
@@ -60,7 +72,7 @@ const env = EnvSchema.parse(process.env);
 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"
+    description: "Unified GraphQL-to-MCP bridge with dynamic schema support."
 }, {
     capabilities: {
         prompts: {},
@@ -75,7 +87,7 @@ let isUpdating = false;
 let updatePromise = null;
 let lastKnownTypeCount = 0;
 /**
- * Smart Hybrid Schema Fetcher (Zero-Error Version)
+ * Smart Hybrid Schema Fetcher
  * @param force If true, blocks and waits for the new schema evolution.
  * If false, returns cache immediately and updates in background.
  */
@@ -88,12 +100,12 @@ async function getSchema(force = false, requestedTypes) {
     }
     // 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
+        // Validation check: ensure requested types exist in current 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
+                // Force a refresh if requested types are missing
                 return await (updatePromise = performUpdate(true));
             }
         }
@@ -118,8 +130,7 @@ async function getSchema(force = false, requestedTypes) {
 }
 /**
  * Internal logic for schema introspection and building.
- * This version uses universal business-type tracking and provides
- * detailed diagnostic reports instead of generic error messages.
+ * Optimized for Multi-Endpoint Broadcast: Uses the first available URL for discovery.
  */
 async function performUpdate(force) {
     isUpdating = true;
@@ -127,41 +138,43 @@ async function performUpdate(force) {
     try {
         const { buildClientSchema, getIntrospectionQuery, printSchema, buildASTSchema, parse: gqlParse, isObjectType } = require("graphql");
         let tempSchema;
-        // --- FETCHING LOGIC (Unified Source) ---
+        // --- FETCHING LOGIC ---
         if (env.SCHEMA) {
             let sdl;
             if (env.SCHEMA.startsWith("http")) {
-                // Remote SDL File: Fetch via HTTP
+                // Remote SDL File
                 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)
+                // Local SDL File via helper
                 sdl = await (0, introspection_js_1.introspectLocalSchema)(env.SCHEMA);
             }
-            // 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, {
+            // --- BROADCAST ADAPTATION ---
+            // Extract the primary endpoint for introspection
+            const endpoints = env.ENDPOINT.split(',').map(url => url.trim());
+            const primaryEndpoint = endpoints[0];
+            // Execute Introspection against the primary target
+            const response = await fetch(primaryEndpoint, {
                 method: "POST",
                 headers: { "Content-Type": "application/json", ...env.HEADERS },
                 body: JSON.stringify({ query: getIntrospectionQuery() }),
             });
             if (!response.ok)
-                throw new Error(`HTTP_${response.status}: ${response.statusText}`);
+                throw new Error(`HTTP_${response.status} at ${primaryEndpoint}: ${response.statusText}`);
             const result = await response.json();
             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) ---
+        // --- UNIFIED STRUCTURAL ANALYSIS ---
         const typeMap = tempSchema.getTypeMap();
-        // Filter "Business Labels" (Nodes) while ignoring internal scalars/system types
+        // Filter domain types while ignoring internal system scalars and types
         const businessTypes = Object.keys(typeMap).filter(typeName => {
             const type = typeMap[typeName];
             return (!typeName.startsWith('__') &&
@@ -169,34 +182,31 @@ async function performUpdate(force) {
                 !['String', 'Int', 'Float', 'Boolean', 'ID', 'BigInt', 'DateTime'].includes(typeName) &&
                 isObjectType(type));
         });
-        // Maintain state for "Gap Analysis"
         lastKnownTypeCount = businessTypes.length;
         const currentSDL = printSchema(tempSchema);
-        // --- CACHE & NOTIFICATION ---
-        // Always update the live object if we successfully built it
+        // Always update the live object upon successful build
         cachedSchemaObject = tempSchema;
         if (currentSDL !== cachedSDL) {
             cachedSDL = currentSDL;
             const duration = ((Date.now() - startTime) / 1000).toFixed(2);
+            const endpointLabel = env.SCHEMA ? 'Local/Remote SDL' : `Live Broadcast Node (${env.ENDPOINT.split(',').length} targets)`;
             return [
                 `✨ SCHEMA EVOLVED (${duration}s)`,
-                `📊 Source: ${env.SCHEMA ? 'Local/Remote SDL' : 'Live Endpoint'}`,
+                `📊 Source: ${endpointLabel}`,
                 `🧬 Labels: ${businessTypes.join(', ') || 'None'}`,
                 `---`,
                 `The bridge has updated the graph model. New types are now queryable.`
             ].join('\n');
         }
         else {
-            // Even if SDL string is the same, we've ensured cachedSchemaObject is set above
             return `✅ Status: Schema stable (${lastKnownTypeCount} labels).`;
         }
     }
     catch (error) {
-        // 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.`
+            `🛠️ Action: Verify your connection and retry.`
         ].join('\n');
     }
     finally {
@@ -206,50 +216,97 @@ async function performUpdate(force) {
 }
 // --- TOOL REGISTRY ---
 const toolHandlers = new Map();
-// This will store schemas for our dynamic HTTP 'list-tools' response
 const registeredToolsMetadata = [];
-/** * 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.
+/**
+ * History buffer for the last 5 operations to support debugging and visualization.
  */
 let executionLogs = [];
-// Tool: query-graphql
+/**
+ * Tool: query-graphql
+ * Handles query broadcast and execution across multiple endpoints.
+ */
 const queryGraphqlHandler = async ({ query, variables, headers }) => {
     try {
         const parsedQuery = (0, language_1.parse)(query);
         const isMutation = parsedQuery.definitions.some((def) => def.kind === "OperationDefinition" && def.operation === "mutation");
-        if (isMutation && !env.ALLOW_MUTATIONS)
+        if (isMutation && !env.ALLOW_MUTATIONS) {
             throw new Error("Mutations are not allowed.");
+        }
         const toolHeaders = headers ? JSON.parse(headers) : {};
         const allHeaders = { "Content-Type": "application/json", ...env.HEADERS, ...toolHeaders };
         let parsedVariables = variables;
         if (typeof variables === 'string')
             parsedVariables = JSON.parse(variables);
-        const response = await fetch(env.ENDPOINT, {
-            method: "POST",
-            headers: allHeaders,
-            body: JSON.stringify({ query, variables: parsedVariables }),
-        });
-        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()
+        // Split multiple endpoints for broadcast
+        const endpoints = env.ENDPOINT.split(',').map(url => url.trim());
+        // Execute parallel requests to all targets
+        const settleResults = await Promise.allSettled(endpoints.map(async (url) => {
+            console.error(`[QUERY] Sending to ${url}`);
+            const response = await fetch(url, {
+                method: "POST",
+                headers: allHeaders,
+                body: JSON.stringify({ query, variables: parsedVariables }),
+                signal: AbortSignal.timeout(5000) // 5s timeout protection
+            });
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status} from ${url}`);
+            }
+            return {
+                url,
+                data: await response.json()
+            };
+        }));
+        const successfulResponses = settleResults
+            .filter((r) => r.status === 'fulfilled')
+            .map(r => r.value);
+        const failedResponses = settleResults
+            .filter((r) => r.status === 'rejected')
+            .map(r => r.reason.message || r.reason);
+        if (successfulResponses.length === 0) {
+            throw new Error(`All endpoints failed: ${failedResponses.join('; ')}`);
+        }
+        const aggregatedResult = {};
+        successfulResponses.forEach((response) => {
+            const data = response.data.data;
+            if (data && data.patterns) {
+                console.error(`[DEBUG] Received ${data.patterns.length} patterns from ${response.url}`);
+            }
+            if (!data)
+                return;
+            Object.keys(data).forEach(key => {
+                if (Array.isArray(data[key])) {
+                    // Merge arrays from different sources
+                    aggregatedResult[key] = [...(aggregatedResult[key] || []), ...data[key]];
+                }
+                else if (typeof data[key] === 'object' && data[key] !== null) {
+                    // Merge objects (e.g. metadata)
+                    aggregatedResult[key] = { ...(aggregatedResult[key] || {}), ...data[key] };
+                }
+                else {
+                    // Use last value for primitives
+                    aggregatedResult[key] = data[key];
+                }
+            });
         });
-        if (executionLogs.length > 5)
-            executionLogs.shift();
-        // 3. Prepare optimized response for Claude
+        // 2. Deduplication (Removes duplicates by 'sticking' field)
+        if (aggregatedResult.patterns) {
+            const unique = new Map();
+            aggregatedResult.patterns.forEach((p) => unique.set(p.sticking, p));
+            aggregatedResult.patterns = Array.from(unique.values());
+        }
+        // 3. Extract Cypher queries from extensions
+        const allCypher = successfulResponses.flatMap(r => r.data.extensions?.cypher || []);
+        const cleanCypher = allCypher.map((c) => c.replace(/^CYPHER: /, '').replace(/^CYPHER 5\n/, '').replace(/\nPARAMS: \{\}$/, ''));
+        // 4. Final response for the AI agent
         const responseForClaude = {
-            result: data.data,
-            // Only add the cypher field if there's actual data to show
-            ...(cleanCypher.length > 0 ? { cypher: cleanCypher } : {})
+            status: {
+                total: endpoints.length,
+                success: successfulResponses.length,
+                failed: failedResponses.length
+            },
+            result: aggregatedResult,
+            ...(cleanCypher.length > 0 ? { cypher: Array.from(new Set(cleanCypher)) } : {}),
+            ...(failedResponses.length > 0 ? { warnings: failedResponses } : {})
         };
         return {
             content: [{
@@ -268,76 +325,76 @@ 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
+ * Provides schema exploration with built-in agent recovery logic.
+ */
 const introspectHandler = async ({ typeNames }) => {
-    // 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.`
+                        `ACTION: Please wait 5-10 seconds for the backend endpoint to respond.`
                 }]
         };
     }
-    // TYPE FIX: Cast to GraphQLSchema so TS knows methods like getTypeMap exist
     const schema = result;
     const typeMap = schema.getTypeMap();
+    const queryType = schema.getQueryType();
+    const queryFields = queryType ? queryType.getFields() : {};
     const mutationType = schema.getMutationType();
     const mutationFields = mutationType ? mutationType.getFields() : {};
-    // --- GAP ANALYSIS ---
+    // Gap analysis for requested types
     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 (missing.length > 0) {
-            const typeKeys = Object.keys(typeMap).filter(t => !t.startsWith('__'));
-            const schemaVersion = `v${typeKeys.length}.${Math.floor(Date.now() / 10000) % 1000}`;
+            const internalTypes = ['Query', 'Mutation', 'Subscription'];
+            const availableEntities = Object.keys(typeMap).filter(t => !t.startsWith('__') && !internalTypes.includes(t));
+            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: Requested entities not found.\n` +
+                            `ACTION: Re-examine available types below.\n\n` +
+                            `AVAILABLE_ENTITIES: ${availableEntities.join(", ")}`
                     }]
             };
         }
     }
-    // 2. Generate General Manifest
+    // Return general manifest if no specific types requested
     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 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
     const filtered = (0, introspection_js_1.introspectSpecificTypes)(schema, typeNames);
     return {
         content: [{ type: "text", text: JSON.stringify(filtered, null, 2) }]
@@ -347,63 +404,54 @@ toolHandlers.set("introspect-schema", introspectHandler);
 (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
+// --- PROMPTS ---
 (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 ---
+/**
+ * Local HTTP server to support GraphiQL UI and SSE transport
+ */
 async function handleHttpRequest(req, res) {
-    // Standard CORS headers for cross-origin compatibility
+    // Standard CORS headers
     res.setHeader('Access-Control-Allow-Origin', '*');
-    res.setHeader('Access-Control-Allow-Methods', 'POST, GET, OPTIONS');
-    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
-    // Handle preflight requests
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, x-mcp-protocol-version, x-mcp-sdk-version');
     if (req.method === 'OPTIONS') {
         res.writeHead(204);
         res.end();
         return;
     }
     const url = new URL(req.url || '', `http://${req.headers.host}`);
-    // Serve Web GUI (GraphiQL) - ONLY if explicitly enabled
+    // Render GraphiQL UI
     if (req.method === 'GET' && (url.pathname === '/' || url.pathname === '/graphiql')) {
-        // 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.");
-        }
+        res.writeHead(200, { 'Content-Type': 'text/html' });
+        return res.end((0, graphiql_js_1.renderGraphiQL)(`http://localhost:6274/mcp`, env.HEADERS));
     }
-    // Process MCP JSON-RPC Endpoint
+    // Process MCP/GraphQL requests
     if (url.pathname === '/mcp' && req.method === 'POST') {
         let body = '';
         req.on('data', chunk => { body += chunk; });
         req.on('end', async () => {
-            let requestId = null; // Defined early to be accessible in catch block
+            let requestId = null;
             try {
-                const request = JSON.parse(body);
-                const { method, id, params } = request;
-                requestId = id;
-                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',
-                        id: requestId,
-                        result: { tools: registeredToolsMetadata }
-                    }));
+                const payload = JSON.parse(body);
+                // Handle raw GraphQL queries (e.g., from Docs or Playground)
+                if (!payload.method && payload.query) {
+                    const handler = toolHandlers.get("query-graphql");
+                    if (handler) {
+                        const mcpResult = await handler({ query: payload.query, variables: payload.variables });
+                        const parsed = JSON.parse(mcpResult.content[0].text);
+                        res.writeHead(200, { 'Content-Type': 'application/json' });
+                        const graphQLResponse = parsed.result.data ? parsed.result : { data: parsed.result };
+                        return res.end(JSON.stringify(graphQLResponse));
+                    }
                 }
-                // --- TOOL EXECUTION (CALL) ---
+                // Standard MCP JSON-RPC handling
+                const { method, id, params } = payload;
+                requestId = id;
                 let targetMethod = method;
                 let toolArgs = params;
-                // Support both direct calls and standard MCP "call-tool" structure
                 if (method === "call-tool" || method === "tools/call") {
                     targetMethod = params.name;
                     toolArgs = params.arguments;
@@ -417,14 +465,9 @@ async function handleHttpRequest(req, res) {
                         error: { code: -32601, message: `Tool ${targetMethod} not found` }
                     }));
                 }
-                // Execute the actual business logic for the tool
                 const result = await handler(toolArgs);
                 res.writeHead(200, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({
-                    jsonrpc: '2.0',
-                    id: requestId,
-                    result
-                }));
+                res.end(JSON.stringify({ jsonrpc: '2.0', id: requestId, result }));
             }
             catch (e) {
                 console.error(`[HTTP-ERROR] ${e.message}`);
@@ -432,18 +475,12 @@ async function handleHttpRequest(req, res) {
                 res.end(JSON.stringify({
                     jsonrpc: '2.0',
                     id: requestId,
-                    error: { code: -32603, message: e.message || "Internal Server Error" }
+                    error: { code: -32603, message: e.message }
                 }));
             }
         });
         return;
     }
-    // Health check endpoint for monitoring
-    if (url.pathname === '/health') {
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        return res.end(JSON.stringify({ status: "ok", server: env.NAME }));
-    }
-    // Default 404 for unknown paths
     res.writeHead(404);
     res.end("Not Found");
 }
@@ -451,7 +488,7 @@ async function handleHttpRequest(req, res) {
 async function main() {
     const isInspector = !!(process.env.MCP_INSPECTOR || process.env.INSPECTOR_PORT);
     const isHttpExplicitlyEnabled = process.env.ENABLE_HTTP === "true";
-    // Open HTTP port by default for MCP SSE, unless explicitly disabled
+    // Enable HTTP port by default unless explicitly disabled or in inspector mode
     if (process.env.ENABLE_HTTP !== "false" && !isInspector) {
         const serverHttp = node_http_1.default.createServer(handleHttpRequest);
         serverHttp.on('error', (e) => {
@@ -460,10 +497,8 @@ async function main() {
             }
         });
         serverHttp.listen(env.MCP_PORT, () => {
-            // 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`);
             }
@@ -471,6 +506,7 @@ async function main() {
     }
     const transport = new stdio_js_1.StdioServerTransport();
     await server.connect(transport);
+    // Background schema initialization
     getSchema().catch(() => { });
 }
 process.on('SIGINT', () => process.exit(0));

package/package.json

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