five9-mcp

align="# ☎️-mcp **9 联系中心，由 AI 掌控。** 一个开源的 [MCP](modelcontextprotocol.io) 服务器，连接 Claude、ChatGPT 或任何 MCP 客户端到 **Five9** 云联系中心 — 在 **Cloudflare Workers** 上运行，**零依赖**。 [](LICENSE) [](https://workers) [](package.json) ](https://.io/badge/protocol-MCP%20streamable%200ea5ehttps://modelcontextprotocol[](#-the-tool[快速开始](#-quick-start--no-terminal · [连接 Claude](#aude-web--desktop [连接 ChatGPT](#connect-chatgpt) · [the-toolbox) · [架构](#%EF%B8%8F) <img src="docs.png" alt="fivecp landing page820"> </div> --- 询问您的 AI> *"谁正在通话，销售队列的深度* 📊 > *"为回访名单活动，附加销售技能并启动它。"* > *"停止 OUTBOUND_AGED 活动这 3 个线索添加到回调列表。"* > *"入职新代理：创建用户，2 级计费* 🧑‍> *"555-867-5309 是否在我们的 DNC 上？拨打之前检查。"* 🚫 > *"通话日志报告并总结放弃率。"* 📈 在后台使用 Five9 的管理员）和统计数据（SOAP Web 服务** — 仍在 Five9 管理界面中运行的 并通过 MCP 流式 HTTP 将它们公开为干净 工具。手工制作的信封，一个 ~的 XML 解析器，没有 npm 包。每个工具都已针对实时 Five9进行了测试。 ## ✨ 内置 Web 界面 部署后，您的 Worker 不 API： | 页面 | 您获得的内容 | |------|--------------| | `/ 一个精致的登陆页面：实时服务器状态、本设置指南、点击即走 连接演练和完整的工具目录 | | `/ | **设置向导** — 在浏览器中输入 Five9 凭证，它们，获取您的访问密钥。无需终端，无需秘密命令 | | `/console` | 一个**交互式控制台** — 粘贴您的访问密钥，选择 73 个分组工具中的任意一个，填写从其架构生成的表单，并直接在浏览器中针对您的实时 Five9 域运行它 | | `/mcp` | MCP 端点本身（ HTTP，无状态| `/health JSON 健康检查 | 控制台是检查凭证、探索每个工具返回的内容或调试活动的最快方式 — 不需要 AI。 <div align="<img src="docs/console.png" alt="The interactive console running check_connection against a9 domain" width="820"> <br><em>控制台在实时 Five9 域上运行 <code>check_connection</code></em> </div> ## 🚀 快速开始 — 无需终端 您需要一个免费的 Cloudflare 账户和一个具有 API 访问 Five9 用户 — **创建一个专用的 Five9**，限定在您希望 AI 执行的范围内，不要重用个人管理员登录。 **1 — 部署到** *(一步点击，在浏览器中)* [ 登录 Cloudflare 并点击通过 — 它会为您创建一个 Worker 副本（以及它需要的 KV 命名空间），并为您提供一个类似 `https://five9-mcp.you.workers.dev` 的 URL。 **2 — 运行设置向导** *(在浏览器中)* 在您的新服务器上打开 **`/setup`**。输入您的 Five9 用户名、密码和地区 — 向导**实时验证它们**，然后为您提供**访问密钥显示一次 — 存储在密码管理器中）。 <div align="center"> <img src="docs/setup-wizard.png" alt="The in-browser setup wizard" width="720"> </div> ** 连接您的 AI** （下面的演练），然后要求它 *"检查连接并活动。"* 🎉 <details> <summary><strong>⌨️ 更喜欢 CLI？</strong></summary> ```sh git clone https://github.com/ryanshatz/five9-mcp cd five9-mcp npx wrangler kv namespace create CONFIG # 将打印的 id 粘贴到 wrangler.toml 中 npx wrangler deploy ``` 然后使用 `/setup` 向导，或跳过它并将凭证作为 Wrangler 机密（机密覆盖向导）： ```sh npx wrangler secret put FIVE9_USERNAME # 例如 apiuser@yourdomain npx wrangler secret put FIVE9_PASSWORD npx wrangler secret put MCP_AUTH_TOKEN # 一个长随机字符串 — 这是您的服务器的密钥 ``` </details> <details> <summary><strong>🌍 非美国域或不同 API 版本？</strong></summary> 默认值位于 `wrangler.toml` 中，适用于美国域： | 变量 | 默认值 | 备注 | |-----|---------|-------| | `FIVE9_API_HOST` | `api.five9.com` | 欧洲：`api.eu.five9.com` · 加拿大：`api.ca.five9.com` | | `FIVE9_ADMIN_VERSION` | `v13` | 配置 Web 服务 WSDL 版本 | | `FIVE9_SUPERVISOR_VERSION` | `v13` | 统计 Web 服务 WSDL 版本 | </details> ## 🔌 连接您的 AI ### 连接 Claude（网页和桌面） 免费计划（一个连接器）、Pro、Max、Team 和 Enterprise 计划上提供自定义连接器。 1. 在 [claude.ai](https://claude.ai) 或 Claude 桌面应用程序中，打开 **设置 → 连接器**。 2. 点击 **添加自定义连接器**。 3. 命名为 **Five9**，粘贴您的服务器 URL **包括 `/mcp` 路径**： `https://<your-worker>.workers.dev/mcp` 4. 点击 **添加**，然后 **连接**。Claude 自动发现此服务器的内置 OAuth 并打开其授权页面。 5. 在 **🔐 five9-mcp** 屏幕上，粘贴您的 `MCP_AUTH_TOKEN` 作为访问密钥并点击 **授权**。 6. 在任何聊天中，打开 **搜索和工具** （＋）菜单，并确保 Five9 连接器已启用。 > **团队/企业：** 所有者首先在 **组织设置 → 连接器** 下添加连接器；成员然后在自己的设置中点击 **连接** 以授权。 ### 连接 ChatGPT 自定义 MCP 连接器需要 **开发者模式** （Plus/Pro；Business/Enterprise 上，管理员必须允许自定义连接器）。 1. 在网页上的 [ChatGPT](https://chatgpt.com) 中，打开 **设置 → 应用程序和连接器** （有时仅标记为 **连接器**）。 2. 在 **高级设置** 下，启用 **开发者模式**。 3. 返回连接器页面，点击 **创建**。 4. 命名为 **Five9**，将 **MCP 服务器 URL** 设置为 `https://<your-worker>.workers.dev/mcp`，并选择 **OAuth** 认证。 5. 确认信任提示并保存。ChatGPT 打开此服务器的授权页面 — 粘贴您的 `MCP_AUTH_TOKEN` 并点击 **授权**。 6. 在新聊天中，打开 ＋/工具菜单并启用 **Five9** 连接器（开发者模式连接器按对话启用）。ChatGPT 要求您确认每个工具调用 — 对于可以启动拨号器的任何操作都很明智。 😄 ### 连接 Claude Code ```sh claude mcp add --transport http five9 https://<your-worker>.workers.dev/mcp \ --header "Authorization: Bearer <your MCP_AUTH_TOKEN>" ``` 原始访问密钥直接作为 bearer 令牌工作 — 无需 OAuth 流程。在 Claude Code 中运行 `/mcp` 以验证。 ### 任何其他 MCP 客户端 任何支持 MCP **流式 HTTP** 的客户端 — 完成或将访问 bearer 令牌 ```sh -X POST httpsyour-worker>.workerscp \ -Authorization: BearerCP_AUTH_TOKEN>" -H "Content-Type: application/json" -d '{"json2.0",","method/call","params":{"_connection","arguments' ``` <details> strong>置 OAuth 工作strong></summary> .js`最小的 OAuth 1 授权服务器数据发现、注册、PKCE刷新令专为**单**部署设计：意屏幕上的”是服务器的访问密钥（`MCP）。 - 所有状态的客户端 ID、身份和令牌MCP_AUTH 密钥的 HHA256 签。无 KV 对象。 - 两种身份验证路径同时工作：OAuth 颁发的令牌 *和*作为 bearer 凭证。 - 通过旋转来撤销所有内容：`npx wr put MCP_AUTH_TOKEN`。 </details> ## 🧰 **73 个工具。** 读取（始终安全 ✏️ = 写入（更改您的域 — 服务器告诉 AI 先与您确认） > 65 个 SOAP 工具（用户名/密码）+ 8 个 OAuth 新平台 REST 工具（消费者密钥/密码 - 参见 [OAuth 新平台 API](#-oauth-new-platform-apis)）。 <details open><strong>🔌 连接与strong></summary | 工具 |做什么 | |--|| | `about` | AI 的操作员 谁运行此基本规则 | 🟢 | `check_connection` | 验证 Five凭证有效；的技能数量 | 🟢 |_api_usage` | Five9 API 使用与速率限制> <details open> <summary><strong 活动</summary> |工具 | 它能|--|------|-------------- 🟢 | `list_campaigns` | 列出活动（名称、类型、状态、 | | `inspect_campaign` | 状态 + 附加列表 + DNIS 一 | | 🟢 | `get_campaign_details` | 完整的活动配置（拨号模式、录音、） | | ✏️ | `create_campaign` | 创建外呼或内呼活动，基本或高级 | | | `modify 编辑任意活动设置 — 读取-修改-写入，只需传递更改 | | ✏️rename_campaign` |活动 | |️ | `delete | 删除活动 | | ✏️ |_campaign` | 启动 / 停止 / / 重置 / 重置列表位置 | | ✏️ | `manage_campaign_lists` |/分离拨号列表，优先级 | | ✏️ | `manage_campaign_skills` |上添加/删除路由技能 | | | `manage_campaign_dnis` | 分离入呼号码 | | ✏️ | `manage_campaign_dispositions` | 在活动上添加/删除代理处置 | | 🟢 |_profiles` | 列出活动配置文件、尝试次数、超时） | | ✏️ | `manage_campaign_profile` | 创建 / 删除活动配置文件 | |️ |_campaign_profile_filter 读取/编辑配置文件 记录的标准和拨号顺序 | </details> <details open> <summary><strong>📋 拨号列表和线索</strong></summary> | | 工具 | 它能做什么 | |--|------|--------------| | 🟢 | `list_dialing_lists` | 列出拨号列表 + 记录| | `create_list `delete_list` | 创建或删除 | | | `add_list` | 将线索推入列表（） | | | `add_list` | 在一次异步导入中批量线索（可 CRM/列表模式| ✏ `delete_record_from | 从列表匹配的记录 | 🟢 |_import_result`列表/CRM 导入的结果 | </details> <details open> <summary><strong> 联系人></summary> | | 工具 | 它 | |--|------|| 🟢 | `search_contacts 按精确的字段值查找联系人 ✏️ | `update_contact` |人（默认安全） | |️ | `bulk_update_contacts` |异步导入中 CRM 联系人（轮询类型“） | | ✏️ | `delete_contact` | 删除联系人（仅当恰好一个匹配时） | | 🟢 | `list_contact_fields` | 域的联系人字段架构 | | ✏️ | `manage_contact_field` | 创建 / 删除自定义 CRM | </details> <details open> <summary><strong>🚫 合规性</strong></summary> | | 它能做什么 | |--|------|--------------| ✏️ | `manage_dnc` | 在域的 DNC上检查 / 添加号码 | | 🟢 | `get_dialing_rules` | 域的拨（时间/状态限制） | </details open> <strong>🧑‍💼 用户和技能</strong></summary | 工具能做什么 | |--|------|--------------| | 🟢 | ` | 列出具有基本信息的用户 | | 🟢 | `get_user_details` | 一个用户的完整记录：角色、技能、组 | | ✏️ | `create_user` | 创建具有角色、技能和组的代理 | | ✏️ | `modify_user` | 编辑用户的技能、组和角色 | | ✏️ | `delete_user` | 删除用户 | | 🟢 | `list_user_profiles` | 角色/权限模板 | | 🟢 | `list_skills` / `get_skill_details` | 技能，有或无分配用户 | | ✏️ | `manage_skill` | 创建 / 修改 / 删除技能 | | ✏️ | `manage_user_skills` | 为用户分配技能，设置级别 | | ✏️ | `set_user_roles` | 授予 / 撤销角色（代理、管理员、主管、报告、crmManager）及其权限选项卡 | | 🟢 | `list_agent_groups` | 代理组 + 成员 | | ✏️ | `manage_agent_group` | 创建 / 删除组，添加/删除代理 | | ✏️ | `manage_reason_code` | 不就绪 / 注销原因代码 | </details> <details open> <summary><strong>🏢 域配置</strong></summary> | | 工具 | 它能做什么 | |--|------|--------------| | 🟢 | `list_dispositions` | 通话处置及其设置 | | ✏️ | `manage_disposition` | 创建 / 修改 / 重命名 / 删除处置（包括重拨计时器） | | 🟢 | `list_ivr_scripts` / `get_ivr_script` | IVR 脚本 — 元数据，或一个脚本的完整 XML | | ✏️ | `manage_ivr_script` | 创建 / 修改 / 删除 IVR 脚本（推送完整 xmlDefinition） | | 🟢 | `list_prompts` | 域上的语音提示 | | ✏️ | `manage_tts_prompt` | 创建 / 修改 / 删除文本转语音提示 | | ✏️ | `manage_wav_prompt` | 创建 / 修改 / 删除预先录制的 WAV 提示（base64；G.711 µ-law 8kHz 单声道） | | 🟢 | `list_dnis` | 已预配的入呼号码（可选仅限未分配） | | 🟢 | `list_call_variables` | 通话变量和变量组 | | ✏️ | `manage_call_variable` | 创建 / 删除自定义通话变量 | | 🟢 | `list_web_connectors` | 网页连接器集成 | | ✏️ | `manage_web_connector` | 创建 / 删除网页连接器（URL 弹出窗口，代理触发） | | ✏️ | `manage_speed_dial` | 列出 / 创建 / 删除快速拨号代码 | | 🟢 | `get_vcc_configuration` | 域级 VCC 设置 | </details> <details open> <summary><strong>📈 报告和实时数据</strong></summary> | | 工具 | 它能做什么 | |--|------|--------------| | 🟢 | `run_report` | 按文件夹 + 名称启动任意报告，可选时间范围 | | 🟢 | `get_report_result` | 轮询报告的 CSV 输出 | | 🟢 | `get_realtime_stats` | 代理状态、ACD 状态、活动状态、活动统计数据（包括拨号器管理器和自动拨号视图） | </details> <details open> <summary><strong>🔐 OAuth 新平台 API（REST）</strong> — 需要单独的凭证，参见下方</summary> 这些工具使用 Five9 的现代 **OAuth 2.0“新平台”REST API**，而不是工具以上使用的 SOAP API。它们需要一个 **API 访问控制凭证**（消费者密钥/密码），而不是 SOAP 用户名/密码 — 参见 [OAuth 新平台 API](#-oauth-new-platform-apis)。 | | 工具 | 它能做什么 | |--|------|--------------| | 🟢 | `rest_check_connection` | 验证 OAuth 凭证 — 获取 bearer 令牌（无域数据） | | 🟢✏️ | `rest_call` | 对任何新平台端点进行通用身份验证调用（方法 + 路径 + 正文），具有速率限制/退避和 ETag 支持 | | 🟢✏️ | `manage_circle` | 圆圈 — 列出 / 获取 / 创建 / 删除 SOAP 等价物） | | 🟢 | `list_np_prompts` | 通过 API 获取语音提示（分页） | | 🟢 | `list_interaction_dis | 通过交互 API 获取处置（比 SOAP 列表更丰富；） | | 🟢 | `_info` | 域元数据（ID、名称、租户端点） | | 🟢 | `list_data_tables 数据表（结构化查找表； 等价物）— 使用单独的 `data-tables` 凭证 | | `get_data_table_rows` | 按数据表行） | </## 🔐 OAuth 新平台 API 除了 SOAP 工具外，服务器还可以调用 Five9 的较新的 **OAuth 2.0 新 API**（例如 Circles、interactions、prompts、domain metadata）。这些使用与名/密码****: - 一个 **API 访问控制** *消费者密钥*消费者密码*，在 Five9 **管理控制台 → API 访问控制** 中生成（一个可用性功能）。生成一个需要 ` applications → Create 权限，并且**迁移到 身份服务**（具有旧版gent/Supervisor 角色的用户在这些角色被删除排除在迁移之外）。 - 将它们配置为环境变量/机密变量（全部与 SOAP 凭证）： ```ini FIVE9_CONSUMER_KEY=... # “所有 API 访问”系列凭证） FIVE9_CONSUMER_SECRET=... FIVE9_DOMAIN_ID=131109 # 您的管理控制台域 ID FIVE9_REST_REGION=US # US | US-ALPHA | CA | EU | IN | UK # 或直接固定基准 URL：FIVE9_REST_BASE_URL=https://api.prod.us.five9.net # 数据表的可选第二个凭证（其自己的密钥）： FIVE9_DTER_KEY=... FIVE9_DT_CONSUMER_SECRET=... ``` 然后运行 `rest_check_connection` 以确认令牌流程。每个凭证的内容由其 **API 系列作用域** 决定 — `all-apis-access` 并不意味着可以调用所有服务，写入访问服务划分。 **多个凭证/系列。** 每个 API 访问属于一个 **系列**（ Apigee API 产品），决定了该密钥可以调用哪些服务。服务器支持 **命名凭证**default`（来自 `FIVE9_CONSUMER_KEY`/`SECRET和 `data-tables`（来自 `FIVE9_DTER_KEY`/`SECRET`表工具自动使用 `data-tables` 凭证；`rest 和 `rest_check_connection` 接受一个 `credential` 参数来。 > **注意：** Five9 的入门文档将令牌列为 `/v1/auth，但实际端点是oauth2/v1/token`** （此客户端使用）。 ## 🎨 自定义操作员上下文 `src/about.js` 文件中包含了通过 MCP 的 `instructions` 字段和 `about` 工具向连接的 AI 提供的信息：谁在操作服务器，为什么存在，以及 AI 应如何行为（例如 *"确认写入操作前"*）。**编辑它以描述您自己的部署** — 它附带原始操作员的上下文作为示例。 ## 🏗️ 架构 无需构建步骤，无需依赖 — `src/` 中的纯 JS 模块： ``` src/ ├── index.js # 路由器，CORS，MCP JSON-RPC 处理程序，/setup 端点 ├── five9.js # SOAP 客户端：信封构建器，~60 行 XML 解析器，每个 Five9 操作一个方法 ├── tools.js # MCP 工具定义（JSON 模式）+ 调度 ├── oauth.js # 无状态 OAuth 2.1 服务器（单操作员模型） ├── config.js # 配置解析：Wrangler 机密 > KV（设置向导） ├── ui.js # 着陆页，设置向导，交互式控制台 └── about.js # 操作员上下文 — 为您的部署编辑此文件 ``` 请求是无状态的：每个 MCP 调用都会使用 HTTP 基本身份验证开启一个新的 Five9 SOAP 交换。统计 API 此外需要一个 `setSessionParameters` 调用，`get_realtime_stats` 在每次调用时执行此操作。 <details> <summary><strong>⚔️ 关于 Five9 SOAP API 的说明（经验教训）</strong></summary> - Five9 的端点由 JAXB 生成，并 **验证子元素顺序** 与 WSDL 序列对抗。如果您扩展此服务器，请拉取 WSDL (`https://api.five9.com/wsadmin/v13/AdminWebService?wsdl`，HTTP 基本身份验证）并精确匹配 `<xs:sequence>` 顺序 — 包括基本类型，如 `basicImportSettings`，其元素在扩展之前出现。 - `addToListCsv` 需要 `cleanListBeforeUpdate`、`crmAddMode`、`crmUpdateMode` 和 `listAddMode`，尽管 WSDL 将它们大多数标记为 `minOccurs="0"`。 - 列表/CRM 导入是 **异步** 的：调用立即返回导入标识符；轮询 `get_import_result` 以获取结果。 - 联系人记录值被包装返回（`<values><data>…</data></values>`）；几个响应返回单个对象，而您期望的是一个包含单个元素的数组。`five9.js` 中的 `toArray()` 规范化了这一点。 - 报告时间标准顺序为 `<end>` **在** `<start>` 之前（JAXB 按字母顺序排序）。 </details> ## 🛡️ 安全 - Five9 凭证仅存在于您的 Cloudflare 账户中 — 作为 Worker 机密或（向导路径）在 Workers KV 命名空间中，静态加密。任何工具都不会返回它们，而 Wrangler 机密始终覆盖 KV。 - 设置向导 **仅在全新、未配置的服务器上开放** — 在部署后立即运行它。配置后，任何更改都需要当前访问密钥，而环境管理的服务器完全拒绝向导更改。 - **始终完成设置（或设置 `MCP_AUTH_TOKEN`）。** 未配置且无访问密钥的服务器是开放的 — 任何找到 URL 的人都可以驱动您的联系中心。 - 写入工具（✏️ 上方）会更改您的域。请将 Five9 API 用户的角色范围限定为您实际希望 AI 执行的操作 — Five9 权限是真正的安全边界。 - `manage_dnc remove` 和 `delete_list` 需要额外谨慎；`about` 说明会告诉 AI 在使用它们之前进行确认。 - 控制台仅在您的浏览器本地存储中存储您的访问密钥，并且调用与您自己的 Worker 进行同源调用。 ## 💻 开发 ```sh npm run dev # wrangler dev on http://localhost:8787 npm run deploy # wrangler deploy ``` 在 `.dev.vars` （gitignored）中放置本地机密： ```ini FIVE9_USERNAME=apiuser@yourdomain FIVE9_PASSWORD=... MCP_AUTH_TOKEN=dev-local-token # 可选 — OAuth 新平台 REST 工具（单独凭证；参见下文） FIVE9_CONSUMER_KEY=... FIVE9_CONSUMER_SECRET=... FIVE9_DOMAIN_ID=131109 FIVE9_REST_REGION=US FIVE9_DT_CONSUMER_KEY=... # 可选： "Data Tables access" 系列 FIVE9_DT_CONSUMER_SECRET=... ``` 然后打开 `http://localhost:8787/console`，粘贴 `dev-local-token`，并针对您的域运行工具 — 或使用上述 curl 片段从 CLI 进行烟雾测试。 ## 🤝 贡献 欢迎 PR！Five9 配置 API 有 ~180 个操作，而此服务器封装了最有用的 58 个 — `five9.js` + `tools.js` 中的模式易于扩展（首先阅读 SOAP 说明，并避免与 WSDL 斗争）。请保持零依赖约束。 ## 📄 许可证 [MIT](LICENSE) · 由 [Ryan Shatzkamer](https://www.linkedin.com/in/ryanshatzkamer) 构建