Add conversation transcription tool (#20)

Author: SketchingDev

README.md

@@ -19,6 +19,7 @@ in the [tools doc](/docs/tools.md).
 | [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                        |
+| [Conversation Transcript](/docs/tools.md#conversation-transcript)             | Retrieves conversation transcript                                        |
 
 ## Authentication
 

docs/tools.md

@@ -37,7 +37,7 @@ Platform API endpoint used:
 
 Returns a breakdown of how many conversations occurred in each specified queue between two dates. Useful for comparing workload across queues.
 
-[Source file](/src/tools/queryQueueVolumes.ts).
+[Source file](/src/tools/queryQueueVolumes/queryQueueVolumes.ts).
 
 ### Inputs
 
@@ -69,7 +69,7 @@ Retrieves conversation analytics for a specific queue between two dates, returni
 ### Inputs
 
 - `queueId`
-  - The UUID ID of the queue to filter conversations by. (e.g., 00000000-0000-0000-0000-000000000000)
+  - The UUID of the queue to filter conversations by. (e.g., 00000000-0000-0000-0000-000000000000)
 - `startDate`
   - The start date/time in ISO-8601 format (e.g., '2024-01-01T00:00:00Z')
 - `endDate`
@@ -118,7 +118,7 @@ Platform API endpoint used:
 
 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).
+[Source file](/src/tools/conversationSentiment/conversationSentiment.ts).
 
 ### Inputs
 
@@ -144,12 +144,12 @@ Retrieves Speech and Text Analytics topics detected for a specific conversation.
 
 Read more [about programs, topics, and phrases](https://help.mypurecloud.com/articles/about-programs-topics-and-phrases/).
 
-[Source file](/src/tools/conversationTopics.ts).
+[Source file](/src/tools/conversationTopics/conversationTopics.ts).
 
 ### Input
 
 - `conversationId`
-  - A UUID ID for a conversation. (e.g., 00000000-0000-0000-0000-000000000000)
+  - A UUID for a conversation. (e.g., 00000000-0000-0000-0000-000000000000)
 
 ### Security
 
@@ -195,3 +195,28 @@ Required Permissions:
 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)
+
+## Conversation Transcript
+
+**Tool name:** `conversation_transcript`
+
+Retrieves a structured transcript of the conversation, including speaker labels, utterance timestamps, and sentiment annotations where available. The transcript is formatted as a time-aligned list of utterances attributed to each participant (e.g., customer or agent)
+
+[Source file](/src/tools/conversationTranscription/conversationTranscription.ts).
+
+### Input
+
+- `conversationId`
+  - The UUID of the conversation to retrieve the transcript for (e.g., 00000000-0000-0000-0000-000000000000)
+
+### Security
+
+Required Permissions:
+
+- `recording:recording:view`
+- `speechAndTextAnalytics:data:view`
+
+Platform API endpoints used:
+
+- [GET /api/v2/conversations/{conversationId}/recordings](https://developer.genesys.cloud/devapps/api-explorer-standalone#get-api-v2-conversations--conversationId--recordings)
+- [GET /api/v2/speechandtextanalytics/conversations/{conversationId}/communications/{communicationId}/transcripturl](https://developer.genesys.cloud/devapps/api-explorer-standalone#get-api-v2-speechandtextanalytics-conversations--conversationId--communications--communicationId--transcripturl)

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@makingchatbots/genesys-cloud-mcp-server",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "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",
@@ -38,7 +38,8 @@
     "@modelcontextprotocol/sdk": "^1.12.1",
     "date-fns": "^4.1.0",
     "purecloud-platform-client-v2": "^223.0.0",
-    "zod": "^3.25.48"
+    "table": "^6.9.0",
+    "zod": "^3.25.56"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.1",

package.json

@@ -1,15 +1,16 @@
+import platformClient from "purecloud-platform-client-v2";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import platformClient from "purecloud-platform-client-v2";
 import { withAuth } from "./withAuth.js";
-import { searchQueues } from "./tools/searchQueues.js";
 import { loadConfig } from "./loadConfig.js";
-import { sampleConversationsByQueue } from "./tools/sampleConversationsByQueue.js";
-import { queryQueueVolumes } from "./tools/queryQueueVolumes.js";
+import { searchQueues } from "./tools/searchQueues.js";
+import { sampleConversationsByQueue } from "./tools/sampleConversationsByQueue/sampleConversationsByQueue.js";
+import { queryQueueVolumes } from "./tools/queryQueueVolumes/queryQueueVolumes.js";
 import { voiceCallQuality } from "./tools/voiceCallQuality.js";
-import { conversationSentiment } from "./tools/conversationSentiment.js";
-import { conversationTopics } from "./tools/conversationTopics.js";
+import { conversationSentiment } from "./tools/conversationSentiment/conversationSentiment.js";
+import { conversationTopics } from "./tools/conversationTopics/conversationTopics.js";
 import { searchVoiceConversations } from "./tools/searchVoiceConversations.js";
+import { conversationTranscription } from "./tools/conversationTranscription/conversationTranscription.js";
 
 const configResult = loadConfig(process.env);
 if (!configResult.success) {
@@ -27,6 +28,7 @@ const server: McpServer = new McpServer({
 const routingApi = new platformClient.RoutingApi();
 const analyticsApi = new platformClient.AnalyticsApi();
 const speechTextAnalyticsApi = new platformClient.SpeechTextAnalyticsApi();
+const recordingApi = new platformClient.RecordingApi();
 
 const searchQueuesTool = searchQueues({ routingApi });
 server.tool(
@@ -121,6 +123,22 @@ server.tool(
   ),
 );
 
+const conversationTranscriptTool = conversationTranscription({
+  recordingApi,
+  speechTextAnalyticsApi,
+  fetchUrl: fetch,
+});
+server.tool(
+  conversationTranscriptTool.schema.name,
+  conversationTranscriptTool.schema.description,
+  conversationTranscriptTool.schema.paramsSchema.shape,
+  withAuth(
+    conversationTranscriptTool.call,
+    config.genesysCloud,
+    platformClient.ApiClient.instance,
+  ),
+);
+
 const transport = new StdioServerTransport();
 await server.connect(transport);
 console.log("Started...");