genesys-mcp

# genesys-mcp A local stdio MCP server that gives Claude Code (or any MCP-compatible client) read-only access to a Genesys Cloud tenant. Built so contact-centre operations and analytics work — queue performance, agent reviews, conversation deep-dives, repeat-caller root-cause analysis, presence/break/away analysis, demand-vs-capacity vs WFM, monthly contact-centre reports — can be done by talking to Claude in plain English instead of clicking through Genesys Admin or Performance dashboards. > **v1.24.0 — September 2026:** **Repeat Contacts & FCR.** New `get_repeat_contact_report` tool reports the Repeat Contact Rate and the derived **FCR** (= 1 − repeat rate) for every window × channel — 7 / 45 days (configurable) × Voice / Messaging / Combined — with cross-channel customer identity (External Contact link → merge/canonical resolution → identifier lookup → normalised raw identifier), a per-channel identity **coverage** block, a lookback that matches but never counts, optional by-day / by-queue breakdowns and a repeat-conversation drill-down. Scope and identity rules live in a runtime-editable `repeatContactReport` config (`get_repeat_contact_config` / `set_repeat_contact_config`, plus `GENESYS_MCP_REPEAT_*` env pins). Settled day-slices and contact resolutions are cached on disk so adjacent periods don't refetch the lookback. 783 tests; 58 tools. > > **v1.23.0 — September 2026:** **brand-level sentiment.** New `sentiment_summary` tool answers *"what was each brand's sentiment last week, and did it move?"* in one call — wraps the transcript-aggregates endpoint (`oSentimentScore` + customer phrase counts) grouped by queue × media, rolls up to brand via tenant.yaml `queues.name_pattern` (skip-listed queues excluded), fires the prior period in parallel for `delta_sentiment`, and keeps no-queue bot/flow rows in a separate `unattributed` block instead of dragging brand means down. Soft-fails on 403 naming the exact scope. 708 tests; 55 tools. > > **v1.20.0 — July 2026:** **participant-attribute search rewritten against the endpoint's real contract.** The Genesys endpoint only supports conversationId/startTime/endTime/divisionId as searchable fields, so the old attribute-criterion request drew a 400 "Search not supported." on every call once the product flag was enabled. `search_conversations_by_attribute` now pulls startTime windows (4h, or 12h for spans over a week; cursor-paginated, newest first, deduplicated) and filters attributes client-side: "key exists with any value" is the default (no more 0–10 enumeration silently dropping "9.0"/"N/A"/non-0–10 scales), a new `available_keys` block lists every key actually seen (with a "did you mean" note on case mismatches), NPS detection tolerates whole-number decimals and no-response sentinels, and queue/agent row ids come from a batched analytics details lookup (best-effort). 30-day retention clamping, a page budget, and `conversations_scanned`/`truncated` keep the limits honest. Rebuild-only — same tool name/count, output additive. 679 tests; 52 tools. > > **v1.19.0 — July 2026:** **recent conversation-detail fallback.** When the async conversations/details archive watermark is behind, `repeat_caller_report` and `repeat_caller_deep_dive` now paginate the synchronous details query and accept it only when every reported `totalHits` row was retrieved exactly once. The tools expose whether the result is complete, provisional, archived, which endpoint supplied it, and the pagination validation. Daily-brief consumers can therefore include yesterday&rsquo;s repeat-caller section while retaining the later authoritative archive repair. > > **v1.18.0 — July 2026:** **fresh-presence fallback + utilization correctness.** When Genesys' archived users/details watermark is behind, `presence_sessions` and `break_overrun_report` now use the recent synchronous details endpoint and accept it only after reconciling active-user durations against qualified user aggregates; the response says whether data is complete, provisional, archived, and which source was used. `agent_utilization` no longer groups by the invalid `routingStatus` dimension: it groups by `userId` and reads routing/presence categories from metric qualifiers, restoring agent effectiveness and occupancy comparisons. Conversation-detail watermark fields survive summary mode. Startup logs and `mcp_health_check` now expose the installed MCP version so stale deployed images are obvious. See the full v1.18 notes for the source-selection, reconciliation, and failure contracts. > > **v1.17.0 — July 2026:** **details-datalake availability.** Presence and repeat-caller tools now query the relevant Genesys availability watermark and explicitly mark recent results incomplete when the requested interval extends past it. Users/details and conversations/details are tracked separately, preventing a successful async job from being mistaken for complete data when its datalake is still settling. > > **v1.16.0 — July 2026:** **customer-first callback correctness.** New `callback_outcomes` classifies conversation details into reached/bridged/not-answered/never-dialled outcomes. Callback aggregate rows no longer report misleading answered or abandoned percentages: customer-first callback outcomes book onto the bridged voice leg, so callback media aggregates cannot measure reach rate. > > **v1.15.0 — July 2026:** **endpoint-correctness pass.** A batch of request/response-shape fixes verified against the Genesys Platform API schema: `search_conversations` now puts ani/queue/user/direction predicates in `segmentFilters` (they were silently ignored in `conversationFilters`); `routing_diagnostic`'s outcome/transfer/eligibility classification now uses real fields (agent-interact segments + `disconnectType`, not the nonexistent `flaggedReason`/`segmentType=="transfer"`) and no longer fabricates skill eligibility; `agent_adherence_review` reads `result.entities` (not top-level `entities`) and adds an `explanations_available` flag so a fetch failure can't be mistaken for "no explanation exists"; `wfm_schedule`'s management-unit discovery no longer calls a 404-only endpoint; `search_conversations_by_attribute` now paginates via the endpoint's real `cursor` field instead of a `pageCount` that was never returned. Plus smaller field-name corrections (recording duration, time-off reviewer, workforce hire date, external-contact identifier types, a bad permission name in a utilization note) and two client-resilience fixes (401 refresh now re-authenticates the same client object; a non-numeric `Retry-After` header no longer crashes the retry loop). 616 tests; 52 tools. > > **v1.14.1 — June 2026:** **bug fix.** `agent_adherence_history` (added in v1.14.0) used the MU-level `historicaladherencequery` endpoint, which is **notification-only** — it returns `downloadUrls: []` and delivers the result over a notification topic, so the tool always soft-failed "still processing" (verified live). Rewired to the **bulk historical-adherence jobs** API (`POST /adherence/historical/bulk` → poll `GET …/bulk/jobs/{id}` → presigned `userResults` download), which is genuinely synchronous-pollable and completes in seconds. Signature is now `management_unit_ids: list[str]` (one item per MU). Works under `workforce-management:readonly` — no extra scope needed. 593 tests; 52 tools. > > **v1.14.0 — June 2026:** **WFM accuracy + adherence coverage.** (1) New `agent_adherence_history` tool returns actual-vs-scheduled **adherence % / conformance %** in-session (submits the async Genesys historical-adherence query, then polls the result download) — the numbers `agent_adherence_review` deliberately doesn't compute. (2) `wfm_schedule` fixed: shift hours are now bucketed by the **business-unit/tenant timezone** (was UTC `.date()`, mis-attributing Sydney shifts to the wrong day — the phantom "11.5h Saturday"), **published schedules only**, and shift activities **de-duplicated** so overlapping schedules can't double-count. (3) Long (multi-year) analytics-aggregate spans now **chunk into ≤12-month sub-queries and merge** in `queue_performance`/`agent_performance`/`agent_utilization`/`volume_vs_forecast`. (4) `agent_utilization`'s missing-scope note reworded so the agent reports `analytics:agentRouting:view` as a *missing scope*, not a tenant block. Tool-selection guidance added to `user_activity_history` (multi-year trends) and `search_conversations_by_attribute` (NPS). 592 tests; 52 tools. > > **v1.13.2 — June 2026:** **bug fix.** `wfm_time_off_requests` was calling `POST /businessunits/{id}/timeoffrequests/query` — an endpoint that doesn't exist in the Genesys Platform API schema. Every call 404'd, surfacing as *"unplanned leave not found"* in reports. The real endpoint is MU-scoped at `/managementunits/{muId}/timeoffrequests/query` (perm `wfm:timeOffRequest:view`). Fixed by adding required `management_unit_ids` param and fanning out one query per MU via `ThreadPoolExecutor`. `cc-monthly-report` SKILL.md updated to pass MU ids. 568 tests; 51 tools. > > **v1.13.1 — June 2026:** **bug fix.** `list_org_presences` no longer crashes with *"unexpected keyword argument 'page_size'"* — removed pagination kwargs from `get_presence_definitions` (the endpoint returns all definitions in one response; the SDK method allowlist is `deactivated` / `divisionId` / `localeCode` only). Also fixed the silently-swallowed same-bug call in `_load_presence_label_cache`. Regression test pins that no pagination kwargs reach the SDK. 564 tests; 51 tools. > > **v1.13 — June 2026:** **cc-workforce-history skill.** New skill wraps the v1.12 `user_activity_history` tool with a multi-year HTML report: (1) active-agent headcount + joiners + leavers per quarter, (2) mean + median tenure trend, (3) per-person first/last active table with joiner/leaver pills. Surfaces a `data_starts_at` callout so callers can interpret pre-retention quarters honestly. Renders the v1.12.1 soft-fail envelope as a clear missing-scope page instead of crashing. 563 tests; 51 tools. > > **v1.12.1 — June 2026:** **wrap-up soft-fail envelope.** Closes a silent-failure → LLM-narrative bug class. When `wrap_up_code_distribution` hits a 403 (missing `analytics:conversationAggregate:view`), the tool now returns the v1.3 canonical soft-fail envelope and the skill renders a visible "⚠️ data not retrieved" callout with the exact missing scope — no more agent-invented "Wrap-code dataset could not be retrieved" narrative paragraphs. SKILL.md instructions tightened to forbid narrative fallback. 552 tests; 51 tools. > > **v1.12 — June 2026:** **workforce history.** New `user_activity_history` tool reconstructs each user's first/last handled-interaction date across active + inactive + deleted users (one `state=any` directory call) and rolls up quarterly headcount, joiner/leaver flags, and mean/median tenure trend. Long windows (3+ years) are chunked into ~yearly slices and fired concurrently. Surfaces `data_starts_at` so callers can tell pre-retention from no-activity. Answers *"active-agent headcount per quarter Jul 2023 → now + tenure trend + first/last-active table"* in one call. 549 tests; 51 tools. > > **v1.11 — June 2026:** **skill wiring catch-up.** No new MCP tools — surfaces every tool added since v1.6 (`agent_utilization`, `wfm_time_off_requests`, `search_conversations_by_attribute`, `wrap_up_code_distribution`) inside the three reporting skills so daily briefs, monthly reports, and coaching packs render NPS, agent/experience scores, wrap-up code distribution + trend, leave summaries, and per-agent occupancy + disposition mix automatically. Every section is gated on the matching tenant.yaml field — tenants that opt out see no broken renders. 524 tests; 50 tools. > > **v1.10 — June 2026:** **wrap-up code distribution + trend.** New `wrap_up_code_distribution` tool answers *"which wrap-up codes did agents use this month, and which ones moved most vs last month?"* — uses `groupBy: ["wrapUpCode"]` on Genesys' conversations-aggregates endpoint to get per-code counts in **one** API call (no more N+1 per-conversation walks), resolves UUIDs to names via a cached catalogue, and fires a second parallel call for the prior interval to surface deltas / movement / new + retired codes. Closes the *"Wrap-up code distribution not available in this run"* gap in `cc-monthly-report` and `cc-daily-brief`. 482 tests; 50 tools. > > **v1.9 — June 2026:** **relicensed MIT → PolyForm Noncommercial 1.0.0.** Source-available, dual-licensed model. Noncommercial use (personal, research, evaluation, education, nonprofits/public-research/government) remains free; commercial use requires a separate licence from the maintainer. > > **v1.8 — June 2026:** **conversation attribute search + NPS auto-detection.** New `search_conversations_by_attribute` tool answers *"what's the NPS today?"* and *"how many conversations had outcome = Resolved?"* — wraps Genesys' dedicated participant-attribute search endpoint, computes the standard NPS rollup automatically when values look 0-10 integer, and surfaces a value distribution for non-numeric attributes. New optional `survey` block in `tenant.yaml` lets tenants configure their NPS / Agent Score / Experience Score attribute keys for upcoming skill wiring (v1.10). 466 tests; 49 tools. > > **v1.7 — June 2026:** **leave / time-off reporting.** New `wfm_time_off_requests` tool answers *"who took leave last 4 weeks?"* — pulls every approved/pending time-off request over an interval, resolves the activity code (Annual Leave / Sick / Personal / etc.) to a human-readable name via a new cached `wfm_activity_codes` lookup, and rolls up totals per user and per leave type. Handles full-day and partial-day requests uniformly. 453 tests; 48 tools. > > **v1.6 — June 2026:** **agent utilization.** New `agent_utilization` tool answers *"how much on-queue time did each agent have, how many calls + messages did they take, and what's the ratio?"* — combining routing-status durations (`ON_QUEUE` / `INTERACTING` / `IDLE` / `NOT_RESPONDING` / `OFF_QUEUE` seconds) with answered counts in one call. Three pre-computed productivity ratios: interactions-per-on-queue-hour (headline), occupancy %, and voice-to-message ratio. Fires the two underlying Genesys aggregates endpoints concurrently. 431 tests; 46 tools. > > **v1.5 — June 2026:** **interval clarity + cross-app robustness.** New `compute_interval` tool turns a period keyword (`today`, `last_week`, `last_28_days`, etc.) into a tenant-timezone-aware ISO interval — foreign LLMs no longer need to do timezone math. The four analytical tools (`queue_performance`, `agent_performance`, `repeat_caller_deep_dive`, `break_overrun_report`) now echo `interval` + `as_of_utc` at the **top** of every response so persisted-file readers see the window in the first lines (closes a real cross-app hallucination bug). Five tool modules deduped onto a single `_intervals` module — no behaviour change for existing callers. 409 tests; 45 tools. > > **v1.4 — June 2026:** **call quality + batch ergonomics.** New `voice_call_quality` returns MOS scores per conversation — the *"was it the network or the agent?"* signal. `get_user_presence_now` resolves presence UUIDs to friendly labels with a process-lifetime cache. `find_user` gains a batch variant for resolving 10-20 names in one concurrent call. `agent_adherence_review` fans its per-user adherence queries out via thread pool (5-10× faster on large tenants). 361 tests; 44 tools. > > **v1.3 — June 2026:** soft-fail consistency + missing discovery tool. Every tool now uses a canonical soft-fail envelope (`status` / `kind` / `message` / id fields). New `list_org_presences` exposes the discovery path for the pre-break presence UUID. `get_conversation`, `queue_estimated_wait_time`, and `lookup_external_contact` all migrated to the shared envelope. > > **v1.2 — June 2026:** inline transcripts. New `get_conversation_transcript` returns structured, time-aligned utterances with speaker labels and optional per-utterance sentiment. The coaching pack uses it automatically — every flagged call ships with an inline transcript excerpt so TLs can read what was said without per-call round-trips. > > **v1.1 — May 2026:** the token-budget release. Four heavy analytics tools (`queue_performance`, `agent_performance`, `repeat_caller_deep_dive`, `break_overrun_report`) gain a `mode: "summary" | "full"` parameter, defaulting to summary. Routine interactive queries use roughly 25–40% of the v1.0 token count with zero loss of signal for any current skill. > > **v1.0 — May 2026:** the tenant-agnostic + correctness floor release. Every tenant-specific assumption that used to be baked into Python now lives in [`tenant.yaml`](docs/tenant-config-schema.md). A new `operating_model` block lets single-brand, message-only, and no-pre-break tenants get clean degraded reports instead of misleading zeros. Queue-name pattern is optional and the loader hard-fails on schema-version drift. > > See [RELEASE-NOTES.md](RELEASE-NOTES.md) for the full history. ## What it does Curated tools for ops/analytics work — queues, agents, conversations, recordings, speech analytics, external contacts, workforce management — plus a generic `call_genesys_api` escape hatch for anything not yet wrapped. **Read-only by design.** The server expects a Client Credentials OAuth client whose role only has `*:readonly` scopes. Even if Claude tried to POST/PUT/DELETE through the escape hatch, Genesys refuses server-side. There are no write tools. ## Will this work on my tenant? v1.0 was the explicit shift from "works on one specific Genesys setup" to "works on any Genesys Cloud tenant — and tells you up-front where your shape differs." Three categories of assumption you can toggle via [`tenant.yaml`](docs/tenant-config-schema.md): | Assumption | Default | Toggle off if | |---|---|---| | **Pre-break presence as drain state** — agents go BUSY/"Pre Break" before scheduled breaks to drain interactions | enabled | your CC doesn't use a pre-break presence; reports render a "tracking disabled" callout instead of zero rows | | **Multi-brand structure** — multiple brand display names share the same CC | enabled | single-brand tenant; reports collapse brand × channel rollup to channel-only | | **Voice + message channels** | both | message-only / voice-only tenant; headline KPI cards skip the irrelevant channel | | **Queue naming pattern** — `{brand} - {channel} - {function}` | matches > 80% | your queues use a different convention; set `name_pattern_match_required: false` to fall back per-queue, or `name_pattern: null` for no structured parsing | | **Specialist role title** | `["Specialist", "Customer Service Specialist"]` (no in-code default in v1.0 — discovered by the setup wizard) | your active users' titles differ; the wizard discovers what's actually in use | Run `python -m genesys_mcp.health_check --strict` after setup. It samples a page of queues to compute the pattern-match rate, cross-checks `specialist_roles` against active user titles, and validates every other tenant.yaml field against the live data. Exit code 0 (ready), 2 (warnings — `--strict`), or 1 (blocked). Use the warnings to decide which `operating_model` toggles to flip. ## Setup Requires Python 3.11+ (developed against 3.14). ### Quickstart (v0.6+) — one-command install After creating your OAuth client (step 1 below), the fastest path is: ```bash git clone https://github.com/laggyzee/genesys-mcp.git cd genesys-mcp ./install.sh ``` The installer syncs deps, prompts for OAuth creds, registers the MCP with Claude Code, symlinks every skill into `~/.claude/skills/`, and runs the health check. Idempotent — re-running it upgrades cleanly. If you'd rather do it manually, follow the numbered steps below. ### 1. Create a Genesys OAuth client Genesys Admin → Integrations → OAuth → Add Client. - **Grant type:** Client Credentials - **Roles:** create or attach a role with these readonly permissions: - **Required for the core tools:** `analytics`, `conversations`, `recordings`, `users`, `routing` - **Optional (Wave 3 tools):** `speech-and-text-analytics`, `external-contacts`, `workforce-management` - **Optional (v0.5 coaching tools):** `quality` — enables the `qa_evaluations` tool and the QA section of `agent_coaching_pack` / the `cc-coaching-prep` skill. Without it, the QA section soft-fails (returns `scope_available: false`) and the rest still works. Copy the Client ID and Client Secret somewhere safe. ### 2. Configure environment variables ```bash git clone https://github.com/laggyzee/genesys-mcp.git cd genesys-mcp cp .env.example ~/.config/genesys-mcp.env chmod 600 ~/.config/genesys-mcp.env # Edit ~/.config/genesys-mcp.env and paste your client_id / client_secret. # Set GENESYS_REGION to your tenant's region (see list below). ``` Supported regions: `ap-southeast-2` (Sydney), `us-east-1` (Virginia), `eu-west-1` (Ireland). Add more in `client.py` if you need them — the SDK supports all Genesys public regions. ### 3. Install ```bash uv sync # or: pip install -e . ``` ### 4. Wire into Claude Code Edit `~/.claude/mcp.json` (or your platform's equivalent) and add: ```json { "mcpServers": { "genesys": { "command": "uv", "args": ["run", "--directory", "/path/to/genesys-mcp", "python", "-m", "genesys_mcp.server"], "env": { "GENESYS_CLIENT_ID": "...", "GENESYS_CLIENT_SECRET": "...", "GENESYS_REGION": "ap-southeast-2" } } } } ``` Restart Claude Code and the `genesys` MCP server will start automatically. ### 5. (Optional) Set up the tenant config — needed for `cc-monthly-report` and other tenant-aware skills Skills that produce tenant-aware artefacts (currently just `cc-monthly-report`, more in future) read tenant-specific knobs — brand list, queue naming pattern, WFM management unit, AHT targets, pre-break presence, output filename — from a single YAML file at `~/.config/genesys-mcp/tenant.yaml` (or `$GENESYS_MCP_CONFIG`). The MCP server itself doesn't need this; only the dependent skills do. Easiest way to populate it: ask Claude *"set up genesys mcp for my tenant"* — that triggers the [`genesys-tenant-setup`](skills/genesys-tenant-setup/SKILL.md) skill, which: 1. Auto-discovers everything it can from your read-only OAuth client (queue naming pattern, brand list, WFM units, pre-break presence, specialist roles) 2. Asks you a short list of policy questions for the rest (tenant display name, AHT targets, output filename) 3. Validates the result against the schema and writes it to `~/.config/genesys-mcp/tenant.yaml` Or by hand: copy [`skills/cc-monthly-report/tenant.example.yaml`](skills/cc-monthly-report/tenant.example.yaml) to `~/.config/genesys-mcp/tenant.yaml` and fill in the values. Schema reference: [`docs/tenant-config-schema.md`](docs/tenant-config-schema.md). ## Tool surface ### Directory & lookups | Tool | Purpose | |---|---| | `list_queues` | List routing queues, optionally filtered by name | | `list_users` | List active/inactive users | | `find_user` | Free-text search by name or email (uses /api/v2/users/search). v1.4: optional `name_contains_list` runs N searches concurrently for TL workflows that need a target + peer set in one call. | | `find_user_by_email` | Exact email lookup | | `get_queue_members` | Who's a member of a given queue, with routing status | | `list_wrapup_codes` | Resolve disposition UUIDs to names | | `list_routing_skills` / `get_user_skills` | Skill catalogue and per-user mapping | | `list_org_presences` | (v1.3) Org-level presence definitions with UUIDs + labels. Filter by `name_contains`. Closes the *"what's my pre-break presence UUID?"* discovery gap — pair with `break_overrun_report` config. | | `compute_interval` | (v1.5) Convert a period keyword (`today`, `yesterday`, `this_week`, `last_week`, `this_month`, `last_month`, `last_7_days`, `last_28_days`) to a tenant-timezone-aware ISO interval. Returns a paste-ready `interval` string for the analytical tools. Call this before any analytical tool when you want a calendar-aligned window in the tenant's local time. | | `get_user_routing_status` / `get_user_presence_now` | Real-time per-user status. v1.4: `get_user_presence_now` resolves the presence definition UUID to a friendly label ("Pre Break", "Coaching", etc.) via a process-lifetime cache. | | `get_user_queues` | Which queues an agent is joined to | ### Real-time & analytics | Tool | Purpose | |---|---| | `queue_observation` | Live snapshot — waiting / interacting / on-queue agents | | `queue_estimated_wait_time` | Genesys' own AI-adjusted EWT model | | `queue_performance` | Per-queue × media aggregates. **Raw metrics match the Genesys "Performance > Queues" UI exactly** (`tAnswered.count` = UI "Answer" column, etc.). Derived fields computed by the MCP — verify via [`mcp-reconcile`](#mcp-reconcile) before any release: `answered`, `abandoned`, `service_level_pct`, `avg_wait_s`, `avg_answer_s`, `avg_handle_s`. Filter shape mirrors the UI's canonical `and+or+or` form. | | `agent_performance` | Per-agent productivity, split per media (voice / message / email / callback). **Raw metrics match "Performance > Agents" UI exactly** (`tAnswered.count`, `tHandle.sum/count`). Headline fields: `answered`, `handled`, `avg_handle_s`, `avg_talk_s`, `avg_acw_s`, `transfer_rate_pct`, plus a `by_media` breakdown. *(Was materially wrong in v0.1 — see release notes.)* Aggregation across buckets / per-media split is MCP logic; cross-check with `mcp-reconcile`. | | `agent_utilization` | (v1.6) Per-agent routing-status durations (`ON_QUEUE` / `INTERACTING` / `IDLE` / `NOT_RESPONDING` / `OFF_QUEUE` seconds) **plus** answered counts (voice / message / callback) in one call. Three pre-computed ratios: `interactions_per_on_queue_hour` (headline), `occupancy_pct`, `voice_to_message_ratio`. Sorted by interactions-per-hour desc — high-throughput agents at the top, agents with no on-queue time at the bottom. Soft-fails on 403 against the routing-status scope (answered counts still populate). | | `presence_sessions` | Per-user break/meal/away sessions over an interval — wraps the analytics/users/details async-jobs flow into a single call | ### Conversations & recordings | Tool | Purpose | |---|---| | `search_conversations` | Search by ANI, queue, agent, direction, time window | | `get_conversation` | Full conversation detail | | `list_recordings` | Recording metadata | | `get_recording_url` | Signed URL for downloading a single recording | | `voice_call_quality` | (v1.4) Per-conversation MOS (Mean Opinion Score) for voice-call quality triage. `quality_label: good/fair/poor` lets coaching briefs flag the *"was it the network or the agent?"* angle before suggesting agent coaching. Up to 100 conversation ids per call; configurable `low_mos_threshold` (default 3.5). | ### Composition reports | Tool | Purpose | |---|---| | `repeat_caller_report` | Pulls voice/message/callback details for an interval, groups by ANI, splits the funnel into IVR-only / ACD-offered / answered / abandoned-in-queue per repeater, plus an org-wide funnel block | | `repeat_caller_deep_dive` | The *why* layer on top of `repeat_caller_report`. Enriches the top repeaters with conversation summaries, AI outcomes (`Resolved` / `Mid Flight` / `Unresolved Chat` / `Escalated`), expected-fix tags, sentiment trajectory, and a heuristic `recommended_action` (`callback_recommended` / `escalate_to_retention` / `route_review` / `monitor`). Org rollup includes top dispositions and the `unresolved_repeaters` priority list. | | `get_repeat_contact_report` | (v1.24) **Repeat Contacts & FCR.** `period_start` / `period_end` (local dates, inclusive) → one row per window × channel: `total_contacts`, `repeat_contacts`, `repeat_rate`, `fcr` (**FCR** = 1 − repeat rate, derived not measured), `unidentified_contacts`, `raw_key_contacts`, identity `coverage`, `config_used`, `warnings[]`. A contact is one conversation; it is a repeat if the same customer had *any* prior in-scope contact within N local calendar days. Voice / Messaging match same-channel priors only, Combined matches either. Lookback (period_start − max window) is fetched for matching only. Optional `breakdown: ["day","queue"]` and `drilldown`. Unspecified params fall back to the `repeatContactReport` config. Includes a `methodology` string. See [Repeat Contacts & FCR](#repeat-contacts--fcr-v124). | | `get_repeat_contact_config` | (v1.24) Effective `repeatContactReport` config + which keys are pinned by `GENESYS_MCP_REPEAT_*` env vars. | | `set_repeat_contact_config` | (v1.24) Deep-merge a partial update into the stored defaults — no redeploy. Validates the whole config first (windows must be positive integers, unknown keys rejected); writes a local JSON file only, never Genesys. | | `break_overrun_report` | Per-agent break / meal / **AWAY** / **PRE_BREAK** signals over an interval. AWAY tracked as raw count + total minutes (no target). PRE_BREAK overruns vs configurable target (default 10 min) — handles the auto-applied pre-break presence and quantifies time spent over the drain window. | | `agent_quality_snapshot` | One-shot agent review combining handle stats, hold-ratio flags, silent-transcript detection, wrap-up note discipline, and optional peer comparison | | `agent_coaching_pack` | One-shot 1:1 prep brief: volume / AHT vs targets, peer-median comparison, sentiment + QA, wrap-up discipline, top flagged calls, and heuristic top-3 recommended coaching focus. v1.2: each flagged call ships with an inline `transcript_excerpt` (~40 utterances) so the brief reads end-to-end without per-call round-trips. Tenant-aware (loads AHT targets, flagged-call thresholds, and coaching heuristics from `tenant.yaml`). Drives the `cc-coaching-prep` skill. | | `live_wallboard` | Per-queue real-time view combining observation + EWT + agents-on-queue in one call | ### Repeat Contacts & FCR (v1.24) `get_repeat_contact_report` answers *"what share of contacts were repeats, and what FCR does that imply?"* for every combination of window (default 7 and 45 days) and channel (Voice, Messaging, Combined). **Definitions.** A *contact* is one Genesys conversation, counted once however many sessions, segments or agents it had. A contact is a *repeat* if the same customer had any prior in-scope contact within the preceding N days — any reason, no intent or wrap-up matching — and the repeat is attributed to the later contact. `repeat_rate = repeat_contacts / total_contacts` for that channel and period; **FCR (Amaysim methodology) = 1 − repeat_rate**. It is derived, not measured: no survey or disposition is involved. Voice-only and Messaging-only rates need the prior contact on the same channel; Combined accepts a prior on either (a call followed by a message within N days is a repeat). **Calculation rules.** Contacts from `period_start − max(window)` to `period_start` are fetched for matching only and never counted. Chains count each link. Two contacts on one day make the second a repeat. A contact never matches itself (conversations are de-duplicated by id). Day boundaries use the configured timezone, and "within N days" compares local calendar dates (a gap of exactly N days is a repeat, N + 1 is not). Scope (direction, abandoned, queues) applies to prior contacts too. **Customer identity.** Every contact resolves to one `customer_key`, in order: (1) the participant's `externalContactId`, resolved to the canonical surviving contact when merged; (2) an External Contact lookup on the normalised raw identifier — first against identifiers already seen on a linked conversation in the same run (free), then the identifier-lookup API, then a contact search accepted only on exactly one match; (3) the normalised raw identifier itself (E.164 phone with a default country, email, web-messaging user id, social handle) — reported as `raw_key_contacts`, because raw keys rarely link a call to a message; (4) no identifier → `unidentified_contacts`: in the denominator, never a repeat. Every result carries `coverage` (count + % per method, per channel), and Combined rows carry a `combined_rate_likely_understated` warning when the External Contact share is below `identity.low_coverage_warning_pct`. **Config — section `repeatContactReport`.** Layered: built-in defaults → a `repeatContactReport:` mapping in tenant.yaml → the runtime store written by `set_repeat_contact_config` (`$GENESYS_MCP_REPEAT_CONTACT_CONFIG`, else `repeat-contact-report.json` beside tenant.yaml) → `GENESYS_MCP_REPEAT_*` env pins (which win, and are reported as `env_overridden_keys`). | Key | Default | Env override | |---|---|---| | `direction` | `inbound` (`outbound`, `all`) | `GENESYS_MCP_REPEAT_DIRECTION` | | `include_abandoned` | `false` — queued but never handled by an agent | `…_INCLUDE_ABANDONED` | | `include_pre_queue` | `false` — ended in IVR / bot before any queue or agent | `…_INCLUDE_PRE_QUEUE` | | `media_types.voice` / `.messaging` | `["voice"]` / `["message"]` (all message subtypes) | `…_VOICE_MEDIA_TYPES`, `…_MESSAGING_MEDIA_TYPES` | | `queue_ids` | `[]` = all queues | `…_QUEUE_IDS` | | `windows_days` | `[7, 45]` — positive integers, custom windows allowed | `…_WINDOWS_DAYS` | | `timezone` | `Australia/Sydney` | `…_TIMEZONE` | | `identity.mode` | `external_contact_first` (or `raw_only`) | `…_IDENTITY_MODE` | | `identity.enable_lookup` | `true` — identity step 2; adds API volume | `…_IDENTITY_ENABLE_LOOKUP` | | `identity.resolve_canonical` | `true` — merge resolution via bulk contact fetch | `…_IDENTITY_RESOLVE_CANONICAL` | | `identity.max_lookups_per_run` | `5000` — period contacts are looked up first | `…_IDENTITY_MAX_LOOKUPS` | | `identity.phone_normalisation` | `{format: "E.164", default_country: "AU"}` | `…_PHONE_DEFAULT_COUNTRY` | | `identity.messaging_keys` | `[email, sms, web_messaging_user, social]` | `…_MESSAGING_KEYS` | | `identity.low_coverage_warning_pct` | `70` | — | | `drilldown_max_rows` | `2000` per window × channel | — | | `cache.*` | `enabled: true`, `settled_after_hours: 24`, `retention_days: 120`, `identity_ttl_hours: 24` | `…_CACHE_ENABLED`, `…_CACHE_DIR` | **Performance and caching.** Conversations are fetched one local day at a time (async details jobs once the archive watermark covers the day, validated synchronous paging before that), fully paged, and reduced to slim records straight away. A cold 45-day lookback walks ~50 day-slices and resolves every distinct External Contact in batches of 50, so the first run can take several minutes on a busy tenant — give the MCP client a generous timeout. Settled, complete days and contact resolutions are cached under `$GENESYS_MCP_CACHE_DIR` (default `~/.cache/genesys-mcp/repeat-contacts/<tenant hash>/`), so adjacent periods and re-runs only fetch new days. The cache contains customer identifiers: files are written `0600` in a `0700` directory, namespaced per OAuth client, and pruned after `cache.retention_days`. Set `cache.enabled: false` to opt out. **Scopes.** `analytics:conversationDetail:view`; External Contact resolution also needs `externalContacts:contact:view` (`external-contacts:readonly`) and degrades to link + raw-key identity with an `external_contacts_unavailable` warning without it. ### Quality management *(needs `quality:readonly`)* | Tool | Purpose | |---|---| | `qa_evaluations` | Per-agent Quality Management evaluation summary over an interval: avg score, pass rate, critical-pass rate, last-evaluated, per-evaluation rows (form, evaluator, score, conversation id). Optional per-question detail + evaluator comments via `include_question_detail=True`. Soft-fails with `scope_available: false` when the scope isn't granted. | ### Routing diagnostics | Tool | Purpose | |---|---| | `routing_diagnostic` | Explains why a specific conversation routed (or didn't) as expected: IVR → queue → outcome path with durations, queue routing rules, eligible-agent counts (session-level from Genesys, current-state for the queue), abandon / answer / transfer classification. | | `routing_diagnostic_aggregate` | (v0.9) Aggregate failure-mode analysis for a queue over an interval. *"Show me all this week's abandons on our general inbound queue — how many were because nobody was eligible vs. all-busy? Which 15-minute windows were worst?"* Closes the v0.5 promise. Heuristic classification: `no_eligible_agents` / `all_eligible_busy` / `abandoned_in_ivr`. Pairs with the v0.7 cc-daily-brief 'worst routes' section — daily-brief surfaces *which* queues failed; this surfaces *why*. | ### Health check (v0.6+) | Tool | Purpose | |---|---| | `mcp_health_check` | End-to-end onboarding check: probes one representative endpoint per OAuth scope (green/red per scope), validates `tenant.yaml` against the schema, verifies the companion skills are symlinked into the Claude Code skills dir. Returns a `verdict` of `ready` / `ready_with_warnings` / `blocked` plus concrete remediation strings for each gap. Also available as a CLI: `python -m genesys_mcp.health_check`. | ### Speech & text analytics *(needs `speech-and-text-analytics:readonly`)* | Tool | Purpose | |---|---| | `get_conversation_summary` | AI-generated summary (topics, key issues) | | `get_conversation_sentiment` | Per-speaker sentiment timeline | | `sentiment_summary` | (v1.23) Aggregate sentiment per queue × media **and per brand** over an interval, with prior-period delta. One transcript-aggregates call, not an N+1 walk. Brand rollup from tenant.yaml `queues.name_pattern`; no-queue bot/flow rows surfaced separately as `unattributed`. Needs `analytics:speechAndTextAnalyticsAggregates:view` (bundled into `analytics:readonly` on tenants verified so far). | | `get_transcript_url` | Signed URL to the full transcript JSON (raw — use `get_conversation_transcript` for parsed) | | `get_conversation_transcript` | (v1.2) Structured, time-aligned utterances with speaker labels (customer/agent/IVR/ACD) and optional per-utterance sentiment. `mode: "summary" | "full"`, `max_utterances` cap with truncation reporting. Powers the coaching pack's inline transcript excerpts on flagged calls. | ### External contacts (CRM) *(needs `external-contacts:readonly`)* | Tool | Purpose | |---|---| | `lookup_external_contact` | Phone/email → CRM record with custom fields | ### Workforce management *(needs `workforce-management:readonly`)* | Tool | Purpose | |---|---| | `list_management_units` / `get_user_management_unit` | WFM topology | | `query_agent_adherence_explanations` | Why an agent was off-schedule | | `agent_adherence_review` | Combines presence overruns with WFM explanations side-by-side | | `wfm_schedule` | Per-day **scheduled hours** (sum of paid-time activities across user shifts) vs **WFM-forecast required hours** (from headcountforecast `requiredPerInterval`). The headline answer to "do we need more staff or just better scheduling shape?" — compares scheduled capacity against demand on every day of the period and flags understaffed days. | | `volume_vs_forecast` | (v0.7) Per-interval **forecast vs actual** comparison — closes the WFM loop alongside `wfm_schedule`. Pulls the published short-term forecast for an interval (`/businessunits/{buId}/weeks/{weekDate}/shorttermforecasts`), pulls actual conversation volume + handle time via analytics aggregates, computes per-bucket variance, and rolls up forecast accuracy (MAPE). Answers *"how good was last week's forecast?"* — WFM analysts currently build this in Excel. | ### Escape hatch | Tool | Purpose | |---|---| | `call_genesys_api` | Generic `/api/v2/*` call (GET/POST/PUT/PATCH/DELETE). Non-GET will 403 unless your OAuth client has write scopes (it shouldn't). | ## Example sessions Once installed, just talk to Claude: - *"Pull last week's answer rate and SLA for our voice queues."* - *"Find Jane Smith and show me her status right now."* - *"What's the estimated wait time on the Sales queue?"* - *"Run the repeat-caller deep dive for last week — top 25 ANIs."* - *"Who's spending the most time over the 10-minute pre-break this month?"* - *"How does our scheduled capacity compare to the WFM forecast for April?"* - *"Pull a quality snapshot for agent X over the last 7 days, compared with their peers."* - *"What's the live wallboard look like for these 6 queues?"* ## Companion skills Five user-installable Claude Code skills ship with this repo. All depend on a per-tenant config at `~/.config/genesys-mcp/tenant.yaml` — see Setup step 5 above for how to populate it (the easiest path is the `genesys-tenant-setup` wizard). ### `cc-monthly-report` Produces a self-contained HTML contact-centre report from one prompt — *"do the monthly CC report for May 2026"* — and drops it at `<output_dir>/<short_name>-CC-<period>.html` (paths configurable per tenant). What the report contains: 1. **LLM narrative synthesis** (v0.7) — four sections written by Claude on top of the data: *Coverage & caveats*, *What worked*, *What went wrong*, *Recommended actions*. Opt-in via `--with-narrative <md-file>`; omit the flag for a data-only build. 2. Executive summary (KPI cards + headline findings) 3. Volume & funnel (brand × channel totals, per-queue tables, daily voice service-level chart, plus the v0.9 **hour-of-day × day-of-week heatmap** that surfaces intra-day staffing patterns the daily chart averages away) 4. Themes (top dispositions, AI outcome distribution, top expected-fix tags) 5. Repeat callers — actionable priority list of unresolved repeaters with summaries 6. Workforce — per-agent productivity (specialists only), AHT vs targets (voice / message / ACW), break / AWAY / pre-break behaviour. v0.9 adds inline-SVG **voice-AHT sparklines** next to each headline AHT so direction of travel is visible at a glance. 7. Performance leverage — quantifies "phantom capacity" (handle hours that would be freed if every agent hit AHT target) + "FCR drag" (handle hours wasted on repeat calls), then compares against the WFM-derived peak-demand shortfall to give a single synthesised verdict: *"more staff or better staff?"* Tenant-agnostic by design: every brand name, queue naming pattern, AHT target, WFM unit ID and presence ID is read from the tenant config. No tenant-specific values are hard-coded in the skill or build script. Living at [`skills/cc-monthly-report/`](skills/cc-monthly-report/) (symlinked under `~/.claude/skills/`). The skill markdown describes the workflow; a Python script does the aggregation and HTML rendering. Reproducible — the same skill against the same period and tenant config gives the same report. ### `cc-coaching-prep` One-prompt 1:1 prep brief for a single agent — *"prep coaching for [agent name] for the last 4 weeks"* — drops a self-contained HTML at `<output_dir>/coaching-<agent-slug>-<period>.html`. What the brief contains: 1. Performance vs targets (KPI cards + colour-coded vs-target pills for voice / message AHT and ACW) 2. Peer comparison table (same-role peers, peer-median for each KPI with delta-vs-peers badges) 3. Sentiment & quality (avg sentiment, QA score / pass rate / critical-pass / last-evaluated, recent evaluations table) 4. Wrap-up & handling (note rate, top dispositions) 5. Top flagged calls (heuristic: sentiment drop, hold ratio, AHT excess, no wrap-up notes — colour-coded reason pills with transcript links) 6. Recommended coaching focus (heuristic top-3 with concrete evidence) v0.9 adds optional LLM narrative synthesis in three sections — *Strengths to acknowledge*, *Areas to coach*, *Suggested talking points* — embedded in the HTML so the TL can re-read them right before walking into the 1:1 instead of scrolling chat history. Tenant-aware: AHT targets, peer-grouping strategy (`role` / `queue` / `mu`), and flagged-call thresholds (sentiment drop, silent seconds, AHT-excess %) all read from `coaching.*` in tenant.yaml. Soft-degrades cleanly: no quality scope → QA section empty; no STA scope → sentiment section empty; the rest still populates. Living at [`skills/cc-coaching-prep/`](skills/cc-coaching-prep/). ### `cc-daily-brief` (v0.7) One-prompt **daily** brief for supervisors at start-of-day — *"daily brief"*, *"morning brief"*, *"how did we go yesterday"*. Drops a one-page HTML at `<output_dir>/daily-brief-<YYYY-MM-DD>.html`. What the brief contains: 1. Headline KPIs — voice + message SL today vs the rolling 7-day median 2. Worst routes — top queues by SL drop vs their rolling median 3. Flagged agents — top agents by voice AHT excess 4. Repeat-caller callback list — unresolved repeaters from yesterday 5. Adherence flags — agents over the combined break/pre-break/meal overrun threshold v0.9 adds optional LLM narrative synthesis in two sections — *Headline* (≤80-word paragraph framing the day vs the rolling median) + *Today's priorities* (top 3 actions for the supervisor's morning standup). Daily briefs are meant to be glanced at; the 4-section monthly shape would be overkill. Tenant-aware: flag thresholds (sentiment dip, AHT excess %, SL drop pp) and the comparison window all read from `daily_brief.*` in tenant.yaml. Designed to fit a laptop screen or Slack share without scrolling — narrower than the monthly report. Living at [`skills/cc-daily-brief/`](skills/cc-daily-brief/). ### `mcp-reconcile` (v0.8) Release-time reconciliation. *"reconcile the MCP against the Genesys UI"* pulls the MCP tool stack for a chosen period (default: last completed week) and outputs a Markdown checklist of side-by-side comparisons: ```markdown | ✓ | Queue | Media | MCP answered | Verify in Genesys UI | |---|---|---|---:|---| | ☐ | Brand A - Activation | voice | 1,247 | Performance → Queues → 18-25 May → Voice column | ``` You click through the live Genesys UI, tick each row off, and either confirm parity or flag a mismatch. Pairs with `make test`: the test suite proves the aggregator maths is stable; reconciliation proves the source numbers still match the UI. Run before each release. Living at [`skills/mcp-reconcile/`](skills/mcp-reconcile/). ### `genesys-tenant-setup` Generates the per-tenant config (`~/.config/genesys-mcp/tenant.yaml`) by auto-discovering whatever it can from the read-only OAuth client (queue patterns, brand list, WFM units, pre-break presence, specialist roles, AHT baselines, timezone) and asking Claude conversational questions for the rest. Writes a validated YAML file when done. Run it once per tenant — anyone forking the repo will use this. Living at [`skills/genesys-tenant-setup/`](skills/genesys-tenant-setup/). ## Testing (v0.8+) The aggregation layer + canonical Genesys-UI filter shapes are covered by a pytest suite: ```bash make test ``` What's tested: - **Aggregators** in `skills/cc-monthly-report/build_report.py` — pure dict→dict functions. Golden fixtures captured from a live tenant (via `tests/_capture_fixtures.py`); structural assertions ensure refactors don't silently change output counts/totals. - **Canonical filter shapes** (`tests/test_analytics_filters.py`) — the v0.2 UI-parity fix is pinned via monkey-patched-SDK tests. A regression to the pre-v0.2 flat-OR shape would fail these tests immediately. - **Helper functions** (formatters, threshold classifiers, sentiment/trend labellers) — parameterised unit tests; no fixtures required. - **HTML rendering** — BeautifulSoup-based structural assertions on column counts, vs-target pill colours, narrative-synthesis sections. - **Conversation deep-link helper** — resolution priority + region mapping + fallback rendering. What's deliberately **not** tested at this layer: - Raw MCP tool wrappers in `tools/*.py` — they mostly call the SDK 1:1. Testing them mostly tests the SDK. The filter-shape assertions cover our own logic; the SDK's correctness isn't our problem. - End-to-end live-tenant calls — covered by the `mcp-reconcile` skill instead: run a reconciliation checklist before each release and click each row off against the live Genesys UI. If a refactor breaks something, the test suite catches structural drift; if Genesys changes endpoint semantics, the reconciliation checklist catches numerical drift. Both are needed. ## Design - **OAuth at startup** — client credentials token fetched on lifespan init, auto-refreshed on 401 via the retry helper. - **No write access from the MCP** — even if the LLM tries to POST/PUT/DELETE, the OAuth scope refuses server-side. Out-of-band administrative writes (e.g. bulk agent provisioning, see [Danger Zone](#-danger-zone--out-of-band-write-scripts) below) use a separate, locally-invoked script with its own write-scoped OAuth client; the MCP server never loads those credentials. - **id → name resolution cache** — internal `naming.Resolver` lazy-loads queue/user/wrap-up names so most responses are human-readable without follow-up calls. - **Composition over wrappers** — `agent_quality_snapshot`, `repeat_caller_report` etc. chain multiple endpoints into single ops-ready reports rather than forcing the caller to do the joining. ## ⚠️ Danger Zone — out-of-band write scripts The MCP server is read-only by design. For the rare administrative tasks that genuinely require writes against your tenant, the [scripts/](scripts/) directory contains **standalone CLIs** that: - Are **not** registered as MCP tools — Claude cannot reach them, regardless of prompt - Use a **separate, write-scoped OAuth client** (`GENESYS_WRITE_CLIENT_ID/SECRET`) — the read-only MCP client is unaware of it and the server's startup code warns loudly if write credentials leak into the MCP process - Default to **`--dry-run`** — explicit `--confirm` is required to write - Ship a **`--self-test`** mode that exercises every write step against a throwaway user before you point the script at real data - Track per-user state in a **ledger** at `/tmp/provision_users/<run-id>/` so a partial failure can resume from the failing step **Read [scripts/README.md](scripts/README.md) before running anything in this directory.** It documents the one-off Genesys admin setup (a separate OAuth client + a tightly-scoped custom role), the tenant assumptions the scripts make (e.g. roles inherited from group membership), and the precise list of permissions to grant. ### Currently shipped | Script | What it does | |---|---| | [`provision_users.py`](scripts/provision_users.py) | Bulk-create agents from a template agent (clones division, manager, location, ACD auto-answer, addresses, title/department, profile skills, routing skills + proficiency, routing languages, group memberships, WFM management unit; sends activation invite). | Quick reference (see [scripts/README.md](scripts/README.md) for the full setup and tenant-assumption notes): ```bash # 1. Verify the OAuth role has every required scope (creates a throwaway user; you delete it manually) python scripts/provision_users.py --self-test --template-email <existing-agent>@example.com # 2. Dry-run a real batch (default — writes nothing) python scripts/provision_users.py --template-email <template>@example.com --emails new_starters.txt # 3. Actually execute python scripts/provision_users.py --template-email <template>@example.com --emails new_starters.txt --confirm ``` ## Companion skill Pair with the [`platform-api`](https://github.com/MakingChatbots/genesys-cloud-skills) skill from MakingChatbots for endpoint discovery — useful when working with `call_genesys_api`. ## Contributing PRs welcome — please read [`CONTRIBUTING.md`](CONTRIBUTING.md) first. In short: sign off your commits under the [DCO](DCO) (`git commit -s`), and note that contributing also grants the maintainer the right to license your contribution under the project's commercial licence (so the project can stay dual-licensed). You keep copyright in your work. Things on the roadmap that someone might want to take a swing at: - Web messaging transcript wrapper (the `/api/v2/conversations/messages/{id}/messages/bulk` flow, which currently needs the `call_genesys_api` escape hatch) - Half-hourly intra-day staffing in `wfm_schedule` (currently rolls up to daily; the v0.9 hour-of-day heatmap covers the *demand* side, but scheduled-capacity bucketing is still daily) - Skill-based routing analysis (which agents have which skills × queue requirements) - GitHub Pages site with anonymised sample reports — distribution/discoverability is the v0.10 candidate, not another feature release Explicitly removed from the backlog: **outbound campaign coverage** (deferred across v0.5–v0.8, dropped in v0.9 — re-add if an outbound-shop user opens an issue). **Forecast-vs-actual analysis** shipped in v0.7 as `volume_vs_forecast`. ## Licence **Source-available, not open source.** This project is licensed under the [PolyForm Noncommercial License 1.0.0](LICENSE) — see [`LICENSE`](LICENSE). - **Noncommercial use is free.** Personal projects, research, evaluation, education, and use by nonprofits, public-research, and government bodies are all permitted at no cost. - **Commercial use requires a separate licence.** You may not use this software — or build a product or service on it — for commercial advantage or monetary compensation without a commercial licence from the maintainer. This includes selling it, offering it as a hosted/managed service, or bundling it into a commercial offering. **Commercial licensing:** email <designsbylwd@gmail.com>, or open a GitHub issue labelled `commercial-license` to start a conversation. **History:** all releases published before this licence change were under the MIT Licence and remain available under MIT for those versions — MIT rights already granted cannot be revoked. This and all future versions are licensed under PolyForm Noncommercial 1.0.0.