@egain/egain-mcp-server 1.0.6 → 1.0.12

package/README.md

@@ -23,6 +23,7 @@ Learn more about the tools and usage of the MCP in the [eGain MCP guide](https:/
 <!-- No Table of Contents [toc] -->
 
 ### Prerequisites  
+- **Node.js version 20+** - Required for running the MCP server. Download from [nodejs.org](https://nodejs.org/)
 - eGain platform version 21.22 or newer.
 - Access mirrors the user's permissions: MCP only sees content that user can see (portal/article visibility).
 - AI Services must be enabled for your tenant and the target portal, or AI tools will not run.
@@ -116,6 +117,27 @@ You'll need to enter your authentication configuration values in the browser for
 - **Configuration problems?** → [FAQ: Configuration Issues](./help/faq.md#configuration-issues)
 - **Tool/Query problems?** → [FAQ: MCP Tool Issues](./help/faq.md#mcp-tool-issues)
 
+### Token Issues (Expired/Stuck Tokens)
+
+If you're experiencing issues with expired tokens or authentication failures:
+
+When using `npx`, token files (`.bearer_token` and `.bearer_token_metadata`) are stored in the directory where you run `npx` from (or where `package.json` exists). To find them:
+
+```bash
+# Search your home directory
+find ~ -name ".bearer_token" -o -name ".bearer_token_metadata" 2>/dev/null
+
+# Or search from your current directory
+find . -name ".bearer_token" -o -name ".bearer_token_metadata" 2>/dev/null
+```
+
+Once found, delete them:
+```bash
+rm /path/to/.bearer_token
+rm /path/to/.bearer_token_metadata
+```
+This will search common locations and show you exactly where your token files are.
+
 ### Common Setup Hurdles
 - **Can't find API Domain?** → [FAQ: Finding API Domain](./help/faq.md#q-i-cant-find-my-api-domain-or-scope-prefix-where-is-it)
 - **Browser didn't open?** → [FAQ: No auth popup](./help/faq.md#no-auth-popup-appears)

package/bin/mcp-server.js

@@ -4046,9 +4046,9 @@ var init_config = __esm(() => {
   SDK_METADATA = {
     language: "typescript",
     openapiDocVersion: "1.0.0",
-    sdkVersion: "1.0.6",
+    sdkVersion: "1.0.12",
     genVersion: "2.723.8",
-    userAgent: "speakeasy-sdk/mcp-typescript 1.0.6 2.723.8 1.0.0 @egain/egain-mcp-server"
+    userAgent: "speakeasy-sdk/mcp-typescript 1.0.12 2.723.8 1.0.0 @egain/egain-mcp-server"
   };
 });
 
@@ -40991,119 +40991,6 @@ class AuthenticationHook {
     const fullUrl = `${baseUrl}?${existingParams.toString()}`;
     return fullUrl;
   }
-  async monitorBrowserForAuthCode() {
-    const platform = process.platform;
-    const timeout = 120;
-    const startTime = Date.now();
-    if (platform === "darwin") {
-      console.error(`\uD83D\uDD0D Monitoring ${this.detectedBrowser} for authorization code...`);
-      let lastUrl = "";
-      while (Date.now() - startTime < timeout * 1000) {
-        try {
-          const script = `
-            tell application "${this.detectedBrowser}"
-              try
-                set currentURL to URL of active tab of front window
-                return currentURL
-              on error
-                return ""
-              end try
-            end tell
-          `;
-          const { stdout } = await execAsync(`osascript -e '${script}'`);
-          const currentUrl = stdout.trim();
-          if (currentUrl && currentUrl !== lastUrl) {
-            lastUrl = currentUrl;
-            console.error(`\uD83D\uDD0D Current URL: ${currentUrl}`);
-          }
-          if (currentUrl && currentUrl.includes("code=")) {
-            console.error("✅ Found authorization code in URL!");
-            const codeMatch = currentUrl.match(/[?&]code=([^&]+)/);
-            if (codeMatch && codeMatch[1]) {
-              const code = decodeURIComponent(codeMatch[1]);
-              console.error(`\uD83D\uDD11 Extracted authorization code (first 20 chars): ${code.substring(0, 20)}...`);
-              console.error(`   Code length: ${code.length} characters`);
-              setImmediate(async () => {
-                try {
-                  await execAsync(`osascript -e 'tell application "${this.detectedBrowser}" to close front window'`);
-                  console.error("✅ Browser window closed");
-                } catch (closeError) {
-                  console.error("⚠️  Could not close browser window:", closeError);
-                }
-              });
-              return code;
-            }
-          }
-          if (currentUrl && currentUrl.includes("error=")) {
-            const errorMatch = currentUrl.match(/[?&]error=([^&]+)/);
-            const errorDescMatch = currentUrl.match(/error_description=([^&]+)/);
-            const error = errorMatch && errorMatch[1] ? decodeURIComponent(errorMatch[1]) : "unknown_error";
-            const errorDesc = errorDescMatch && errorDescMatch[1] ? decodeURIComponent(errorDescMatch[1]) : "No description";
-            throw new Error(`OAuth error: ${error} - ${errorDesc}`);
-          }
-        } catch (error) {
-          if (error instanceof Error && error.message.includes("OAuth error:")) {
-            throw error;
-          }
-        }
-        await new Promise((resolve) => setTimeout(resolve, 500));
-      }
-      throw new Error("Authentication timeout. Please try again.");
-    } else if (platform === "win32") {
-      console.error(`\uD83D\uDD0D Monitoring ${this.detectedBrowser} for authorization code...`);
-      let lastTitle = "";
-      while (Date.now() - startTime < timeout * 1000) {
-        try {
-          const browserProcessName = this.detectedBrowser.replace(".exe", "");
-          const psScript = `
-            $process = Get-Process -Name "${browserProcessName}" -ErrorAction SilentlyContinue | 
-              Where-Object { $_.MainWindowHandle -ne 0 } | 
-              Select-Object -First 1
-            if ($process) {
-              $process.MainWindowTitle
-            }
-          `.replace(/\n\s+/g, " ");
-          const { stdout } = await execAsync(`powershell -Command "${psScript}"`);
-          const windowTitle = stdout.trim();
-          if (windowTitle && windowTitle !== lastTitle) {
-            lastTitle = windowTitle;
-            console.error(`\uD83D\uDD0D Browser window: ${windowTitle.substring(0, 100)}...`);
-            if (windowTitle.includes("code=") || windowTitle.includes("localhost:3333")) {
-              console.error("✅ Detected OAuth callback!");
-              const codeMatch = windowTitle.match(/code=([^&\s]+)/);
-              if (codeMatch && codeMatch[1]) {
-                const code = decodeURIComponent(codeMatch[1]);
-                console.error(`\uD83D\uDD11 Extracted authorization code (first 20 chars): ${code.substring(0, 20)}...`);
-                console.error(`   Code length: ${code.length} characters`);
-                setImmediate(async () => {
-                  try {
-                    await execAsync(`powershell -Command "Stop-Process -Name '${browserProcessName}' -Force"`);
-                    console.error("✅ Browser window closed");
-                  } catch (closeError) {
-                    console.error("⚠️  Could not close browser window:", closeError);
-                  }
-                });
-                return code;
-              }
-            }
-            if (windowTitle.includes("error=")) {
-              const errorMatch = windowTitle.match(/error=([^&\s]+)/);
-              const error = errorMatch && errorMatch[1] ? decodeURIComponent(errorMatch[1]) : "unknown_error";
-              throw new Error(`OAuth error: ${error}`);
-            }
-          }
-        } catch (error) {
-          if (error instanceof Error && error.message.includes("OAuth error:")) {
-            throw error;
-          }
-        }
-        await new Promise((resolve) => setTimeout(resolve, 500));
-      }
-      throw new Error("Authentication timeout. The browser window title did not show the authorization code. Please ensure your redirect URL is http://localhost:3333/callback for automatic detection on Windows.");
-    } else {
-      throw new Error("Linux is not supported. Use macOS or Windows for automatic authentication.");
-    }
-  }
   async getUserAccessToken(code) {
     const { clientId, clientSecret, redirectUri, accessUrl } = this.authConfig;
     console.error("\uD83D\uDD04 Starting token exchange...");
@@ -41237,6 +41124,21 @@ class AuthenticationHook {
           return true;
         } else {
           console.error(`⏰ AUTH: Token expires in ${Math.round(timeUntilExpiry / 1000)} seconds - treating as expired`);
+          const projectRoot2 = getProjectRoot();
+          const tokenPath = path.join(projectRoot2, ".bearer_token");
+          try {
+            if (fs.existsSync(tokenPath)) {
+              fs.unlinkSync(tokenPath);
+              console.error("\uD83D\uDDD1️  Deleted expired bearer token file");
+            }
+            if (fs.existsSync(metadataPath)) {
+              fs.unlinkSync(metadataPath);
+              console.error("\uD83D\uDDD1️  Deleted expired bearer token metadata file");
+            }
+          } catch (error) {
+            console.error("⚠️  Failed to delete expired token files:", error);
+          }
+          this.token = null;
           return false;
         }
       }
@@ -41255,9 +41157,17 @@ class AuthenticationHook {
           console.error(`\uD83D\uDD11 Found existing bearer token at: ${tokenPath}`);
           return token;
         }
+      } else {
+        if (this.token) {
+          console.error("\uD83D\uDDD1️  Token file deleted, clearing in-memory token");
+          this.token = null;
+        }
       }
     } catch (error) {
       console.error("Could not load existing token:", error);
+      if (this.token) {
+        this.token = null;
+      }
     }
     return null;
   }
@@ -41362,26 +41272,7 @@ class AuthenticationHook {
             }));
             console.error("\uD83D\uDD0D Starting browser URL monitoring for authorization code...");
             setImmediate(async () => {
-              try {
-                const code = await this.monitorBrowserForAuthCode();
-                console.error("✅ Authorization code detected:", code.substring(0, 10) + "...");
-                const accessToken = await this.getUserAccessToken(code);
-                console.error("✅ Access token received");
-                this.token = accessToken;
-                if (this.portalCacheHook) {
-                  try {
-                    const fakeRequest = new Request(this.authConfig.environmentUrl, {
-                      headers: { Authorization: `Bearer ${accessToken}` }
-                    });
-                    await this.portalCacheHook.ensureCacheInitialized(fakeRequest);
-                  } catch (error) {}
-                }
-                console.error("\uD83C\uDF89 Authentication complete! Stopping config server...");
-                this.stopConfigServer();
-              } catch (authError) {
-                console.error("❌ Authentication monitoring error:", authError);
-                this.stopConfigServer();
-              }
+              await this.monitorBrowserWithRetry();
             });
           } catch (error) {
             res.writeHead(500, { "Content-Type": "application/json" });
@@ -41459,30 +41350,7 @@ class AuthenticationHook {
               }));
               console.error("\uD83D\uDD0D Starting browser URL monitoring for authorization code...");
               setImmediate(async () => {
-                try {
-                  const code = await this.monitorBrowserForAuthCode();
-                  console.error("✅ Authorization code detected:", code.substring(0, 10) + "...");
-                  const accessToken = await this.getUserAccessToken(code);
-                  console.error("✅ Access token received");
-                  this.token = accessToken;
-                  if (this.portalCacheHook) {
-                    console.error("\uD83D\uDD04 Triggering cache initialization...");
-                    try {
-                      const fakeRequest = new Request(this.authConfig.environmentUrl, {
-                        headers: { Authorization: `Bearer ${accessToken}` }
-                      });
-                      await this.portalCacheHook.ensureCacheInitialized(fakeRequest);
-                      console.error("✅ Cache initialization completed");
-                    } catch (error) {
-                      console.error("⚠️  Cache initialization failed:", error);
-                    }
-                  }
-                  console.error("\uD83C\uDF89 Authentication complete! Stopping config server...");
-                  this.stopConfigServer();
-                } catch (authError) {
-                  console.error("❌ Authentication monitoring error:", authError);
-                  this.stopConfigServer();
-                }
+                await this.monitorBrowserWithRetry();
               });
             } catch (error) {
               console.error("❌ Error processing authentication request:", error);
@@ -41539,8 +41407,14 @@ class AuthenticationHook {
                 console.error("\uD83C\uDF89 Authentication complete! Stopping config server...");
                 this.stopConfigServer();
               } catch (authError) {
-                console.error("❌ Token exchange error:", authError);
-                this.stopConfigServer();
+                const isOAuthError = authError instanceof Error && authError.message.includes("OAuth error:");
+                if (isOAuthError) {
+                  console.error("❌ OAuth authentication error:", authError.message);
+                  console.error("\uD83D\uDCA1 The configuration server will remain running. Please try again with correct credentials.");
+                } else {
+                  console.error("❌ Token exchange error:", authError);
+                  this.stopConfigServer();
+                }
               }
             });
             res.writeHead(200, { "Content-Type": "text/html" });
@@ -41607,6 +41481,120 @@ class AuthenticationHook {
       });
     });
   }
+  async monitorBrowserWithRetry() {
+    const platform = process.platform;
+    const timeout = 120;
+    const startTime = Date.now();
+    let oAuthErrorLogged = false;
+    let lastUrl = "";
+    let lastErrorUrl = null;
+    if (platform === "darwin") {
+      console.error(`\uD83D\uDD0D Monitoring ${this.detectedBrowser} for authorization code...`);
+    } else if (platform === "win32") {
+      console.error(`\uD83D\uDD0D Monitoring ${this.detectedBrowser} for authorization code...`);
+    }
+    while (true) {
+      try {
+        if (Date.now() - startTime >= timeout * 1000) {
+          throw new Error("Authentication timeout. Please try again.");
+        }
+        let currentUrl = "";
+        if (platform === "darwin") {
+          const script = `
+            tell application "${this.detectedBrowser}"
+              try
+                set currentURL to URL of active tab of front window
+                return currentURL
+              on error
+                return ""
+              end try
+            end tell
+          `;
+          const { stdout } = await execAsync(`osascript -e '${script}'`);
+          currentUrl = stdout.trim();
+        } else if (platform === "win32") {
+          const browserProcessName = this.detectedBrowser.replace(".exe", "");
+          const psScript = `
+            $process = Get-Process -Name "${browserProcessName}" -ErrorAction SilentlyContinue | 
+              Where-Object { $_.MainWindowHandle -ne 0 } | 
+              Select-Object -First 1
+            if ($process) {
+              $process.MainWindowTitle
+            }
+          `.replace(/\n\s+/g, " ");
+          const { stdout } = await execAsync(`powershell -Command "${psScript}"`);
+          currentUrl = stdout.trim();
+        }
+        if (currentUrl && currentUrl !== lastUrl) {
+          lastUrl = currentUrl;
+          console.error(`\uD83D\uDD0D Current URL: ${currentUrl}`);
+        }
+        if (currentUrl && currentUrl.includes("code=")) {
+          const codeMatch = currentUrl.match(/[?&]code=([^&]+)/);
+          if (codeMatch && codeMatch[1]) {
+            const code = decodeURIComponent(codeMatch[1]);
+            console.error("✅ Found authorization code in URL!");
+            console.error(`\uD83D\uDD11 Extracted authorization code (first 20 chars): ${code.substring(0, 20)}...`);
+            setImmediate(async () => {
+              try {
+                if (platform === "darwin") {
+                  await execAsync(`osascript -e 'tell application "${this.detectedBrowser}" to close front window'`);
+                } else if (platform === "win32") {
+                  const browserProcessName = this.detectedBrowser.replace(".exe", "");
+                  await execAsync(`powershell -Command "Stop-Process -Name '${browserProcessName}' -Force"`);
+                }
+              } catch (closeError) {}
+            });
+            console.error("✅ Authorization code detected:", code.substring(0, 10) + "...");
+            const accessToken = await this.getUserAccessToken(code);
+            console.error("✅ Access token received");
+            this.token = accessToken;
+            if (this.portalCacheHook) {
+              try {
+                const fakeRequest = new Request(this.authConfig.environmentUrl, {
+                  headers: { Authorization: `Bearer ${accessToken}` }
+                });
+                await this.portalCacheHook.ensureCacheInitialized(fakeRequest);
+                console.error("✅ Cache initialization completed");
+              } catch (error) {
+                console.error("⚠️  Cache initialization failed:", error);
+              }
+            }
+            console.error("\uD83C\uDF89 Authentication complete! Stopping config server...");
+            this.stopConfigServer();
+            return;
+          }
+        }
+        if (currentUrl && currentUrl.includes("error=")) {
+          if (currentUrl !== lastErrorUrl) {
+            lastErrorUrl = currentUrl;
+            const errorMatch = currentUrl.match(/[?&]error=([^&]+)/);
+            const errorDescMatch = currentUrl.match(/error_description=([^&]+)/);
+            const error = errorMatch && errorMatch[1] ? decodeURIComponent(errorMatch[1]) : "unknown_error";
+            const errorDesc = errorDescMatch && errorDescMatch[1] ? decodeURIComponent(errorDescMatch[1]) : "No description";
+            if (!oAuthErrorLogged) {
+              console.error("❌ OAuth authentication error:", `${error} - ${errorDesc}`);
+              console.error("\uD83D\uDCA1 The configuration server will remain running. Please try again with correct credentials.");
+              console.error("\uD83D\uDD0D Continuing to monitor browser for authorization code...");
+              oAuthErrorLogged = true;
+            }
+          }
+        } else {
+          if (lastErrorUrl !== null) {
+            lastErrorUrl = null;
+            oAuthErrorLogged = false;
+          }
+        }
+        await new Promise((resolve) => setTimeout(resolve, 500));
+      } catch (error) {
+        if (!(error instanceof Error && error.message.includes("OAuth error:"))) {
+          console.error("❌ Authentication monitoring error:", error);
+          this.stopConfigServer();
+          return;
+        }
+      }
+    }
+  }
   stopConfigServer() {
     if (this.configServer) {
       console.error("\uD83D\uDEAA Stopping configuration server...");
@@ -41742,6 +41730,7 @@ class AuthenticationHook {
         }
       } else {
         console.error("⏰ Existing token is expired or not found, proceeding with fresh login...");
+        this.token = null;
       }
       const hasConfig = this.authConfig.environmentUrl && this.authConfig.clientId && this.authConfig.redirectUri && this.authConfig.authUrl && this.authConfig.accessUrl;
       if (!hasConfig) {
@@ -46810,14 +46799,55 @@ var init_getPortals2 = __esm(() => {
     name: "get-portals",
     description: `Get All Portals Accessible To User
 
+Get All Portals Accessible to User
+
 ## Overview
-  The Get All Portals Accessible to User API allows a user to fetch all portals accessible to user across all department.
-  * If no access tags are specified for a portal, then any user can access the portal.
-  * If access tags are specified for a portal, users with a user profile that allows access have access to the portal. For users with multiple user profiles, the user profile that allows access does not need to be the active user profile.
-  * All the global users(partition) cannot be assigned user profiles; their access is limited to portals without access restrictions.
-  * The only articles returned are associated to an Article type when the parameter, “Include in browse on portals” is set to "Yes".
-  * When the "shortUrlTemplate" query parameter is provided, the API filters accessible portals according to the specified language and template name. Portal Short URL specific to to the "shortUrlTemplate" query parameter value is returned in the response.
-  * When there is no short URL available for a specific language, the API returns a portal object with an empty "shortURL" field.
+The Get All Portals Accessible to User API allows a user to fetch all portals accessible to the user across all departments.
+- If no access tags are specified for a portal, any user can access the portal.
+- If access tags are specified for a portal, users with a user profile that allows access can access the portal. For users with multiple user profiles, the user profile that allows access does not need to be the active user profile.
+- Global users (partition) cannot be assigned user profiles; their access is limited to portals without access restrictions.
+- The only articles returned are associated to an Article type when the parameter “Include in browse on portals” is set to "Yes".
+- When the \`shortUrlTemplate\` query parameter is provided, the API filters accessible portals according to the specified language and template name. A portal short URL specific to the \`shortUrlTemplate\` value is returned in the response when available. If there is no short URL for a language, the portal object returns an empty \`shortURL\` field.
+
+## Pagination behavior (CRITICAL for AI assistants)
+
+**IMPORTANT**: This endpoint is paginated. When searching for a portal by name or listing portals, you MUST automatically fetch ALL pages before concluding that a portal doesn't exist.
+
+### Automatic pagination is REQUIRED when:
+- User asks to find a portal by name (e.g., "business portal", "Master portal")
+- User requests to list or see all portals
+- You need to resolve a natural portal name to its ID
+
+### How to detect more pages exist:
+The response includes \`paginationInfo\` with:
+- \`count\`: Total number of items across all pages
+- \`pagenum\`: Current page number
+- \`pagesize\`: Items per page (default: 25)
+
+**Check for more pages if ANY of these are true:**
+1. The number of portals returned equals \`pagesize\` (e.g., exactly 25 portals returned)
+2. \`paginationInfo.count > (pagenum * pagesize)\` - there are more items beyond this page
+3. The response includes a \`link\` array with a \`next\` relation
+
+### Required pagination workflow:
+1. Start with \`$pagenum=1\` and \`$pagesize=25\` (default)
+2. After receiving the response, check \`paginationInfo\`
+3. **If more pages exist** (using the checks above), automatically call this endpoint again with \`$pagenum=2\`, then \`$pagenum=3\`, etc.
+4. Continue incrementing \`$pagenum\` until:
+   - A page returns fewer portals than \`pagesize\` (indicating the last page)
+   - A page returns zero portals
+   - \`pagenum * pagesize >= paginationInfo.count\` (if count represents total items)
+5. Merge all portals from all pages by unique portal ID
+6. Only then search through the complete merged list or report results to the user
+
+### Example scenario:
+If you search for "business portal" and the first page returns 25 portals but none match:
+- DO NOT immediately tell the user the portal doesn't exist
+- Check \`paginationInfo.count\` - if it's > 25, automatically fetch page 2
+- Continue fetching until all pages are retrieved
+- Search the complete merged list before concluding the portal doesn't exist
+
+This ensures reliable portal name-to-ID resolution and prevents false "not found" errors.
 `,
     annotations: {
       destructiveHint: false,
@@ -47817,7 +47847,7 @@ The Search API is a hybrid search service that combines semantic understanding w
 function createMCPServer(deps) {
   const server = new McpServer({
     name: "EgainMcp",
-    version: "1.0.6"
+    version: "1.0.12"
   });
   const getClient = deps.getSDK || (() => new EgainMcpCore({
     security: deps.security,
@@ -49064,7 +49094,7 @@ var routes = ln({
 var app = _e(routes, {
   name: "mcp",
   versionInfo: {
-    currentVersion: "1.0.6"
+    currentVersion: "1.0.12"
   }
 });
 Yt(app, process3.argv.slice(2), buildContext(process3));
@@ -49072,5 +49102,5 @@ export {
   app
 };
 
-//# debugId=3CD281DB81F8829C64756E2164756E21
+//# debugId=4532247C421ADCA364756E2164756E21
 //# sourceMappingURL=mcp-server.js.map