genesys-cloud-mcp-plus/README.md

Genesys Cloud MCP Plus - Advanced Model Context Protocol server with 15 comprehensive tools for contact center analytics, real-time monitoring, and wrap-up code analysis. Enhanced with multi-media support and enterprise-grade features.

# Genesys Cloud MCP Plus

🚀 **Advanced Model Context Protocol Server for Genesys Cloud**

A comprehensive MCP server providing 15 powerful tools for contact center analytics, real-time monitoring, and intelligent conversation analysis. Designed for enterprise-grade AI applications with full omnichannel support.

## 🌟 Features

### 📊 **Historical Analytics (8 Tools)**
- **Queue Volume Analysis** - Compare conversation volumes across queues
- **Conversation Sampling** - Retrieve representative conversation samples
- **Voice Call Quality** - Analyze MOS scores and call quality metrics
- **Conversation Sentiment** - Sentiment analysis across interactions
- **Conversation Topics** - Extract business topics and intents
- **Conversation Transcripts** - Full conversation transcripts with timestamps
- **Enhanced Media Search** - Multi-channel conversation discovery
- **Agent Performance Analytics** - Media-type breakdown of agent metrics

### ⚡ **Real-Time Monitoring (3 Tools)**
- **Live Queue Status** - Real-time queue metrics and agent availability
- **Agent Presence Monitoring** - Current agent status and routing state
- **Active Conversation Tracking** - Monitor ongoing customer interactions

### 🏷️ **Wrap-Up Code Analytics (1 Tool)**
- **Comprehensive Wrap-Up Analysis** - Understand interaction types and volumes
- **Multi-language Support** - Handles Arabic/English bilingual environments
- **Queue-specific Filtering** - Targeted analysis by queue or service area

### 🔍 **Utility Tools (3 Tools)**
- **Queue Search** - Find queues by name with wildcard support
- **Agent Directory** - Monitor agent information and status
- **Enhanced Conversation Search** - Advanced filtering across all media types

## 📋 **Supported Media Types**
- 📞 Voice calls
- 💬 Chat interactions  
- 📧 Email conversations
- 📱 SMS/Text messaging
- 🤖 Bot interactions
- 📹 Video calls
- 🌐 Social media interactions
- 📞 Callback requests

## 🛠️ Installation

### NPM Installation
```bash
npm install -g genesys-cloud-mcp-plus
```

### Manual Installation
```bash
git clone https://github.com/AmrKhalil9/genesys-cloud-mcp-plus.git
cd genesys-cloud-mcp-plus
npm install
npm run build
```

## ⚙️ Configuration

### Environment Variables
```bash
export GENESYSCLOUD_REGION="your-region"  # e.g., "eu-central-1", "me-central-1", "us-east-1"
export GENESYSCLOUD_OAUTHCLIENT_ID="your-client-id"
export GENESYSCLOUD_OAUTHCLIENT_SECRET="your-client-secret"
```

**Region Examples:**
- **UAE/Middle East**: `me-central-1`
- **EMEA**: `eu-central-1`
- **Americas**: `us-east-1`
- **Australia**: `ap-southeast-2`
- **Japan**: `ap-northeast-1`

### Supported Regions

#### **🌎 Americas (5 Regions)**
- `us-east-1` → `mypurecloud.com` (Americas - Main)
- `us-east-2` → `use2.us-gov-pure.cloud` (FedRAMP - US Government)
- `us-west-2` → `usw2.pure.cloud` (US West)
- `ca-central-1` → `cac1.pure.cloud` (Canada)
- `sa-east-1` → `sae1.pure.cloud` (South America)

#### **🌍 Europe, Middle East, Africa (5 Regions)**
- `eu-central-1` → `mypurecloud.de` (EMEA - Main)
- `eu-west-1` → `mypurecloud.ie` (Ireland)
- `eu-west-2` → `euw2.pure.cloud` (Europe West 2)
- `eu-central-2` → `euc2.pure.cloud` (Europe Central 2)
- `me-central-1` → `mec1.pure.cloud` (Middle East - UAE)

#### **🌏 Asia Pacific (5 Regions)**
- `ap-southeast-2` → `mypurecloud.com.au` (Australia)
- `ap-northeast-1` → `mypurecloud.jp` (Japan)
- `ap-south-1` → `aps1.pure.cloud` (Asia Pacific South)
- `ap-northeast-2` → `apne2.pure.cloud` (Asia Pacific Northeast 2)
- `ap-northeast-3` → `apne3.pure.cloud` (Asia Pacific Northeast 3)

**Total: 15 Regions** - Full global coverage including UAE/Middle East support!

### OAuth Permissions Required
Your OAuth client needs these permissions:
- `analytics:conversationAggregate:view`
- `analytics:conversationDetail:view`
- `routing:queue:view`
- `users:basic:view`
- `presence:basic:view`
- `speechandtextanalytics:data:view`

## 🚀 Usage

### Claude Desktop Integration

#### **Method 1: Global Installation (Recommended)**
First install globally:
```bash
npm install -g genesys-cloud-mcp-plus
```

Then add to your `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "genesys-cloud-mcp-plus": {
      "type": "stdio",
      "command": "genesys-cloud-mcp-plus",
      "env": {
        "GENESYSCLOUD_REGION": "eu-central-1",
        "GENESYSCLOUD_OAUTHCLIENT_ID": "<PUT OAUTHCLIENT ID HERE>",
        "GENESYSCLOUD_OAUTHCLIENT_SECRET": "<PUT OAUTHCLIENT SECRET HERE>"
      }
    }
  }
}
```

#### **Method 2: NPX (No Installation Required)**
Add this to your `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "genesys-cloud-mcp-plus": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "genesys-cloud-mcp-plus"],
      "env": {
        "GENESYSCLOUD_REGION": "eu-central-1",
        "GENESYSCLOUD_OAUTHCLIENT_ID": "<PUT OAUTHCLIENT ID HERE>",
        "GENESYSCLOUD_OAUTHCLIENT_SECRET": "<PUT OAUTHCLIENT SECRET HERE>"
      }
    }
  }
}
```

#### **Configuration Examples by Region:**
- **UAE/Middle East**: `"GENESYSCLOUD_REGION": "me-central-1"`
- **EMEA**: `"GENESYSCLOUD_REGION": "eu-central-1"`
- **Americas**: `"GENESYSCLOUD_REGION": "us-east-1"`
- **Australia**: `"GENESYSCLOUD_REGION": "ap-southeast-2"`
- **Japan**: `"GENESYSCLOUD_REGION": "ap-northeast-1"`
- **FedRAMP**: `"GENESYSCLOUD_REGION": "us-east-2"`

#### **Complete Example Configuration:**
```json
{
  "mcpServers": {
    "genesys-cloud-mcp-plus": {
      "type": "stdio",
      "command": "genesys-cloud-mcp-plus",
      "env": {
        "GENESYSCLOUD_REGION": "me-central-1",
        "GENESYSCLOUD_OAUTHCLIENT_ID": "29aa13c7-1693-47dc-8672-fb502990971c",
        "GENESYSCLOUD_OAUTHCLIENT_SECRET": "bCoYOs1qeOcXjDfwQM6XVA-kfYIl0wYiLyLVrbj7IAc"
      }
    }
  }
}
```

### Quick Setup Guide

1. **Install the package:**
   ```bash
   npm install -g genesys-cloud-mcp-plus
   ```

2. **Get your Genesys Cloud credentials:**
   - Go to Genesys Cloud Admin → Integrations → OAuth
   - Create a new OAuth client with required permissions
   - Copy the Client ID and Client Secret

3. **Configure Claude Desktop:**
   - Open `claude_desktop_config.json`
   - Add the MCP server configuration (see examples above)
   - Replace placeholders with your actual credentials

4. **Restart Claude Desktop** and start exploring your data!

### Command Line
```bash
# Start the MCP server
genesys-cloud-mcp-plus

# Development mode
npm run dev

# Build for production
npm run build
```

## 📚 Tool Reference

### Historical Analytics
| Tool | Purpose | Use Case |
|------|---------|----------|
| `search_queues` | Find queues by name | "Find all sales queues" |
| `query_queue_volumes` | Compare queue volumes | "Which queue is busiest today?" |
| `sample_conversations_by_queue` | Get conversation samples | "Show me recent support calls" |
| `voice_call_quality` | Analyze call quality | "Check call quality for conversation X" |
| `conversation_sentiment` | Sentiment analysis | "What's the sentiment of these calls?" |
| `conversation_topics` | Topic detection | "What topics were discussed?" |
| `conversation_transcript` | Full transcripts | "Get transcript for conversation X" |
| `enhanced_conversation_search` | Multi-media search | "Find all chat conversations today" |

### Real-Time Monitoring  
| Tool | Purpose | Use Case |
|------|---------|----------|
| `real_time_queue_status` | Live queue metrics | "How many agents are available?" |
| `real_time_agent_presence` | Agent status monitoring | "Who's online right now?" |
| `live_conversation_monitoring` | Active interactions | "What conversations are happening?" |

### Analytics & Insights
| Tool | Purpose | Use Case |
|------|---------|----------|
| `wrap_up_code_analytics` | Interaction type analysis | "How many inquiries came today?" |
| `agent_media_type_performance` | Agent performance by channel | "How is John performing on chat?" |
| `agent_status_monitoring` | Agent directory | "Show me all active agents" |
| `search_voice_conversations` | Voice-specific search | "Find voice calls from this number" |

## 🔍 Example Queries

### Business Intelligence
```
"What were the top 3 wrap-up codes for our support queue this week?"
"Which agents handled the most chat conversations yesterday?"
"Show me sentiment analysis for all conversations from customer X"
```

### Operations Monitoring
```
"How many agents are currently available?"
"What conversations are active right now?"
"Which queue has the longest wait times?"
```

### Quality Assurance
```
"Find conversations with poor call quality scores"
"What topics are customers asking about most?"
"Show me transcripts from escalated calls"
```

## 🛡️ Enterprise Features

- **🔒 Secure Authentication** - OAuth 2.0 with client credentials
- **🌍 Multi-Region Support** - Works with all Genesys Cloud regions
- **🗣️ Multi-Language** - Supports bilingual environments (Arabic/English)
- **📊 Comprehensive Analytics** - 15 different analytical perspectives
- **⚡ Real-Time Data** - Live monitoring capabilities
- **🔧 Production Ready** - Error handling, logging, and retry logic

## 📖 Documentation

- [AI Agent Guide](./AI_AGENT_GUIDE.md) - Complete guide for AI implementations
- [Changelog](./CHANGELOG.md) - Version history and new features
- [API Reference](./docs/API.md) - Detailed tool documentation

## 👥 Authors & Contributors

### Original Author
**Lucas Woodward** - [MakingChatbots.com](https://makingchatbots.com)
- Created the foundational MCP server with 8 core analytics tools
- Established the original architecture and Genesys Cloud integration

### Enhanced Version
**Amr Khalil**
- Added 7 new tools including real-time monitoring and wrap-up code analytics
- Enhanced existing tools with improved error handling and performance
- Transformed basic server into comprehensive enterprise-grade platform

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

## 📝 License

ISC License - see [LICENSE](./LICENSE) for details.

## 🔗 Links

- [GitHub Repository](https://github.com/AmrKhalil9/genesys-cloud-mcp-plus)
- [NPM Package](https://www.npmjs.com/package/genesys-cloud-mcp-plus)
- [MakingChatbots.com](https://makingchatbots.com)

## 📞 Support

For issues, questions, or feature requests:
- GitHub Issues: [Report here](https://github.com/AmrKhalil9/genesys-cloud-mcp-plus/issues)
- Documentation: Check the AI Agent Guide for implementation details

---

**Built with ❤️ for the AI and Contact Center Community**