Add title annotation to tools (#24)

Author: SketchingDev

Dockerfile

@@ -0,0 +1,22 @@
+FROM node:22.12-alpine AS builder
+
+COPY ./ /app
+
+WORKDIR /app
+
+RUN --mount=type=cache,target=/root/.npm npm install
+RUN --mount=type=cache,target=/root/.npm npm run build
+
+FROM node:22.12-alpine AS release
+
+WORKDIR /app
+
+COPY --from=builder /app/dist /app/dist
+COPY --from=builder /app/package.json /app/package.json
+COPY --from=builder /app/package-lock.json /app/package-lock.json
+
+ENV NODE_ENV=production
+
+RUN npm ci --ignore-scripts --omit-dev
+
+ENTRYPOINT ["node", "dist/index.js"]

README.md

@@ -5,10 +5,7 @@
 
 A Model Context Protocol (MCP) server for Genesys Cloud's Platform API.
 
-## Tools Overview
-
-An overview of the tools that this MCP server makes available. Read more about each specific tool
-in the [tools doc](/docs/tools.md).
+## Features
 
 | Tool                                                                          | Description                                                              |
 | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
@@ -21,6 +18,29 @@ in the [tools doc](/docs/tools.md).
 | [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                                        |
 
+## Usage with Claude Desktop
+
+Add this to your `claude_desktop_config.json`:
+
+### NPX
+
+```json
+{
+  "mcpServers": {
+    "genesys-cloud": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@makingchatbots/genesys-cloud-mcp-server"],
+      "env": {
+        "GENESYSCLOUD_REGION": "<PUT REGION HERE>",
+        "GENESYSCLOUD_OAUTHCLIENT_ID": "<PUT OAUTHCLIENT ID HERE>",
+        "GENESYSCLOUD_OAUTHCLIENT_SECRET": "<PUT OAUTHCLIENT SECRET HERE>"
+      }
+    }
+  }
+}
+```
+
 ## Authentication
 
 This currently only supports a stdio server. To configure authentication you'll need to:
@@ -32,7 +52,9 @@ This currently only supports a stdio server. To configure authentication you'll
    - `GENESYSCLOUD_OAUTHCLIENT_ID`
    - `GENESYSCLOUD_OAUTHCLIENT_SECRET`
 
-## Getting Started
+## Development
+
+### Getting Started
 
 ```bash
 nvm use

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@makingchatbots/genesys-cloud-mcp-server",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "description": "A Model Context Protocol (MCP) server exposing Genesys Cloud tools for LLMs, including sentiment analysis, conversation search, topic detection and more.",
   "bin": "./dist/cli.js",
   "type": "module",

src/auth/OAuthClientCredentialsWrapper.ts

@@ -1,8 +1,8 @@
+import { z } from "zod";
 import { type ApiClientClass } from "purecloud-platform-client-v2";
 import { type ToolCall } from "../tools/utils/createTool.js";
-import { ConfigRetriever } from "../createConfigRetriever.js";
+import { type ConfigRetriever } from "../createConfigRetriever.js";
 import { errorResult } from "../tools/utils/errorResult.js";
-import { z } from "zod";
 
 let isAuthenticated = false;
 

src/index.ts

@@ -11,17 +11,15 @@ import { conversationTopics } from "./tools/conversationTopics/conversationTopic
 import { searchVoiceConversations } from "./tools/searchVoiceConversations.js";
 import { conversationTranscription } from "./tools/conversationTranscription/conversationTranscription.js";
 import { OAuthClientCredentialsWrapper } from "./auth/OAuthClientCredentialsWrapper.js";
-import packageInfo from "../package.json" with { type: "json" };
 
-const configRetriever = createConfigRetriever(process.env);
 const withAuth = OAuthClientCredentialsWrapper(
-  configRetriever,
+  createConfigRetriever(process.env),
   platformClient.ApiClient.instance,
 );
 
 const server: McpServer = new McpServer({
   name: "Genesys Cloud",
-  version: packageInfo.version,
+  version: "0.0.13", // Same version as version in package.json
 });
 
 const routingApi = new platformClient.RoutingApi();
@@ -34,9 +32,7 @@ server.tool(
   searchQueuesTool.schema.name,
   searchQueuesTool.schema.description,
   searchQueuesTool.schema.paramsSchema.shape,
-  {
-    title: "",
-  },
+  searchQueuesTool.schema.annotations,
   withAuth(searchQueuesTool.call),
 );
 
@@ -47,6 +43,7 @@ server.tool(
   sampleConversationsByQueueTool.schema.name,
   sampleConversationsByQueueTool.schema.description,
   sampleConversationsByQueueTool.schema.paramsSchema.shape,
+  sampleConversationsByQueueTool.schema.annotations,
   withAuth(sampleConversationsByQueueTool.call),
 );
 
@@ -55,6 +52,7 @@ server.tool(
   queryQueueVolumesTool.schema.name,
   queryQueueVolumesTool.schema.description,
   queryQueueVolumesTool.schema.paramsSchema.shape,
+  queryQueueVolumesTool.schema.annotations,
   withAuth(queryQueueVolumesTool.call),
 );
 
@@ -63,6 +61,7 @@ server.tool(
   voiceCallQualityTool.schema.name,
   voiceCallQualityTool.schema.description,
   voiceCallQualityTool.schema.paramsSchema.shape,
+  voiceCallQualityTool.schema.annotations,
   withAuth(voiceCallQualityTool.call),
 );
 
@@ -73,6 +72,7 @@ server.tool(
   conversationSentimentTool.schema.name,
   conversationSentimentTool.schema.description,
   conversationSentimentTool.schema.paramsSchema.shape,
+  conversationSentimentTool.schema.annotations,
   withAuth(conversationSentimentTool.call),
 );
 
@@ -84,6 +84,7 @@ server.tool(
   conversationTopicsTool.schema.name,
   conversationTopicsTool.schema.description,
   conversationTopicsTool.schema.paramsSchema.shape,
+  conversationTopicsTool.schema.annotations,
   withAuth(conversationTopicsTool.call),
 );
 
@@ -94,6 +95,7 @@ server.tool(
   searchVoiceConversationsTool.schema.name,
   searchVoiceConversationsTool.schema.description,
   searchVoiceConversationsTool.schema.paramsSchema.shape,
+  searchVoiceConversationsTool.schema.annotations,
   withAuth(searchVoiceConversationsTool.call),
 );
 
@@ -106,6 +108,7 @@ server.tool(
   conversationTranscriptTool.schema.name,
   conversationTranscriptTool.schema.description,
   conversationTranscriptTool.schema.paramsSchema.shape,
+  conversationTranscriptTool.schema.annotations,
   withAuth(conversationTranscriptTool.call),
 );
 

src/tools/conversationSentiment/conversationSentiment.test.ts

@@ -1,13 +1,13 @@
 import { beforeEach, describe, expect, test, vi } from "vitest";
-import { MockedObjectDeep } from "@vitest/spy";
+import { type MockedObjectDeep } from "@vitest/spy";
 import { randomUUID } from "node:crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
-import { McpError } from "@modelcontextprotocol/sdk/types.js";
+import { type McpError } from "@modelcontextprotocol/sdk/types.js";
 import {
   conversationSentiment,
-  ToolDependencies,
+  type ToolDependencies,
 } from "./conversationSentiment.js";
 
 describe("Conversation Sentiment Tool", () => {
@@ -30,6 +30,7 @@ describe("Conversation Sentiment Tool", () => {
       toolDefinition.schema.name,
       toolDefinition.schema.description,
       toolDefinition.schema.paramsSchema.shape,
+      toolDefinition.schema.annotations,
       toolDefinition.call,
     );
 
@@ -47,6 +48,7 @@ describe("Conversation Sentiment Tool", () => {
     expect(tools.tools[0]).toStrictEqual({
       name: "conversation_sentiment",
       title: undefined,
+      annotations: { title: "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.",
       inputSchema: {
@@ -70,7 +72,6 @@ describe("Conversation Sentiment Tool", () => {
         additionalProperties: false,
         $schema: "http://json-schema.org/draft-07/schema#",
       },
-      annotations: undefined,
     });
   });
 

src/tools/conversationSentiment/conversationSentiment.ts

@@ -40,6 +40,7 @@ export const conversationSentiment: ToolFactory<
       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.",
+      annotations: { title: "Conversation Sentiment" },
       paramsSchema,
     },
     call: async ({ conversationIds }) => {

src/tools/conversationTopics/conversationTopics.test.ts

@@ -1,11 +1,14 @@
 import { beforeEach, describe, expect, test, vi } from "vitest";
-import { MockedObjectDeep } from "@vitest/spy";
+import { type MockedObjectDeep } from "@vitest/spy";
 import { randomUUID } from "node:crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
-import { McpError } from "@modelcontextprotocol/sdk/types.js";
-import { conversationTopics, ToolDependencies } from "./conversationTopics.js";
+import { type McpError } from "@modelcontextprotocol/sdk/types.js";
+import {
+  conversationTopics,
+  type ToolDependencies,
+} from "./conversationTopics.js";
 
 describe("Conversation Topics Tool", () => {
   let toolDeps: MockedObjectDeep<ToolDependencies>;
@@ -31,6 +34,7 @@ describe("Conversation Topics Tool", () => {
       toolDefinition.schema.name,
       toolDefinition.schema.description,
       toolDefinition.schema.paramsSchema.shape,
+      toolDefinition.schema.annotations,
       toolDefinition.call,
     );
 
@@ -48,6 +52,7 @@ describe("Conversation Topics Tool", () => {
     expect(tools.tools[0]).toStrictEqual({
       name: "conversation_topics",
       title: undefined,
+      annotations: { title: "Conversation Topics" },
       description:
         "Retrieves Speech and Text Analytics topics detected for a specific conversation. Topics represent business-level intents (e.g. cancellation, billing enquiry) inferred from recognised phrases in the customer-agent interaction.",
       inputSchema: {
@@ -64,7 +69,6 @@ describe("Conversation Topics Tool", () => {
         additionalProperties: false,
         $schema: "http://json-schema.org/draft-07/schema#",
       },
-      annotations: undefined,
     });
   });
 

src/tools/conversationTopics/conversationTopics.ts

@@ -39,6 +39,7 @@ export const conversationTopics: ToolFactory<
   createTool({
     schema: {
       name: "conversation_topics",
+      annotations: { title: "Conversation Topics" },
       description:
         "Retrieves Speech and Text Analytics topics detected for a specific conversation. Topics represent business-level intents (e.g. cancellation, billing enquiry) inferred from recognised phrases in the customer-agent interaction.",
       paramsSchema,

src/tools/conversationTranscription/conversationTranscription.test.ts

@@ -1,14 +1,14 @@
 import { beforeEach, describe, expect, test, vi } from "vitest";
-import { MockedObjectDeep } from "@vitest/spy";
+import { type MockedObjectDeep } from "@vitest/spy";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { randomUUID } from "node:crypto";
 import {
   conversationTranscription,
-  ToolDependencies,
+  type ToolDependencies,
 } from "./conversationTranscription.js";
-import { TranscriptResponseFormat } from "./TranscriptResponse.js";
+import { type TranscriptResponseFormat } from "./TranscriptResponse.js";
 
 describe("Conversation Transcription Tool", () => {
   let toolDeps: MockedObjectDeep<ToolDependencies>;
@@ -35,6 +35,7 @@ describe("Conversation Transcription Tool", () => {
       toolDefinition.schema.name,
       toolDefinition.schema.description,
       toolDefinition.schema.paramsSchema.shape,
+      toolDefinition.schema.annotations,
       toolDefinition.call,
     );
 
@@ -52,6 +53,7 @@ describe("Conversation Transcription Tool", () => {
     expect(tools.tools[0]).toStrictEqual({
       name: "conversation_transcript",
       title: undefined,
+      annotations: { title: "Conversation Transcript" },
       description:
         "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)",
       inputSchema: {
@@ -69,7 +71,6 @@ describe("Conversation Transcription Tool", () => {
 
         $schema: "http://json-schema.org/draft-07/schema#",
       },
-      annotations: undefined,
     });
   });