@egain/egain-mcp-server 1.0.6 → 1.0.12

package/esm/src/mcp-server/tools/getPortals.js

@@ -11,14 +11,55 @@ export const tool$getPortals = {
     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,

package/esm/src/mcp-server/tools/getPortals.js.map

@@ -1 +1 @@
-{"version":3,"file":"getPortals.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/getPortals.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AAC/E,OAAO,EAAE,YAAY,EAAkB,MAAM,aAAa,CAAC;AAE3D,MAAM,IAAI,GAAG;IACX,OAAO,EAAE,6BAA6B;CACvC,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAgC;IAC1D,IAAI,EAAE,aAAa;IACnB,WAAW,EAAE;;;;;;;;;;CAUd;IACC,WAAW,EAAE;QACX,iBAAiB,EAAE,KAAK;QACxB,gBAAgB,EAAE,KAAK;QACvB,eAAe,EAAE,KAAK;QACtB,cAAc,EAAE,IAAI;KACrB;IACD,IAAI;IACJ,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,UAAU,CACxC,MAAM,EACN,IAAI,CAAC,OAAO,EACZ,EAAE,YAAY,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,EAAE,CACzC,CAAC,QAAQ,EAAE,CAAC;QAEb,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;gBACvD,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAE3B,OAAO,YAAY,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;CACF,CAAC"}
+{"version":3,"file":"getPortals.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/getPortals.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AAC/E,OAAO,EAAE,YAAY,EAAkB,MAAM,aAAa,CAAC;AAE3D,MAAM,IAAI,GAAG;IACX,OAAO,EAAE,6BAA6B;CACvC,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAgC;IAC1D,IAAI,EAAE,aAAa;IACnB,WAAW,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmDd;IACC,WAAW,EAAE;QACX,iBAAiB,EAAE,KAAK;QACxB,gBAAgB,EAAE,KAAK;QACvB,eAAe,EAAE,KAAK;QACtB,cAAc,EAAE,IAAI;KACrB;IACD,IAAI;IACJ,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,UAAU,CACxC,MAAM,EACN,IAAI,CAAC,OAAO,EACZ,EAAE,YAAY,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,EAAE,CACzC,CAAC,QAAQ,EAAE,CAAC;QAEb,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;gBACvD,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAE3B,OAAO,YAAY,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;CACF,CAAC"}

package/esm/src/models/getmyportalsop.d.ts

@@ -13,8 +13,8 @@ export type GetMyPortalsRequest = {
     shortUrlTemplate?: string | undefined;
     Dollar_sort?: SortIdNameDepartment | undefined;
     Dollar_order?: Order | undefined;
-    Dollar_pagenum?: number | undefined;
     Dollar_pagesize?: number | undefined;
+    Dollar_pagenum?: number | undefined;
 };
 export declare const GetMyPortalsRequest$zodSchema: z.ZodType<GetMyPortalsRequest, z.ZodTypeDef, unknown>;
 export type GetMyPortalsResponse = {

package/esm/src/models/getmyportalsop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"getmyportalsop.d.ts","sourceRoot":"","sources":["../../../src/models/getmyportalsop.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAAE,cAAc,EAA4B,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EACL,oBAAoB,EAErB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,+BAA+B,EAEhC,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,KAAK,EAAmB,MAAM,YAAY,CAAC;AACpD,OAAO,EACL,oBAAoB,EAErB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,aAAa,EAA2B,MAAM,oBAAoB,CAAC;AAE5E,MAAM,MAAM,mBAAmB,GAAG;IAChC,cAAc,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IAC5C,WAAW,EAAE,+BAA+B,CAAC;IAC7C,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,WAAW,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAAC;IAC/C,YAAY,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IACjC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC,CAAC;AAEF,eAAO,MAAM,6BAA6B,EAAE,CAAC,CAAC,OAAO,CACnD,mBAAmB,EACnB,CAAC,CAAC,UAAU,EACZ,OAAO,CAqBP,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,QAAQ,CAAC;IACtB,oBAAoB,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAAC;IACxD,aAAa,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CAC3C,CAAC;AAEF,eAAO,MAAM,8BAA8B,EAAE,CAAC,CAAC,OAAO,CACpD,oBAAoB,EACpB,CAAC,CAAC,UAAU,EACZ,OAAO,CAOP,CAAC"}
+{"version":3,"file":"getmyportalsop.d.ts","sourceRoot":"","sources":["../../../src/models/getmyportalsop.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAAE,cAAc,EAA4B,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EACL,oBAAoB,EAErB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,+BAA+B,EAEhC,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,KAAK,EAAmB,MAAM,YAAY,CAAC;AACpD,OAAO,EACL,oBAAoB,EAErB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,aAAa,EAA2B,MAAM,oBAAoB,CAAC;AAE5E,MAAM,MAAM,mBAAmB,GAAG;IAChC,cAAc,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IAC5C,WAAW,EAAE,+BAA+B,CAAC;IAC7C,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,WAAW,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAAC;IAC/C,YAAY,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IACjC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC,CAAC;AAEF,eAAO,MAAM,6BAA6B,EAAE,CAAC,CAAC,OAAO,CACnD,mBAAmB,EACnB,CAAC,CAAC,UAAU,EACZ,OAAO,CAqBP,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,QAAQ,CAAC;IACtB,oBAAoB,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAAC;IACxD,aAAa,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CAC3C,CAAC;AAEF,eAAO,MAAM,8BAA8B,EAAE,CAAC,CAAC,OAAO,CACpD,oBAAoB,EACpB,CAAC,CAAC,UAAU,EACZ,OAAO,CAOP,CAAC"}

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "dxt_version": "0.1",
   "name": "@egain/egain-mcp-server",
-  "version": "1.0.6",
+  "version": "1.0.12",
   "description": "",
   "long_description": "eGain Portal, Retrieve, Search, Answers APIs: Enterprise knowledge APIs for managing portals, searching content, retrieving AI-powered answers, and accessing content chunks for custom integrations.",
   "author": {
@@ -40,7 +40,7 @@
     },
     {
       "name": "get-portals",
-      "description": "Get All Portals Accessible To User\n\n## Overview\n  The Get All Portals Accessible to User API allows a user to fetch all portals accessible to user across all department.\n  * If no access tags are specified for a portal, then any user can access the portal.\n  * 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.\n  * All the global users(partition) cannot be assigned user profiles; their access is limited to portals without access restrictions.\n  * The only articles returned are associated to an Article type when the parameter, “Include in browse on portals” is set to \"Yes\".\n  * 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.\n  * When there is no short URL available for a specific language, the API returns a portal object with an empty \"shortURL\" field.\n"
+      "description": "Get All Portals Accessible To User\n\nGet All Portals Accessible to User\n\n## Overview\nThe Get All Portals Accessible to User API allows a user to fetch all portals accessible to the user across all departments.\n- If no access tags are specified for a portal, any user can access the portal.\n- 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.\n- Global users (partition) cannot be assigned user profiles; their access is limited to portals without access restrictions.\n- The only articles returned are associated to an Article type when the parameter “Include in browse on portals” is set to \"Yes\".\n- 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.\n\n## Pagination behavior (CRITICAL for AI assistants)\n\n**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.\n\n### Automatic pagination is REQUIRED when:\n- User asks to find a portal by name (e.g., \"business portal\", \"Master portal\")\n- User requests to list or see all portals\n- You need to resolve a natural portal name to its ID\n\n### How to detect more pages exist:\nThe response includes \\`paginationInfo\\` with:\n- \\`count\\`: Total number of items across all pages\n- \\`pagenum\\`: Current page number\n- \\`pagesize\\`: Items per page (default: 25)\n\n**Check for more pages if ANY of these are true:**\n1. The number of portals returned equals \\`pagesize\\` (e.g., exactly 25 portals returned)\n2. \\`paginationInfo.count > (pagenum * pagesize)\\` - there are more items beyond this page\n3. The response includes a \\`link\\` array with a \\`next\\` relation\n\n### Required pagination workflow:\n1. Start with \\`$pagenum=1\\` and \\`$pagesize=25\\` (default)\n2. After receiving the response, check \\`paginationInfo\\`\n3. **If more pages exist** (using the checks above), automatically call this endpoint again with \\`$pagenum=2\\`, then \\`$pagenum=3\\`, etc.\n4. Continue incrementing \\`$pagenum\\` until:\n   - A page returns fewer portals than \\`pagesize\\` (indicating the last page)\n   - A page returns zero portals\n   - \\`pagenum * pagesize >= paginationInfo.count\\` (if count represents total items)\n5. Merge all portals from all pages by unique portal ID\n6. Only then search through the complete merged list or report results to the user\n\n### Example scenario:\nIf you search for \"business portal\" and the first page returns 25 portals but none match:\n- DO NOT immediately tell the user the portal doesn't exist\n- Check \\`paginationInfo.count\\` - if it's > 25, automatically fetch page 2\n- Continue fetching until all pages are retrieved\n- Search the complete merged list before concluding the portal doesn't exist\n\nThis ensures reliable portal name-to-ID resolution and prevents false \"not found\" errors.\n"
     },
     {
       "name": "make-suggestion",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@egain/egain-mcp-server",
-  "version": "1.0.6",
+  "version": "1.0.12",
   "author": "Emily Loh - eGain Corporation",
   "type": "module",
   "sideEffects": false,

package/src/funcs/getPortals.ts

@@ -32,14 +32,55 @@ import { Result } from "../types/fp.js";
  * Get All Portals Accessible To User
  *
  * @remarks
+ * 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.
  */
 export function getPortals(
   client$: EgainMcpCore,