Add conversation sentiment tool (#11)

Adds a tool to retrieve conversation sentiment

Author: SketchingDev

README.md

@@ -16,6 +16,7 @@ in the [tools doc](/docs/tools.md).
 | [Query Queue Volumes](/docs/tools.md#query-queue-volumes)                     | Retrieves conversation volumes and member count by Queue IDs             |
 | [Sample Conversations By Queue](/docs/tools.md#sample-conversations-by-queue) | Retrieves a representative sample of Conversation IDs for a Queue ID     |
 | [Voice Call Quality](/docs/tools.md#voice-call-quality)                       | Retrieves voice call quality metrics for one or more conversations by ID |
+| [Conversation Sentiment](/docs/tools.md#conversation-sentiment)               | Retrieves the sentiment for one or more conversations by ID              |
 
 ## Authentication
 

docs/tools.md

@@ -12,20 +12,22 @@ or listing available queues.
 
 ### Inputs
 
-* `name`
-  * The name (or partial name) of the routing queue(s) to search for. Wildcards ('*') are supported for pattern matching (e.g., 'Support*', '*Emergency', '*Sales*'). Use '*' alone to retrieve all queues.
-* `pageNumber`
-  * The page number of the results to retrieve, starting from 1. Defaults to 1 if not specified. Used with 'pageSize' for navigating large result sets.
-* `pageSize`
-  * The maximum number of queues to return per page. Defaults to 100 if not specified. Used with 'pageNumber' for pagination. The maximum value is 500.
+- `name`
+  - The name (or partial name) of the routing queue(s) to search for. Wildcards ('\*') are supported for pattern matching (e.g., 'Support\*', '\*Emergency', '\*Sales\*'). Use '\*' alone to retrieve all queues.
+- `pageNumber`
+  - The page number of the results to retrieve, starting from 1. Defaults to 1 if not specified. Used with 'pageSize' for navigating large result sets.
+- `pageSize`
+  - The maximum number of queues to return per page. Defaults to 100 if not specified. Used with 'pageNumber' for pagination. The maximum value is 500.
 
 ### Security
 
 Required permission:
-* `routing:queue:view`
+
+- `routing:queue:view`
 
 Platform API endpoint used:
-* [`GET /api/v2/routing/queues`](https://developer.genesys.cloud/routing/routing/#get-api-v2-routing-queues)
+
+- [`GET /api/v2/routing/queues`](https://developer.genesys.cloud/routing/routing/#get-api-v2-routing-queues)
 
 ## Query Queue Volumes
 
@@ -36,22 +38,24 @@ dates. Useful for comparing workload across queues.
 
 ### Inputs
 
-* `queueIds`
-  * The IDs of the queues to filter conversations by. Max 300.
-* `startDate`
-  * The start date/time in ISO-8601 format (e.g., '2024-01-01T00:00:00Z').
-* `endDate`
-  * The end date/time in ISO-8601 format (e.g., '2024-01-07T23:59:59Z').
+- `queueIds`
+  - The IDs of the queues to filter conversations by. Max 300.
+- `startDate`
+  - The start date/time in ISO-8601 format (e.g., '2024-01-01T00:00:00Z').
+- `endDate`
+  - The end date/time in ISO-8601 format (e.g., '2024-01-07T23:59:59Z').
 
 ### Security
 
 Required permission:
-* `analytics:conversationDetail:view`
+
+- `analytics:conversationDetail:view`
 
 Platform API endpoints used:
-* [`POST /api/v2/analytics/conversations/details/jobs`](https://developer.genesys.cloud/analyticsdatamanagement/analytics/analytics-apis#post-api-v2-analytics-conversations-details-jobs)
-* [`GET /api/v2/analytics/conversations/details/jobs/{jobId}`](https://developer.genesys.cloud/analyticsdatamanagement/analytics/analytics-apis#get-api-v2-analytics-conversations-details-jobs--jobId-)
-* [`GET /api/v2/analytics/conversations/details/jobs/{jobId}/results`](https://developer.genesys.cloud/analyticsdatamanagement/analytics/analytics-apis#get-api-v2-analytics-conversations-details-jobs--jobId--results)
+
+- [`POST /api/v2/analytics/conversations/details/jobs`](https://developer.genesys.cloud/analyticsdatamanagement/analytics/analytics-apis#post-api-v2-analytics-conversations-details-jobs)
+- [`GET /api/v2/analytics/conversations/details/jobs/{jobId}`](https://developer.genesys.cloud/analyticsdatamanagement/analytics/analytics-apis#get-api-v2-analytics-conversations-details-jobs--jobId-)
+- [`GET /api/v2/analytics/conversations/details/jobs/{jobId}/results`](https://developer.genesys.cloud/analyticsdatamanagement/analytics/analytics-apis#get-api-v2-analytics-conversations-details-jobs--jobId--results)
 
 ## Sample Conversations By Queue
 
@@ -60,22 +64,24 @@ representative sample of conversation IDs. Useful for reporting, investigation,
 
 ### Inputs
 
-* `queueId`
-  * The ID of the queue to filter conversations by.
-* `startDate`
-  * The start date/time in ISO-8601 format (e.g., '2024-01-01T00:00:00Z').
-* `endDate`
-  * The end date/time in ISO-8601 format (e.g., '2024-01-07T23:59:59Z').
+- `queueId`
+  - The ID of the queue to filter conversations by.
+- `startDate`
+  - The start date/time in ISO-8601 format (e.g., '2024-01-01T00:00:00Z').
+- `endDate`
+  - The end date/time in ISO-8601 format (e.g., '2024-01-07T23:59:59Z').
 
 ### Security
 
-Required Permissions:
-* `analytics:conversationDetail:view`
+Required Permission:
+
+- `analytics:conversationDetail:view`
 
 Platform API endpoints used:
-* [`POST /api/v2/analytics/conversations/details/jobs`](https://developer.genesys.cloud/analyticsdatamanagement/analytics/analytics-apis#post-api-v2-analytics-conversations-details-jobs)
-* [`GET /api/v2/analytics/conversations/details/jobs/{jobId}`](https://developer.genesys.cloud/analyticsdatamanagement/analytics/analytics-apis#get-api-v2-analytics-conversations-details-jobs--jobId-)
-* [`GET /api/v2/analytics/conversations/details/jobs/{jobId}/results`](https://developer.genesys.cloud/analyticsdatamanagement/analytics/analytics-apis#get-api-v2-analytics-conversations-details-jobs--jobId--results)
+
+- [`POST /api/v2/analytics/conversations/details/jobs`](https://developer.genesys.cloud/analyticsdatamanagement/analytics/analytics-apis#post-api-v2-analytics-conversations-details-jobs)
+- [`GET /api/v2/analytics/conversations/details/jobs/{jobId}`](https://developer.genesys.cloud/analyticsdatamanagement/analytics/analytics-apis#get-api-v2-analytics-conversations-details-jobs--jobId-)
+- [`GET /api/v2/analytics/conversations/details/jobs/{jobId}/results`](https://developer.genesys.cloud/analyticsdatamanagement/analytics/analytics-apis#get-api-v2-analytics-conversations-details-jobs--jobId--results)
 
 ## Voice Call Quality
 
@@ -89,13 +95,39 @@ Read more [about MOS scores and how they're determined](https://developer.genesy
 
 ### Inputs
 
-* `conversationIds`
-  * A list of up to 100 conversation IDs to evaluate voice call quality for.
+- `conversationIds`
+  - A list of up to 100 conversation IDs to evaluate voice call quality for.
+
+### Security
+
+Required Permission:
+
+- `analytics:conversationDetail:view`
+
+Platform API endpoint used:
+
+- [`GET /api/v2/analytics/conversations/details`](https://developer.genesys.cloud/analyticsdatamanagement/analytics/analytics-apis#get-api-v2-analytics-conversations-details)
+
+## Conversation Sentiment
+
+Retrieves sentiment analysis scores for one or more conversations. Sentiment is evaluated based on customer phrases,
+categorized as positive, neutral, or negative. The result includes both a numeric sentiment score (-100 to 100)
+and an interpreted sentiment label.
+
+[Source file](/src/tools/conversationSentiment.ts).
+
+### Inputs
+
+- `conversationIds`
+  - A list of up to 100 conversation IDs to retrieve sentiment for.
 
 ### Security
 
 Required Permissions:
-* `analytics:conversationDetail:view`
+
+- `speechAndTextAnalytics:data:view`
+- `recording:recording:view`
 
 Platform API endpoint used:
-* [`GET /api/v2/analytics/conversations/details`](https://developer.genesys.cloud/analyticsdatamanagement/analytics/analytics-apis#get-api-v2-analytics-conversations-details)
+
+- [GET /api/v2/speechandtextanalytics/conversations/{conversationId}](https://developer.genesys.cloud/analyticsdatamanagement/speechtextanalytics/#get-api-v2-speechandtextanalytics-conversations--conversationId-)

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@makingchatbots/genesys-cloud-mcp-server",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "A MCP server for connecting LLMs to Genesys Cloud's Platform API",
   "exports": "./dist/index.js",
   "type": "module",

package.json

@@ -7,6 +7,7 @@ import { loadConfig } from "./loadConfig.js";
 import { sampleConversationsByQueue } from "./tools/sampleConversationsByQueue.js";
 import { queryQueueVolumes } from "./tools/queryQueueVolumes.js";
 import { voiceCallQuality } from "./tools/voiceCallQuality.js";
+import { conversationSentiment } from "./tools/conversationSentiment.js";
 
 const configResult = loadConfig(process.env);
 if (!configResult.success) {
@@ -68,6 +69,7 @@ server.tool(
         platformClient.ApiClient.instance,
       ),
 );
+
 const voiceCallQualityTool = voiceCallQuality({
   analyticsApi: new platformClient.AnalyticsApi(),
 });
@@ -84,5 +86,21 @@ server.tool(
       ),
 );
 
+const conversationSentimentTool = conversationSentiment({
+  speechTextAnalyticsApi: new platformClient.SpeechTextAnalyticsApi(),
+});
+server.tool(
+  conversationSentimentTool.schema.name,
+  conversationSentimentTool.schema.description,
+  conversationSentimentTool.schema.paramsSchema.shape,
+  config.mockingEnabled
+    ? conversationSentimentTool.mockCall
+    : withAuth(
+        conversationSentimentTool.call,
+        config.genesysCloud,
+        platformClient.ApiClient.instance,
+      ),
+);
+
 const transport = new StdioServerTransport();
 await server.connect(transport);

src/index.ts

@@ -0,0 +1,120 @@
+import { z } from "zod";
+import { createTool, type ToolFactory } from "./utils/createTool.js";
+import { isUnauthorisedError } from "./utils/genesys/isUnauthorisedError.js";
+import { type SpeechTextAnalyticsApi } from "purecloud-platform-client-v2";
+import { type CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+
+interface Dependencies {
+  readonly speechTextAnalyticsApi: SpeechTextAnalyticsApi;
+}
+
+const paramsSchema = z.object({
+  conversationIds: z
+    .array(
+      z
+        .string()
+        .uuid()
+        .describe(
+          "A unique ID for a Genesys Cloud conversation. Must be a valid UUID.",
+        ),
+    )
+    .min(1)
+    .max(100)
+    .describe(
+      "A list of up to 100 conversation IDs to retrieve sentiment for.",
+    ),
+});
+
+function errorResult(errorMessage: string): CallToolResult {
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text",
+        text: errorMessage,
+      },
+    ],
+  };
+}
+
+function interpretSentiment(score?: number): string {
+  if (score === undefined) return "Unknown";
+  if (score > 55) return "Positive";
+  if (score >= 20 && score <= 55) return "Slightly Positive";
+  if (score > -20 && score < 20) return "Neutral";
+  if (score >= -55 && score <= -20) return "Slightly Negative";
+  return "Negative";
+}
+
+export const conversationSentiment: ToolFactory<
+  Dependencies,
+  typeof paramsSchema
+> = ({ speechTextAnalyticsApi }) =>
+  createTool({
+    schema: {
+      name: "conversation_sentiment",
+      description:
+        "Retrieves sentiment analysis scores for one or more conversations. Sentiment is evaluated based on customer phrases, categorized as positive, neutral, or negative. The result includes both a numeric sentiment score (-100 to 100) and an interpreted sentiment label.",
+      paramsSchema,
+    },
+    call: async ({ conversationIds }) => {
+      try {
+        const conversations = await Promise.all(
+          conversationIds.map((id) =>
+            speechTextAnalyticsApi.getSpeechandtextanalyticsConversation(id),
+          ),
+        );
+
+        const output: string[] = [];
+
+        for (const convo of conversations) {
+          const id = convo.conversation?.id;
+          const score = convo.sentimentScore;
+
+          if (id === undefined || score === undefined) continue;
+          const scaledScore = Math.round(score * 100);
+
+          output.push(
+            `• Conversation ID: ${id}\n  • Sentiment Score: ${String(scaledScore)} (${interpretSentiment(scaledScore)})`,
+          );
+        }
+
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                output.length > 0
+                  ? [
+                      `Sentiment results for ${String(output.length)} conversation(s):`,
+                      ...output,
+                    ].join("\n\n")
+                  : "No sentiment data found for the given conversation IDs.",
+            },
+          ],
+        };
+      } catch (error: unknown) {
+        const message = isUnauthorisedError(error)
+          ? "Failed to retrieve sentiment analysis: Unauthorised access. Please check API credentials or permissions."
+          : `Failed to retrieve sentiment analysis: ${error instanceof Error ? error.message : JSON.stringify(error)}`;
+
+        return errorResult(message);
+      }
+    },
+    mockCall: async ({ conversationIds }) => {
+      return Promise.resolve({
+        content: [
+          {
+            type: "text",
+            text: [
+              `Sentiment results for ${String(conversationIds.length)} conversation(s):`,
+              ...conversationIds.map((id, index) => {
+                const score = [-80, 0, 25, 55, 85][index % 5];
+                return `• Conversation ID: ${id}\n  • Sentiment Score: ${String(score)} (${interpretSentiment(score)})`;
+              }),
+            ].join("\n\n"),
+          },
+        ],
+      });
+    },
+  });

src/tools/conversationSentiment.ts

@@ -0,0 +1,56 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { join } from "path";
+import { afterEach, describe, expect, test } from "vitest";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+
+describe("conversation sentiment tool", () => {
+  let client: Client | null = null;
+
+  afterEach(async () => {
+    if (client) await client.close();
+  });
+
+  test("mock", async () => {
+    // Debugging server possible by setting breakpoint inside js file
+
+    const transport = new StdioClientTransport({
+      command: "node",
+      args: ["--inspect", join(__dirname, "../dist/index.js")],
+      env: {
+        // Provides path for node binary to be used in test
+        PATH: process.env.PATH!,
+        MOCKING_ENABLED: "true",
+      },
+    });
+
+    client = new Client({
+      name: "test-client",
+      version: "1.0.0",
+    });
+
+    await client.connect(transport);
+
+    const queueName = "Test";
+    const result = await client.callTool({
+      name: "conversation_sentiment",
+      arguments: {
+        conversationIds: [
+          "00000000-0000-0000-0000-000000000001",
+          "00000000-0000-0000-0000-000000000002",
+        ],
+      },
+    });
+
+    const text = (result as CallToolResult).content[0].text;
+    expect(text).toStrictEqual(
+      `Sentiment results for 2 conversation(s):
+
+• Conversation ID: 00000000-0000-0000-0000-000000000001
+  • Sentiment Score: -80 (Negative)
+
+• Conversation ID: 00000000-0000-0000-0000-000000000002
+  • Sentiment Score: 0 (Neutral)`,
+    );
+  });
+});