Yeastar P-Series PBX

Yeastar MCP 服务

面向 Yeastar P-Series PBX System OpenAPI 的 MCP 服务，为 AI 助手和 WYRE Conduit 网关提供只读视图，涵盖分机、分机组、中继、入站／出站路由、IVR 菜单、响铃组、队列（包括实时通话／坐席状态）、公司联系人目录、通话详细记录（CDR）、通话报告、备份元数据和证书元数据。

设备／版本范围

此连接器面向 P-Series Appliance Edition 的 OpenAPI，基础路径为 openapi/v1.0。 根据 Yeastar 自己的开发文档（help.yeastar.com，《P-Series Appliance Edition Developer Guide》），该 API 仅支持以下设备：

• 硬件型号 P550、P560 和 P570，且运行 PBX 固件 37.7.0.16 或更高版本。 文档未说明其他 Appliance Edition 硬件（例如 P510）支持此 API——文档明确指出该功能“仅支持 P550、P560 和 P570”，没有附加条件。
• 文档未说明任何端点存在更严格的型号限制——此连接器实现的所有端点均适用相同的 P550／P560／P570 + 固件 37.7.0.16 及以上要求。

Cloud Edition 是独立产品，拥有自己的开发指南和 OpenAPI 接口（基础路径结构同为 openapi/v1.0，文档中注明的固件要求为 84.7.0.17 及以上），但此连接器的请求／响应格式未经独立验证。Appliance Edition 和 Cloud Edition 的指南在某些方面有所不同（例如，Cloud Edition 还记录了此处未涵盖的 v2.0 CDR 接口）。如果客户使用 Cloud Edition，应将此连接器视为未经验证，而非确认不兼容——两份指南对大多数基础 OpenAPI 机制（令牌交换、响应封装、分页）的描述相同，但此处没有任何端点经过实时 Cloud Edition 实例测试。

Software Edition（可自托管、非设备版）及任何其他 P-Series 变体均不在范围内——上述 Appliance Edition API 支持声明中未提及这些版本，此连接器也未对其进行评估。

如果客户实际使用的硬件／版本未知，请先通过 PBX Web 门户（Settings -> About，或查看 yeastar_get_system_information 中显示的型号）进行确认，再判断此连接器是否可用——如果 PBX 不属于 P550／P560／P570（Appliance），也不是 Cloud Edition，则很可能会直接拒绝 get_token，因为其门户中根本没有可用的 API 功能开关。

身份验证

每台 Yeastar P-Series PBX 都是独立设备，拥有自己的域名／IP 和凭据——没有共享的托管 API 端点。客户需要在 PBX 的 Web 门户中自行启用 API（Integrations -> API，将“API”切换为开启），并在那里生成 Client ID 和 Client Secret。这不是基于浏览器的 OAuth 授权同意流程——客户直接将生成的 Client ID/Secret 粘贴到连接表单中，其形式与此工具集中的其他可自托管／自带实例连接器（例如 Hudu、IT Glue）相同，而非 Cork 等 SaaS 供应商使用的共享应用授权码流程。

此连接器会自行使用 Client ID/Secret 换取短期有效的访问令牌——绝不会将它们直接转发到 PBX 请求中。根据 Yeastar 文档（POST /openapi/v1.0/get_token），实际请求格式确实是 {"username": "<Client ID>", "password": "<Client Secret>"}——Yeastar 自己的文档明确指出这些字段就是 Client ID/Secret（“从 PBX Web 门户中的 Client ID 获取 username”），并非单独的凭据；此连接器保留了这些字段名称，而不对其重命名，因为这正是供应商 API 实际要求的传输格式。

**令牌有效期与缓存。**访问令牌在 30 分钟后过期；刷新令牌在 24 小时后过期。Yeastar 还将每个应用的同时有效令牌数限制为 8 个。因此，此连接器不会在每次工具调用时都签发新令牌——src/client.ts 会在内存中按设备 + Client ID + Client Secret 缓存访问令牌，并在令牌距离过期不到 60 秒之前重复使用。收到 TOKEN EXPIRED 响应（errcode 10004）时，连接器会透明地签发新令牌，并对失败的调用恰好重试一次。这是有意偏离此工具集中其他连接器的模式（它们会按请求签发令牌或持有单个静态密钥）——这是因为 Yeastar 的令牌机制确实有此要求，而非单纯为了优化：如果不缓存，任何会话在 30 分钟内进行超过 8 次工具调用，就会开始收到 Yeastar 返回的 MAX LIMITATION EXCEEDED（errcode 60002）错误。

在网关模式下，Conduit 网关会通过 X-Yeastar-Pbx-Domain / X-Yeastar-Client-Id / X-Yeastar-Client-Secret 标头注入并逐个请求传入这三个凭据字段。/mcp 请求缺少其中任何一个标头时，都会被拒绝并返回 401，且不会回退到进程环境中的 YEASTAR_*。在本地／stdio 模式以及 HTTP AUTH_MODE=env 模式下，这些凭据从 YEASTAR_PBX_DOMAIN / YEASTAR_CLIENT_ID / YEASTAR_CLIENT_SECRET 读取。

HTTP 还要求进行服务间身份验证。设置 CONDUIT_S2S_SECRET 后，每个 /mcp 请求都必须包含 X-Gateway-S2S。标头值格式为 t=<unix seconds>,v1=<hex hmac-sha256>。MAC 是对 ASCII 消息 t=<unix seconds>（与标头中出现的 t= 前缀相同）进行 HMAC-SHA256 运算的结果，密钥为 CONDUIT_S2S_SECRET，编码为小写十六进制。时间戳必须与服务器时钟相差不超过 300 秒。缺少或无效的标头会在读取供应商凭据之前触发 401 响应。该密钥绝不会写入日志。/health 和 /healthz 仍无需身份验证，也不会读取凭据。stdio 传输不使用 CONDUIT_S2S_SECRET。

请求限制

• HTTP 请求体上限为 256 KiB（262144 字节）。X-Gateway-S2S 检查通过后（在网关模式下，还需提供 X-Yeastar-* 凭据标头），如果 Content-Length 超过上限，则返回带有 JSON-RPC 错误的 413。未提供 Content-Length 的请求体由 MCP SDK 传输层限制。未经身份验证的请求仍会优先收到 401。
• tools/call 参数上限为 10,000 个元素（包括任意深度的每个数组项和对象键）。输入超出上限时，会返回固定的 isError 工具结果（"Tool input exceeds the maximum of 10000 elements"），不会回显工具名称，也不会进行分发。

这些限制旨在应对 CVE-2026-111768 / GHSA-46jr-4wx8-v453（验证期间内存耗尽）和 GHSA-f897-62hf-6gxq（缺少请求体／批次上限）。

每个请求还必须包含 User-Agent: OpenAPI 标头 —— Yeastar 的 API 会拒绝缺少此标头的请求（错误代码 40002，"PARAMETER ERROR"）。

防御性字段剥离。 中继配置通常会在读取返回的同一对象中包含 SIP 注册机密（身份验证／注册密码），而且仅凭文档无法通过机器验证 Yeastar 对这些对象的架构。本连接器中每个工具的每个响应，在送达模型之前都会经过 stripSecretFields()：在任意深度匹配 /secret|password|pwd/i 的对象键都会被删除。这是一项全面的安全保护措施，作为下方端点级排除项的补充，而非替代（完全不会调用 extension/getpassword 和 conference/viewpassword）。

凭据权限范围调查结果

已通过代码结构验证（本代码库）： 本连接器的 src/client.ts 恰好实现了一个 HTTP 动词函数 doGet —— 本代码库中没有任何 doPost/doPut/doDelete，因此无论凭据本身拥有什么权限，它都无法向 PBX 发出写入／控制／删除请求。src/__tests__/tool-scope.test.ts 固定了准确的 26 个工具集合，并断言没有工具名称匹配写入／控制／暴露凭据的令牌列表。

厂商文档有说明，但未独立验证： PBX 自身的管理门户是否提供任何方法，将 Client ID/Secret 对限制为只读访问，文档中没有说明。根据 help.yeastar.com 上的“Enable Yeastar P-Series PBX API”页面，启用 API 后只会显示一个开关（“API”开／关），以及可选的 IP 限制允许列表和状态监控配置 —— 整个流程中没有提及权限组、角色或范围选择。这与 Cisco Duo（cisco-duo-mcp）等情况不同，后者的厂商管理面板会为每项集成明确提供 Grant Read Resource / Grant Write Resource 开关。实际影响是：据 Yeastar 自身文档所述，为此连接器生成的 Client ID/Secret 对能够调用 PBX 的完整写入／控制 API，尽管本连接器的代码从不使用这些权限。 文档中提到的唯一厂商端补偿性控制是可选的 IP 限制允许列表（将凭据限定为只能从 Conduit 的出口 IP 使用）——建议启用。如果确实存在更精细的凭据权限范围机制，只是未公开记录，则本连接器开发期间未能找到，应视为未经确认。

配置

环境变量	描述
YEASTAR_PBX_DOMAIN	此设备自身的域名/IP 和端口，例如 https://pbx.example.com:8088（OpenAPI 默认端口为 8088）。不带协议的主机名会按 https 处理。
YEASTAR_CLIENT_ID	OAuth 风格的 Client ID，在 PBX Web 门户的 Integrations -> API 下生成。
YEASTAR_CLIENT_SECRET	OAuth 风格的 Client Secret，在同一位置生成。
MCP_TRANSPORT	stdio（默认）或 http。
AUTH_MODE	env（默认，读取上述变量）或 gateway（通过 X-Yeastar-Pbx-Domain/X-Yeastar-Client-Id/X-Yeastar-Client-Secret 按请求传入凭据）。Gateway 模式下，缺少其中任一标头都会返回 401，且绝不会回退到 YEASTAR_*。容器镜像和 Compose 默认使用 gateway。
CONDUIT_S2S_SECRET	启动 HTTP 传输必需。该值为空或为已知占位符（changeme、secret、replace-me、your-s2s-secret 及其他公开示例值）时，进程会记录错误并以非零状态退出。未设置时，Compose 不会启动。切勿提交真实值。
MCP_ALLOW_INSECURE_DEV	仅限本地开发时，设为 1，即可在没有 CONDUIT_S2S_SECRET 的情况下启动 HTTP。进程会记录警告，不会强制要求 X-Gateway-S2S，且仅绑定到 127.0.0.1。非环回地址的 MCP_HTTP_HOST（包括 0.0.0.0）会导致启动被拒绝。即使设置了此标志，已知占位符密钥仍会导致启动被拒绝。
MCP_HTTP_HOST	设置了真实 CONDUIT_S2S_SECRET 时使用的绑定地址。未设置时，沿用历史默认值 0.0.0.0。容器镜像和 Compose 会在容器内设置为 0.0.0.0，并将主机端口发布到 127.0.0.1。没有密钥时，不安全开发模式的绕过机制仅监听 127.0.0.1，并拒绝非环回地址。
MCP_HTTP_PORT	HTTP 端口。默认为 8080。
LOG_LEVEL	debug | info（默认）| warn | error。

工具

全部 26 个工具均为只读。即使剥离字段后，鉴于中继线配置与电话密钥较为接近，yeastar_get_trunk 在 Conduit 的 VENDOR_TOOL_CONFIG 中还会被归类为敏感工具。

系统

• yeastar_get_system_information - 此设备的型号、固件版本和主机名。
• yeastar_get_system_capacity - 当前许可的分机/中继线/并发通话容量使用情况。

分机

• yeastar_list_extensions - 列出分机基本信息，以及各设备的在线/状态信息。
• yeastar_get_extension - 获取单个分机的完整详情（绝不包含其密码）。

分机组

• yeastar_list_extension_groups - 列出分机组。
• yeastar_get_extension_group - 获取一个分机组的完整详情（包括成员分机）。

中继线

• yeastar_list_trunks - 列出已配置的中继线。
• yeastar_get_trunk - 获取单个中继线的完整详情，并剥离形似密钥的字段。
• yeastar_list_itsp_trunks - 列出创建中继线时可用的 ITSP（VoIP 提供商）模板。

路由

• yeastar_list_inbound_routes / yeastar_get_inbound_route - 呼入路由。
• yeastar_list_outbound_routes / yeastar_get_outbound_route - 呼出路由。

IVR

• yeastar_list_ivrs / yeastar_get_ivr - 自动话务员菜单。

响铃组

• yeastar_list_ring_groups / yeastar_get_ring_group。

队列

• yeastar_list_queues / yeastar_get_queue - 队列配置。
• yeastar_get_queue_call_status - 队列中正在等待/处理的实时通话。
• yeastar_get_queue_agent_status - 队列坐席的实时登录/暂停状态。

通讯录

• yeastar_list_company_contacts - 公司全员共享的通讯录。

CDR

• yeastar_list_cdr - 通话详单，可选用 start_time/end_time 限定范围。

通话报告

• yeastar_list_call_reports - 汇总通话统计数据，可选用 start_time/end_time 限定范围。

备份

• yeastar_list_backups - 备份元数据（名称、时间、大小），用于监控备份运行状况。

证书

• yeastar_list_certificates - TLS 证书元数据（名称、域名、有效期），用于监控证书是否即将过期。

范围

这是一个刻意保持精简的只读 v1 接口。 src/client.ts 只实现了一个 HTTP 动词函数（doGet）——整个代码库中没有任何 doPost/doPut/doDelete，因此下面列出的所有写入/控制操作排除项都由代码结构强制执行，而非仅通过文档说明。src/__tests__/tool-scope.test.ts 固定了准确的 26 个工具集合。

下面列出的操作名称摘自 Yeastar 自己的 “API Interfaces & Events Summary” 参考页面（help.yeastar.com，P-Series Appliance Edition Developer Guide），并在注明处与各个端点的文档页面进行了交叉核对。

关于此列表，有一点命名空间说明值得注意： Yeastar 自己的参考摘要中，某些删除/控制操作使用 HTTP GET（例如 extension/delete、queue/agent_login），而非 DELETE/POST——此连接器按操作语义排除它们（因为它们会修改数据或执行操作），而不只是按 HTTP 方法排除。上文所说的“仅通过 GET 实现”，描述的是此连接器自身的动词函数，并不表示 Yeastar 所有使用 GET 方法的端点都可以安全调用。

硬性排除项 - 暴露凭据（从未实现）

• extension/getpassword - 返回分机当前使用的 SIP/门户密码。
• conference/viewpassword - 返回会议室当前使用的密码。

硬性排除项 - 使用 GET 动词但实际是操作而非读取的端点（从未实现）

• del_token - 撤销当前 API 令牌。
• extension/delete、extension_group/delete、organization/delete、trunk/delete、company_contact/delete、phonebook/delete、inbound_route/delete、outbound_route/delete、vm/delete、vm/delete_extension_vm、extension_vm_greeting/delete、vm_greeting/delete、ivr/delete、ringgroup/delete、queue/delete、conference/delete、paging/delete、pin_list/delete、block_numbers/delete、allow_numbers/delete、message_channel/delete、message_queues/delete、message_campaign/delete、message_session/delete、certificate/delete、backup/delete、wakeupcall/delete - 删除对象。
• queue/agent_login、queue/agent_pause、agent/login、agent/pause - 让坐席登录/退出队列或更改其暂停状态。

Hard-excluded - documented write/create/update/provisioning operations (never implemented)

• System: system/sendemail.
• Extensions: extension/create, extension/update, extension/send_welcome_email, extension/uploadtempavatarfile.
• Extension Groups: extension_group/create, extension_group/update.
• Organization: organization/create, organization/update.
• Trunks: trunk/create, trunk/update.
• Contacts/Phonebook: company_contact/create, company_contact/update, phonebook/create, phonebook/update.
• Auto Provisioning: phone/batchcreate, phone/batchupdate, phone/batchreprovision, phone/batchreboot, phone/batchdelete.
• Routes: inbound_route/create, inbound_route/update, outbound_route/create, outbound_route/update.
• Voicemail: vm/create, vm/update, extension_vm_greeting/upload, vm_greeting/upload.
• IVR: ivr/create, ivr/update.
• Ring Groups: ringgroup/create, ringgroup/update, ringgroup/updateoptions.
• Queues: queue/create, queue/update, queue/honor_wrapup_time, queue_pause_reason/update, queue_option/update.
• Conference: conference/create, conference/start_interim_conference, conference/invite_member, conference/kick_member, conference/mute_member, conference/unmute_member, conference/update.
• Paging: paging/create, paging/update.
• Recording/Auto settings: autorecord/update.
• PIN & Number Control: pin_list/create, pin_list/update, block_numbers/create, block_numbers/update, allow_numbers/create, allow_numbers/update.
• Call Notes/Messaging: callnotes/update, message_channel/uploadphoto, message_channel/create, message_channel/createlivechat, message_channel/update, message_channel/updatelivechat, message_queue/create, message_queue/update, message_campaign/create, message_campaign/update, message_campaign/retry, message_session/transfer, message_session/close, message_session/archive, message_session/unarchive, message/batchupload, message/send, message/reaction.
• Voice Prompts: play_list/create, custom_prompt/upload.
• Infrastructure: webserver/update, certificate/upload, certificate/create, certificate/update, backup/create.
• API Feature Settings: extension_status_monitor/update, trunk_status_monitor/update, webhook/update.
• CDR: cdr/updateoption, cdr/updatedownloadoption.
• Hotel: wakeupcall/create, wakeupcall/update, hotel/checkout.
• SMS: sms/create.
• Call Control: call/dial, call/accept_inbound, call/refuse_inbound, call/listen, call/hold, call/unhold, call/mute, call/unmute, call/park, call/directly_forward_to_voicemail, call/transfer, call/add_member, call/play_prompt, call/hangup, call/record_start, call/record_pause, call/record_unpause.
• uaCSTA Call Control: uacsta_call/accept, uacsta_call/refuse, uacsta_call/hangup.

严格排除——批量内容、音频或未经验证的密钥安全性（从未实现）

• recording/list、recording/search、recording/download、recording/playtoextension——通话录音音频。
• vm/query、vm/get、vm/download、vm_group/list、vm_global_greeting/list、extension_vm_greeting/list、vm_greeting/list、extension_vm_greeting/record、extension_vm_greeting/play、extension_vm_greeting/download、vm_greeting/record、vm_greeting/play、vm_greeting/download——语音邮件内容、音频和个人问候语。
• backup/download——实际的备份文件，其中可能包含配置密钥。（仅元数据的 backup/list 已实现。）
• system_log/list、system_log/download——系统日志；尚未单独验证其内容是否安全，不含密钥，也未确认存在足以处理任意日志行的等效字段级剥离机制。
• certificate/get、certificate/query——超出列表元数据范围的完整证书详情；尚未评估其中是否可能包含私钥材料。（仅元数据的 certificate/list 已实现。）

v1 范围之外（只读，因范围较窄而未实现——可在之后作为有意规划的后续工作添加）

• 消息/SMS/聊天： message_channel/*、message_queue/*、message_campaign/*、message_session/*、message/get、message/query——不属于以语音 PBX 为重点的 v1 范围。
• 寻呼： paging/list、paging/search、paging/get、paging/query。
• 会议： conference/list、conference/search、conference/get、conference/query、query_interim_conference、conference/query_ongoing_conference。
• PIN 列表和号码控制： pin_list/*、block_numbers/*、allow_numbers/*（读取变体）。
• 语音提示： play_list/list、play_list/get、play_list/query、custom_ringtone/list。
• 个人电话簿（区别于已实现的 company_contact）：phonebook/list、phonebook/search、phonebook/get、phonebook/query。
• 自动配置： phone/search、phone/get、auto_provisioning/compatibility。
• 组织： organization/list、organization/search、organization/get、organization/query。
• 通话备注： callnotes/get。
• API 功能设置（API 表面本身的元配置，不是 PBX 电话状态）：extension_status_monitor/list、trunk_status_monitor/list、webhook/query、webhook/test。
• 酒店管理： wakeupcall/list、wakeupcall/get、wakeupcall/query。
• Yeastar 自行归入“Call Control”类别的实时通话状态查询： call/query、call/park_status——尽管名义上是只读操作，仍谨慎地将其排除，这与本连接器严格禁止涉及供应商自行归类为通话控制的任何操作的范围边界一致。
• 参考数据： timezone/list。
• 系统： system/get_menuoptions——UI 菜单元数据，不属于 PBX 配置/监控数据。
• 超出已实现范围的 CDR/报告变体： cdr/search、cdr/download、cdr/getoption、cdr/getdownloadoption（v1.0）；call_report/detail、call_report/download；call_schedule_report/list、call_schedule_report/download；myreport/list。独立的 Cloud Edition openapi/v2.0 CDR 接口完全不在范围内（参见上文“设备/版本范围”）。
• /search 和 /query 变体： 对于每种除 /list 和 /get 外还提供 /search 和 /query 文档的资源类型（extension、extension_group、trunk、inbound_route、outbound_route、ivr、ringgroup、queue、company_contact、pin_list、block_numbers、allow_numbers、message_channel、message_queue、message_campaign、message_session、play_list、certificate、backup、wakeupcall），本连接器仅实现 /list + /get。/search 是经过筛选的列表，而 /query 是按多个 ID 批量获取详细信息；对于本连接器的监控用例，两者都与 list + get 有大量重叠。

如果有需求，可在审慎决定范围后将其作为后续工作添加——不会默认添加。

开发

npm install
npm run build
npm test
npm run lint   # tsc --noEmit

# HTTP refuses to start until CONDUIT_S2S_SECRET is set
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" npm run start:http

# Local HTTP only, without a service-to-service secret (binds 127.0.0.1)
MCP_ALLOW_INSECURE_DEV=1 npm run start:http

Docker

该镜像在容器内监听 0.0.0.0（MCP_HTTP_HOST），并默认使用 AUTH_MODE=gateway。启动时仍要求设置 CONDUIT_S2S_SECRET，否则会拒绝运行。请在回环地址上发布端口。在 gateway 模式下，Yeastar 凭证会随每个请求以标头形式传入；不会从环境变量读取。

docker build -t yeastar-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  yeastar-mcp

如果未设置 CONDUIT_S2S_SECRET，Compose 会拒绝启动；它会设置 AUTH_MODE=gateway，不会注入 YEASTAR_PBX_DOMAIN / YEASTAR_CLIENT_ID / YEASTAR_CLIENT_SECRET，并发布 127.0.0.1:8080:8080：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

单租户 HTTP（AUTH_MODE=env）仍要求设置 S2S 密钥，之后会使用 YEASTAR_* 环境变量。它与 gateway Compose 服务相互独立：

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e YEASTAR_PBX_DOMAIN=https://pbx.example.com:8088 \
  -e YEASTAR_CLIENT_ID=... \
  -e YEASTAR_CLIENT_SECRET=... \
  -p 127.0.0.1:8080:8080 \
  yeastar-mcp

任一模式下的 X-Gateway-S2S 格式均为 t=<unix seconds>,v1=<hmac-sha256 hex of the string t=<unix seconds>>，并使用 CONDUIT_S2S_SECRET 签名。