@letoribo/mcp-graphql-enhanced 3.8.1 → 3.9.1

package/README.md

@@ -23,6 +23,30 @@ 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.
 
+## 🚀 Federated Multi-Node Architecture (v3.9.1+)
+The server operates as a Federated GraphQL Gateway, merging independent nodes into a unified system.
+
+*   **Zero Breaking Changes**: If you provide a single URL in `ENDPOINT`, the server behaves exactly as before.
+*   **Federated Introspection**: Scans all endpoints simultaneously to build a global capability map.
+*   **Smart Aggregation**: When multiple comma-separated URLs are provided, the server broadcasts queries and merges results using universal deep deduplication (object-level).
+*   **Conflict Handling**: Identifies structural differences in identical Type names across nodes and exposes them uniquely.
+*   **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.
+
+#### 💡 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/index.js

@@ -16,19 +16,29 @@ 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 - Strict validation
+ */
 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')
+            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")
@@ -57,57 +67,52 @@ const EnvSchema = zod_1.default.object({
         .default("auto"),
 });
 const env = EnvSchema.parse(process.env);
+/**
+ * Initialize MCP Server with full capabilities
+ */
 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: "Federated GraphQL-to-MCP bridge with broadcast introspection and full type visibility."
 }, {
     capabilities: {
         prompts: {},
         tools: {}
     }
 });
-// --- CACHE STATE ---
+// --- GLOBAL STATE MANAGEMENT ---
 let cachedSDL = null;
 let cachedSchemaObject = null;
+let cachedSchemas = [];
 let schemaLoadError = null;
 let isUpdating = false;
 let updatePromise = null;
-let lastKnownTypeCount = 0;
 /**
- * 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.
+ * Schema Fetcher with dependency tracking
  */
 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
+        if (requestedTypes && cachedSchemas.length > 0) {
+            const allTypes = new Set(cachedSchemas.flatMap(s => Object.keys(s.getTypeMap())));
+            const missing = requestedTypes.filter(t => !allTypes.has(t));
+            if (missing.length > 0)
                 return await (updatePromise = performUpdate(true));
-            }
         }
-        return cachedSDL;
+        return cachedSchemaObject;
     }
     if (force)
         schemaLoadError = null;
     if (schemaLoadError)
         throw schemaLoadError;
-    // 3. Trigger update
     updatePromise = performUpdate(force);
     try {
         if (force || !cachedSDL) {
-            await updatePromise; // Wait for update to complete
+            await updatePromise;
             return cachedSchemaObject;
         }
         return cachedSchemaObject;
@@ -117,378 +122,279 @@ 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.
+ * Federated Update: Orchestrates introspection across all endpoints
  */
 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) {
-            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);
-            }
-            // 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, {
+        const endpoints = env.ENDPOINT.split(',').map(url => url.trim());
+        console.error(`[SYNC] Initializing broadcast to ${endpoints.length} nodes...`);
+        const results = await Promise.allSettled(endpoints.map(async (url) => {
+            const response = await fetch(url, {
                 method: "POST",
                 headers: { "Content-Type": "application/json", ...env.HEADERS },
-                body: JSON.stringify({ query: getIntrospectionQuery() }),
+                body: JSON.stringify({ query: (0, graphql_1.getIntrospectionQuery)() }),
+                signal: AbortSignal.timeout(10000)
             });
             if (!response.ok)
-                throw new Error(`HTTP_${response.status}: ${response.statusText}`);
+                throw new Error(`HTTP Error ${response.status}`);
             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);
+                throw new Error("Empty introspection data");
+            const schema = (0, graphql_1.buildClientSchema)(result.data);
+            schema._originUrl = url;
+            return { url, schema };
+        }));
+        const successful = results
+            .filter((r) => r.status === 'fulfilled')
+            .map(r => r.value);
+        const failures = results
+            .filter((r) => r.status === 'rejected')
+            .map(r => r.reason.message);
+        if (successful.length === 0) {
+            throw new Error(`Federation failed. All nodes unreachable: ${failures.join(', ')}`);
         }
-        // --- 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));
+        // Update cache with all discovered schemas
+        cachedSchemas = successful.map(s => s.schema);
+        cachedSchemaObject = cachedSchemas[0]; // Baseline schema
+        cachedSDL = (0, graphql_1.printSchema)(cachedSchemaObject);
+        // Generate Node Manifest for AI reasoning (Full data, no slices)
+        global.nodeManifest = successful.map(node => {
+            const typeMap = node.schema.getTypeMap();
+            const domainTypes = Object.keys(typeMap).filter(name => {
+                const type = typeMap[name];
+                return !name.startsWith('__') && !(0, graphql_1.isScalarType)(type);
+            });
+            return {
+                endpoint: node.url,
+                availableMutations: Object.keys(node.schema.getMutationType()?.getFields() || {}),
+                domainEntities: domainTypes
+            };
         });
-        // Maintain state for "Gap Analysis"
-        lastKnownTypeCount = businessTypes.length;
-        const currentSDL = printSchema(tempSchema);
-        // --- CACHE & NOTIFICATION ---
-        // Always update the live object if we successfully built it
-        cachedSchemaObject = tempSchema;
-        if (currentSDL !== cachedSDL) {
-            cachedSDL = currentSDL;
-            const duration = ((Date.now() - startTime) / 1000).toFixed(2);
-            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 {
-            // Even if SDL string is the same, we've ensured cachedSchemaObject is set above
-            return `✅ Status: Schema stable (${lastKnownTypeCount} labels).`;
-        }
+        const uniqueTypeCount = new Set(cachedSchemas.flatMap(s => Object.keys(s.getTypeMap()))).size;
+        const duration = ((Date.now() - startTime) / 1000).toFixed(2);
+        return `✅ FEDERATION SYNCED: ${successful.length} active nodes, ${uniqueTypeCount} unique types discovered in ${duration}s.`;
     }
     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.`
-        ].join('\n');
+        console.error(`[CRITICAL] Sync failure: ${error.message}`);
+        schemaLoadError = error;
+        return `❌ SYNC ERROR: ${error.message}`;
     }
     finally {
         isUpdating = false;
         updatePromise = null;
     }
 }
-// --- TOOL REGISTRY ---
+// --- TOOLS IMPLEMENTATION ---
 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.
+/**
+ * Tool: query-graphql
+ * Broadcasts queries to all nodes and merges results with universal deduplication.
  */
-let executionLogs = [];
-// Tool: query-graphql
 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)
-            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()
+        const hasMutation = parsedQuery.definitions.some((def) => def.kind === "OperationDefinition" && def.operation === "mutation");
+        if (hasMutation && !env.ALLOW_MUTATIONS) {
+            throw new Error("Mutation execution is blocked by ALLOW_MUTATIONS=false.");
+        }
+        const runtimeHeaders = headers ? JSON.parse(headers) : {};
+        const fetchHeaders = { "Content-Type": "application/json", ...env.HEADERS, ...runtimeHeaders };
+        const fetchVariables = variables ? (typeof variables === 'string' ? JSON.parse(variables) : variables) : undefined;
+        const endpoints = env.ENDPOINT.split(',').map(url => url.trim());
+        const executeResults = await Promise.allSettled(endpoints.map(async (url) => {
+            const response = await fetch(url, {
+                method: "POST",
+                headers: fetchHeaders,
+                body: JSON.stringify({ query, variables: fetchVariables }),
+                signal: AbortSignal.timeout(15000)
+            });
+            if (!response.ok)
+                throw new Error(`Node ${url} returned ${response.status}`);
+            return { url, data: await response.json() };
+        }));
+        const successes = executeResults
+            .filter((r) => r.status === 'fulfilled')
+            .map(r => r.value);
+        if (successes.length === 0)
+            throw new Error("Execution failed on all available nodes.");
+        // Aggregate and Deduplicate
+        const mergedData = {};
+        successes.forEach((resp) => {
+            const nodeData = resp.data.data;
+            if (!nodeData)
+                return;
+            Object.keys(nodeData).forEach(key => {
+                if (Array.isArray(nodeData[key])) {
+                    const existing = mergedData[key] || [];
+                    const combined = [...existing, ...nodeData[key]];
+                    // Universal object-level deduplication
+                    mergedData[key] = Array.from(new Set(combined.map(v => JSON.stringify(v))))
+                        .map(s => JSON.parse(s));
+                }
+                else if (typeof nodeData[key] === 'object' && nodeData[key] !== null) {
+                    mergedData[key] = { ...(mergedData[key] || {}), ...nodeData[key] };
+                }
+                else {
+                    mergedData[key] = nodeData[key];
+                }
+            });
         });
-        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 } : {})
-        };
+        // Restore Cypher extraction logic
+        const cypherLogs = successes.flatMap(r => r.data.extensions?.cypher || []);
+        const cleanCypher = cypherLogs.map((c) => c.replace(/^CYPHER: /, '').replace(/^CYPHER 5\n/, '').replace(/\nPARAMS: \{\}$/, ''));
         return {
             content: [{
                     type: "text",
-                    text: JSON.stringify(responseForClaude, null, 2)
+                    text: JSON.stringify({
+                        meta: { nodes_queried: endpoints.length, nodes_responding: successes.length },
+                        data: mergedData,
+                        ...(cleanCypher.length > 0 ? { cypher_execution_plan: cleanCypher } : {})
+                    }, null, 2)
                 }]
         };
     }
     catch (error) {
-        throw new Error(`Execution failed: ${error.message}`);
+        return { content: [{ type: "text", text: `❌ Execution error: ${error.message}` }], isError: true };
     }
 };
 toolHandlers.set("query-graphql", queryGraphqlHandler);
-(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(),
+(0, tool_registry_js_1.registerTool)(server, toolHandlers, registeredToolsMetadata, "query-graphql", "Execute a GraphQL query across all nodes in the federated system", {
+    query: zod_1.default.string().describe("The GraphQL query or mutation string"),
+    variables: zod_1.default.string().optional().describe("JSON string of variables"),
+    headers: zod_1.default.string().optional().describe("JSON string of extra headers"),
 }, queryGraphqlHandler);
 /**
  * Tool: introspect-schema
- * Main handler for the introspection tool.
- * Implements "Agent Recovery" logic to guide the LLM when entities are missing.
+ * Provides a global view of all nodes and resolves type conflicts.
  */
 const introspectHandler = async ({ typeNames }) => {
-    // 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();
-    // 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 => {
-            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 [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(", ")}`
-                    }]
-            };
-        }
+    await getSchema(true);
+    if (cachedSchemas.length === 0) {
+        return { content: [{ type: "text", text: "❌ System is not initialized." }] };
     }
-    // --- 3. GENERAL MANIFEST GENERATION ---
-    // If no typeNames provided, return a high-level overview of the entry points
+    // Default: Return the Manifest of all nodes
     if (!typeNames || typeNames.length === 0) {
-        const discoveredEntities = new Set();
-        if (queryType) {
-            // 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 manifest = global.nodeManifest || [];
+        const body = manifest.map((m) => `🌐 NODE: ${m.endpoint}\n   ACTIONS: ${m.availableMutations.join(', ') || 'none'}\n   ENTITIES: ${m.domainEntities.join(', ')}`).join('\n\n');
+        return { content: [{ type: "text", text: `FEDERATED SCHEMA OVERVIEW\n\n${body}` }] };
+    }
+    const resolution = {};
+    for (const name of typeNames) {
+        const variants = [];
+        for (const schema of cachedSchemas) {
+            const found = (0, introspection_js_1.introspectSpecificTypes)(schema, [name]);
+            if (found && found[name]) {
+                variants.push({ origin: schema._originUrl, data: found[name] });
+            }
+        }
+        if (variants.length === 0)
+            continue;
+        if (variants.length === 1) {
+            resolution[name] = variants[0].data;
+        }
+        else {
+            // Check for structural equality
+            const baseline = JSON.stringify(variants[0].data);
+            const allMatch = variants.every(v => JSON.stringify(v.data) === baseline);
+            if (allMatch) {
+                resolution[name] = variants[0].data;
+            }
+            else {
+                // Conflict: Expose all variants with node origin
+                variants.forEach((v, idx) => {
+                    resolution[`${name}_from_node_${idx + 1}`] = {
+                        ...v.data,
+                        _meta: { origin_node: v.origin, conflict: "Structural difference detected across schemas" }
+                    };
+                });
+            }
         }
-        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: ${entryPoints.join(", ") || "None"}\n` +
-                        `TOTAL_SCHEMA_TYPES: ${allTypes.length}\n\n` +
-                        `ALL_AVAILABLE_TYPES: ${allTypes.join(", ")}`
-                }]
-        };
     }
-    // --- 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) }]
+        content: [{
+                type: "text",
+                text: JSON.stringify(resolution, null, 2)
+            }]
     };
 };
 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(),
+(0, tool_registry_js_1.registerTool)(server, toolHandlers, registeredToolsMetadata, "introspect-schema", "Retrieve full type definitions and resolve conflicts across all system nodes", {
+    typeNames: zod_1.default.array(zod_1.default.string()).optional().describe("List of type names to introspect"),
 }, 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 ---
+// --- PROMPT REGISTRY ---
+(0, prompt_registry_js_1.registerPrompt)(server, "system-health", "Check status of all nodes", "Perform a simple __typename query on all endpoints.");
+// --- HTTP ADAPTER FOR GRAPHIQL & SSE ---
 async function handleHttpRequest(req, res) {
-    // Standard CORS headers for cross-origin compatibility
     res.setHeader('Access-Control-Allow-Origin', '*');
-    res.setHeader('Access-Control-Allow-Methods', 'POST, GET, OPTIONS');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
     res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
-    // Handle preflight requests
     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
     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:${env.MCP_PORT}/mcp`, env.HEADERS));
     }
-    // Process MCP JSON-RPC Endpoint
     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
             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 }
-                    }));
-                }
-                // --- TOOL EXECUTION (CALL) ---
-                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;
-                }
-                const handler = toolHandlers.get(targetMethod);
+                const payload = JSON.parse(body);
+                const { method, id, params } = payload;
+                const target = (method === "call-tool" || method === "tools/call") ? params.name : method;
+                const args = (method === "call-tool" || method === "tools/call") ? params.arguments : params;
+                const handler = toolHandlers.get(target);
                 if (!handler) {
                     res.writeHead(404);
-                    return res.end(JSON.stringify({
-                        jsonrpc: '2.0',
-                        id: requestId,
-                        error: { code: -32601, message: `Tool ${targetMethod} not found` }
-                    }));
+                    return res.end(JSON.stringify({ error: { code: -32601, message: "Method not found" } }));
                 }
-                // Execute the actual business logic for the tool
-                const result = await handler(toolArgs);
+                const result = await handler(args);
                 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, result }));
             }
             catch (e) {
-                console.error(`[HTTP-ERROR] ${e.message}`);
                 res.writeHead(500);
-                res.end(JSON.stringify({
-                    jsonrpc: '2.0',
-                    id: requestId,
-                    error: { code: -32603, message: e.message || "Internal Server Error" }
-                }));
+                res.end(JSON.stringify({ error: { 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");
 }
-// --- STARTUP ---
+// --- SERVER LIFECYCLE ---
 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
     if (process.env.ENABLE_HTTP !== "false" && !isInspector) {
-        const serverHttp = node_http_1.default.createServer(handleHttpRequest);
-        serverHttp.on('error', (e) => {
-            if (e.code === 'EADDRINUSE') {
-                console.error(`[HTTP-ERROR] Port ${env.MCP_PORT} is busy.`);
-            }
+        const httpSrv = node_http_1.default.createServer(handleHttpRequest);
+        httpSrv.on('error', (e) => {
+            if (e.code === 'EADDRINUSE')
+                console.error(`[ERROR] Port ${env.MCP_PORT} already in use.`);
         });
-        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`);
+        httpSrv.listen(env.MCP_PORT, () => {
+            console.error(`[SYSTEM] Federated Bridge v${getVersion()} active on port ${env.MCP_PORT}`);
+            console.error(`📡 SSE Endpoint: http://localhost:${env.MCP_PORT}/mcp`);
+            if (process.env.ENABLE_HTTP === "true") {
+                console.error(`🎨 GraphiQL: http://localhost:${env.MCP_PORT}/graphiql`);
             }
         });
     }
     const transport = new stdio_js_1.StdioServerTransport();
     await server.connect(transport);
-    getSchema().catch(() => { });
+    // Initial background sync
+    getSchema(true).catch(err => console.error(`[BOOT-WARN] Initial sync failed: ${err.message}`));
 }
-process.on('SIGINT', () => process.exit(0));
-process.on('SIGTERM', () => process.exit(0));
-main().catch(error => {
-    console.error(`[FATAL] ${error}`);
+// Global process management
+process.on('SIGINT', () => { console.error('[SYSTEM] Shutting down...'); process.exit(0); });
+process.on('SIGTERM', () => { process.exit(0); });
+main().catch(err => {
+    console.error(`[FATAL] Startup failed: ${err.message}`);
     process.exit(1);
 });

package/package.json

@@ -50,5 +50,5 @@
 		"tsx": "^4.21.0",
 		"typescript": "5.8.3"
 	},
-	"version": "3.8.1"
+	"version": "3.9.1"
 }