@chkp/documentation-mcp 1.1.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @chkp/documentation-mcp
 
+## 1.4.1
+
+### Patch Changes
+
+- b5fdd00: General improvements and updates (synced from internal repository)
+
+## 1.3.0
+
+### Minor Changes
+
+- 56cf1d2: Updated implementation and features, Modified 3 file(s) (synced from internal repository)
+
 ## 1.1.0
 
 ### Minor Changes

package/README.md

@@ -63,7 +63,8 @@ Set the following environment variables:
 
 - `CLIENT_ID`: Client ID for authentication with Check Point Documentation Tool (required)
 - `SECRET_KEY`: Secret Key for authentication with Check Point Documentation Tool (required)
-- `REGION`: Documentation Tool region - EU, US, STG, or Local (default: EU)
+- `AUTH_URL`: Authentication URL copied from the API key creation dialog (e.g. `https://cloudinfra-gw.portal.checkpoint.com/auth/external`). Recommended — the path suffix is stripped automatically so you can paste it directly. When set, `REGION` is inferred and does not need to be set separately.
+- `REGION`: Short region code — `EU`, `US`, `STG`, or `LOCAL` (default: `EU`). Use this instead of `AUTH_URL` for backwards-compatible configurations.
   
 ---
 
@@ -75,7 +76,7 @@ Set the following environment variables:
 
 - `CLIENT_ID`: Your client ID for Documentation Tool authentication
 - `SECRET_KEY`: Your secret key for Documentation Tool authentication
-- `REGION`: Set to "Local" for on-premises deployment
+- `REGION`: Set to `LOCAL` for on-premises deployment
   
 ---
 
@@ -107,13 +108,15 @@ It is expected to work with any MCP client that supports the Model Context Proto
       "env": {
         "CLIENT_ID": "YOUR_CLIENT_ID",
         "SECRET_KEY": "YOUR_SECRET_KEY",
-        "REGION": "EU"
+        "AUTH_URL": "YOUR_AUTH_URL"
       }
     }
   }
 }
 ```
 
+> **Tip:** Copy `AUTH_URL` directly from the Authentication URL shown in the API key creation dialog. The path suffix is stripped automatically — no manual editing needed.
+
 ### Configuring the Claude Desktop App
 
 #### For macOS:
@@ -143,7 +146,7 @@ Add the server configuration:
       "env": {
         "CLIENT_ID": "YOUR_CLIENT_ID",
         "SECRET_KEY": "YOUR_SECRET_KEY",
-        "REGION": "EU"
+        "AUTH_URL": "YOUR_AUTH_URL"
       }
     }
   }
@@ -170,7 +173,7 @@ Add this configuration:
         "env": {
           "CLIENT_ID": "YOUR_CLIENT_ID",
           "SECRET_KEY": "YOUR_SECRET_KEY",
-          "REGION": "EU"
+          "AUTH_URL": "YOUR_AUTH_URL"
         }
       }
     }
@@ -219,7 +222,17 @@ npm run build
 You can run the server locally for development using [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) or any compatible MCP client.
 
 ```bash
-node FULL_PATH_TO_SERVER/packages/copilot/dist/index.js --client-id "YOUR_CLIENT_ID" --secret-key "YOUR_SECRET_KEY" --region "EU"
+# Option A: use the Authentication URL from the API key creation dialog
+node FULL_PATH_TO_SERVER/packages/documentation-tool/dist/index.js \
+  --client-id "YOUR_CLIENT_ID" \
+  --secret-key "YOUR_SECRET_KEY" \
+  --auth-url "YOUR_AUTH_URL"
+
+# Option B: use a region code (EU / US / STG / LOCAL)
+node FULL_PATH_TO_SERVER/packages/documentation-tool/dist/index.js \
+  --client-id "YOUR_CLIENT_ID" \
+  --secret-key "YOUR_SECRET_KEY" \
+  --region "EU"
 ```
 
 ---

package/dist/index.js

@@ -16,7 +16,7 @@ __export(ui_dialog_exports, {
   showLoginDialog: () => showLoginDialog
 });
 import { createServer } from "http";
-import { URL } from "url";
+import { URL as URL2 } from "url";
 import { exec } from "child_process";
 import { promisify } from "util";
 import * as fs2 from "fs";
@@ -87,7 +87,7 @@ var init_ui_dialog = __esm({
         });
       }
       handleRequest(req, res, config) {
-        const url = new URL(req.url, `http://localhost:${this.port}`);
+        const url = new URL2(req.url, `http://localhost:${this.port}`);
         if (req.method === "GET" && url.pathname === "/") {
           res.writeHead(200, { "Content-Type": "text/html" });
           res.end(this.generateHTML(config));
@@ -309,7 +309,7 @@ var init_ui_dialog = __esm({
         try {
           let url;
           try {
-            url = new URL(urlString);
+            url = new URL2(urlString);
             if (!["http:", "https:"].includes(url.protocol) || url.hostname !== "localhost" && url.hostname !== "127.0.0.1") {
               throw new Error("Invalid URL protocol or non-localhost hostname");
             }
@@ -370,6 +370,165 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import fs from "fs";
 import http from "http";
 import { randomUUID } from "crypto";
+
+// ../mcp-utils/dist/settings-manager.js
+var SettingsManager = class _SettingsManager {
+  /**
+   * Creates a new SettingsManager
+   * @param settingsClass The Settings class to use for creating settings instances
+   */
+  constructor(settingsClass) {
+    this.settingsMap = /* @__PURE__ */ new Map();
+    this.defaultSessionId = "default";
+    this.settingsClass = settingsClass;
+  }
+  /**
+   * Get settings for a specific session
+   * @param sessionId The session ID (defaults to 'default' for stdio mode)
+   * @returns Settings instance for the session
+   */
+  getSettings(sessionId) {
+    const sid = sessionId || this.defaultSessionId;
+    if (!this.settingsMap.has(sid)) {
+      this.settingsMap.set(sid, new this.settingsClass());
+    }
+    return this.settingsMap.get(sid);
+  }
+  /**
+   * Set settings for a specific session
+   * @param settings The settings object to set
+   * @param sessionId The session ID (defaults to 'default' for stdio mode)
+   */
+  setSettings(settings, sessionId) {
+    const sid = sessionId || this.defaultSessionId;
+    this.settingsMap.set(sid, settings);
+  }
+  /**
+   * Injects debug settings from source into settings object
+   * @param settings The settings object to update
+   * @param source Source object containing debug information
+   * @private
+   */
+  injectDebug(settings, source) {
+    const debug = source?.debug ?? _SettingsManager.globalDebugState ?? process.env.DEBUG;
+    if (typeof debug !== "undefined") {
+      if (source?.debug !== void 0) {
+        _SettingsManager.globalDebugState = source.debug;
+      }
+      if (typeof settings.set === "function") {
+        settings.set("debug", debug);
+      } else {
+        settings.debug = debug;
+      }
+      if (debug) {
+        console.error("Debug enabled. Source object contents:");
+        console.error(JSON.stringify(source, null, 2));
+      }
+    }
+  }
+  /**
+   * Print settings object for debugging by dynamically discovering its properties
+   * @param settings The settings object to print
+   * @private
+   */
+  printSettingsDebug(settings) {
+    if (typeof settings.get === "function") {
+      console.error("Settings (using get method):");
+      if (settings.data && typeof settings.data === "object") {
+        Object.entries(settings.data).forEach(([key, value]) => {
+          console.error(`  ${key}: ${JSON.stringify(value)}`);
+        });
+      } else {
+        console.error("  Unable to enumerate settings properties - no accessible data structure");
+      }
+    } else {
+      console.error("Settings (plain object):");
+      Object.entries(settings).forEach(([key, value]) => {
+        console.error(`  ${key}: ${JSON.stringify(value)}`);
+      });
+    }
+  }
+  /**
+   * Create settings from command-line arguments
+   * @param args Command line arguments
+   * @param sessionId Optional session ID
+   * @returns Settings instance
+   */
+  createFromArgs(args, sessionId) {
+    const settings = this.settingsClass.fromArgs(args);
+    this.injectDebug(settings, args);
+    this.setSettings(settings, sessionId);
+    return settings;
+  }
+  /**
+   * Create settings from HTTP headers
+   * @param headers HTTP headers
+   * @param sessionId Optional session ID
+   * @returns Settings instance
+   */
+  createFromHeaders(headers, sessionId) {
+    const verbose = _SettingsManager.globalDebugState;
+    if (verbose) {
+      console.error("[SettingsManager.createFromHeaders] Verbose: Starting with sessionId:", sessionId || "(default)");
+      console.error("[SettingsManager.createFromHeaders] Verbose: Incoming headers count:", Object.keys(headers).length);
+    }
+    if (_SettingsManager.globalDebugState) {
+      console.error("=== createFromHeaders Debug Info ===");
+      console.error("Incoming headers:");
+      console.error(JSON.stringify(headers, null, 2));
+    }
+    if (verbose && (!headers || Object.keys(headers).length === 0)) {
+      console.error("[SettingsManager.createFromHeaders] Verbose: WARNING - Headers object is empty or undefined");
+    }
+    const normalizedHeaders = {};
+    for (const [key, value] of Object.entries(headers)) {
+      const normalizedKey = key.includes("_") ? key.replace(/_/g, "-") : key;
+      normalizedHeaders[normalizedKey] = value;
+      if (verbose) {
+        console.error(`[SettingsManager.createFromHeaders] Verbose: Header normalized: "${key}" -> "${normalizedKey}"`);
+      }
+    }
+    if (verbose) {
+      console.error("[SettingsManager.createFromHeaders] Verbose: Normalized headers count:", Object.keys(normalizedHeaders).length);
+    }
+    if (_SettingsManager.globalDebugState) {
+      console.error("Normalized headers:");
+      console.error(JSON.stringify(normalizedHeaders, null, 2));
+    }
+    const debugHeader = normalizedHeaders["debug"] || normalizedHeaders["Debug"] || normalizedHeaders["DEBUG"];
+    const debugSource = { debug: debugHeader !== void 0 ? debugHeader : _SettingsManager.globalDebugState };
+    if (verbose) {
+      console.error("[SettingsManager.createFromHeaders] Verbose: Calling settingsClass.fromHeaders");
+    }
+    const settings = this.settingsClass.fromHeaders(normalizedHeaders);
+    if (verbose) {
+      console.error("[SettingsManager.createFromHeaders] Verbose: Settings object created");
+    }
+    this.injectDebug(settings, debugSource);
+    if (_SettingsManager.globalDebugState) {
+      console.error("Final settings object for session:", sessionId || "(default)");
+      this.printSettingsDebug(settings);
+      console.error("=== End createFromHeaders Debug Info ===");
+    }
+    if (verbose) {
+      console.error("[SettingsManager.createFromHeaders] Verbose: Storing settings for session:", sessionId || "(default)");
+    }
+    this.setSettings(settings, sessionId);
+    return settings;
+  }
+  /**
+   * Clear settings for a session
+   * @param sessionId The session ID to clear
+   */
+  clearSession(sessionId) {
+    if (sessionId !== this.defaultSessionId) {
+      this.settingsMap.delete(sessionId);
+    }
+  }
+};
+SettingsManager.globalDebugState = void 0;
+
+// ../mcp-utils/dist/launcher.js
 async function launchMCPServer(configPath, serverModule2) {
   const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
   const program = new Command();
@@ -378,7 +537,7 @@ async function launchMCPServer(configPath, serverModule2) {
   }
   config.options.forEach((option) => {
     const envValue = option.env ? process.env[option.env] : void 0;
-    const defaultValue = option.default || envValue;
+    const defaultValue = envValue || option.default;
     if (option.type === "boolean") {
       const boolDefault = envValue === "true" || option.default === "true";
       program.option(option.flag, option.description, boolDefault);
@@ -437,6 +596,7 @@ async function launchMCPServer(configPath, serverModule2) {
 }
 async function launchHTTPServer(config, serverModule2, port) {
   const transports = {};
+  const serverInstances = {};
   const server2 = http.createServer(async (req, res) => {
     if (req.url === "/" || req.url === "/mcp") {
       const sessionId = req.headers["mcp-session-id"];
@@ -458,31 +618,65 @@ async function launchHTTPServer(config, serverModule2, port) {
           }
           let transport;
           if (sessionId && transports[sessionId]) {
+            const verbose = SettingsManager.globalDebugState;
+            if (verbose) {
+              console.error("[launchHTTPServer] Verbose: Reusing existing transport for session:", sessionId);
+            }
             transport = transports[sessionId];
             if (!serverModule2.settingsManager) {
               throw new Error("ServerModule must have a settingsManager. Create it with createServerModule.");
             }
-            serverModule2.settingsManager.createFromHeaders(headersToEnvVars(req.headers, config), sessionId);
+            if (verbose) {
+              console.error("[launchHTTPServer] Verbose: Converting headers for existing session");
+            }
+            const envHeaders = headersToEnvVars(req.headers, config);
+            if (verbose) {
+              console.error("[launchHTTPServer] Verbose: Creating settings from headers for existing session");
+            }
+            serverModule2.settingsManager.createFromHeaders(envHeaders, sessionId);
           } else if (!sessionId && body && body.method === "initialize") {
             transport = new StreamableHTTPServerTransport({
               sessionIdGenerator: () => randomUUID(),
               onsessioninitialized: (sid) => {
+                const verbose = SettingsManager.globalDebugState;
+                if (verbose) {
+                  console.error("[launchHTTPServer] Verbose: New session initialized:", sid);
+                }
                 transports[sid] = transport;
+                if (verbose) {
+                  console.error("[launchHTTPServer] Verbose: Converting headers for new session");
+                  console.error("[launchHTTPServer] Verbose: Raw request headers:", Object.keys(req.headers));
+                }
                 const headers = headersToEnvVars(req.headers, config);
+                if (verbose) {
+                  console.error("[launchHTTPServer] Verbose: Converted headers count:", Object.keys(headers).length);
+                }
                 const metadata = {
                   userAgent: req.headers["user-agent"],
                   origin: req.headers.origin || req.headers.referer,
                   remoteAddress: req.socket.remoteAddress,
                   initialPath: req.url
                 };
+                if (verbose) {
+                  console.error("[launchHTTPServer] Verbose: Creating session in session manager");
+                }
                 serverModule2.sessionManager.createSession(sid, metadata);
+                if (verbose) {
+                  console.error("[launchHTTPServer] Verbose: Creating settings from headers for new session");
+                }
                 serverModule2.settingsManager.createFromHeaders(headers, sid);
+                if (verbose) {
+                  console.error("[launchHTTPServer] Verbose: Session initialization complete");
+                }
               }
             });
             transport.onclose = () => {
               const sid = transport.sessionId;
               if (sid) {
                 delete transports[sid];
+                if (serverInstances[sid]) {
+                  delete serverInstances[sid];
+                }
                 serverModule2.settingsManager.clearSession(sid);
                 serverModule2.apiManagerFactory.clearSession(sid);
                 serverModule2.sessionManager.removeSession(sid);
@@ -498,7 +692,22 @@ async function launchHTTPServer(config, serverModule2, port) {
                 transport
               };
             };
-            await serverModule2.server.connect(transport).catch((error) => {
+            let serverToConnect;
+            if (serverModule2.createServerInstance) {
+              const sessionServer = serverModule2.createServerInstance();
+              serverToConnect = sessionServer;
+              const originalOnSessionInit = transport.onsessioninitialized;
+              transport.onsessioninitialized = (sid) => {
+                serverInstances[sid] = sessionServer;
+                if (originalOnSessionInit) {
+                  originalOnSessionInit(sid);
+                }
+              };
+            } else {
+              serverToConnect = serverModule2.server;
+              console.error("Warning: Using shared server instance. Consider providing createServerInstance for better multi-user support.");
+            }
+            await serverToConnect.connect(transport).catch((error) => {
               console.error("Error connecting to HTTP transport:", error);
             });
           } else {
@@ -549,18 +758,11 @@ async function launchHTTPServer(config, serverModule2, port) {
     } else if (req.url === "/health" || req.url === "/status") {
       res.writeHead(200, { "Content-Type": "application/json" });
       const sessionCount = serverModule2.sessionManager.getSessionCount();
-      const sessions = serverModule2.sessionManager.getAllSessions().map((session) => ({
-        id: session.sessionId,
-        createdAt: session.createdAt,
-        lastActive: session.lastActive
-        // Don't include potentially sensitive metadata
-      }));
       res.end(JSON.stringify({
         status: "ok",
         server: config.name,
         version: serverModule2.pkg.version,
-        activeSessions: sessionCount,
-        sessions
+        activeSessions: sessionCount
       }));
     } else {
       res.writeHead(404, { "Content-Type": "text/plain" });
@@ -576,168 +778,75 @@ async function launchHTTPServer(config, serverModule2, port) {
   });
 }
 function headersToEnvVars(headers, config) {
+  const verbose = SettingsManager.globalDebugState;
+  if (verbose) {
+    console.error("[headersToEnvVars] Verbose: Converting headers to env vars");
+    console.error("[headersToEnvVars] Verbose: Input headers count:", Object.keys(headers).length);
+    console.error("[headersToEnvVars] Verbose: Input header keys:", Object.keys(headers));
+    if (!headers || Object.keys(headers).length === 0) {
+      console.error("[headersToEnvVars] Verbose: WARNING - Headers object is empty");
+    }
+  }
+  if (!headers || Object.keys(headers).length === 0) {
+    return {};
+  }
   const result = {};
   for (const [name, value] of Object.entries(headers)) {
     if (value !== void 0) {
       const envName = name.toUpperCase().replace(/-/g, "_");
       result[envName] = value;
+      if (verbose) {
+        console.error(`[headersToEnvVars] Verbose: Basic mapping: "${name}" -> "${envName}"`);
+      }
     }
   }
+  if (verbose) {
+    console.error("[headersToEnvVars] Verbose: After basic mapping, result keys:", Object.keys(result));
+  }
   if (config && config.options) {
+    if (verbose) {
+      console.error("[headersToEnvVars] Verbose: Config provided, building header-to-env mapping");
+    }
     const headerToEnvMap = {};
     for (const option of config.options) {
       if (option.env) {
         const flagName = option.flag.split(" ")[0].replace(/^--?/, "").replace(/-/g, "_");
         headerToEnvMap[flagName.toLowerCase()] = option.env;
+        if (verbose) {
+          console.error(`[headersToEnvVars] Verbose: Mapping: "${flagName.toLowerCase()}" -> "${option.env}"`);
+        }
         headerToEnvMap[option.env.toLowerCase()] = option.env;
       }
     }
+    if (verbose) {
+      console.error("[headersToEnvVars] Verbose: headerToEnvMap:", headerToEnvMap);
+    }
+    let mappedCount = 0;
     for (const [headerName, headerValue] of Object.entries(headers)) {
       if (headerValue !== void 0) {
         const normalizedHeaderName = headerName.toLowerCase().replace(/-/g, "_");
         const envVarName = headerToEnvMap[normalizedHeaderName];
         if (envVarName) {
           result[envVarName] = headerValue;
+          mappedCount++;
+          if (verbose) {
+            console.error(`[headersToEnvVars] Verbose: Config mapping: "${headerName}" -> "${envVarName}"`);
+          }
         }
       }
     }
-  }
-  return result;
-}
-
-// ../mcp-utils/dist/settings-manager.js
-var SettingsManager = class _SettingsManager {
-  /**
-   * Creates a new SettingsManager
-   * @param settingsClass The Settings class to use for creating settings instances
-   */
-  constructor(settingsClass) {
-    this.settingsMap = /* @__PURE__ */ new Map();
-    this.defaultSessionId = "default";
-    this.settingsClass = settingsClass;
-  }
-  /**
-   * Get settings for a specific session
-   * @param sessionId The session ID (defaults to 'default' for stdio mode)
-   * @returns Settings instance for the session
-   */
-  getSettings(sessionId) {
-    const sid = sessionId || this.defaultSessionId;
-    if (!this.settingsMap.has(sid)) {
-      this.settingsMap.set(sid, new this.settingsClass());
-    }
-    return this.settingsMap.get(sid);
-  }
-  /**
-   * Set settings for a specific session
-   * @param settings The settings object to set
-   * @param sessionId The session ID (defaults to 'default' for stdio mode)
-   */
-  setSettings(settings, sessionId) {
-    const sid = sessionId || this.defaultSessionId;
-    this.settingsMap.set(sid, settings);
-  }
-  /**
-   * Injects debug settings from source into settings object
-   * @param settings The settings object to update
-   * @param source Source object containing debug information
-   * @private
-   */
-  injectDebug(settings, source) {
-    const debug = source?.debug ?? _SettingsManager.globalDebugState ?? process.env.DEBUG;
-    if (typeof debug !== "undefined") {
-      if (source?.debug !== void 0) {
-        _SettingsManager.globalDebugState = source.debug;
-      }
-      if (typeof settings.set === "function") {
-        settings.set("debug", debug);
-      } else {
-        settings.debug = debug;
-      }
-      if (debug) {
-        console.error("Debug enabled. Source object contents:");
-        console.error(JSON.stringify(source, null, 2));
-      }
-    }
-  }
-  /**
-   * Print settings object for debugging by dynamically discovering its properties
-   * @param settings The settings object to print
-   * @private
-   */
-  printSettingsDebug(settings) {
-    if (typeof settings.get === "function") {
-      console.error("Settings (using get method):");
-      if (settings.data && typeof settings.data === "object") {
-        Object.entries(settings.data).forEach(([key, value]) => {
-          console.error(`  ${key}: ${JSON.stringify(value)}`);
-        });
-      } else {
-        console.error("  Unable to enumerate settings properties - no accessible data structure");
-      }
-    } else {
-      console.error("Settings (plain object):");
-      Object.entries(settings).forEach(([key, value]) => {
-        console.error(`  ${key}: ${JSON.stringify(value)}`);
-      });
-    }
-  }
-  /**
-   * Create settings from command-line arguments
-   * @param args Command line arguments
-   * @param sessionId Optional session ID
-   * @returns Settings instance
-   */
-  createFromArgs(args, sessionId) {
-    const settings = this.settingsClass.fromArgs(args);
-    this.injectDebug(settings, args);
-    this.setSettings(settings, sessionId);
-    return settings;
-  }
-  /**
-   * Create settings from HTTP headers
-   * @param headers HTTP headers
-   * @param sessionId Optional session ID
-   * @returns Settings instance
-   */
-  createFromHeaders(headers, sessionId) {
-    if (_SettingsManager.globalDebugState) {
-      console.error("=== createFromHeaders Debug Info ===");
-      console.error("Incoming headers:");
-      console.error(JSON.stringify(headers, null, 2));
-    }
-    const normalizedHeaders = {};
-    for (const [key, value] of Object.entries(headers)) {
-      const normalizedKey = key.includes("_") ? key.replace(/_/g, "-") : key;
-      normalizedHeaders[normalizedKey] = value;
-    }
-    if (_SettingsManager.globalDebugState) {
-      console.error("Normalized headers:");
-      console.error(JSON.stringify(normalizedHeaders, null, 2));
-    }
-    const debugHeader = normalizedHeaders["debug"] || normalizedHeaders["Debug"] || normalizedHeaders["DEBUG"];
-    const debugSource = { debug: debugHeader !== void 0 ? debugHeader : _SettingsManager.globalDebugState };
-    const settings = this.settingsClass.fromHeaders(normalizedHeaders);
-    this.injectDebug(settings, debugSource);
-    if (_SettingsManager.globalDebugState) {
-      console.error("Final settings object:");
-      this.printSettingsDebug(settings);
-      console.error("=== End createFromHeaders Debug Info ===");
+    if (verbose) {
+      console.error(`[headersToEnvVars] Verbose: Mapped ${mappedCount} headers using config`);
     }
-    this.setSettings(settings, sessionId);
-    return settings;
+  } else if (verbose) {
+    console.error("[headersToEnvVars] Verbose: No config provided, skipping config-based mapping");
   }
-  /**
-   * Clear settings for a session
-   * @param sessionId The session ID to clear
-   */
-  clearSession(sessionId) {
-    if (sessionId !== this.defaultSessionId) {
-      this.settingsMap.delete(sessionId);
-    }
+  if (verbose) {
+    console.error("[headersToEnvVars] Verbose: Final result keys:", Object.keys(result));
+    console.error("[headersToEnvVars] Verbose: Final result (sanitized):", Object.fromEntries(Object.entries(result).map(([k, v]) => [k, k.toLowerCase().includes("key") || k.toLowerCase().includes("token") || k.toLowerCase().includes("password") ? "***" : v])));
   }
-};
-SettingsManager.globalDebugState = void 0;
+  return result;
+}
 
 // ../mcp-utils/dist/api-manager-factory.js
 var APIManagerFactory = class {
@@ -758,11 +867,27 @@ var APIManagerFactory = class {
    * @returns API Manager instance for the session
    */
   getAPIManager(sessionId) {
+    const verbose = SettingsManager.globalDebugState;
     const sid = sessionId || this.defaultSessionId;
+    if (verbose) {
+      console.error("[APIManagerFactory.getAPIManager] Verbose: Getting API manager for session:", sid);
+    }
     if (!this.apiManagerMap.has(sid)) {
+      if (verbose) {
+        console.error("[APIManagerFactory.getAPIManager] Verbose: API manager not in cache, creating new one");
+      }
       const settings2 = this.settingsManager.getSettings(sid);
+      if (verbose) {
+        console.error("[APIManagerFactory.getAPIManager] Verbose: Retrieved settings from settings manager");
+        console.error("[APIManagerFactory.getAPIManager] Verbose: Creating API manager from settings");
+      }
       const apiManager2 = this.createAPIManagerFromSettings(settings2);
+      if (verbose) {
+        console.error("[APIManagerFactory.getAPIManager] Verbose: API manager created successfully");
+      }
       this.apiManagerMap.set(sid, apiManager2);
+    } else if (verbose) {
+      console.error("[APIManagerFactory.getAPIManager] Verbose: Using cached API manager");
     }
     const apiManager = this.apiManagerMap.get(sid);
     const settings = this.settingsManager.getSettings(sid);
@@ -777,7 +902,17 @@ var APIManagerFactory = class {
    * @returns API Manager instance
    */
   createAPIManagerFromSettings(settings) {
-    return this.apiManagerClass.create(settings);
+    const verbose = SettingsManager.globalDebugState;
+    if (verbose) {
+      console.error("[APIManagerFactory.createAPIManagerFromSettings] Verbose: Creating API manager from settings");
+      console.error("[APIManagerFactory.createAPIManagerFromSettings] Verbose: Settings type:", typeof settings);
+      console.error("[APIManagerFactory.createAPIManagerFromSettings] Verbose: Settings keys:", settings ? Object.keys(settings) : "null");
+    }
+    const apiManager = this.apiManagerClass.create(settings);
+    if (verbose) {
+      console.error("[APIManagerFactory.createAPIManagerFromSettings] Verbose: API manager created");
+    }
+    return apiManager;
   }
   /**
    * Clear API manager for a session
@@ -1130,7 +1265,8 @@ var SessionManager = class {
 
 // ../mcp-utils/dist/server-utils.js
 function getHeaderValue(headers, key) {
-  const value = headers[key] || headers[key.toUpperCase()] || headers[key.toLowerCase()];
+  const normalizedKey = key.replace(/_/g, "-");
+  const value = headers[normalizedKey] || headers[normalizedKey.toUpperCase()] || headers[normalizedKey.toLowerCase()];
   return typeof value === "string" ? value : Array.isArray(value) ? value[0] : void 0;
 }
 function createApiRunner(serverModule2) {
@@ -1139,7 +1275,47 @@ function createApiRunner(serverModule2) {
     return await apiManager.callApi(method, uri, data, domain);
   };
 }
-function createServerModule(server2, Settings2, pkg2, apiManagerClass, toolPolicyCallback) {
+function wrapServerWithTracking(server2, createServerFn) {
+  const registrations = [];
+  const originalTool = server2.tool?.bind(server2);
+  const originalPrompt = server2.prompt?.bind(server2);
+  const originalResource = server2.resource?.bind(server2);
+  if (originalTool) {
+    server2.tool = function(...args) {
+      registrations.push({ type: "tool", method: "tool", args: [...args] });
+      return originalTool(...args);
+    };
+  }
+  if (originalPrompt) {
+    server2.prompt = function(...args) {
+      registrations.push({ type: "prompt", method: "prompt", args: [...args] });
+      return originalPrompt(...args);
+    };
+  }
+  if (originalResource) {
+    server2.resource = function(...args) {
+      registrations.push({ type: "resource", method: "resource", args: [...args] });
+      return originalResource(...args);
+    };
+  }
+  const createInstance = () => {
+    const newServer = createServerFn();
+    for (const reg of registrations) {
+      if (newServer[reg.method]) {
+        newServer[reg.method](...reg.args);
+      }
+    }
+    if (typeof server2.setToolPolicy === "function" && typeof newServer.setToolPolicy === "function") {
+      const toolPolicy = server2._toolPolicyCallback;
+      if (toolPolicy) {
+        newServer.setToolPolicy(toolPolicy);
+      }
+    }
+    return newServer;
+  };
+  return { wrappedServer: server2, createInstance };
+}
+function createServerModule(server2, Settings2, pkg2, apiManagerClass, toolPolicyCallback, createServerFn) {
   const settingsManager = new SettingsManager(Settings2);
   const apiManagerFactory = new APIManagerFactory(apiManagerClass, settingsManager);
   const sessionManager = new SessionManager();
@@ -1147,6 +1323,15 @@ function createServerModule(server2, Settings2, pkg2, apiManagerClass, toolPolic
     console.error("[createServerModule] Setting tool policy callback on server");
     server2.setToolPolicy(toolPolicyCallback);
   }
+  const serverFactory = createServerFn || server2._createServerFn;
+  let createServerInstance;
+  if (serverFactory) {
+    const { wrappedServer, createInstance } = wrapServerWithTracking(server2, serverFactory);
+    createServerInstance = createInstance;
+    console.error("[createServerModule] Server factory enabled - HTTP multi-user support active");
+  } else {
+    console.error("[createServerModule] Warning: No server factory provided - HTTP multi-user may have issues");
+  }
   return {
     server: server2,
     Settings: Settings2,
@@ -1154,7 +1339,8 @@ function createServerModule(server2, Settings2, pkg2, apiManagerClass, toolPolic
     apiManagerFactory,
     sessionManager,
     pkg: pkg2,
-    toolPolicyCallback
+    toolPolicyCallback,
+    createServerInstance
   };
 }
 
@@ -1277,9 +1463,15 @@ var CPMcpServer = class extends McpServer {
     if (typeof callback === "function") {
       const toolName = args[0];
       const wrappedCallback = async (...callbackArgs) => {
-        const extra = callbackArgs[1];
+        let extra = callbackArgs[1];
+        if (!extra && callbackArgs[0]?.sessionId) {
+          extra = callbackArgs[0];
+        }
         trackToolCall(this.mcpName, toolName, this.mcpVersion, extra).catch(() => {
         });
+        if (callbackArgs.length === 1 && callbackArgs[0]?.sessionId) {
+          return callback({}, callbackArgs[0]);
+        }
         return callback(...callbackArgs);
       };
       args[args.length - 1] = wrappedCallback;
@@ -1304,7 +1496,11 @@ function createMcpServer(importMetaUrl, serverInfo, options) {
     name: serverInfo.name || pkg2.name,
     version: serverInfo.version || pkg2.version
   };
+  const createServerFn = () => {
+    return new CPMcpServer(fullServerInfo, options);
+  };
   const server2 = new CPMcpServer(fullServerInfo, options);
+  server2._createServerFn = createServerFn;
   return { server: server2, pkg: pkg2 };
 }
 
@@ -1331,9 +1527,59 @@ function nullOrEmpty(val) {
 
 // ../infra/dist/settings.js
 var Settings = class _Settings {
-  constructor({ apiKey = process.env.API_KEY, username = process.env.USERNAME, password = process.env.PASSWORD, s1cUrl = process.env.S1C_URL, managementHost = process.env.MANAGEMENT_HOST, managementPort = process.env.MANAGEMENT_PORT || "443", cloudInfraToken = process.env.CLOUD_INFRA_TOKEN, clientId = process.env.CLIENT_ID, secretKey = process.env.SECRET_KEY, region = process.env.REGION || "EU", devPort = process.env.DEV_PORT || "8006" } = {}) {
+  normalizeRegion(region) {
+    if (!region) {
+      return void 0;
+    }
+    const normalized = region.trim().toUpperCase();
+    return this.isValidRegion(normalized) ? normalized : void 0;
+  }
+  /**
+   * Extract the base gateway URL (scheme + host) from a full URL.
+   * Allows users to copy-paste any URL from the API key creation dialog
+   * without having to strip the path manually.
+   * Falls back to the original string if URL parsing fails.
+   */
+  static stripGatewayPath(url) {
+    try {
+      const parsed = new URL(url);
+      return `${parsed.protocol}//${parsed.host}`;
+    } catch {
+      return url;
+    }
+  }
+  /**
+   * Detect the region from a gateway base URL
+   */
+  static detectRegionFromUrl(url) {
+    if (url.includes("cloudinfra-gw-us.portal.checkpoint.com"))
+      return "US";
+    if (url.includes("cloudinfra-gw.portal.checkpoint.com"))
+      return "EU";
+    if (url.includes("dev-cloudinfra-gw"))
+      return "STG";
+    return void 0;
+  }
+  constructor({ apiKey = process.env.API_KEY, username = process.env.USERNAME, password = process.env.PASSWORD, s1cUrl = process.env.S1C_URL, managementHost = process.env.MANAGEMENT_HOST, managementPort = process.env.MANAGEMENT_PORT || "443", cloudInfraToken = process.env.CLOUD_INFRA_TOKEN, clientId = process.env.CLIENT_ID, secretKey = process.env.SECRET_KEY, region = process.env.REGION || "EU", devPort = process.env.DEV_PORT || "8006", gatewayUrl } = {}) {
     this.region = "EU";
     this.devPort = "8006";
+    this.gatewayUrl = "";
+    const verbose = SettingsManager.globalDebugState;
+    if (verbose) {
+      console.error("[Settings] Verbose: Constructor called with params:", {
+        apiKey: apiKey ? "***" : void 0,
+        username: username ? "***" : void 0,
+        password: password ? "***" : void 0,
+        s1cUrl,
+        managementHost,
+        managementPort,
+        cloudInfraToken: cloudInfraToken ? "***" : void 0,
+        clientId,
+        secretKey: secretKey ? "***" : void 0,
+        region,
+        devPort
+      });
+    }
     this.apiKey = apiKey;
     this.username = username;
     this.password = password;
@@ -1343,8 +1589,21 @@ var Settings = class _Settings {
     this.cloudInfraToken = cloudInfraToken;
     this.clientId = clientId;
     this.secretKey = secretKey;
-    this.region = this.isValidRegion(region) ? region : "EU";
+    this.region = this.normalizeRegion(region) || "EU";
     this.devPort = devPort;
+    this.gatewayUrl = this.resolveGatewayUrl(this.region, gatewayUrl);
+    if (verbose) {
+      console.error("[Settings] Verbose: After assignment:", {
+        apiKey: this.apiKey ? "***" : void 0,
+        username: this.username ? "***" : void 0,
+        password: this.password ? "***" : void 0,
+        s1cUrl: this.s1cUrl,
+        managementHost: this.managementHost,
+        managementPort: this.managementPort,
+        cloudInfraToken: this.cloudInfraToken ? "***" : void 0,
+        region: this.region
+      });
+    }
     this.validate();
   }
   /**
@@ -1354,10 +1613,10 @@ var Settings = class _Settings {
     return ["EU", "US", "STG", "LOCAL"].includes(region.toUpperCase());
   }
   /**
-   * Get Cloud Infra Gateway based on region
+   * Get the base gateway URL for a given region
    */
-  getCloudInfraGateway() {
-    switch (this.region) {
+  getRegionGatewayUrl(region) {
+    switch (region) {
       case "EU":
         return "https://cloudinfra-gw.portal.checkpoint.com";
       case "US":
@@ -1369,23 +1628,88 @@ var Settings = class _Settings {
         return "";
     }
   }
+  /**
+   * Resolve the base gateway URL from either a provided URL or the configured region.
+   * If a URL is provided, its path suffix is stripped so users can paste the full
+   * auth URL from the API key creation dialog (e.g. ending in /auth/external).
+   * When the URL implies a different region, this.region is updated to match.
+   */
+  resolveGatewayUrl(region, providedUrl) {
+    if (!providedUrl) {
+      return this.getRegionGatewayUrl(region);
+    }
+    const base = _Settings.stripGatewayPath(providedUrl);
+    const detectedRegion = _Settings.detectRegionFromUrl(base);
+    if (detectedRegion && detectedRegion !== this.region) {
+      this.region = detectedRegion;
+    }
+    return base;
+  }
+  /**
+   * Get the base Cloud Infra Gateway URL.
+   * Returns the precomputed gatewayUrl (derived from region or a provided URL).
+   */
+  getCloudInfraGateway() {
+    return this.gatewayUrl;
+  }
   /**
    * Validate the settings
    */
   validate() {
+    const verbose = SettingsManager.globalDebugState;
+    if (verbose) {
+      console.error("[Settings] Verbose: Validating settings...");
+      console.error("[Settings] Verbose: s1cUrl:", this.s1cUrl || "(empty)");
+      console.error("[Settings] Verbose: managementHost:", this.managementHost || "(empty)");
+      console.error("[Settings] Verbose: apiKey:", this.apiKey ? "***" : "(empty)");
+      console.error("[Settings] Verbose: cloudInfraToken:", this.cloudInfraToken ? "***" : "(empty)");
+      console.error("[Settings] Verbose: username:", this.username ? "***" : "(empty)");
+      console.error("[Settings] Verbose: password:", this.password ? "***" : "(empty)");
+    }
     if (!nullOrEmpty(this.s1cUrl) && nullOrEmpty(this.apiKey) && nullOrEmpty(this.cloudInfraToken)) {
+      if (verbose) {
+        console.error("[Settings] Verbose: Validation FAILED - S1C URL provided but no API key or CI token");
+      }
       throw new Error("API key or CI Token is required for S1C (via --api-key or API_KEY env var)");
     }
     if (!nullOrEmpty(this.managementHost) && nullOrEmpty(this.apiKey) && (nullOrEmpty(this.username) || nullOrEmpty(this.password))) {
+      if (verbose) {
+        console.error("[Settings] Verbose: Validation FAILED - Management host provided but no API key or credentials");
+      }
       throw new Error("Either API key or username/password are required for on-prem management (via CLI args or env vars)");
     }
     if (nullOrEmpty(this.s1cUrl) && nullOrEmpty(this.managementHost)) {
+      if (verbose) {
+        console.error("[Settings] Verbose: WARNING - Neither s1cUrl nor managementHost provided");
+      }
+    }
+    if (verbose) {
+      console.error("[Settings] Verbose: Validation PASSED");
     }
   }
   /**
    * Create settings from command-line arguments
    */
   static fromArgs(args) {
+    const verbose = SettingsManager.globalDebugState;
+    if (verbose) {
+      console.error("[Settings.fromArgs] Verbose: Creating settings from args");
+      console.error("[Settings.fromArgs] Verbose: Raw args:", {
+        apiKey: args.apiKey ? "***" : void 0,
+        username: args.username ? "***" : void 0,
+        password: args.password ? "***" : void 0,
+        s1cUrl: args.s1cUrl,
+        managementHost: args.managementHost,
+        managementPort: args.managementPort,
+        cloudInfraToken: args.cloudInfraToken ? "***" : void 0,
+        region: args.region,
+        hasOtherKeys: Object.keys(args).length > 10
+      });
+      const hasAnyValue = args.apiKey || args.username || args.password || args.s1cUrl || args.managementHost || args.cloudInfraToken;
+      if (!hasAnyValue) {
+        console.error("[Settings.fromArgs] Verbose: WARNING - Args object appears empty, no authentication values found");
+      }
+    }
     return new _Settings({
       apiKey: args.apiKey,
       username: args.username,
@@ -1396,8 +1720,9 @@ var Settings = class _Settings {
       cloudInfraToken: args.cloudInfraToken,
       clientId: args.clientId,
       secretKey: args.secretKey,
-      region: typeof args.region === "string" ? args.region.toUpperCase() : void 0,
-      devPort: args.devPort
+      region: typeof args.region === "string" ? args.region.trim().toUpperCase() : void 0,
+      devPort: args.devPort,
+      gatewayUrl: args.gatewayUrl
     });
   }
   /**
@@ -1405,7 +1730,12 @@ var Settings = class _Settings {
    * Maps headers to environment variable format based on server config
    */
   static fromHeaders(headers) {
-    return new _Settings({
+    const verbose = SettingsManager.globalDebugState;
+    if (verbose) {
+      console.error("[Settings.fromHeaders] Verbose: Creating settings from headers");
+      console.error("[Settings.fromHeaders] Verbose: Available header keys:", Object.keys(headers));
+    }
+    const extractedValues = {
       apiKey: getHeaderValue(headers, "API-KEY"),
       username: getHeaderValue(headers, "USERNAME"),
       password: getHeaderValue(headers, "PASSWORD"),
@@ -1415,8 +1745,41 @@ var Settings = class _Settings {
       cloudInfraToken: getHeaderValue(headers, "CLOUD-INFRA-TOKEN"),
       clientId: getHeaderValue(headers, "CLIENT-ID"),
       secretKey: getHeaderValue(headers, "SECRET-KEY"),
-      region: getHeaderValue(headers, "REGION")?.toUpperCase(),
-      devPort: getHeaderValue(headers, "DEV-PORT")
+      region: getHeaderValue(headers, "REGION"),
+      devPort: getHeaderValue(headers, "DEV-PORT"),
+      gatewayUrl: getHeaderValue(headers, "GATEWAY-URL")
+    };
+    if (verbose) {
+      console.error("[Settings.fromHeaders] Verbose: Extracted values:", {
+        apiKey: extractedValues.apiKey ? "***" : void 0,
+        username: extractedValues.username ? "***" : void 0,
+        password: extractedValues.password ? "***" : void 0,
+        s1cUrl: extractedValues.s1cUrl,
+        managementHost: extractedValues.managementHost,
+        managementPort: extractedValues.managementPort,
+        cloudInfraToken: extractedValues.cloudInfraToken ? "***" : void 0,
+        region: extractedValues.region,
+        devPort: extractedValues.devPort
+      });
+      const hasAnyValue = extractedValues.apiKey || extractedValues.username || extractedValues.password || extractedValues.s1cUrl || extractedValues.managementHost || extractedValues.cloudInfraToken;
+      if (!hasAnyValue) {
+        console.error("[Settings.fromHeaders] Verbose: WARNING - No authentication values found in headers");
+        console.error("[Settings.fromHeaders] Verbose: Full headers object (sanitized):", Object.fromEntries(Object.entries(headers).map(([k, v]) => [k, k.toLowerCase().includes("key") || k.toLowerCase().includes("token") || k.toLowerCase().includes("password") ? "***" : v])));
+      }
+    }
+    return new _Settings({
+      apiKey: extractedValues.apiKey,
+      username: extractedValues.username,
+      password: extractedValues.password,
+      s1cUrl: extractedValues.s1cUrl,
+      managementHost: extractedValues.managementHost,
+      managementPort: extractedValues.managementPort,
+      cloudInfraToken: extractedValues.cloudInfraToken,
+      clientId: extractedValues.clientId,
+      secretKey: extractedValues.secretKey,
+      region: extractedValues.region?.toUpperCase(),
+      devPort: extractedValues.devPort,
+      gatewayUrl: extractedValues.gatewayUrl
     });
   }
 };
@@ -1579,16 +1942,32 @@ var DocumentationToolAPIManager = class _DocumentationToolAPIManager {
 // src/settings.ts
 var DocumentationToolSettings = class _DocumentationToolSettings extends Settings {
   constructor(args = {}) {
-    super(args);
+    super({
+      ...args,
+      gatewayUrl: args.authUrl || args.gatewayUrl
+    });
   }
   /**
    * Create DocumentationToolSettings from command-line arguments for Documentation Tool
    */
   static fromArgs(args) {
+    if (!args.authUrl && !args.region) {
+      throw new Error(
+        "Provide either --auth-url (Authentication URL from the API key creation dialog) or --region (EU, US, STG, or LOCAL)"
+      );
+    }
     return new _DocumentationToolSettings({
       ...args
     });
   }
+  static fromHeaders(headers) {
+    return new _DocumentationToolSettings({
+      clientId: getHeaderValue(headers, "CLIENT-ID"),
+      secretKey: getHeaderValue(headers, "SECRET-KEY"),
+      region: getHeaderValue(headers, "REGION"),
+      authUrl: getHeaderValue(headers, "AUTH-URL")
+    });
+  }
 };
 
 // src/index.ts

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chkp/documentation-mcp",
-  "version": "1.1.0",
+  "version": "1.4.0",
   "description": "Check Point Documentation Tool Service - API integration with Check Point Documentation Tool",
   "type": "module",
   "main": "dist/index.js",
@@ -26,8 +26,8 @@
     "start": "node dist/index.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.11.1",
-    "axios": "^1.12.1",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "axios": "^1.13.5",
     "commander": "^13.1.0",
     "node-machine-id": "^1.1.12",
     "zod": "^3.22.4"

package/dist/server-config.json

@@ -7,20 +7,33 @@
       "description": "Client ID for authentication with Documentation Tool",
       "env": "CLIENT_ID",
       "required": true,
-      "type": "string"
+      "type": "string",
+      "help": "Client ID for Check Point Documentation Tool authentication. To obtain: log in to the Infinity Portal → API Keys → New → New User API Key → copy the generated Client ID"
     },
     {
       "flag": "--secret-key <secret-key>",
       "description": "Secret Key for authentication with Documentation Tool",
       "env": "SECRET_KEY",
       "required": true,
-      "type": "string"
+      "type": "string",
+      "help": "Secret Key for Check Point Documentation Tool authentication. Generated alongside the Client ID — copy and store it securely at creation time as it will not be shown again"
+    },
+    {
+      "flag": "--auth-url <url>",
+      "description": "Authentication URL from the API key creation dialog",
+      "env": "AUTH_URL",
+      "required": true,
+      "type": "string",
+      "help": "Paste the Authentication URL shown when creating your API key (e.g. https://cloudinfra-gw.portal.checkpoint.com/auth/external). The path suffix is stripped automatically so you can copy it directly from the portal"
     },
     {
       "flag": "--region <region>",
-      "description": "Documentation Tool region: EU, US, STG, or Local",
+      "description": "Documentation Tool region: EU, US, STG, or LOCAL",
       "env": "REGION",
-      "type": "string"
+      "required": false,
+      "hidden": true,
+      "type": "string",
+      "help": "Alternative to --auth-url. Region code for your deployment: EU, US, STG, or LOCAL. Use this if you know your region and prefer not to copy the full authentication URL"
     }
   ]
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chkp/documentation-mcp",
-  "version": "1.1.0",
+  "version": "1.4.0",
   "description": "Check Point Documentation Tool Service - API integration with Check Point Documentation Tool",
   "type": "module",
   "main": "dist/index.js",
@@ -26,9 +26,9 @@
     "start": "node dist/index.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.4",
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "commander": "^13.1.0",
-    "axios": "^1.12.1",
+    "axios": "^1.13.5",
     "node-machine-id": "^1.1.12",
     "zod": "^3.24.4"
   },