@egain/egain-mcp-server 1.0.1

package/src/mcp-server/tools/makeSuggestion.ts

@@ -0,0 +1,53 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { makeSuggestion } from "../../funcs/makeSuggestion.js";
+import { MakeSuggestionRequest$zodSchema } from "../../models/makesuggestionop.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: MakeSuggestionRequest$zodSchema,
+};
+
+export const tool$makeSuggestion: ToolDefinition<typeof args> = {
+  name: "make-suggestion",
+  description: `Make a Suggestion
+
+Make a Suggestion
+
+## Prerequisites
+- 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., "EB-123456789")
+
+## Overview
+The Make a Suggestion API allows users to create an Article Suggestion from within a knowledge portal. This enables users to submit feedback, request new articles, or suggest improvements to existing content.
+
+Users can submit suggestions with details about what they're looking for, which helps content creators understand user needs and improve the knowledge base.
+`,
+  annotations: {
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": false,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await makeSuggestion(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

package/src/mcp-server/tools/queryAnswers.ts

@@ -0,0 +1,53 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { queryAnswers } from "../../funcs/queryAnswers.js";
+import { PostPortalIDAnswersRequest$zodSchema } from "../../models/postportalidanswersop.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: PostPortalIDAnswersRequest$zodSchema,
+};
+
+export const tool$queryAnswers: ToolDefinition<typeof args> = {
+  name: "query-answers",
+  description: `Get the best answer for a user query
+
+Get Answers
+
+## Prerequisites
+- 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., "EB-123456789")
+
+## Overview
+The Answers API enables users to get the best answer for a user query. This API can return certified answers or generative answers along with search results, providing users with comprehensive responses to their questions.
+
+The API leverages AI capabilities to provide intelligent answers based on the knowledge base content, making it easier for users to find the information they need quickly and accurately.
+`,
+  annotations: {
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": false,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await queryAnswers(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

package/src/mcp-server/tools/queryRetrieve.ts

@@ -0,0 +1,55 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { queryRetrieve } from "../../funcs/queryRetrieve.js";
+import { PostPortalIDRetrieveRequest$zodSchema } from "../../models/postportalidretrieveop.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: PostPortalIDRetrieveRequest$zodSchema,
+};
+
+export const tool$queryRetrieve: ToolDefinition<typeof args> = {
+  name: "query-retrieve",
+  description: `Retrieve Chunks
+
+Retrieve Chunks
+
+## 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")
+
+## 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.
+`,
+  annotations: {
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": false,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await queryRetrieve(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

package/src/mcp-server/tools/querySearch.ts

@@ -0,0 +1,44 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { querySearch } from "../../funcs/querySearch.js";
+import { AiSearchRequest$zodSchema } from "../../models/aisearchop.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: AiSearchRequest$zodSchema,
+};
+
+export const tool$querySearch: ToolDefinition<typeof args> = {
+  name: "query-search",
+  description: `Get the best search results for a user query
+
+The Search API is a hybrid search service that combines semantic understanding with keyword precision to deliver fast, contextual, and relevant results from your enterprise knowledge base. It enables secure, role-aware access to articles, FAQs, and documentation across customer, agent, and employee interfaces. Each query returns a ranked list of results with snippets, metadata, and relevance scores. <br>**This endpoint is only available for Self Service environments.**
+`,
+  annotations: {
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": true,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await querySearch(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

package/src/mcp-server/tools.ts

@@ -0,0 +1,156 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import {
+  CallToolResult,
+  ServerNotification,
+  ServerRequest,
+} from "@modelcontextprotocol/sdk/types.js";
+import { objectOutputType, ZodRawShape, ZodTypeAny } from "zod";
+import { EgainMcpCore } from "../core.js";
+import { ConsoleLogger } from "./console-logger.js";
+import { MCPScope } from "./scopes.js";
+import { isAsyncIterable, isBinaryData, valueToBase64 } from "./shared.js";
+
+export type ToolDefinition<Args extends undefined | ZodRawShape = undefined> =
+  Args extends ZodRawShape ? {
+      name: string;
+      description: string;
+      scopes?: MCPScope[];
+      args: Args;
+      annotations: {
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+        readOnlyHint: boolean;
+      };
+      tool: (
+        client: EgainMcpCore,
+        args: objectOutputType<Args, ZodTypeAny>,
+        extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+      ) => CallToolResult | Promise<CallToolResult>;
+    }
+    : {
+      name: string;
+      description: string;
+      scopes?: MCPScope[];
+      args?: undefined;
+      annotations: {
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+        readOnlyHint: boolean;
+      };
+      tool: (
+        client: EgainMcpCore,
+        extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+      ) => CallToolResult | Promise<CallToolResult>;
+    };
+
+// Optional function to assist with formatting tool results
+export async function formatResult(
+  value: unknown,
+  init: { response?: Response | undefined },
+): Promise<CallToolResult> {
+  if (typeof value === "undefined") {
+    return { content: [] };
+  }
+
+  const { response } = init;
+  const contentType = response?.headers.get("content-type") ?? "";
+  let content: CallToolResult["content"] = [];
+
+  if (contentType.search(/\bjson\b/g)) {
+    content = [{ type: "text", text: JSON.stringify(value) }];
+  } else if (
+    contentType.startsWith("text/event-stream")
+    && isAsyncIterable(value)
+  ) {
+    content = await consumeSSE(value);
+  } else if (contentType.startsWith("text/") && typeof value === "string") {
+    content = [{ type: "text", text: value }];
+  } else if (isBinaryData(value) && contentType.startsWith("image/")) {
+    const data = await valueToBase64(value);
+    content = data == null
+      ? []
+      : [{ type: "image", data, mimeType: contentType }];
+  } else {
+    return {
+      content: [{
+        type: "text",
+        text: `Unsupported content type: "${contentType}"`,
+      }],
+      isError: true,
+    };
+  }
+
+  return { content };
+}
+
+async function consumeSSE(
+  value: AsyncIterable<unknown>,
+): Promise<CallToolResult["content"]> {
+  const content: CallToolResult["content"] = [];
+
+  for await (const chunk of value) {
+    if (typeof chunk === "string") {
+      content.push({ type: "text", text: chunk });
+    } else {
+      content.push({ type: "text", text: JSON.stringify(chunk) });
+    }
+  }
+
+  return content;
+}
+
+export function createRegisterTool(
+  logger: ConsoleLogger,
+  server: McpServer,
+  getSDK: () => EgainMcpCore,
+  allowedScopes: Set<MCPScope>,
+  allowedTools?: Set<string>,
+): <A extends ZodRawShape | undefined>(tool: ToolDefinition<A>) => void {
+  return <A extends ZodRawShape | undefined>(tool: ToolDefinition<A>): void => {
+    if (allowedTools && !allowedTools.has(tool.name)) {
+      return;
+    }
+
+    const scopes = tool.scopes ?? [];
+    if (allowedScopes.size > 0 && scopes.length === 0) {
+      return;
+    }
+
+    if (
+      allowedScopes.size > 0
+      && !scopes.every((s: MCPScope) => allowedScopes.has(s))
+    ) {
+      return;
+    }
+
+    if (tool.args) {
+      server.tool(
+        tool.name,
+        tool.description,
+        tool.args,
+        tool.annotations,
+        async (args, ctx) => {
+          return tool.tool(getSDK(), args, ctx);
+        },
+      );
+    } else {
+      server.tool(
+        tool.name,
+        tool.description,
+        tool.annotations,
+        async (_, ctx) => {
+          return tool.tool(getSDK(), ctx);
+        },
+      );
+    }
+
+    logger.debug("Registered tool", { name: tool.name });
+  };
+}

package/src/models/acceptlanguage.ts

@@ -0,0 +1,30 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+
+/**
+ * The language that describes the details of a resource. Resources available in different languages may differ from each other.<li>If <code>$lang</code> is not passed, then the portal's default language is used.</li><br><br>**Important**: When using this API via SDK or MCP, use the parameter name `Dollar_lang`, not `$lang` or `lang`.
+ */
+export const AcceptLanguage$zodSchema = z.enum([
+  "en-US",
+  "es-ES",
+  "fr-FR",
+  "it-IT",
+  "de-DE",
+  "nl-NL",
+  "pt-BR",
+  "pt-PT",
+  "da-DK",
+  "ru-RU",
+  "fr-CA",
+  "zh-CN",
+  "ja-JP",
+  "ko-KR",
+  "sv-SE",
+]).describe(
+  "The language that describes the details of a resource. Resources available in different languages may differ from each other.<li>If <code>$lang</code> is not passed, then the portal's default language is used.</li><br><br>**Important**: When using this API via SDK or MCP, use the parameter name `Dollar_lang`, not `$lang` or `lang`.",
+);
+
+export type AcceptLanguage = z.infer<typeof AcceptLanguage$zodSchema>;

package/src/models/accessibleportal.ts

@@ -0,0 +1,27 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { Department, Department$zodSchema } from "./department.js";
+import { ShortURL, ShortURL$zodSchema } from "./shorturl.js";
+
+export type AccessiblePortal = {
+  id?: string | undefined;
+  name?: string | undefined;
+  description?: string | undefined;
+  department?: Department | undefined;
+  shortURL?: Array<ShortURL> | undefined;
+};
+
+export const AccessiblePortal$zodSchema: z.ZodType<
+  AccessiblePortal,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  department: Department$zodSchema.optional(),
+  description: z.string().optional(),
+  id: z.string().optional(),
+  name: z.string().optional(),
+  shortURL: z.array(ShortURL$zodSchema).optional(),
+});

package/src/models/additionalsnippets.ts

@@ -0,0 +1,43 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+
+/**
+ * Format of the source document (HTML, DOCX, PPTX or PDF).
+ */
+export const AdditionalSnippetsDocType$zodSchema = z.enum([
+  "HTML",
+  "DOCX",
+  "PDF",
+  "PPTX",
+]).describe("Format of the source document (HTML, DOCX, PPTX or PDF).");
+
+export type AdditionalSnippetsDocType = z.infer<
+  typeof AdditionalSnippetsDocType$zodSchema
+>;
+
+export type AdditionalSnippets = {
+  id: string;
+  name: string;
+  docType: AdditionalSnippetsDocType;
+  docName?: string | undefined;
+  snippet: string;
+  keywordSnippet?: string | undefined;
+  relevanceScore: number;
+};
+
+export const AdditionalSnippets$zodSchema: z.ZodType<
+  AdditionalSnippets,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  docName: z.string().optional(),
+  docType: AdditionalSnippetsDocType$zodSchema,
+  id: z.string(),
+  keywordSnippet: z.string().optional(),
+  name: z.string(),
+  relevanceScore: z.number(),
+  snippet: z.string(),
+});

package/src/models/aisearchop.ts

@@ -0,0 +1,62 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import {
+  LanguageCodeParameter,
+  LanguageCodeParameter$zodSchema,
+} from "./languagecodeparameter.js";
+import { SearchResponse, SearchResponse$zodSchema } from "./searchresponse.js";
+
+export type AiSearchRequest = {
+  q: string;
+  portalID: string;
+  dollarFilterUserProfileID?: string | undefined;
+  Dollar_lang?: LanguageCodeParameter | undefined;
+  dollarFilterTags?: { [k: string]: Array<string> } | undefined;
+  dollarFilterTopicIds?: Array<string> | undefined;
+  articleCustomAdditionalAttributes?: string | undefined;
+};
+
+export const AiSearchRequest$zodSchema: z.ZodType<
+  AiSearchRequest,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  Dollar_lang: LanguageCodeParameter$zodSchema.default("en-US"),
+  articleCustomAdditionalAttributes: z.string().describe(
+    "One or more comma-separated names for article custom attributes defined by the user to be returned.",
+  ).optional(),
+  dollarFilterTags: z.record(z.array(z.string())).describe(
+    "An object where each key is a **Category Tag ID** (numeric string),  \n"
+      + "and each value is an array of **Tag IDs** for that category.\n"
+      + "",
+  ).optional(),
+  dollarFilterTopicIds: z.array(z.string()).optional(),
+  dollarFilterUserProfileID: z.string().describe(
+    "The Readable ID of the user profile.",
+  ).optional(),
+  portalID: z.string().describe(
+    "The ID of the portal being accessed.<br><br>A portal ID is composed of a 2-4 letter prefix, followed by a dash and 4-15 digits.",
+  ),
+  q: z.string().describe("The search query string."),
+});
+
+export type AiSearchResponse = {
+  ContentType: string;
+  StatusCode: number;
+  RawResponse: Response;
+  SearchResponse?: SearchResponse | undefined;
+};
+
+export const AiSearchResponse$zodSchema: z.ZodType<
+  AiSearchResponse,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  ContentType: z.string(),
+  RawResponse: z.instanceof(Response),
+  SearchResponse: SearchResponse$zodSchema.optional(),
+  StatusCode: z.number().int(),
+});

package/src/models/allaccessibleportals.ts

@@ -0,0 +1,27 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import {
+  AccessiblePortal,
+  AccessiblePortal$zodSchema,
+} from "./accessibleportal.js";
+import { PaginationInfo, PaginationInfo$zodSchema } from "./paginationinfo.js";
+
+/**
+ * Success
+ */
+export type AllAccessiblePortals = {
+  portal?: Array<AccessiblePortal> | undefined;
+  paginationInfo?: PaginationInfo | undefined;
+};
+
+export const AllAccessiblePortals$zodSchema: z.ZodType<
+  AllAccessiblePortals,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  paginationInfo: PaginationInfo$zodSchema.optional(),
+  portal: z.array(AccessiblePortal$zodSchema).optional(),
+}).describe("Success");

package/src/models/answersrequest.ts

@@ -0,0 +1,67 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+
+/**
+ * The channel where the query originated, e.g., directly from the portal or via a custom integration.
+ */
+export const AnswersRequestType$zodSchema = z.enum([
+  "portal",
+  "custom",
+]).describe(
+  "The channel where the query originated, e.g., directly from the portal or via a custom integration.",
+);
+
+export type AnswersRequestType = z.infer<typeof AnswersRequestType$zodSchema>;
+
+export type AnswersRequestChannel = {
+  type?: AnswersRequestType | undefined;
+  name?: string | undefined;
+};
+
+export const AnswersRequestChannel$zodSchema: z.ZodType<
+  AnswersRequestChannel,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  name: z.string().default("portal"),
+  type: AnswersRequestType$zodSchema.default("portal"),
+});
+
+/**
+ * Additional contextual metadata that enriches the query, providing the LLM with relevant details for tailoring the response.
+ */
+export type Context = {
+  userContext?: string | undefined;
+  pageContext?: string | undefined;
+  companyContext?: string | undefined;
+};
+
+export const Context$zodSchema: z.ZodType<Context, z.ZodTypeDef, unknown> = z
+  .object({
+    companyContext: z.string().optional(),
+    pageContext: z.string().optional(),
+    userContext: z.string().optional(),
+  }).describe(
+    "Additional contextual metadata that enriches the query, providing the LLM with relevant details for tailoring the response.",
+  );
+
+export type AnswersRequest = {
+  channel?: AnswersRequestChannel | undefined;
+  context?: Context | undefined;
+  eventId: string;
+  sessionId: string;
+};
+
+export const AnswersRequest$zodSchema: z.ZodType<
+  AnswersRequest,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  channel: z.lazy(() => AnswersRequestChannel$zodSchema).optional(),
+  context: z.lazy(() => Context$zodSchema).optional(),
+  eventId: z.string(),
+  sessionId: z.string(),
+});