@egain/egain-mcp-server 1.0.26 → 1.1.0

package/src/funcs/{queryRetrieve.ts → retrieveChunks.ts}

@@ -22,9 +22,11 @@ import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
 import {
   RetrieveChunksRequest,
   RetrieveChunksRequest$zodSchema,
-  RetrieveChunksResponse,
-  RetrieveChunksResponse$zodSchema,
 } from "../models/retrievechunksop.js";
+import {
+  RetrieveResponse,
+  RetrieveResponse$zodSchema,
+} from "../models/retrieveresponse.js";
 import { APICall, APIPromise } from "../types/async.js";
 import { Result } from "../types/fp.js";
 
@@ -33,25 +35,58 @@ import { Result } from "../types/fp.js";
  *
  * @remarks
  * Retrieve Chunks
+ * ## Overview
+ * The Retrieve API enables enterprises to directly access relevant content chunks from their organizational knowledge sources. It is designed for scenarios where developers want granular control over retrieved information, such as powering custom search, analytics, or retrieval-augmented generation (RAG) pipelines.
+ * In addition to raw chunk retrieval, the API can return **Certified Answers** if it meets the 'Certified Answer' threshold score. Responses include relevance scores, metadata, and references to maintain transparency and flexibility.
+ * By leveraging the Retrieve API, organizations can build tailored experiences while retaining confidence in the source material.
  *
  * ## Prerequisites
- * - **Requires a valid portal ID** (required parameter). If you don't have the portal ID, first call 'get-portals' to get available portals.
- * - Portal ID format: 2-4 letter prefix + dash + 4-15 digits (e.g., "EB-123456789")
+ * - Requires a valid portal ID. If you don't have the portal ID, first call 'get-portals' to get available portals.
+ * - Portal ID format: 2-4 letter prefix + dash + 4-15 digits (e.g., "PROD-1004")
  *
- * ## Overview
- * The Retrieve API enables enterprises to directly access relevant content chunks from their organizational knowledge sources. It is designed for scenarios where developers want granular control over retrieved information, such as powering custom search, analytics, or retrieval-augmented generation (RAG) pipelines.
+ * ## How to Use This Tool
+ * All inputs must be wrapped inside a request object. Provide a search query and language. Optional filters can be used to narrow results by tags, topics, or user profile.
  *
- * In addition to raw chunk retrieval, the API can return **Certified Answers** if it meets the 'Certified Answer' threshold score. Responses include relevance scores, metadata, and references to maintain transparency and flexibility.
+ * **Parameter Format**:
+ * - Always wrap parameters in a `request` object: `{"request": {"portalID": "PZ-9999", "q": "loan information", "Dollar_lang": "en-US"}}`
+ * - Required parameters:
+ *   - `portalID` (string) - The portal ID (format: 2-4 letter prefix + dash + 4-15 digits, e.g., "PZ-9999")
+ *   - `q` (string) - The search query string
+ *   - `Dollar_lang` (string) - Language code (e.g., "en-US")
+ * - Optional parameters:
+ *   - `dollarFilterUserProfileID` (string) - User profile ID filter
+ *   - `dollarFilterTags` (object) - Object where keys are Category Tag IDs and values are arrays of Tag IDs
+ *   - `dollarFilterTopicIds` (array) - Array of topic IDs to filter by
+ *   - `RetrieveRequest` (object) - Additional request body parameters:
+ *     - `channel` (object) - Channel information (optional, recommended to omit)
+ *     - `eventId` (string) - Event ID
+ *     - `sessionId` (string) - Session ID
  *
- * By leveraging the Retrieve API, organizations can build tailored experiences while retaining confidence in the source material.
+ * **Example**: To retrieve chunks for query "loan information" from portal "PZ-9999", call with:
+ * ```json
+ * {"request": {"portalID": "PZ-9999", "q": "loan information", "Dollar_lang": "en-US"}}
+ * ```
+ *
+ * **Example with RetrieveRequest body**:
+ * ```json
+ * {"request": {"portalID": "PZ-9999", "q": "loan information", "Dollar_lang": "en-US", "RetrieveRequest": {"eventId": "event-123", "sessionId": "session-456"}}}
+ * ```
+ *
+ * ## Displaying Results (MCP-Specific)
+ * **CRITICAL**: When this tool returns data successfully, you MUST display the results to the user in your response. Do not silently process the data - always show the user what was returned.
+ *
+ * **What to display:**
+ * Always display results. Show each article name, article ID, snippet, and relevance score. If a certified answer is returned, display it first and list its references.
+ *
+ * **Example**: "I found 5 relevant articles about loan information: 1) [Article Name] (ID: PROD-123) - [snippet]..."
  */
-export function queryRetrieve(
+export function retrieveChunks(
   client$: EgainMcpCore,
   request: RetrieveChunksRequest,
   options?: RequestOptions,
 ): APIPromise<
   Result<
-    RetrieveChunksResponse,
+    RetrieveResponse,
     | APIError
     | SDKValidationError
     | UnexpectedClientError
@@ -75,7 +110,7 @@ async function $do(
 ): Promise<
   [
     Result<
-      RetrieveChunksResponse,
+      RetrieveResponse,
       | APIError
       | SDKValidationError
       | UnexpectedClientError
@@ -173,7 +208,7 @@ async function $do(
   };
 
   const [result$] = await M.match<
-    RetrieveChunksResponse,
+    RetrieveResponse,
     | APIError
     | SDKValidationError
     | UnexpectedClientError
@@ -182,9 +217,9 @@ async function $do(
     | RequestTimeoutError
     | ConnectionError
   >(
-    M.json(200, RetrieveChunksResponse$zodSchema, { key: "RetrieveResponse" }),
-    M.nil(400, RetrieveChunksResponse$zodSchema),
-    M.nil(500, RetrieveChunksResponse$zodSchema),
+    M.json(200, RetrieveResponse$zodSchema, { key: "RetrieveResponse" }),
+    M.nil(400, RetrieveResponse$zodSchema),
+    M.nil(500, RetrieveResponse$zodSchema),
   )(response, req$, { extraFields: responseFields$ });
 
   return [result$, { status: "complete", request: req$, response }];

package/src/hooks/auth-hook.ts

@@ -73,7 +73,6 @@ export class AuthenticationHook implements SDKInitHook, BeforeRequestHook {
   private authConfig: AuthConfig;
   private codeVerifier: string;
   private codeChallenge: string;
-  private portalCacheHook?: any; // PortalCacheHook reference
   private configServer: http.Server | null = null; // HTTP server for configuration form
   private detectedBrowser: string = 'Google Chrome'; // Default fallback
   private authCancelled: boolean = false; // Track if user cancelled authentication
@@ -111,8 +110,7 @@ export class AuthenticationHook implements SDKInitHook, BeforeRequestHook {
     };
   }
 
-  constructor(portalCacheHook?: any) {
-    this.portalCacheHook = portalCacheHook;
+  constructor() {
     this.authConfig = this.loadAuthConfig();
     
     // Generate secure PKCE values instead of using hardcoded ones
@@ -1179,18 +1177,6 @@ export class AuthenticationHook implements SDKInitHook, BeforeRequestHook {
                 
                 this.token = accessToken;
                 
-                // Trigger cache initialization if available
-                if (this.portalCacheHook) {
-                  try {
-                    const fakeRequest = new Request(this.authConfig.environmentUrl!, {
-                      headers: { 'Authorization': `Bearer ${accessToken}` }
-                    });
-                    await this.portalCacheHook.ensureCacheInitialized(fakeRequest);
-                  } catch (error) {
-                    // Cache init failure is non-fatal
-                  }
-                }
-                
                 console.error('🎉 Authentication complete! Stopping config server...');
                 
                 // Close browser window on Windows (macOS handles this via AppleScript in monitoring)
@@ -1669,17 +1655,7 @@ export class AuthenticationHook implements SDKInitHook, BeforeRequestHook {
         // If code is 'code-received', token was already set by callback handler
         if (code === 'code-received') {
           // Token already set, just ensure cache is initialized
-          if (this.portalCacheHook && this.token) {
-            try {
-              const fakeRequest = new Request(this.authConfig.environmentUrl!, {
-                headers: { 'Authorization': `Bearer ${this.token}` }
-              });
-              await this.portalCacheHook.ensureCacheInitialized(fakeRequest);
-              console.error('✅ Cache initialization completed');
-            } catch (error) {
-              console.error('⚠️  Cache initialization failed:', error);
-            }
-          }
+          
           console.error('🎉 Authentication complete! Stopping config server...');
           this.stopConfigServer();
           return; // Success - exit
@@ -1690,19 +1666,7 @@ export class AuthenticationHook implements SDKInitHook, BeforeRequestHook {
         console.error('✅ Access token received');
         
         this.token = accessToken;
-        
-        // Trigger cache initialization if available
-        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('🎉 Authentication complete! Stopping config server...');
         this.stopConfigServer();
@@ -1901,18 +1865,6 @@ export class AuthenticationHook implements SDKInitHook, BeforeRequestHook {
             
             this.token = accessToken;
             
-            // Trigger cache initialization if available
-            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('🎉 Authentication complete! Stopping config server...');
             this.stopConfigServer();
@@ -2273,18 +2225,6 @@ export class AuthenticationHook implements SDKInitHook, BeforeRequestHook {
           console.error('🎉 Using existing valid bearer token (lazy mode)');
           this.token = existingToken;
           
-          // Trigger cache initialization with existing token
-          if (this.portalCacheHook) {
-            try {
-              const fakeRequest = new Request(this.authConfig.environmentUrl || 'https://api-dev9.knowledge.ai/knowledge', {
-                headers: { 'Authorization': `Bearer ${existingToken}` }
-              });
-              await this.portalCacheHook.ensureCacheInitialized(fakeRequest);
-            } catch (error) {
-              // Cache init failure is non-fatal
-            }
-          }
-          
           return this.token;
         }
       } else {

package/src/hooks/registration.ts

@@ -1,7 +1,5 @@
 import { Hooks } from "./types.js";
 import { AuthenticationHook } from "./auth-hook.js";
-import { PortalCacheHook } from "./portal-cache-hook.js";
-import { PortalLookupHook } from "./portal-lookup-hook.js";
 import { ServerRoutingHook } from "./server-routing-hook.js";
 import { VersionCheckHook } from "./version-check-hook.js";
 
@@ -25,26 +23,13 @@ export function initHooks(hooks: Hooks) {
   const serverRoutingHook = new ServerRoutingHook();
   hooks.registerBeforeCreateRequestHook(serverRoutingHook);
   console.error('✅ ROUTING: Registered server routing hook for before create request');
-  
-  // 2. Portal Cache Hook - caches portal names/IDs after authentication
-  // Create this so we can pass it to the auth hook
-  const portalCacheHook = new PortalCacheHook();
-  hooks.registerSDKInitHook(portalCacheHook); // Handles full initialization
-  hooks.registerBeforeCreateRequestHook(portalCacheHook); // Synchronous readiness check only
-  console.error('✅ CACHE: Registered portal cache hook for SDK init and before create request');
 
-  // 3. Authentication Hook - handles login popup and token management
-  // Pass portal cache hook reference so it can trigger cache initialization after auth
-  const authHook = new AuthenticationHook(portalCacheHook);
+
+  // 2. Authentication Hook - handles login popup and token management
+  const authHook = new AuthenticationHook();
   hooks.registerSDKInitHook(authHook);
   hooks.registerBeforeRequestHook(authHook); // Register for automatic token refresh
   console.error('✅ AUTH: Registered authentication hook for SDK init and before request');
 
-  // 4. Portal Lookup Hook - translates portal names to IDs in requests
-  // Now synchronous since cache is guaranteed ready after SDKInit
-  const portalLookupHook = new PortalLookupHook(portalCacheHook);
-  hooks.registerBeforeRequestHook(portalLookupHook); // Should be mostly synchronous now
-  console.error('✅ LOOKUP: Registered portal lookup hook for before request');
-
   console.error('🎉 All eGain MCP hooks registered successfully!');
 }