@natomalabs/natoma-mcp-gateway 1.0.2 → 1.0.4

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/base.js

@@ -1,6 +1,5 @@
 // base.ts
-export const NATOMA_NMS_SERVER_URL = "https://api.natoma.app/api/mcp";
-export const NATOMA_ENTERPRISE_SERVER_URL = "https://api.natoma.app/api/mcp";
+export const NATOMA_ENTERPRISE_SERVER_URL = "https://api.natoma.app/mcp";
 export const MCP_SESSION_ID_HEADER = "Mcp-Session-Id";
 // Handle EPIPE errors gracefully
 process.stdout.on("error", (err) => {
@@ -23,20 +22,24 @@ export class BaseMCPGateway {
     reconnectDelay;
     apiKey;
     constructor(config) {
-        // Set base URL based on gateway type
-        this.baseUrl = config?.isEnterprise
-            ? NATOMA_ENTERPRISE_SERVER_URL
-            : NATOMA_NMS_SERVER_URL;
+        // 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;
+        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] Gateway Type: ${config?.isEnterprise ? "Enterprise" : "NMS"}`);
         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}`);
     }

package/build/gateway.js

@@ -1,16 +1,16 @@
 #!/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"),
-    };
+    if (!args.includes("--enterprise")) {
+        console.error("Error: --enterprise flag is required");
+        process.exit(1);
+    }
 }
 // Main function
 async function main() {
-    const { enterprise } = parseArgs();
+    parseArgs();
     const slug = process.env.NATOMA_MCP_SERVER_INSTALLATION_ID;
     if (!slug) {
         console.error("Please set NATOMA_MCP_SERVER_INSTALLATION_ID env var");
@@ -20,14 +20,17 @@ async function main() {
         slug,
         apiKey: process.env.NATOMA_MCP_API_KEY,
         maxReconnectAttempts: 5,
-        reconnectDelay: enterprise ? 2000 : 1000,
-        timeout: enterprise ? 60000 : undefined,
+        reconnectDelay: 2000,
+        timeout: 60000,
+        isEnterprise: true, // Mandatory flag
+        customUrl: process.env.NATOMA_MCP_CUSTOM_URL, // Optional custom URL from env
     };
-    // Create appropriate gateway based on flag
-    const gateway = enterprise
-        ? new EnterpriseGateway(config)
-        : new NMSGateway(config);
-    console.error(`--- Starting ${enterprise ? "Enterprise" : "NMS"} Gateway ---`);
+    // Always create Enterprise gateway
+    const gateway = new EnterpriseGateway(config);
+    console.error(`--- Starting Enterprise Gateway ---`);
+    if (config.customUrl) {
+        console.error(`--- Using custom URL: ${config.customUrl} ---`);
+    }
     try {
         await gateway.connect();
         process.stdin.on("data", (data) => {
@@ -46,8 +49,8 @@ async function main() {
             console.error("Uncaught exception:", err);
             shutdown();
         });
-        // Optional health check for enterprise gateway
-        if (enterprise && gateway instanceof EnterpriseGateway) {
+        // Health check for enterprise gateway
+        if (gateway instanceof EnterpriseGateway) {
             setInterval(async () => {
                 if (gateway.ready) {
                     const ok = await gateway.healthCheck();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@natomalabs/natoma-mcp-gateway",
-  "version": "1.0.2",
-  "description": "Natoma MCP Gateway with NMS and Enterprise modes",
+  "version": "1.0.4",
+  "description": "Natoma MCP Gateway",
   "license": "MIT",
   "type": "module",
   "bin": {

package/build/cli.js

@@ -1,64 +0,0 @@
-import yargs from 'yargs';
-import { hideBin } from 'yargs/helpers';
-import { setupCommand } from './setup.js';
-import { MCPGateway } from './gateway.js';
-import chalk from 'chalk';
-const startCommand = {
-    command: 'start',
-    describe: 'Start the Natoma MCP Gateway',
-    builder: (yargs) => {
-        return yargs
-            .option('url', {
-            type: 'string',
-            describe: 'The Natoma MCP URL to connect to',
-        })
-            .option('apiKey', {
-            type: 'string',
-            describe: 'API key for authentication',
-            demandOption: true,
-        })
-            .option('slug', {
-            type: 'string',
-            describe: 'Installation ID/slug for the connection',
-        });
-    },
-    handler: async (argv) => {
-        try {
-            const { url, apiKey, slug } = argv;
-            console.log(chalk.cyan('🚀 Starting Natoma MCP Gateway...'));
-            if (url) {
-                console.log(chalk.cyan(`   URL: ${url}`));
-            }
-            if (slug) {
-                console.log(chalk.cyan(`   Installation ID: ${slug}`));
-            }
-            const gateway = new MCPGateway({
-                apiKey: apiKey || process.env.NATOMA_MCP_API_KEY,
-                slug: slug || process.env.NATOMA_MCP_SERVER_INSTALLATION_ID,
-            });
-            await gateway.connect();
-            console.log(chalk.green('✅ Connected to Natoma MCP Server'));
-            process.stdin.on("data", (data) => gateway.processMessage(data));
-            // Handle cleanup
-            const cleanup = () => {
-                console.log(chalk.yellow("Shutting down..."));
-                gateway.cleanup();
-                process.exit(0);
-            };
-            process.on("SIGINT", cleanup);
-            process.on("SIGTERM", cleanup);
-        }
-        catch (error) {
-            console.log(chalk.red('\n❌ Error occurred while starting Natoma MCP Gateway:'));
-            console.log(chalk.red(`   ${error.message}`));
-            console.log(chalk.yellow('\nPlease try again or contact support if the issue persists.\n'));
-            process.exit(1);
-        }
-    },
-};
-yargs(hideBin(process.argv))
-    .command(setupCommand)
-    .command(startCommand)
-    .demandCommand(1, 'You need to specify a command.')
-    .help()
-    .argv;

package/build/nms-gateway.js

@@ -1,131 +0,0 @@
-// nms-gateway.ts
-import EventSource from "eventsource";
-import { BaseMCPGateway } from "./base.js";
-// NMS Gateway (Non-Enterprise) - EventSource based
-export class NMSGateway extends BaseMCPGateway {
-    eventSource = null;
-    sessionId = null;
-    sseUrl;
-    messageUrl;
-    constructor(config) {
-        // Set isEnterprise to false for NMS Gateway
-        super({ ...config, isEnterprise: false });
-        const slug = config?.slug;
-        this.sseUrl = slug ? `${this.baseUrl}/${slug}` : `${this.baseUrl}`;
-        this.messageUrl = slug
-            ? `${this.baseUrl}/${slug}/message`
-            : `${this.baseUrl}/message`;
-        // Debug the URLs
-        console.error(`[NMSGateway] Base URL: ${this.baseUrl}`);
-        console.error(`[NMSGateway] SSE URL: ${this.sseUrl}`);
-        console.error(`[NMSGateway] Message URL: ${this.messageUrl}`);
-    }
-    async connect() {
-        if (this.eventSource) {
-            console.error("Closing existing connection");
-            this.eventSource.close();
-        }
-        return new Promise((resolve, reject) => {
-            const headers = {
-                Accept: "text/event-stream",
-            };
-            if (this.apiKey) {
-                headers["Authorization"] = `Bearer ${this.apiKey}`;
-            }
-            this.eventSource = new EventSource(this.sseUrl, { headers });
-            this.eventSource.onopen = () => {
-                console.error("--- SSE backend connected");
-                this.reconnectAttempts = 0;
-                resolve();
-            };
-            this.eventSource.onerror = (error) => {
-                console.error(`--- SSE backend error: ${error?.message}`);
-                this.handleConnectionError(error);
-                reject(error);
-            };
-            this.setupEventListeners();
-        });
-    }
-    setupEventListeners() {
-        if (!this.eventSource)
-            return;
-        this.eventSource.addEventListener("endpoint", (event) => {
-            const match = event.data.match(/sessionId=([^&]+)/);
-            if (match) {
-                this.sessionId = match[1];
-                this.isReady = true;
-                console.error(`Session established: ${this.sessionId}`);
-                this.processQueuedMessages();
-            }
-        });
-        this.eventSource.addEventListener("message", (event) => {
-            try {
-                console.error(`<-- ${event.data}`);
-                console.log(event.data);
-            }
-            catch (error) {
-                console.error(`Error handling message: ${error}`);
-            }
-        });
-    }
-    async handleConnectionError(error) {
-        console.error(`Connection error: ${error.message}`);
-        if (this.eventSource?.readyState === EventSource.CLOSED) {
-            console.error("EventSource connection closed");
-            await this.reconnect();
-        }
-    }
-    async reconnect() {
-        if (this.reconnectAttempts >= this.maxReconnectAttempts) {
-            console.error(`Max reconnection attempts (${this.maxReconnectAttempts}) reached, exiting...`);
-            process.exit(1);
-        }
-        this.reconnectAttempts++;
-        this.isReady = false;
-        try {
-            await new Promise((resolve) => setTimeout(resolve, this.reconnectDelay));
-            await this.connect();
-        }
-        catch (error) {
-            console.error(`Reconnection failed: ${error}`);
-        }
-    }
-    async processMessage(input) {
-        if (!this.isReady || !this.sessionId) {
-            this.messageQueue.push(input);
-            return;
-        }
-        const message = input.toString().trim();
-        console.error(`--> ${message}`);
-        try {
-            const url = `${this.messageUrl}?sessionId=${this.sessionId}`;
-            const headers = {
-                "Content-Type": "application/json",
-            };
-            if (this.apiKey) {
-                headers["Authorization"] = `Bearer ${this.apiKey}`;
-            }
-            const response = await fetch(url, {
-                method: "POST",
-                headers,
-                body: message,
-            });
-            if (!response.ok) {
-                if (response.status === 503) {
-                    await this.reconnect();
-                }
-                else {
-                    console.error(`Error from server: ${response.status} ${response.statusText}`);
-                }
-            }
-        }
-        catch (error) {
-            console.error(`Request error: ${error}`);
-        }
-    }
-    cleanup() {
-        if (this.eventSource) {
-            this.eventSource.close();
-        }
-    }
-}

package/build/setup.js

@@ -1,186 +0,0 @@
-// setup.ts
-import fs from "fs";
-import path from "path";
-import os from "os";
-import chalk from "chalk";
-export const setupCommand = {
-    command: "setup <url>",
-    describe: "Setup command for Natoma MCP Gateway integration",
-    builder: (yargs) => {
-        return yargs
-            .positional("url", {
-            type: "string",
-            describe: "The Natoma MCP URL to use",
-            demandOption: true,
-        })
-            .option("client", {
-            type: "string",
-            describe: "Client to use (claude, windsurf, cursor)",
-            default: "claude",
-            choices: ["claude", "windsurf", "cursor"],
-        })
-            .option("apiKey", {
-            type: "string",
-            describe: "API key for authentication",
-            demandOption: true,
-        });
-    },
-    handler: async (argv) => {
-        const { url, client, apiKey } = argv;
-        try {
-            console.log(chalk.cyan("📝 Configuration Details:"));
-            console.log(`   URL: ${chalk.green(url)}`);
-            console.log(`   Client: ${chalk.green(client)}`);
-            if (apiKey) {
-                console.log(`   API Key: ${chalk.green("****" + apiKey.slice(-4))}`);
-            }
-            console.log("");
-            console.log(chalk.cyan("💾 Saving configurations..."));
-            saveMcpConfig(url, client, apiKey);
-            console.log(chalk.cyan(`\n🚀 All done! Please restart ${client} for changes to take effect\n`));
-        }
-        catch (error) {
-            console.log(chalk.red("\n❌ Error occurred while setting up Natoma MCP:"));
-            console.log(chalk.red(`   ${error.message}`));
-            console.log(chalk.yellow("\nPlease try again or contact support if the issue persists.\n"));
-        }
-    },
-};
-function saveMcpConfig(url, clientType, apiKey) {
-    // Create config object for the gateway
-    const config = {
-        command: "npx",
-        args: ["@natomalabs/natoma-mcp-gateway@latest", "start", "--url", url],
-        env: {
-            npm_config_yes: "true",
-        },
-    };
-    // If API key is provided, add it to the environment variables
-    if (apiKey) {
-        config.env["NATOMA_MCP_API_KEY"] = apiKey;
-        // Also add it to the args so it's passed to the start command
-        config.args.push("--apiKey", apiKey);
-    }
-    // Extract installation ID from URL for Cursor
-    const urlParts = url.split("/");
-    const installationId = urlParts[urlParts.length - 1];
-    const sseConfig = {
-        url: url,
-        apiKey: apiKey,
-        slug: installationId,
-    };
-    const homeDir = os.homedir();
-    // Define platform-specific paths
-    const platformPaths = {
-        win32: {
-            baseDir: process.env.APPDATA || path.join(homeDir, "AppData", "Roaming"),
-            vscodePath: path.join("Code", "User", "globalStorage"),
-        },
-        darwin: {
-            baseDir: path.join(homeDir, "Library", "Application Support"),
-            vscodePath: path.join("Code", "User", "globalStorage"),
-        },
-        linux: {
-            baseDir: process.env.XDG_CONFIG_HOME || path.join(homeDir, ".config"),
-            vscodePath: path.join("Code/User/globalStorage"),
-        },
-    };
-    const platform = process.platform;
-    // Check if platform is supported
-    if (!platformPaths[platform]) {
-        console.log(chalk.yellow(`\n⚠️ Platform ${platform} is not supported.`));
-        return;
-    }
-    const { baseDir } = platformPaths[platform];
-    // Define client-specific paths
-    const clientPaths = {
-        claude: {
-            configDir: path.join(baseDir, "Claude"),
-            configPath: path.join(baseDir, "Claude", "claude_desktop_config.json"),
-        },
-        windsurf: {
-            configDir: path.join(homeDir, ".codeium", "windsurf"),
-            configPath: path.join(homeDir, ".codeium", "windsurf", "mcp_config.json"),
-        },
-        cursor: {
-            configDir: path.join(homeDir, ".cursor"),
-            configPath: path.join(homeDir, ".cursor", "mcp.json"),
-        },
-    };
-    if (!clientPaths[clientType]) {
-        console.log(chalk.yellow(`\n⚠️ Client ${clientType} is not supported.`));
-        return;
-    }
-    const { configDir, configPath } = clientPaths[clientType];
-    // Create config directory if it doesn't exist
-    if (!fs.existsSync(configDir)) {
-        fs.mkdirSync(configDir, { recursive: true });
-    }
-    // Handle client-specific configuration format
-    if (clientType === "claude") {
-        let claudeConfig = { mcpServers: {} };
-        if (fs.existsSync(configPath)) {
-            try {
-                claudeConfig = JSON.parse(fs.readFileSync(configPath, "utf8"));
-            }
-            catch (error) {
-                console.log(chalk.yellow("⚠️  Creating new config file"));
-            }
-        }
-        // Ensure mcpServers exists
-        if (!claudeConfig.mcpServers)
-            claudeConfig.mcpServers = {};
-        // Update only the mcpServers entry
-        claudeConfig.mcpServers[url] = config;
-        fs.writeFileSync(configPath, JSON.stringify(claudeConfig, null, 2));
-        console.log(chalk.green(`✅ Configuration saved to: ${configPath}`));
-    }
-    else if (clientType === "windsurf") {
-        let windsurfConfig = { mcpServers: {} };
-        if (fs.existsSync(configPath)) {
-            try {
-                windsurfConfig = JSON.parse(fs.readFileSync(configPath, "utf8"));
-            }
-            catch (error) {
-                console.log(chalk.yellow("⚠️  Creating new config file"));
-            }
-        }
-        // Ensure mcpServers exists
-        if (!windsurfConfig.mcpServers)
-            windsurfConfig.mcpServers = {};
-        // Now TypeScript knows mcpServers exists
-        windsurfConfig.mcpServers[url] = config;
-        fs.writeFileSync(configPath, JSON.stringify(windsurfConfig, null, 2));
-        console.log(chalk.green(`✅ Configuration saved to: ${configPath}`));
-    }
-    else if (clientType === "cursor") {
-        let cursorConfig = { mcpServers: {} };
-        if (fs.existsSync(configPath)) {
-            try {
-                cursorConfig = JSON.parse(fs.readFileSync(configPath, "utf8"));
-            }
-            catch (error) {
-                console.log(chalk.yellow("⚠️  Creating new config file"));
-            }
-        }
-        // Ensure mcpServers exists
-        if (!cursorConfig.mcpServers)
-            cursorConfig.mcpServers = {};
-        // Remove existing config if it exists
-        if (cursorConfig.mcpServers[url]) {
-            delete cursorConfig.mcpServers[url];
-        }
-        try {
-            // Create a unique key for Cursor's configuration
-            const newKey = `natoma_${installationId}`;
-            cursorConfig.mcpServers[newKey] = sseConfig;
-            fs.writeFileSync(configPath, JSON.stringify(cursorConfig, null, 2));
-            console.log(chalk.green(`✅ Configuration saved to: ${configPath}`));
-        }
-        catch (error) {
-            console.log(chalk.red("❌ Error occurred while setting up MCP:"));
-            console.log(chalk.red(`   ${error.message}`));
-            console.log(chalk.yellow("\nPlease try again or contact support if the issue persists.\n"));
-        }
-    }
-}