Add tool to Search Voice Conversations (#19)

Author: SketchingDev

README.md

@@ -18,6 +18,7 @@ in the [tools doc](/docs/tools.md).
 | [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              |
 | [Conversation Topics](/docs/tools.md#conversation-topics)                     | Retrieves the topics for a conversation by ID                            |
+| [Search Voice Conversation](/docs/tools.md#search-voice-conversations)        | Searches voice conversations by optional criteria                        |
 
 ## Authentication
 

docs/tools.md

@@ -164,3 +164,34 @@ Platform API endpoints used:
 - [GET /api/v2/speechandtextanalytics/topics](https://developer.genesys.cloud/analyticsdatamanagement/speechtextanalytics/#get-api-v2-speechandtextanalytics-topics)
 - [GET /api/v2/analytics/conversations/{conversationId}/details](https://developer.genesys.cloud/analyticsdatamanagement/analytics/analytics-apis#get-api-v2-analytics-conversations--conversationId--details)
 - [POST /api/v2/analytics/transcripts/aggregates/query](https://developer.genesys.cloud/analyticsdatamanagement/analytics/analytics-apis#post-api-v2-analytics-transcripts-aggregates-query)
+
+## Search Voice Conversations
+
+**Tool name:** `search_voice_conversations`
+
+Searches for voice conversations within a specified time window, optionally filtering by phone number. Returns a paginated list of conversation metadata for use in further analysis or tool calls.
+
+[Source file](/src/tools/searchVoiceConversations.ts).
+
+### Input
+
+- `phoneNumber`
+  - Optional. Filters results to only include conversations involving this phone number (e.g., '+440000000000')
+- `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 conversations to return per page. Defaults to 100 if not specified. Used with 'pageNumber' for pagination. The maximum value is 500
+- `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`
+
+Platform API endpoints used:
+
+- [POST /api/v2/analytics/conversations/details/query](https://developer.genesys.cloud/devapps/api-explorer-standalone#post-api-v2-analytics-conversations-details-query)

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "@makingchatbots/genesys-cloud-mcp-server",
-  "version": "0.0.7",
-  "description": "A MCP server for connecting LLMs to Genesys Cloud's Platform API",
+  "version": "0.0.8",
+  "description": "A Model Context Protocol (MCP) server exposing Genesys Cloud tools for LLMs, including sentiment analysis, conversation search, topic detection and more.",
   "exports": "./dist/index.js",
   "type": "module",
   "license": "ISC",
@@ -35,26 +35,27 @@
     "prepublishOnly": "npm run test && npm run build"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.11.4",
-    "purecloud-platform-client-v2": "^221.0.0",
-    "zod": "^3.24.4"
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "date-fns": "^4.1.0",
+    "purecloud-platform-client-v2": "^223.0.0",
+    "zod": "^3.25.48"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.1",
-    "@eslint/js": "^9.27.0",
+    "@eslint/js": "^9.28.0",
     "@types/eslint-config-prettier": "^6.11.3",
-    "@types/node": "^22.15.18",
-    "@typescript-eslint/eslint-plugin": "^8.32.1",
-    "@typescript-eslint/parser": "^8.32.1",
-    "eslint": "^9.27.0",
+    "@types/node": "^22.15.29",
+    "@typescript-eslint/eslint-plugin": "^8.33.1",
+    "@typescript-eslint/parser": "^8.33.1",
+    "eslint": "^9.28.0",
     "eslint-config-prettier": "^10.1.5",
-    "eslint-import-resolver-typescript": "^4.3.5",
-    "lint-staged": "^16.0.0",
+    "eslint-import-resolver-typescript": "^4.4.2",
+    "lint-staged": "^16.1.0",
     "prettier": "^3.5.3",
     "tsx": "^4.19.4",
     "typescript": "^5.8.3",
-    "typescript-eslint": "^8.32.1",
-    "vitest": "^3.1.3"
+    "typescript-eslint": "^8.33.1",
+    "vitest": "^3.2.0"
   },
   "lint-staged": {
     "src/*.ts": [
@@ -78,6 +79,11 @@
   "keywords": [
     "mcp",
     "modelcontextprotocol",
-    "genesys cloud"
+    "tool-calling",
+    "llm-integration",
+    "genesys-cloud",
+    "speech-and-text-analytics",
+    "sentiment-analysis",
+    "conversation-analysis"
   ]
 }

package.json

@@ -9,6 +9,7 @@ import { queryQueueVolumes } from "./tools/queryQueueVolumes.js";
 import { voiceCallQuality } from "./tools/voiceCallQuality.js";
 import { conversationSentiment } from "./tools/conversationSentiment.js";
 import { conversationTopics } from "./tools/conversationTopics.js";
+import { searchVoiceConversations } from "./tools/searchVoiceConversations.js";
 
 const configResult = loadConfig(process.env);
 if (!configResult.success) {
@@ -106,6 +107,20 @@ server.tool(
   ),
 );
 
+const searchVoiceConversationsTool = searchVoiceConversations({
+  analyticsApi,
+});
+server.tool(
+  searchVoiceConversationsTool.schema.name,
+  searchVoiceConversationsTool.schema.description,
+  searchVoiceConversationsTool.schema.paramsSchema.shape,
+  withAuth(
+    searchVoiceConversationsTool.call,
+    config.genesysCloud,
+    platformClient.ApiClient.instance,
+  ),
+);
+
 const transport = new StdioServerTransport();
 await server.connect(transport);
 console.log("Started...");

src/index.ts

@@ -170,6 +170,7 @@ describe("Search Queues Tool", () => {
 Found the following queues matching "test-queue":
 • Name: test-queue
   • ID: ${queueId}
+
 --- Pagination Info ---
 Page Number: N/A
 Page Size: N/A

src/tools/searchQueues.test.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 import type { Models, RoutingApi } from "purecloud-platform-client-v2";
 import { isUnauthorisedError } from "./utils/genesys/isUnauthorisedError.js";
 import { createTool, type ToolFactory } from "./utils/createTool.js";
+import { paginationSection } from "./utils/paginationSection.js";
 
 type PartRequired<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
 
@@ -25,14 +26,6 @@ function formatQueues(
     total?: number;
   },
 ) {
-  const paginationDetails = [
-    "--- Pagination Info ---",
-    `Page Number: ${pagination.pageNumber ? String(pagination.pageNumber) : "N/A"}`,
-    `Page Size: ${pagination.pageSize ? String(pagination.pageSize) : "N/A"}`,
-    `Total Pages: ${pagination.pageCount ? String(pagination.pageCount) : "N/A"}`,
-    `Total Matching Queues: ${pagination.total ? String(pagination.total) : "N/A"}`,
-  ].join("\n");
-
   const queueItems = queues.flatMap((q) => [
     `• Name: ${q.name}`,
     `  • ID: ${q.id}`,
@@ -45,7 +38,8 @@ function formatQueues(
   return [
     `Found the following queues matching "${inputQueueName}":`,
     ...queueItems,
-    paginationDetails,
+    "",
+    ...paginationSection("Total Matching Queues", pagination),
   ].join("\n");
 }