yeastar-mcp

# Yeastar MCP Server

MCP server for the [Yeastar P-Series PBX System](https://www.yeastar.com/p-series-pbx-system/) OpenAPI - read-only visibility into extensions, extension groups, trunks, inbound/outbound routes, IVR menus, ring groups, queues (including live call/agent status), the company contact directory, call detail records (CDR), call reports, backup metadata, and certificate metadata, for AI assistants and the WYRE Conduit gateway.

## Appliance/Edition Scope

**This connector targets the P-Series Appliance Edition's OpenAPI, base path `openapi/v1.0`.** Per Yeastar's own developer docs (help.yeastar.com, "P-Series Appliance Edition Developer Guide"), the API is **only** supported on:

- **Hardware models P550, P560, and P570** running **PBX firmware 37.7.0.16 or later**. Other Appliance Edition hardware (e.g. P510) is not documented as supporting the API at all - the docs state functionality "is only supported on P550, P560, and P570" without qualification.
- The docs do not describe any narrower per-endpoint model restriction beyond that - every endpoint this connector implements is covered by the same P550/P560/P570 + firmware-37.7.0.16+ statement.

**Cloud Edition is a separate product with its own developer guide and its own OpenAPI surface** (same `openapi/v1.0` base path structure, firmware requirement documented as 84.7.0.17+), which this connector's request/response shapes were **not** independently verified against - Appliance and Cloud Edition guides diverge in places (e.g. Cloud Edition additionally documents a v2.0 CDR surface not covered here). If a customer runs Cloud Edition, treat this connector as **unverified, not confirmed-incompatible** - most of the base OpenAPI mechanics (token exchange, response envelope, pagination) are described identically in both guides, but no endpoint here has been tested against a live Cloud Edition instance.

**Software Edition (self-hosted, non-appliance) and any other P-Series variant are out of scope** - not mentioned in the Appliance Edition API-support statement above, and not evaluated for this connector.

If a customer's actual hardware/edition is unknown, verify against the PBX web portal (Settings -> About, or the model shown in `yeastar_get_system_information`) before assuming this connector will work - a PBX outside P550/P560/P570 (Appliance) or Cloud Edition will very likely reject `get_token` outright with the API feature toggle unavailable in its portal at all.

## Authentication

Each Yeastar P-Series PBX is its own appliance, with its own domain/IP and its own credentials - there is no shared hosted API endpoint. A customer enables the API themselves in their PBX's web portal (**Integrations -> API**, toggle "API" on) and generates a **Client ID** and **Client Secret** there. This is **not** a browser-based OAuth consent flow - the customer pastes the resulting Client ID/Secret directly into the connect form, the same shape as this fleet's other self-hosted/BYO-instance connectors (e.g. Hudu, IT Glue), not the shared-app Authorization Code flow used for SaaS vendors like Cork.

This connector exchanges the Client ID/Secret for a short-lived **access token** itself - it never proxies them directly into a PBX request. Per Yeastar's docs (`POST /openapi/v1.0/get_token`), the wire format is genuinely `{"username": "<Client ID>", "password": "<Client Secret>"}` - Yeastar's own docs are explicit that these fields *are* the Client ID/Secret ("obtain the username from the Client ID on PBX web portal"), not a separate credential; this connector preserves that field naming rather than renaming it, since it's what the vendor's API actually expects on the wire.

**Token lifetime and caching.** Access tokens expire after **30 minutes**; refresh tokens after 24 hours. Yeastar also caps each application to **8 simultaneous valid tokens**. Because of that cap, this connector does not mint a fresh token on every tool call - `src/client.ts` caches the access token in memory, keyed by appliance + Client ID + Client Secret, and reuses it across calls until it's within 60 seconds of expiring. On a `TOKEN EXPIRED` response (errcode `10004`), it transparently mints a fresh token and retries the failed call exactly once. This is a deliberate deviation from the pattern in this fleet's other connectors (which mint per-request or hold a single static key) - it exists because Yeastar's token model genuinely requires it, not as an optimization for its own sake: without caching, any session making more than 8 tool calls within a 30-minute window would start failing with `MAX LIMITATION EXCEEDED` (errcode `60002`) from Yeastar itself.

In gateway mode, the three credential fields arrive per-request via `X-Yeastar-Pbx-Domain` / `X-Yeastar-Client-Id` / `X-Yeastar-Client-Secret` headers, injected by the Conduit gateway. In local/stdio mode they're read once from `YEASTAR_PBX_DOMAIN` / `YEASTAR_CLIENT_ID` / `YEASTAR_CLIENT_SECRET`.

**Every request also passes a mandatory `User-Agent: OpenAPI` header** - Yeastar's API rejects requests missing it (errcode `40002`, "PARAMETER ERROR").

**Defensive field-stripping.** Trunk configuration commonly carries SIP registration secrets (auth/register passwords) inline in the same object a read returns, and Yeastar's schema for these objects isn't machine-verifiable from the docs alone. Every response from every tool in this connector - not just trunk tools - passes through `stripSecretFields()` before it ever reaches the model: any object key matching `/secret|password|pwd/i`, at any depth, is dropped. This is a blanket safety net on top of, not instead of, the endpoint-level exclusions below (`extension/getpassword` and `conference/viewpassword` are never called at all).

### Credential-scope finding

**Structurally verified (this codebase):** this connector's `src/client.ts` implements exactly one HTTP verb function, `doGet` - there is no `doPost`/`doPut`/`doDelete` anywhere in this codebase, so it is *incapable* of issuing a write/control/delete request to the PBX regardless of what the credential itself is permitted to do. `src/__tests__/tool-scope.test.ts` pins the exact 26-tool set and asserts no tool name matches a write/control/credential-exposing token list.

**Vendor-documented, not independently verified:** whether the PBX's own admin portal offers any way to scope a Client ID/Secret pair to read-only access is **not documented**. Per help.yeastar.com's "Enable Yeastar P-Series PBX API" page, enabling the API surfaces exactly one toggle ("API" on/off) plus an optional IP-restriction allowlist and status-monitor configuration - no permission-group, role, or scope selection is described anywhere in that flow. This differs from e.g. Cisco Duo (`cisco-duo-mcp`), where the vendor's own admin panel offers explicit `Grant Read Resource` / `Grant Write Resource` toggles per integration. **The practical implication: a Client ID/Secret pair generated for this connector is, as far as Yeastar's own documentation shows, capable of the PBX's full write/control API even though this connector's code never exercises that capability.** The only vendor-side compensating control documented is the optional IP-restriction allowlist (scope the credential to only be usable from Conduit's egress IP(s)) - recommend enabling it. If a narrower credential-scoping mechanism does exist and simply isn't documented publicly, it wasn't found during this connector's build and should be treated as unconfirmed.

## Configuration

| Env var | Description |
|---|---|
| `YEASTAR_PBX_DOMAIN` | This appliance's own domain/IP and port, e.g. `https://pbx.example.com:8088` (default OpenAPI port is 8088). A bare host with no scheme is treated as `https`. |
| `YEASTAR_CLIENT_ID` | OAuth-style Client ID, generated in the PBX web portal under Integrations -> API. |
| `YEASTAR_CLIENT_SECRET` | OAuth-style Client Secret, generated in the same place. |
| `MCP_TRANSPORT` | `stdio` (default) or `http`. |
| `AUTH_MODE` | `env` (default, reads the vars above) or `gateway` (credentials arrive per-request via `X-Yeastar-Pbx-Domain`/`X-Yeastar-Client-Id`/`X-Yeastar-Client-Secret` headers, injected by the Conduit gateway). |
| `CONDUIT_S2S_SECRET` | When set, the HTTP transport requires a valid `X-Gateway-S2S` header (Conduit sidecar auth) on every `/mcp` request. |
| `LOG_LEVEL` | `debug` \| `info` (default) \| `warn` \| `error`. |

## Tools

All 26 tools are read-only. `yeastar_get_trunk` is additionally classified sensitive in Conduit's `VENDOR_TOOL_CONFIG` given trunk config's proximity to telephony secrets, even after field-stripping.

### System
- `yeastar_get_system_information` - this appliance's model, firmware version, hostname.
- `yeastar_get_system_capacity` - current usage against licensed extension/trunk/concurrent-call capacity.

### Extensions
- `yeastar_list_extensions` - list extensions with basic info and per-device online/presence status.
- `yeastar_get_extension` - full detail for a single extension (never includes its password).

### Extension Groups
- `yeastar_list_extension_groups` - list extension groups.
- `yeastar_get_extension_group` - full detail (member extensions) for one group.

### Trunks
- `yeastar_list_trunks` - list configured trunks.
- `yeastar_get_trunk` - full detail for a single trunk, with secret-shaped fields stripped.
- `yeastar_list_itsp_trunks` - list ITSP (VoIP provider) templates available for trunk creation.

### Routes
- `yeastar_list_inbound_routes` / `yeastar_get_inbound_route` - inbound call routing.
- `yeastar_list_outbound_routes` / `yeastar_get_outbound_route` - outbound call routing.

### IVR
- `yeastar_list_ivrs` / `yeastar_get_ivr` - auto-attendant menus.

### Ring Groups
- `yeastar_list_ring_groups` / `yeastar_get_ring_group`.

### Queues
- `yeastar_list_queues` / `yeastar_get_queue` - queue configuration.
- `yeastar_get_queue_call_status` - live calls waiting/in-progress in a queue.
- `yeastar_get_queue_agent_status` - l