# laggyzee/genesys-mcp architecture

> Architecture diagram of the GitHub repository laggyzee/genesys-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/laggyzee/genesys-mcp
- Repository: https://github.com/laggyzee/genesys-mcp

## Overview

genesys-mcp is a local, read-only stdio MCP server for exploring and analyzing a Genesys Cloud contact-centre tenant. The principal workflow is an MCP client request routed by the server to a registered domain tool; the tool queries Genesys through the authenticated client and returns operational results such as queue, agent, conversation, or workforce reports. Separate branches cover coaching, quality, sentiment, repeat contacts/FCR, and workforce management. The source excerpts establish server registration and several shared helpers; unsampled tool internals are represented by README capabilities and SOURCE INDEX references, so uncertain call paths are omitted.

Main entry points: [`src/genesys_mcp/server.py`](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/server.py) (stdio server), [`src/genesys_mcp/tools/repeat_contacts.py`](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/repeat_contacts.py) (Repeat contacts and FCR), [`src/genesys_mcp/tools/reports.py`](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/reports.py) (Operational reports), [`src/genesys_mcp/client.py`](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/client.py) (OAuth API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["MCP interface"]
  node_server["stdio server<br/>[server.py]"]
end

subgraph group_analytics["Operations analytics"]
  node_analytics_tools["Queue and agent analytics<br/>[analytics.py]"]
  node_reports["Operational reports<br/>[reports.py]"]
  node_utilization["Agent utilization<br/>[utilization.py]"]
  node_sentiment["Sentiment analysis<br/>[sentiment.py]"]
  node_coaching["Coaching pack<br/>[coaching.py]"]
  node_quality["Quality reviews<br/>[quality.py]"]
end

subgraph group_contact["Conversation insights"]
  node_conversations["Conversation search<br/>[conversations.py]"]
  node_attribute_search["Attribute search"]
  node_repeat_contacts["Repeat contacts and FCR<br/>[repeat_contacts.py]"]
  node_speech["Speech analytics"]
  node_routing["Routing diagnostics<br/>[routing.py]"]
end

subgraph group_workforce["Workforce operations"]
  node_presence["Presence analysis<br/>[presence.py]"]
  node_wfm["Schedules and adherence<br/>[wfm.py]"]
  node_workforce_history["Workforce history"]
  node_timeoff["Time off<br/>[timeoff.py]"]
end

subgraph group_core["Shared runtime"]
  node_client["OAuth API client<br/>[client.py]"]
  node_aggregates["Aggregate helpers<br/>[_aggregates.py]"]
  node_availability["Archive availability<br/>[_availability.py]"]
  node_details["Conversation details"]
  node_intervals["Time intervals<br/>[_intervals.py]"]
  node_tenant["Tenant configuration<br/>[tenant.py]"]
  node_naming["Name resolution<br/>[naming.py]"]
  node_links["Contact identity links"]
  node_envelopes["Soft-fail envelopes<br/>[_envelopes.py]"]
  node_repeat_config["Repeat report config"]
  node_repeat_cache[("Repeat-contact cache<br/>[repeat_contacts.py]")]
end

node_operator(("MCP client"))
node_genesys["Genesys Cloud"]

node_operator -->|"sends MCP requests"| node_server
node_server -->|"initializes API"| node_client
node_server -->|"registers tools"| node_analytics_tools
node_server -->|"registers tools"| node_reports
node_server -->|"registers tools"| node_utilization
node_server -->|"registers tools"| node_sentiment
node_server -->|"registers tools"| node_coaching
node_server -->|"registers tools"| node_quality
node_server -->|"registers tools"| node_conversations
node_server -->|"registers tools"| node_attribute_search
node_server -->|"registers tools"| node_repeat_contacts
node_server -->|"registers tools"| node_speech
node_server -->|"registers tools"| node_routing
node_server -->|"registers tools"| node_presence
node_server -->|"registers tools"| node_wfm
node_server -->|"registers tools"| node_workforce_history
node_server -->|"registers tools"| node_timeoff
node_client -->|"authenticates API calls"| node_genesys
node_analytics_tools -->|"uses API client"| node_client
node_reports -->|"uses helpers"| node_aggregates
node_reports -->|"uses detail data"| node_details
node_reports -->|"uses intervals"| node_intervals
node_utilization -->|"uses helpers"| node_aggregates
node_utilization -->|"uses intervals"| node_intervals
node_sentiment -->|"uses helpers"| node_aggregates
node_sentiment -->|"reads tenant settings"| node_tenant
node_coaching -->|"uses helpers"| node_aggregates
node_coaching -->|"uses quality tools"| node_quality
node_coaching -->|"uses report tools"| node_reports
node_conversations -.->|"uses API client"| node_client
node_attribute_search -->|"uses intervals"| node_intervals
node_repeat_contacts -->|"fetches details"| node_details
node_repeat_contacts -->|"uses intervals"| node_intervals
node_repeat_contacts -->|"loads configuration"| node_repeat_config
node_repeat_contacts -->|"resolves identity"| node_links
node_repeat_contacts -->|"caches day slices"| node_repeat_cache
node_speech -->|"uses soft-fail shape"| node_envelopes
node_routing -->|"uses report helpers"| node_reports
node_presence -.->|"uses availability"| node_availability
node_wfm -->|"uses intervals"| node_intervals
node_workforce_history -->|"uses API client"| node_client
node_timeoff -->|"uses intervals"| node_intervals
node_naming -->|"fetches names"| node_client

click node_server "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/server.py"
click node_analytics_tools "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/analytics.py"
click node_reports "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/reports.py"
click node_utilization "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/utilization.py"
click node_sentiment "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/sentiment.py"
click node_coaching "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/coaching.py"
click node_quality "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/quality.py"
click node_conversations "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/conversations.py"
click node_attribute_search "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/attribute_search.py"
click node_repeat_contacts "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/repeat_contacts.py"
click node_speech "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/speech_analytics.py"
click node_routing "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/routing.py"
click node_presence "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/presence.py"
click node_wfm "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/wfm.py"
click node_workforce_history "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/workforce_history.py"
click node_timeoff "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/timeoff.py"
click node_client "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/client.py"
click node_aggregates "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/_aggregates.py"
click node_availability "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/_availability.py"
click node_details "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/_conversation_details.py"
click node_intervals "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/_intervals.py"
click node_tenant "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tenant.py"
click node_naming "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/naming.py"
click node_links "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/conversation_links.py"
click node_envelopes "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/_envelopes.py"
click node_repeat_config "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/_repeat_contact_config.py"
click node_repeat_cache "https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/repeat_contacts.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_operator toneBlue
class node_analytics_tools,node_reports,node_utilization,node_sentiment,node_coaching,node_quality toneAmber
class node_conversations,node_attribute_search,node_repeat_contacts,node_speech,node_routing toneMint
class node_presence,node_wfm,node_workforce_history,node_timeoff toneRose
class node_client,node_aggregates,node_availability,node_details,node_intervals,node_tenant,node_naming,node_links,node_envelopes,node_repeat_config,node_repeat_cache,node_genesys toneIndigo
```

## Components

### MCP interface

- [stdio server](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/server.py): `src/genesys_mcp/server.py`

### Operations analytics

- [Queue and agent analytics](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/analytics.py): `src/genesys_mcp/tools/analytics.py`
- [Operational reports](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/reports.py): `src/genesys_mcp/tools/reports.py`
- [Agent utilization](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/utilization.py): `src/genesys_mcp/tools/utilization.py`
- [Sentiment analysis](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/sentiment.py): `src/genesys_mcp/tools/sentiment.py`
- [Coaching pack](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/coaching.py): `src/genesys_mcp/tools/coaching.py`
- [Quality reviews](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/quality.py): `src/genesys_mcp/tools/quality.py`

### Conversation insights

- [Conversation search](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/conversations.py): `src/genesys_mcp/tools/conversations.py`
- [Attribute search](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/attribute_search.py): `src/genesys_mcp/tools/attribute_search.py`
- [Repeat contacts and FCR](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/repeat_contacts.py): `src/genesys_mcp/tools/repeat_contacts.py`
- [Speech analytics](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/speech_analytics.py): `src/genesys_mcp/tools/speech_analytics.py`
- [Routing diagnostics](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/routing.py): `src/genesys_mcp/tools/routing.py`

### Workforce operations

- [Presence analysis](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/presence.py): `src/genesys_mcp/tools/presence.py`
- [Schedules and adherence](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/wfm.py): `src/genesys_mcp/tools/wfm.py`
- [Workforce history](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/workforce_history.py): `src/genesys_mcp/tools/workforce_history.py`
- [Time off](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/timeoff.py): `src/genesys_mcp/tools/timeoff.py`

### Shared runtime

- [OAuth API client](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/client.py): `src/genesys_mcp/client.py`
- [Aggregate helpers](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/_aggregates.py): `src/genesys_mcp/_aggregates.py`
- [Archive availability](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/_availability.py): `src/genesys_mcp/_availability.py`
- [Conversation details](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/_conversation_details.py): `src/genesys_mcp/_conversation_details.py`
- [Time intervals](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/_intervals.py): `src/genesys_mcp/_intervals.py`
- [Tenant configuration](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tenant.py): `src/genesys_mcp/tenant.py`
- [Name resolution](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/naming.py): `src/genesys_mcp/naming.py`
- [Contact identity links](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/conversation_links.py): `src/genesys_mcp/conversation_links.py`
- [Soft-fail envelopes](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/_envelopes.py): `src/genesys_mcp/_envelopes.py`
- [Repeat report config](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/_repeat_contact_config.py): `src/genesys_mcp/_repeat_contact_config.py`
- [Repeat-contact cache](https://github.com/laggyzee/genesys-mcp/blob/main/src/genesys_mcp/tools/repeat_contacts.py): `src/genesys_mcp/tools/repeat_contacts.py`

### Other components

- **MCP client**
- **Genesys Cloud**

## Connections

- MCP client → stdio server: sends MCP requests
- stdio server → OAuth API client: initializes API (evidence: `src/genesys_mcp/server.py`)
- stdio server → Queue and agent analytics: registers tools (evidence: `src/genesys_mcp/server.py`)
- stdio server → Operational reports: registers tools (evidence: `src/genesys_mcp/server.py`)
- stdio server → Agent utilization: registers tools (evidence: `src/genesys_mcp/server.py`)
- stdio server → Sentiment analysis: registers tools (evidence: `src/genesys_mcp/server.py`)
- stdio server → Coaching pack: registers tools (evidence: `src/genesys_mcp/server.py`)
- stdio server → Quality reviews: registers tools (evidence: `src/genesys_mcp/server.py`)
- stdio server → Conversation search: registers tools (evidence: `src/genesys_mcp/server.py`)
- stdio server → Attribute search: registers tools (evidence: `src/genesys_mcp/server.py`)
- stdio server → Repeat contacts and FCR: registers tools (evidence: `src/genesys_mcp/server.py`)
- stdio server → Speech analytics: registers tools (evidence: `src/genesys_mcp/server.py`)
- stdio server → Routing diagnostics: registers tools (evidence: `src/genesys_mcp/server.py`)
- stdio server → Presence analysis: registers tools (evidence: `src/genesys_mcp/server.py`)
- stdio server → Schedules and adherence: registers tools (evidence: `src/genesys_mcp/server.py`)
- stdio server → Workforce history: registers tools (evidence: `src/genesys_mcp/server.py`)
- stdio server → Time off: registers tools (evidence: `src/genesys_mcp/server.py`)
- OAuth API client → Genesys Cloud: authenticates API calls (evidence: `src/genesys_mcp/client.py`)
- Queue and agent analytics → OAuth API client: uses API client (evidence: `src/genesys_mcp/server.py`)
- Operational reports → Aggregate helpers: uses helpers (evidence: `src/genesys_mcp/tools/reports.py`)
- Operational reports → Conversation details: uses detail data (evidence: `src/genesys_mcp/tools/reports.py`)
- Operational reports → Time intervals: uses intervals (evidence: `src/genesys_mcp/tools/reports.py`)
- Agent utilization → Aggregate helpers: uses helpers (evidence: `src/genesys_mcp/tools/utilization.py`)
- Agent utilization → Time intervals: uses intervals (evidence: `src/genesys_mcp/tools/utilization.py`)
- Sentiment analysis → Aggregate helpers: uses helpers (evidence: `src/genesys_mcp/tools/sentiment.py`)
- Sentiment analysis → Tenant configuration: reads tenant settings (evidence: `src/genesys_mcp/tools/sentiment.py`)
- Coaching pack → Aggregate helpers: uses helpers (evidence: `src/genesys_mcp/tools/coaching.py`)
- Coaching pack → Quality reviews: uses quality tools (evidence: `src/genesys_mcp/tools/coaching.py`)
- Coaching pack → Operational reports: uses report tools (evidence: `src/genesys_mcp/tools/coaching.py`)
- Conversation search → OAuth API client: uses API client
- Attribute search → Time intervals: uses intervals (evidence: `src/genesys_mcp/tools/attribute_search.py`)
- Repeat contacts and FCR → Conversation details: fetches details (evidence: `src/genesys_mcp/tools/repeat_contacts.py`)
- Repeat contacts and FCR → Time intervals: uses intervals (evidence: `src/genesys_mcp/tools/repeat_contacts.py`)
- Repeat contacts and FCR → Repeat report config: loads configuration (evidence: `src/genesys_mcp/tools/repeat_contacts.py`)
- Repeat contacts and FCR → Contact identity links: resolves identity (evidence: `src/genesys_mcp/tools/repeat_contacts.py`)
- Repeat contacts and FCR → Repeat-contact cache: caches day slices (evidence: `src/genesys_mcp/tools/repeat_contacts.py`)
- Speech analytics → Soft-fail envelopes: uses soft-fail shape (evidence: `src/genesys_mcp/tools/speech_analytics.py`)
- Routing diagnostics → Operational reports: uses report helpers (evidence: `src/genesys_mcp/tools/routing.py`)
- Presence analysis → Archive availability: uses availability
- Schedules and adherence → Time intervals: uses intervals (evidence: `src/genesys_mcp/tools/wfm.py`)
- Workforce history → OAuth API client: uses API client (evidence: `src/genesys_mcp/tools/workforce_history.py`)
- Time off → Time intervals: uses intervals (evidence: `src/genesys_mcp/tools/timeoff.py`)
- Name resolution → OAuth API client: fetches names (evidence: `src/genesys_mcp/naming.py`)
