yeastar-mcp
# yeastar-mcp
[](https://github.com/OWNER/yeastar-mcp/actions/workflows/ci.yml)
[](https://github.com/OWNER/yeastar-mcp/actions/workflows/codeql.yml)
[](LICENSE)


Server MCP per amministrare un centralino **Yeastar P-Series Software Edition** da un assistente AI
(Claude Code, Claude Desktop o altri client MCP). Gira **dentro la LAN del centralino** e usa la
OpenAPI ufficiale del PBX (`openapi/v1.0`).
- **Lettura** di tutto: interni, gruppi, trunk, rotte, IVR, ring group, code, orari, festività,
rubriche, blacklist, telefoni, impostazioni globali, CDR, stato live di code e chiamate.
- **Modifica** con un flusso in due fasi: **anteprima → conferma**. Nessuna modifica parte senza un
`sì` esplicito.
- Prima di ogni modifica il server salva uno **snapshot**. Dopo la modifica rilegge la configurazione
e verifica che i valori siano stati applicati. Tutto finisce nel **registro**, e ogni modifica di
configurazione si può **annullare**.
> Stato: versione 0.1.0. È stata testata contro un PBX simulato che riproduce il formato della
> OpenAPI, **non ancora contro un centralino reale**. Prima di usarla in produzione provala su
> un'istanza di test o in finestra di manutenzione, e fai un backup (vedi sotto).
---
## Come funziona una modifica
```
Utente: "cambia il nome dell'interno 2000 in Mario Rossi"
│
├─ yeastar_search(extension, "2000") → id 39
├─ yeastar_prepare_change(extension, update, 39, {caller_id_name: "Mario Rossi"})
│ legge lo stato attuale, calcola il diff, NON tocca il PBX
│ ← change_id chg_1a2b3c4d + anteprima (prima/dopo)
│
Assistente: "Cambio caller_id_name da 'Leo Ball' a 'Mario Rossi'. Confermi?"
Utente: "sì"
│
└─ yeastar_apply_change(chg_1a2b3c4d, confirm=true)
1. ricontrolla che nessuno abbia cambiato l'interno nel frattempo
2. salva lo snapshot "prima" in data/snapshots/
3. esegue la modifica
4. rilegge l'interno e verifica il risultato
5. scrive la riga nel registro data/audit.jsonl
```
### Conferma diretta dell'utente (MCP elicitation)
Se il client supporta l'*elicitation* MCP, `yeastar_apply_change` non si fida solo dell'assistente.
Il server mostra **direttamente a te**, nell'interfaccia del client, un modulo Sì/No con il riepilogo
della modifica (segreti mascherati). L'assistente non può compilarlo al tuo posto. Se rispondi No o
chiudi il modulo, la modifica viene annullata.
| `CONFIRM_MODE` | Comportamento |
|---|---|
| `auto` (default) | Modulo di conferma se il client lo supporta, altrimenti conferma in chat |
| `elicit` | Modulo obbligatorio: con client che non lo supportano le modifiche sono rifiutate |
| `chat` | Solo conferma in chat, tramite l'assistente |
Il registro annota per ogni modifica il canale di conferma (`confermata_tramite`).
Le anteprime scadono dopo 15 minuti (`CHANGE_TTL_SECONDS`) e si possono applicare una sola volta.
`yeastar_prepare_rollback(change_id)` prepara l'annullamento: ripristina i valori precedenti, elimina
l'oggetto creato oppure ricrea quello cancellato. Anche l'annullamento passa da anteprima e conferma.
## Strumenti (tool) esposti
| Tool | Cosa fa | Modifica il PBX? |
|---|---|---|
| `yeastar_overview` | Modello, firmware, capacità, stato del server | no |
| `yeastar_catalog` | Risorse e operazioni supportate | no |
| `yeastar_list` / `yeastar_search` / `yeastar_get` / `yeastar_query` | Lettura delle risorse | no |
| `yeastar_read` | Qualsiasi endpoint di sola lettura (CDR, `queue/agent_status`, `call/query`, `system/get_menuoptions`…) | no |
| `yeastar_prepare_change` | Anteprima di create/update/delete di una risorsa o di un'impostazione globale | no |
| `yeastar_prepare_operation` | Anteprima di un'operazione live (riavvio telefoni, pausa agenti, chiamate, conferenze) | no |
| `yeastar_prepare_raw` | Anteprima di una chiamata diretta a un endpoint fuori catalogo | no |
| `yeastar_prepare_rollback` | Anteprima dell'annullamento di una modifica applicata | no |
| `yeastar_apply_change` | **Applica** una modifica preparata (`confirm=true`) | **sì** |
| `yeastar_cancel_change` / `yeastar_pending_changes` | Gestione delle anteprime in attesa | no |
| `yeastar_audit_log` | Registro delle modifiche | no |
**Risorse** (`yeastar_catalog` dà l'elenco completo):
- interni: `extension`, `extension_group`, `organization`
- routing: `trunk`, `inbound_route`, `outbound_route`, `ivr`, `ring_group`, `queue`, `paging`, `conference`, `custom_prompt`
- orari: `timezone`, `business_hour`, `holiday`
- rubriche: `company_contact`, `phonebook`, `blocked_number`, `allowed_number`, `pin_list`
- telefoni e sistema: `phone`, `backup`, `wakeup_call`
- impostazioni globali: `feature_codes`, `auto_recording`, `ring_group_options`, `queue_options`,
`queue_pause_reasons`, `preferences`, `prompt_preferences`, `web_server`,
`extension_status_monitor`, `trunk_status_monitor`, `webhook`, `cdr_options`
**Operazioni live:**
- telefoni: `phone_reboot`, `phone_reprovision`, `phone_batch_create/update/delete`
- agenti e code: `agent_login`, `agent_pause`, `queue_agents_login`, `queue_agents_pause`
- conferenze: `conference_*`
- chiamate: `call_dial`, `call_hangup`, `call_transfer`, `call_hold`…
- varie: `extension_send_welcome_email`
## Sicurezza
- **Bearer token obbligatorio** in HTTP (`MCP_AUTH_TOKEN`, almeno 24 caratteri). Il confronto è a
tempo costante. Senza token il server risponde 401.
- **Allowlist IP** facoltativa (`MCP_ALLOWED_IPS`) e protezione da DNS rebinding (`MCP_ALLOWED_HOSTS`).
- **HTTPS** diretto con `MCP_TLS_CERT`/`MCP_TLS_KEY`, oppure dietro un reverse proxy.
- **Bloccati di default:**
- endpoint che restituiscono password/PIN in chiaro (`extension/getpassword`,
`conference/viewpassword`…), riattivabili con `YEASTAR_ALLOW_SECRETS`;
- ascolto e registrazione di chiamate (`call/listen`, `call/record_*`), riattivabili con
`YEASTAR_ALLOW_CALL_MONITORING`. Valuta prima i vincoli dell'art. 4 dello Statuto dei lavoratori
e del GDPR;
- gestione token e attivazione del PBX (sempre).
- **Mascheramento:** password, PIN e token compaiono come `***` nelle risposte all'assistente. Un
valore `***` inviato in una modifica viene rifiutato, così non si sovrascrive un PIN per sbaglio.
- **Modalità sola lettura** con `YEASTAR_READ_ONLY=true`.
- **Log puliti:** il token del PBX non viene scritto nei log, perché gli URL di httpx sono silenziati.
- **Un solo token condiviso**, rinnovato automaticamente e revocato all'arresto: Yeastar ammette al
massimo 8 token per applicazione.
- **Conferma anche nel client.** Non mettere `yeastar_apply_change` tra i tool "sempre consentiti"
del client. Così, oltre alla conferma in chat, il client ti chiede il permesso a ogni applicazione.
## 1. Preparare il centralino
1. Sul portale del PBX vai in **Integrations → API** e attiva l'API.
2. Annota **Client ID** e **Client Secret**.
3. Tra gli IP consentiti per l'API aggiungi l'IP della macchina che farà girare questo server.
4. Verifica che il firmware sia almeno 83.7.0.16 (consigliato l'ultimo disponibile).
## 2. Installazione con Docker (consigliata)
Su una VM o un host nella stessa LAN del centralino. Puoi usare l'immagine pubblicata a ogni release,
`ghcr.io/OWNER/yeastar-mcp:<versione>` (amd64/arm64, con SBOM e attestazione), verificabile con
`gh attestation verify oci://ghcr.io/OWNER/yeastar-mcp:<versione> --owner OWNER`. In alternativa
costruiscila dal sorgente:
```bash
cp .env.example .env
# compila YEASTAR_BASE_URL, YEASTAR_CLIENT_ID, YEASTAR_CLIENT_SECRET, MCP_AUTH_TOKEN, MCP_ALLOWED_IPS
python3 -c "import secrets; print(secrets.token_urlsafe(32))" # per MCP_AUTH_TOKEN
# in docker-compose.yml sostituisci 192.168.1.20 con l'IP LAN dell'host
docker compose up -d --build
docker compose logs -f
curl http://192.168.1.20:8765/healthz # {"status":"ok"}
```
I dati persistenti (registro e snapshot) stanno in `./data`.
### Senza Docker
```bash
uv sync --no-dev # oppure: python3 -m venv .venv && . .venv/bin/activate && pip install .
set -a; . ./.env; set +a
uv run yeastar-mcp
```
Per un servizio permanente puoi usare un'unità systemd che esegue `yeastar-mcp` con
`EnvironmentFile=/percorso/.env`.
## 3. Collegare il client
Il client deve stare in una rete che raggiunge il server (la LAN o una VPN). I connettori
personalizzati di claude.ai sul web partono dal cloud e **non vedono la tua LAN**. Usa quindi uno dei
client qui sotto.
**Claude Code**
```bash
claude mcp add --transport http yeastar http://192.168.1.20:8765/mcp \
--header "Authorization: Bearer IL_TUO_TOKEN"
```
**Claude Desktop**, tramite il bridge `mcp-remote` (serve Node.js). In `claude_desktop_config.json`:
```json
{
"mcpServers": {
"yeastar": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://192.168.1.20:8765/mcp",
"--allow-http", "--header", "Authorization:${YEASTAR_MCP_AUTH}"],
"env": { "YEASTAR_MCP_AUTH": "Bearer IL_TUO_TOKEN" }
}
}
}
```
Con HTTPS attivo usa `https://` e togli `--allow-http`.
**Uso locale senza rete** (stdio, client e server sulla stessa macchina): imposta
`MCP_TRANSPORT=stdio` e avvia `yeastar-mcp` come comando del client. In questa modalità il token non
serve.
## Esempi di richieste
- "Mostrami tutti gli interni e quali telefoni sono offline"
- "Che agenti sono in pausa nella coda 6400?" (usa `yeastar_read queue/agent_status`)
- "Aggiungi il 24 dicembre pomeriggio alle festività"
- "Cambia la destinazione fuori orario della rotta in ingresso 'Principale' sull'IVR 6200"
- "Riavvia il telefono della reception"
- "Fai un backup prima di procedere" (`yeastar_prepare_change backup create`)
- "Annulla l'ultima modifica" (`yeastar_audit_log`, poi `yeastar_prepare_rollback`)
## Note sull'API Yeastar
- Ogni oggetto ha un `id` univoco diverso dal numero: l'interno 2000 può avere id 39. Il server lo
trova con `yeastar_search`.
- Gli update inviano solo i campi cambiati. I campi **lista** (per esempio
`outbound_route_permission` o `pause_reason_list`) vengono **sostituiti per intero**: l'anteprima
lo segnala con un avviso.
- Se il PBX normalizza un valore (per esempio un'email in minuscolo), la verifica restituisce
`DA CONTROLLARE` con i valori letti. Non è un errore, ma conviene darci un'occhiata.
- Il rollback di una cancellazione ricrea l'oggetto con un **nuovo id**. I riferimenti in rotte,
gruppi e code e le password di registrazione vanno ripristinati a mano.
- La documentazione Yeastar usa sia `extension_group/…` sia `extensiongroup/…`: il server prova
entrambi e ricorda quello che funziona.
- I nomi dei parametri delle operazioni live seguono la
[Developer Guide Yeastar](https://help.yeastar.com/en/p-series-software-edition/developer-guide/api-interfaces-and-events-summary.html).
`yeastar_catalog` riporta esempi e link.
## File su disco
| Percorso | Contenuto |
|---|---|
| `data/audit.jsonl` | Una riga JSON per ogni modifica (riuscita o rifiutata dal PBX), con i segreti mascherati |
| `data/snapshots/<change_id>.json` | Stato prima (e dopo) di ogni modifica. Permessi 600: può contenere PIN |
## Configurazione completa
Tutte le variabili, commentate, sono in [`.env.example`](.env.example).
## Sviluppo
```bash
uv sync && uv run pre-commit install
uv run ruff format --check . && uv run ruff check . && uv run mypy && uv run pytest --cov
```
I test avviano un PBX simulato e il server MCP vero in HTTP, poi lo usano con un client MCP vero
(sia con l'handshake classico sia con quello del protocollo 2026-07-28). Coprono:
- autenticazione, allowlist IP, DNS rebinding, sola lettura;
- mascheramento dei segreti, alias dei percorsi;
- anteprima/conferma, conferma diretta via elicitation (sì, no, chiusura), deriva concorrente;
- verifica post-modifica, rollback di update/create/delete;
- errori del PBX, rinnovo e scadenza del token, blocco degli endpoint sensibili;
- avvio da riga di comando.
Le regole del progetto sono in [CONTRIBUTING.md](CONTRIBUTING.md). Le segnalazioni di sicurezza
vanno fatte come indicato in [SECURITY.md](SECURITY.md), che contiene anche il modello di minaccia.
## Roadmap
- [ ] Test su centralini reali (firmware 83.2x) e catalogo dei parametri delle operazioni live
- [ ] OAuth 2.1 (spec MCP authorization) per avere più amministratori con identità e permessi distinti
- [ ] Anteprime legate alla sessione/utente che le ha preparate
- [ ] Eventi Yeastar (webhook/WebSocket) esposti come notifiche MCP
- [ ] Interfaccia e messaggi in inglese
## Crediti
Sviluppato da **[NextGen Technologies Italia](https://n3xtgentech.it/)** (Next Gen Technologies
Italia SRLS, Prato), che si occupa di reti aziendali, AI e infrastrutture. Per installazione e
assistenza: [prenota una call](https://n3xtgentech.it/prenota-call.html).
Progetto indipendente, non affiliato a Yeastar. "Yeastar" e "P-Series" sono marchi dei rispettivi
proprietari.
Rilasciato con licenza [MIT](LICENSE).
TDQS
Scored across 15 tools
Most tools have clearly distinct roles: list/search/get/query separate basic listing, lookup, single-detail, and batch-detail reads, while prepare_change, prepare_operation, prepare_raw, and prepare_rollback are differentiated by config changes, live operations, raw escape hatch, and rollback. Some overlap remains between yeastar_read and the catalog-based read tools, since read can also retrieve status/report data that overlaps conceptually with get/query/list.
All tools use a consistent yeastar_ snake_case prefix, and the core workflow names (prepare_change, apply_change, cancel_change, pending_changes, audit_log) are highly predictable. Minor inconsistency comes from mixing verb-style names (list, search, get, query, read) with noun-style names (overview, catalog, audit_log), though the pattern remains readable.
Fifteen tools is at the upper end of the ideal range but appropriate for a PBX management server that separates read operations, safe preparation, application, cancellation, rollback, and auditing. Each tool appears to serve a distinct part of the configuration/live-operation lifecycle rather than duplicating another.
The server covers discovery (overview, catalog), read workflows (list, search, get, query, read), safe write workflows (prepare/apply/cancel/pending), rollback, raw endpoint escape, and audit logging. This provides broad CRUD/lifecycle coverage for PBX configuration and live operations with no obvious dead ends, especially because generic read and raw/prepare paths cover uncatalogued endpoints.