@natomalabs/natoma-mcp-gateway 1.0.3 → 1.0.5

package/README.md

@@ -4,12 +4,13 @@ A robust, production-ready gateway that bridges stdio-based MCP clients (like Cl
 
 ## Overview
 
-The Natoma MCP Gateway acts as a translation layer that enables seamless communication between different MCP (Model Context Protocol) implementations. It supports both standard and enterprise deployment modes, with automatic reconnection, health monitoring, and robust error handling.
+The Natoma MCP Gateway acts as a translation layer that enables seamless communication between different MCP (Model Context Protocol) implementations. It operates exclusively in enterprise mode, providing production-grade features including automatic reconnection, health monitoring, and robust error handling.
 
 ## Features
 
-- **Dual Gateway Modes**: NMS (standard) and Enterprise gateways for different deployment scenarios
+- **Enterprise Gateway**: Production-ready gateway with enhanced reliability and monitoring
 - **Protocol Translation**: Converts stdio JSON-RPC messages to HTTP/SSE format and vice versa
+- **Custom URL Support**: Configure custom endpoints for private deployments
 
 ## Installation
 
@@ -26,13 +27,28 @@ Required environment variables:
 - `NATOMA_MCP_SERVER_INSTALLATION_ID`: Your MCP server installation ID/slug
 - `NATOMA_MCP_API_KEY`: Your Natoma API key for authentication
 
-### Command Line Usage
+Optional environment variables:
+
+- `NATOMA_MCP_CUSTOM_URL`: Custom endpoint URL (overrides default api.natoma.app endpoint)
+
+### Corporate Proxy/Firewall Support
+
+If you're running in a corporate environment with tools like ZScaler that perform TLS interception, you may encounter certificate validation errors. You can resolve this using Node.js's built-in support for custom CA certificates:
 
 ```bash
-# Standard NMS Gateway mode
+# Export your corporate CA bundle
+export NODE_EXTRA_CA_CERTS="/path/to/corporate-ca-bundle.pem"
+
+# Run the gateway
 npx @natomalabs/natoma-mcp-gateway
+```
 
-# Enterprise Gateway mode
+This approach is the standard Node.js solution for corporate environments.
+
+### Command Line Usage
+
+```bash
+# Run the gateway (--enterprise flag is required)
 npx @natomalabs/natoma-mcp-gateway --enterprise
 ```
 
@@ -46,7 +62,8 @@ Add to your Claude Desktop MCP configuration:
     "your-server-name": {
       "command": "npx",
       "args": [
-        "@natomalabs/natoma-mcp-gateway"
+        "@natomalabs/natoma-mcp-gateway",
+        "--enterprise"
       ],
       "env": {
         "NATOMA_MCP_SERVER_INSTALLATION_ID": "your-installation-id",
@@ -57,26 +74,60 @@ Add to your Claude Desktop MCP configuration:
 }
 ```
 
-For enterprise deployments, add `--enterprise` to the args array.
+For custom endpoint URLs:
 
-## Architecture
+```json
+{
+  "mcpServers": {
+    "your-server-name": {
+      "command": "npx",
+      "args": [
+        "@natomalabs/natoma-mcp-gateway",
+        "--enterprise"
+      ],
+      "env": {
+        "NATOMA_MCP_SERVER_INSTALLATION_ID": "your-installation-id",
+        "NATOMA_MCP_API_KEY": "your-api-key",
+        "NATOMA_MCP_CUSTOM_URL": "https://your-custom-endpoint.com/mcp"
+      }
+    }
+  }
+}
+```
+
+For corporate environments with custom certificates:
 
-### Gateway Modes
+```json
+{
+  "mcpServers": {
+    "your-server-name": {
+      "command": "npx",
+      "args": [
+        "@natomalabs/natoma-mcp-gateway",
+        "--enterprise"
+      ],
+      "env": {
+        "NATOMA_MCP_SERVER_INSTALLATION_ID": "your-installation-id",
+        "NATOMA_MCP_API_KEY": "your-api-key",
+        "NODE_EXTRA_CA_CERTS": "/path/to/corporate-ca-bundle.pem"
+      }
+    }
+  }
+}
+```
 
-#### NMS Gateway (Standard)
+## Architecture
 
-- Uses EventSource for Server-Sent Events
-- Optimized for standard MCP deployments
-- Faster reconnection times (1 second)
-- HTTP-based message delivery
+### Enterprise Gateway
 
-#### Enterprise Gateway
+The gateway operates in enterprise mode with the following features:
 
-- Uses fetch API with enhanced features
+- Uses fetch API with enhanced reliability
 - Support for both JSON and SSE responses
 - Health check monitoring (every 5 minutes)
 - Extended timeouts (60 seconds)
 - Enhanced error recovery
+- Custom endpoint URL support
 
 ### Protocol Flow
 
@@ -92,9 +143,11 @@ The gateway accepts several configuration options through the `MCPConfig` interf
 
 - `slug`: Server installation ID (required)
 - `apiKey`: Authentication API key (required)
+- `isEnterprise`: Must be set to `true` (mandatory for enterprise mode)
+- `customUrl`: Optional custom endpoint URL (overrides default api.natoma.app)
 - `maxReconnectAttempts`: Maximum reconnection attempts (default: 5)
-- `reconnectDelay`: Delay between reconnection attempts (default: 1000ms for NMS, 2000ms for Enterprise)
-- `timeout`: Request timeout (default: 30000ms for NMS, 60000ms for Enterprise)
+- `reconnectDelay`: Delay between reconnection attempts (default: 2000ms)
+- `timeout`: Request timeout (default: 60000ms)
 
 ## What is MCP?
 

package/build/constants.js

@@ -0,0 +1,3 @@
+export const NATOMA_ENTERPRISE_SERVER_URL = 'https://mcp.natoma.app';
+export const MCP_SESSION_ID_HEADER = 'Mcp-Session-Id';
+export const JSON_RPC_VERSION = '2.0';

package/build/gateway.js

@@ -1,67 +1,449 @@
-#!/usr/bin/env node
-import { NMSGateway } from "./nms-gateway.js";
-import { EnterpriseGateway } from "./ent-gateway.js";
-// Parse command line arguments
-function parseArgs() {
-    const args = process.argv.slice(2);
-    return {
-        enterprise: args.includes("--enterprise"),
-    };
-}
-// Main function
-async function main() {
-    const { enterprise } = parseArgs();
-    const slug = process.env.NATOMA_MCP_SERVER_INSTALLATION_ID;
-    if (!slug) {
-        console.error("Please set NATOMA_MCP_SERVER_INSTALLATION_ID env var");
-        process.exit(1);
-    }
-    const config = {
-        slug,
-        apiKey: process.env.NATOMA_MCP_API_KEY,
-        maxReconnectAttempts: 5,
-        reconnectDelay: enterprise ? 2000 : 1000,
-        timeout: enterprise ? 60000 : undefined,
-    };
-    // Create appropriate gateway based on flag
-    const gateway = enterprise
-        ? new EnterpriseGateway(config)
-        : new NMSGateway(config);
-    console.error(`--- Starting ${enterprise ? "Enterprise" : "NMS"} Gateway ---`);
-    try {
-        await gateway.connect();
-        process.stdin.on("data", (data) => {
-            gateway.processMessage(data).catch((err) => {
-                console.error("Error in processMessage:", err);
+import { JSON_RPC_VERSION, MCP_SESSION_ID_HEADER, NATOMA_ENTERPRISE_SERVER_URL } from './constants.js';
+// Handle EPIPE errors gracefully
+process.stdout.on('error', (err) => {
+    if (err.code === 'EPIPE') {
+        process.exit(0);
+    }
+});
+process.stderr.on('error', (err) => {
+    if (err.code === 'EPIPE') {
+        process.exit(0);
+    }
+});
+// Enterprise Gateway - Fetch based with enhanced features
+export class Gateway {
+    isReady = false;
+    messageQueue = [];
+    reconnectAttempts = 0;
+    baseUrl;
+    maxReconnectAttempts;
+    reconnectDelay;
+    apiKey;
+    sessionHeaders = {};
+    endpointUrl;
+    timeout;
+    sseAbortController = null;
+    constructor(config) {
+        // Validate that config is provided with required isEnterprise flag
+        if (!config || config.isEnterprise !== true) {
+            throw new Error('Configuration with isEnterprise: true is required for MCP Gateway');
+        }
+        // Use custom URL if provided, otherwise use enterprise URL
+        this.baseUrl = config.customUrl || NATOMA_ENTERPRISE_SERVER_URL;
+        this.maxReconnectAttempts = 3;
+        this.reconnectDelay = 1000;
+        this.apiKey = config.apiKey;
+        // Validate that API key is provided
+        if (!this.apiKey) {
+            throw new Error('API key is required for MCP Gateway');
+        }
+        // Debug logging
+        console.error(`[BaseMCPGateway] Base URL set to: ${this.baseUrl}`);
+        if (config.customUrl) {
+            console.error(`[BaseMCPGateway] Using custom URL`);
+        }
+        console.error(`[BaseMCPGateway] API Key: ${this.apiKey ? 'PROVIDED' : 'NOT PROVIDED'}`);
+        console.error(`[BaseMCPGateway] Max reconnect attempts: ${this.maxReconnectAttempts}`);
+        // Debug the inherited baseUrl
+        console.error(`[Gateway] Inherited baseUrl: ${this.baseUrl}`);
+        const slug = config?.slug;
+        this.endpointUrl = slug ? `${this.baseUrl}/${slug}` : `${this.baseUrl}`;
+        this.timeout = config?.timeout ?? 30000;
+        // Debug final endpoint URL
+        console.error(`[Gateway] Final endpoint URL: ${this.endpointUrl}`);
+        console.error(`[Gateway] Timeout: ${this.timeout}ms`);
+    }
+    // Simplified validation for production - only log errors
+    validateResponse(response, originalRequest) {
+        if (!response || typeof response !== 'object') {
+            console.error('❌ Invalid response format');
+            return response;
+        }
+        if (Array.isArray(response)) {
+            response.forEach((elem, idx) => {
+                this.validateSingleResponse(elem, idx);
             });
-        });
-        const shutdown = () => {
-            console.error("Shutting down...");
-            gateway.cleanup();
-            process.exit(0);
+        }
+        else {
+            this.validateSingleResponse(response);
+        }
+        return response;
+    }
+    validateSingleResponse(resp, index) {
+        const prefix = index !== undefined ? `#${index}: ` : '';
+        if (resp.jsonrpc !== JSON_RPC_VERSION) {
+            console.error(`❌ ${prefix}Invalid jsonrpc version`);
+        }
+        const hasResult = resp.hasOwnProperty('result');
+        const hasError = resp.hasOwnProperty('error');
+        if (!hasResult && !hasError) {
+            console.error(`❌ ${prefix}Response missing both 'result' and 'error' fields`);
+        }
+        if (hasError && resp.error) {
+            console.error(`❌ ${prefix}Server error: ${resp.error.message}`);
+        }
+    }
+    async connect() {
+        try {
+            console.error('--- Connecting to MCP server');
+            console.error(`--- Connection URL: ${this.endpointUrl}`);
+            const initializeRequest = {
+                jsonrpc: JSON_RPC_VERSION,
+                method: 'initialize',
+                params: {
+                    capabilities: {
+                        tools: {},
+                        prompts: {},
+                        resources: {},
+                        logging: {}
+                    },
+                    clientInfo: {
+                        name: 'claude-desktop-gateway',
+                        version: '1.0.0'
+                    },
+                    protocolVersion: '2025-03-26'
+                },
+                id: 1
+            };
+            const response = await this.makeRequest(initializeRequest);
+            if (response && response.result) {
+                this.isReady = true;
+                this.reconnectAttempts = 0;
+                console.error('--- MCP server connected successfully');
+                await this.processQueuedMessages();
+            }
+            else {
+                throw new Error(`Initialize failed: ${JSON.stringify(response.error)}`);
+            }
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            console.error(`--- Connection failed: ${errorMessage}`);
+            throw error;
+        }
+    }
+    async makeRequest(messageBody) {
+        const headers = {
+            'Content-Type': 'application/json',
+            Accept: 'application/json, text/event-stream',
+            ...this.sessionHeaders
         };
-        process.on("SIGINT", shutdown);
-        process.on("SIGTERM", shutdown);
-        process.on("uncaughtException", (err) => {
-            console.error("Uncaught exception:", err);
-            shutdown();
+        if (this.apiKey) {
+            headers['Authorization'] = `Bearer ${this.apiKey}`;
+        }
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        let resp;
+        try {
+            resp = await fetch(this.endpointUrl, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(messageBody),
+                signal: controller.signal
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new Error(`Request timeout after ${this.timeout}ms`);
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+        // Update session headers
+        resp.headers.forEach((value, key) => {
+            if (key.toLowerCase() === MCP_SESSION_ID_HEADER.toLowerCase()) {
+                this.sessionHeaders[MCP_SESSION_ID_HEADER] = value;
+            }
         });
-        // Optional health check for enterprise gateway
-        if (enterprise && gateway instanceof EnterpriseGateway) {
-            setInterval(async () => {
-                if (gateway.ready) {
-                    const ok = await gateway.healthCheck();
-                    if (!ok) {
-                        console.error("Health check failed; reconnecting");
-                        await gateway.handleConnectionError(new Error("Health check failed"));
+        if (!resp.ok) {
+            const text = await resp.text();
+            console.error(`❌ HTTP Error ${resp.status}: ${text}`);
+            throw new Error(`HTTP ${resp.status}: ${text}`);
+        }
+        const contentType = resp.headers.get('content-type') || '';
+        // Handle JSON response
+        if (contentType.includes('application/json')) {
+            const raw = await resp.text();
+            if (!raw || raw.trim() === '') {
+                throw new Error('Empty JSON response');
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch (parseErr) {
+                console.error('❌ Failed to parse JSON response');
+                throw new Error(`Invalid JSON: ${parseErr.message}`);
+            }
+            this.validateResponse(parsed, messageBody);
+            return parsed;
+        }
+        // Handle SSE stream
+        if (contentType.includes('text/event-stream')) {
+            if (this.sseAbortController) {
+                this.sseAbortController.abort();
+            }
+            this.sseAbortController = new AbortController();
+            await this.readSSEStream(resp, messageBody);
+            return null;
+        }
+        // Handle 202 Accepted
+        if (resp.status === 202) {
+            return {};
+        }
+        const txt = await resp.text();
+        console.error(`❌ Unexpected Content-Type ${contentType}`);
+        throw new Error(`Unexpected Content-Type: ${contentType}`);
+    }
+    async readSSEStream(response, originalRequest) {
+        if (!response.body) {
+            console.error('❌ No response body for SSE');
+            return;
+        }
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                let parts = buffer.split(/\r?\n\r?\n/);
+                buffer = parts.pop() || '';
+                for (const chunk of parts) {
+                    const lines = chunk.split(/\r?\n/);
+                    for (const line of lines) {
+                        if (line.startsWith('data:')) {
+                            const payload = line.slice(5).trim();
+                            // Handle session establishment
+                            const sidMatch = payload.match(/sessionId=([^&]+)/);
+                            if (sidMatch) {
+                                this.sessionHeaders[MCP_SESSION_ID_HEADER] = sidMatch[1];
+                                this.isReady = true;
+                                console.error(`Session established: ${sidMatch[1]}`);
+                                await this.processQueuedMessages();
+                                continue;
+                            }
+                            // Handle JSON-RPC messages
+                            try {
+                                const obj = JSON.parse(payload);
+                                this.validateResponse(obj, originalRequest);
+                                console.log(JSON.stringify(obj));
+                            }
+                            catch {
+                                console.log(payload);
+                            }
+                        }
+                    }
+                }
+            }
+            console.error('⚠️ SSE stream closed by server');
+            await this.handleConnectionError(new Error('SSE closed'));
+        }
+        catch (err) {
+            if (err.name !== 'AbortError') {
+                console.error('❌ Error reading SSE:', err);
+                await this.handleConnectionError(err);
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    async handleConnectionError(error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.error(`Connection error: ${errorMessage}`);
+        if (this.sseAbortController) {
+            this.sseAbortController.abort();
+            this.sseAbortController = null;
+        }
+        if (this.reconnectAttempts >= this.maxReconnectAttempts) {
+            console.error(`Max reconnect attempts reached. Exiting.`);
+            process.exit(1);
+        }
+        this.reconnectAttempts++;
+        this.isReady = false;
+        this.sessionHeaders = {};
+        console.error(`Reconnecting in ${this.reconnectDelay}ms (attempt ${this.reconnectAttempts})`);
+        await new Promise((r) => setTimeout(r, this.reconnectDelay));
+        await this.connect();
+    }
+    parseMultipleJSON(input) {
+        const messages = [];
+        let braceCount = 0;
+        let inString = false;
+        let escapeNext = false;
+        let startIndex = -1;
+        for (let i = 0; i < input.length; i++) {
+            const char = input[i];
+            if (escapeNext) {
+                escapeNext = false;
+                continue;
+            }
+            if (char === '\\') {
+                escapeNext = true;
+                continue;
+            }
+            if (char === '"' && !escapeNext) {
+                inString = !inString;
+            }
+            if (!inString) {
+                if (char === '{') {
+                    if (braceCount === 0)
+                        startIndex = i;
+                    braceCount++;
+                }
+                else if (char === '}') {
+                    braceCount--;
+                    if (braceCount === 0 && startIndex >= 0) {
+                        const jsonObj = input.substring(startIndex, i + 1).trim();
+                        if (jsonObj)
+                            messages.push(jsonObj);
+                        startIndex = -1;
                     }
                 }
-            }, 5 * 60 * 1000); // Every 5 minutes
+            }
+        }
+        return messages;
+    }
+    async processMessage(input) {
+        if (!this.isReady) {
+            this.messageQueue.push(input);
+            return;
+        }
+        const rawInput = input.toString().trim();
+        try {
+            const fragments = this.parseMultipleJSON(rawInput);
+            if (fragments.length === 0) {
+                console.error('⚠️ No JSON found in input');
+                return;
+            }
+            for (const raw of fragments) {
+                console.error(`--> ${raw}`);
+                const body = JSON.parse(raw);
+                const isNotification = !body.hasOwnProperty('id');
+                if (isNotification) {
+                    await this.makeNotificationRequest(body);
+                    continue;
+                }
+                const responseObj = await this.makeRequest(body);
+                if (responseObj) {
+                    const respStr = JSON.stringify(responseObj);
+                    console.log(respStr);
+                }
+            }
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            console.error(`❌ Request error: ${errMsg}`);
+            if (errMsg.includes('fetch') ||
+                errMsg.includes('timeout') ||
+                errMsg.includes('503') ||
+                errMsg.includes('502')) {
+                await this.handleConnectionError(err);
+            }
+            else {
+                // Send error response if we can determine the request ID
+                let originalId = null;
+                try {
+                    const fragments = this.parseMultipleJSON(rawInput);
+                    if (fragments.length > 0) {
+                        const parsed = JSON.parse(fragments[0]);
+                        if (parsed.hasOwnProperty('id')) {
+                            originalId = parsed.id;
+                        }
+                    }
+                }
+                catch (parseErr) {
+                    console.error(`⚠️ Failed to extract request ID for error response: ${parseErr instanceof Error ? parseErr.message : String(parseErr)}`);
+                }
+                if (originalId !== null) {
+                    const errorResponse = {
+                        jsonrpc: JSON_RPC_VERSION,
+                        error: {
+                            code: -32603,
+                            message: `Gateway error: ${errMsg}`
+                        },
+                        id: originalId
+                    };
+                    console.log(JSON.stringify(errorResponse));
+                }
+            }
         }
     }
-    catch (err) {
-        console.error("Fatal error:", err);
-        process.exit(1);
+    async makeNotificationRequest(messageBody) {
+        const headers = {
+            'Content-Type': 'application/json',
+            Accept: 'application/json, text/event-stream',
+            ...this.sessionHeaders
+        };
+        if (this.apiKey) {
+            headers['Authorization'] = `Bearer ${this.apiKey}`;
+        }
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const resp = await fetch(this.endpointUrl, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(messageBody),
+                signal: controller.signal
+            });
+            resp.headers.forEach((value, key) => {
+                if (key.toLowerCase() === MCP_SESSION_ID_HEADER.toLowerCase()) {
+                    this.sessionHeaders[MCP_SESSION_ID_HEADER] = value;
+                }
+            });
+            if (!resp.ok && resp.status !== 202) {
+                const text = await resp.text();
+                console.error(`❌ Notification error ${resp.status}: ${text}`);
+                throw new Error(`HTTP ${resp.status}: ${text}`);
+            }
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new Error(`Notification timeout after ${this.timeout}ms`);
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    cleanup() {
+        this.isReady = false;
+        this.sessionHeaders = {};
+        if (this.sseAbortController) {
+            this.sseAbortController.abort();
+            this.sseAbortController = null;
+        }
+    }
+    async healthCheck() {
+        try {
+            const pingRequest = {
+                jsonrpc: JSON_RPC_VERSION,
+                method: 'ping',
+                id: 'health-check'
+            };
+            const resp = await this.makeRequest(pingRequest);
+            return resp !== null && !resp.hasOwnProperty('error');
+        }
+        catch {
+            return false;
+        }
+    }
+    get ready() {
+        return this.isReady;
+    }
+    async processQueuedMessages() {
+        while (this.messageQueue.length > 0) {
+            const message = this.messageQueue.shift();
+            if (message) {
+                await this.processMessage(message);
+            }
+        }
     }
 }
-main();