@egain/egain-mcp-server 1.0.1

package/src/mcp-server/prompts.ts

@@ -0,0 +1,121 @@
+/*
+ * 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 {
+  GetPromptResult,
+  ServerNotification,
+  ServerRequest,
+} from "@modelcontextprotocol/sdk/types.js";
+import {
+  objectOutputType,
+  ZodOptional,
+  ZodType,
+  ZodTypeAny,
+  ZodTypeDef,
+} from "zod";
+import { EgainMcpCore } from "../core.js";
+import { ConsoleLogger } from "./console-logger.js";
+import { MCPScope } from "./scopes.js";
+
+// '@modelcontextprotocol/sdk' currently does not export this type
+export type PromptArgsRawShape = {
+  [k: string]:
+    | ZodType<string, ZodTypeDef, string>
+    | ZodOptional<ZodType<string, ZodTypeDef, string>>;
+};
+
+export type PromptDefinition<
+  Args extends undefined | PromptArgsRawShape = undefined,
+> = Args extends PromptArgsRawShape ? {
+    name: string;
+    description?: string;
+    scopes?: MCPScope[];
+    args: Args;
+    prompt: (
+      client: EgainMcpCore,
+      args: objectOutputType<Args, ZodTypeAny>,
+      extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+    ) => GetPromptResult | Promise<GetPromptResult>;
+  }
+  : {
+    name: string;
+    description?: string;
+    scopes?: MCPScope[];
+    args?: undefined;
+    prompt: (
+      client: EgainMcpCore,
+      extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+    ) => GetPromptResult | Promise<GetPromptResult>;
+  };
+
+// Optional function to assist with formatting prompt results
+export async function formatResult(value: string): Promise<GetPromptResult> {
+  return {
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: value,
+        },
+      },
+    ],
+  };
+}
+
+export function createRegisterPrompt(
+  logger: ConsoleLogger,
+  server: McpServer,
+  getSDK: () => EgainMcpCore,
+  allowedScopes: Set<MCPScope>,
+): <A extends PromptArgsRawShape | undefined>(
+  prompt: PromptDefinition<A>,
+) => void {
+  return <A extends PromptArgsRawShape | undefined>(
+    prompt: PromptDefinition<A>,
+  ): void => {
+    const scopes = prompt.scopes ?? [];
+    if (allowedScopes.size > 0 && scopes.length === 0) {
+      return;
+    }
+
+    if (
+      allowedScopes.size > 0
+      && !scopes.every((s: MCPScope) => allowedScopes.has(s))
+    ) {
+      return;
+    }
+
+    if (prompt.args) {
+      if (prompt.description) {
+        server.prompt(
+          prompt.name,
+          prompt.description,
+          prompt.args,
+          async (args, ctx) => prompt.prompt(getSDK(), args, ctx),
+        );
+      } else {
+        server.prompt(
+          prompt.name,
+          prompt.args,
+          async (args, ctx) => prompt.prompt(getSDK(), args, ctx),
+        );
+      }
+    } else {
+      if (prompt.description) {
+        server.prompt(
+          prompt.name,
+          prompt.description,
+          async (ctx) => prompt.prompt(getSDK(), ctx),
+        );
+      } else {
+        server.prompt(prompt.name, async (ctx) => prompt.prompt(getSDK(), ctx));
+      }
+    }
+
+    logger.debug("Registered prompt", { name: prompt.name });
+  };
+}

package/src/mcp-server/resources.ts

@@ -0,0 +1,176 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import {
+  McpServer,
+  ResourceMetadata,
+  ResourceTemplate,
+} from "@modelcontextprotocol/sdk/server/mcp.js";
+import { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import { Variables } from "@modelcontextprotocol/sdk/shared/uriTemplate.js";
+import {
+  ReadResourceResult,
+  ServerNotification,
+  ServerRequest,
+} from "@modelcontextprotocol/sdk/types.js";
+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 ReadResourceCallback = (
+  client: EgainMcpCore,
+  uri: URL,
+  extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+) => ReadResourceResult | Promise<ReadResourceResult>;
+
+export type ResourceDefinition = {
+  name: string;
+  description?: string;
+  metadata?: ResourceMetadata;
+  scopes?: MCPScope[];
+  resource: string;
+  read: ReadResourceCallback;
+};
+
+export type ReadResourceTemplateCallback = (
+  client: EgainMcpCore,
+  uri: URL,
+  vars: Variables,
+  extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+) => ReadResourceResult | Promise<ReadResourceResult>;
+
+export type ResourceTemplateDefinition = {
+  name: string;
+  description: string;
+  metadata?: ResourceMetadata;
+  scopes?: MCPScope[];
+  resource: ResourceTemplate;
+  read: ReadResourceTemplateCallback;
+};
+
+// Optional function to assist with formatting resource results
+export async function formatResult(
+  value: unknown,
+  uri: URL,
+  init: { mimeType?: string | undefined; response?: Response | undefined },
+): Promise<ReadResourceResult> {
+  if (typeof value === "undefined") {
+    return { contents: [] };
+  }
+
+  let contents: ReadResourceResult["contents"] = [];
+
+  const mimeType = init.mimeType ?? init.response?.headers.get("content-type")
+    ?? "";
+
+  if (mimeType.search(/\bjson\b/g) !== -1) {
+    contents = [{ uri: uri.toString(), mimeType, text: JSON.stringify(value) }];
+  } else if (
+    mimeType.startsWith("text/event-stream")
+    && isAsyncIterable(value)
+  ) {
+    contents = [
+      {
+        uri: uri.toString(),
+        mimeType: "application/json",
+        text: await stringifySSEToJSON(value),
+      },
+    ];
+  } else if (
+    (mimeType.startsWith("text/") || mimeType.startsWith("application/"))
+    && typeof value === "string"
+  ) {
+    contents = [{ uri: uri.toString(), mimeType, text: value }];
+  } else if (isBinaryData(value)) {
+    const blob = await valueToBase64(value);
+    contents = blob == null ? [] : [{ uri: uri.toString(), blob, mimeType }];
+  } else {
+    throw new Error(`Unsupported content type: "${mimeType}"`);
+  }
+
+  return { contents };
+}
+
+async function stringifySSEToJSON(
+  value: AsyncIterable<unknown>,
+): Promise<string> {
+  const payloads = [];
+
+  for await (const chunk of value) {
+    payloads.push(chunk);
+  }
+
+  return JSON.stringify(payloads);
+}
+
+export function createRegisterResource(
+  logger: ConsoleLogger,
+  server: McpServer,
+  getSDK: () => EgainMcpCore,
+  allowedScopes: Set<MCPScope>,
+): (resource: ResourceDefinition) => void {
+  return (resource: ResourceDefinition): void => {
+    const scopes = resource.scopes ?? [];
+    if (allowedScopes.size > 0 && scopes.length === 0) {
+      return;
+    }
+
+    if (
+      allowedScopes.size > 0
+      && !scopes.every((s: MCPScope) => allowedScopes.has(s))
+    ) {
+      return;
+    }
+
+    const metadata: ResourceMetadata = {
+      ...resource.metadata,
+      description: resource.description,
+    };
+
+    server.resource(
+      resource.name,
+      resource.resource,
+      metadata,
+      async (uri, ctx) => resource.read(getSDK(), uri, ctx),
+    );
+
+    logger.debug("Registered resource", { name: resource.name });
+  };
+}
+
+export function createRegisterResourceTemplate(
+  logger: ConsoleLogger,
+  server: McpServer,
+  getSDK: () => EgainMcpCore,
+  allowedScopes: Set<MCPScope>,
+): (resource: ResourceTemplateDefinition) => void {
+  return (resource: ResourceTemplateDefinition): void => {
+    const scopes = resource.scopes ?? [];
+    if (allowedScopes.size > 0 && scopes.length === 0) {
+      return;
+    }
+
+    if (
+      allowedScopes.size > 0
+      && !scopes.every((s: MCPScope) => allowedScopes.has(s))
+    ) {
+      return;
+    }
+
+    const metadata: ResourceMetadata = {
+      ...resource.metadata,
+      description: resource.description,
+    };
+
+    server.resource(
+      resource.name,
+      resource.resource,
+      metadata,
+      async (uri, vars, ctx) => resource.read(getSDK(), uri, vars, ctx),
+    );
+
+    logger.debug("Registered resource template", { name: resource.name });
+  };
+}

package/src/mcp-server/scopes.ts

@@ -0,0 +1,7 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+export const mcpScopes = [] as const;
+
+export type MCPScope = (typeof mcpScopes)[number];

package/src/mcp-server/server.ts

@@ -0,0 +1,91 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { EgainMcpCore } from "../core.js";
+import { SDKOptions } from "../lib/config.js";
+import type { ConsoleLogger } from "./console-logger.js";
+import { createRegisterPrompt } from "./prompts.js";
+import {
+  createRegisterResource,
+  createRegisterResourceTemplate,
+} from "./resources.js";
+import { MCPScope } from "./scopes.js";
+import { createRegisterTool } from "./tools.js";
+import { tool$getAnnouncements } from "./tools/getAnnouncements.js";
+import { tool$getArticle } from "./tools/getArticle.js";
+import { tool$getPopularArticles } from "./tools/getPopularArticles.js";
+import { tool$getPortals } from "./tools/getPortals.js";
+import { tool$makeSuggestion } from "./tools/makeSuggestion.js";
+import { tool$queryAnswers } from "./tools/queryAnswers.js";
+import { tool$queryRetrieve } from "./tools/queryRetrieve.js";
+import { tool$querySearch } from "./tools/querySearch.js";
+
+export function createMCPServer(deps: {
+  logger: ConsoleLogger;
+  allowedTools?: string[] | undefined;
+  scopes?: MCPScope[] | undefined;
+  getSDK?: () => EgainMcpCore;
+  serverURL?: string | undefined;
+  security?: SDKOptions["security"] | undefined;
+  server?: SDKOptions["server"] | undefined;
+  API_DOMAIN?: SDKOptions["API_DOMAIN"] | undefined;
+}) {
+  const server = new McpServer({
+    name: "EgainMcp",
+    version: "1.0.1",
+  });
+
+  const getClient = deps.getSDK || (() =>
+    new EgainMcpCore({
+      security: deps.security,
+      serverURL: deps.serverURL,
+      server: deps.server,
+      API_DOMAIN: deps.API_DOMAIN,
+      debugLogger: deps.logger.level === "debug"
+        ? {
+          log: (...args) => console.log(...args),
+          group: (...args) => console.group(...args),
+          groupEnd: (...args) => console.groupEnd(...args),
+        }
+        : undefined,
+    }));
+
+  const scopes = new Set(deps.scopes);
+
+  const allowedTools = deps.allowedTools && new Set(deps.allowedTools);
+  const tool = createRegisterTool(
+    deps.logger,
+    server,
+    getClient,
+    scopes,
+    allowedTools,
+  );
+  const resource = createRegisterResource(
+    deps.logger,
+    server,
+    getClient,
+    scopes,
+  );
+  const resourceTemplate = createRegisterResourceTemplate(
+    deps.logger,
+    server,
+    getClient,
+    scopes,
+  );
+  const prompt = createRegisterPrompt(deps.logger, server, getClient, scopes);
+  const register = { tool, resource, resourceTemplate, prompt };
+  void register; // suppress unused warnings
+
+  tool(tool$getArticle);
+  tool(tool$getAnnouncements);
+  tool(tool$getPopularArticles);
+  tool(tool$getPortals);
+  tool(tool$makeSuggestion);
+  tool(tool$queryAnswers);
+  tool(tool$querySearch);
+  tool(tool$queryRetrieve);
+
+  return server;
+}

package/src/mcp-server/shared.ts

@@ -0,0 +1,78 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+
+type BinaryData =
+  | Uint8Array
+  | ArrayBuffer
+  | Blob
+  | ReadableStream
+  | Response
+  | string;
+
+const base64Schema = z.string().base64();
+
+export function bytesToBase64(u8arr: Uint8Array): string {
+  return btoa(String.fromCodePoint(...u8arr));
+}
+
+export async function consumeStream(
+  stream: ReadableStream<Uint8Array>,
+): Promise<Uint8Array> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (value != null) chunks.push(value);
+      if (done) break;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  return new Uint8Array(await new Blob(chunks).arrayBuffer());
+}
+
+export function isAsyncIterable(
+  value: unknown,
+): value is AsyncIterable<string> {
+  return (
+    typeof value === "object" && value != null && Symbol.asyncIterator in value
+  );
+}
+
+export function isBinaryData(value: unknown): value is BinaryData {
+  return (
+    value instanceof Uint8Array
+    || value instanceof ArrayBuffer
+    || value instanceof Blob
+    || value instanceof ReadableStream
+    || value instanceof Response
+    || typeof value === "string"
+  );
+}
+
+export async function valueToBase64(
+  value: BinaryData | null | undefined,
+): Promise<string | null> {
+  if (value == null) {
+    return null;
+  } else if (value instanceof Uint8Array) {
+    return bytesToBase64(value);
+  } else if (value instanceof ArrayBuffer) {
+    return bytesToBase64(new Uint8Array(value));
+  } else if (value instanceof Response || value instanceof Blob) {
+    return bytesToBase64(new Uint8Array(await value.arrayBuffer()));
+  } else if (value instanceof ReadableStream) {
+    return bytesToBase64(await consumeStream(value));
+  } else if (typeof value === "string") {
+    return base64Schema.parse(value);
+  } else {
+    value satisfies never;
+    throw new Error(`Unsupported image value type: ${typeof value}`);
+  }
+}

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

@@ -0,0 +1,53 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { getAnnouncements } from "../../funcs/getAnnouncements.js";
+import { GetAnnouncementArticlesRequest$zodSchema } from "../../models/getannouncementarticlesop.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: GetAnnouncementArticlesRequest$zodSchema,
+};
+
+export const tool$getAnnouncements: ToolDefinition<typeof args> = {
+  name: "get-announcements",
+  description: `Get Announcement Articles
+
+Get Announcements
+
+## 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 Get Announcements API allows a user to retrieve all announcement articles for a specific portal. Announcements are special articles that are prominently displayed to users and typically contain important updates, news, or notifications.
+
+This API returns announcement articles with their full content, metadata, and any associated attachments or links.
+`,
+  annotations: {
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": true,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await getAnnouncements(
+      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/getArticle.ts

@@ -0,0 +1,56 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { getArticle } from "../../funcs/getArticle.js";
+import { GetArticleByIdRequest$zodSchema } from "../../models/getarticlebyidop.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: GetArticleByIdRequest$zodSchema,
+};
+
+export const tool$getArticle: ToolDefinition<typeof args> = {
+  name: "get-article",
+  description: `Get Article by ID
+
+Get Article by ID
+
+## 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")
+- Requires a valid article ID. Article ID format: 2-4 letter prefix + dash + 4-15 digits (e.g., "PROD-2996")
+
+## Overview
+The Get Article by ID API allows a user to retrieve a specific article using its ID. Additional article attributes and contextual views can be specified in the query parameters.
+
+This API returns structured authoring attributes of Issue, Environment, Cause and Confidence Level when the following conditions are met:
+- The "Allow Structured Authoring" setting is enabled at the partition/department level
+- The "Use Structured Authoring" flag is set on the article type
+`,
+  annotations: {
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": true,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await getArticle(
+      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/getPopularArticles.ts

@@ -0,0 +1,53 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { getPopularArticles } from "../../funcs/getPopularArticles.js";
+import { GetpopulararticlesRequest$zodSchema } from "../../models/getpopulararticlesop.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: GetpopulararticlesRequest$zodSchema,
+};
+
+export const tool$getPopularArticles: ToolDefinition<typeof args> = {
+  name: "get-popular-articles",
+  description: `Get Popular Articles
+
+Get Popular Articles
+
+## 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 Popular Articles API allows a user to retrieve the most popular articles from a specific portal. Popular articles are typically determined by user engagement metrics such as views, ratings, or usage frequency.
+
+This API returns a list of popular articles with their metadata, allowing users to discover the most relevant and frequently accessed content within the portal.
+`,
+  annotations: {
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": true,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await getPopularArticles(
+      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/getPortals.ts

@@ -0,0 +1,51 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { getPortals } from "../../funcs/getPortals.js";
+import { GetMyPortalsRequest$zodSchema } from "../../models/getmyportalsop.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: GetMyPortalsRequest$zodSchema,
+};
+
+export const tool$getPortals: ToolDefinition<typeof args> = {
+  name: "get-portals",
+  description: `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.
+`,
+  annotations: {
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": true,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await getPortals(
+      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);
+  },
+};