# centralita-vpbx-mcp

MCP (Model Context Protocol) para la **centralita virtual `vpbx.me`** (plataforma de PBX en la nube basada en Java/JAX-RS sobre FreeSWITCH). Da a un asistente compatible con MCP (Claude Code, Claude Desktop, etc.) acceso a la telefonía: historial, grabaciones, llamadas en tiempo real, click-to-call, control de llamadas, extensiones, colas, agentes, contactos y buzones.

Arquitectura TypeScript/Node sobre el SDK oficial de MCP. La API está documentada en [`API_REFERENCE.md`](./API_REFERENCE.md).

> ⚠️ Proyecto comunitario, no oficial de la plataforma. Úsalo solo con centralitas para las que tengas autorización.

---

## Qué puede hacer (52 herramientas)

### 🟢 Solo lectura (siempre disponibles)
- **Tiempo real:** `pbx_live_status` (llamadas en curso + estado de extensiones).
- **Historial (CDR):** `pbx_list_calls`, `pbx_get_call`, `pbx_count_calls`.
- **Grabaciones:** `pbx_get_recording_url`, `pbx_download_recording` (guarda el MP3 a disco), `pbx_download_voicemail_audio`.
- **Extensiones:** `pbx_list_extensions`, `pbx_get_extension`, `pbx_find_extension_by_username`.
- **Colas:** `pbx_list_queues`, `pbx_get_queue`, `pbx_queue_callers`, `pbx_queue_state`, `pbx_queue_waittime`.
- **Agentes:** `pbx_list_agents`, `pbx_get_agent`, `pbx_agent_breaktypes`, `pbx_agent_status`, `pbx_agent_statuscount`.
- **Contactos:** `pbx_list_contacts`, `pbx_get_contact`.
- **Locuciones / buzones:** `pbx_list_announcements`, `pbx_get_announcement`, `pbx_list_voicemails`, `pbx_get_voicemail`.
- **Encuestas:** `pbx_list_surveys`.

### 🔵 Atajos / informes (solo lectura, alto valor)
- `pbx_calls_in_range` — **todas** las llamadas de un día/rango (pagina solo y deduplica) + resumen.
- `pbx_calls_report` — **informe por extensión**: salientes/entrantes/atendidas/minutos, resolviendo el número de extensión a su nombre.
- `pbx_extension_directory` — directorio número → nombre → email.
- `pbx_recordings_in_range` — llamadas grabadas de un periodo, listas para descargar y transcribir.

### 🟠 Acciones de llamada — candado `CENTRALITA_ENABLE_CALLS`
`pbx_originate_call`, `pbx_click_to_call_external`, `pbx_click_to_call_queue`, `pbx_click_to_call_inverse_queue`, `pbx_hangup`, `pbx_schedule_hangup`, `pbx_blind_transfer`, `pbx_attended_transfer_start/complete/cancel`, `pbx_start_recording`, `pbx_stop_recording`, `pbx_broadcast_audio`.

### 🔴 Escritura de configuración — candado `CENTRALITA_ENABLE_WRITES`
`pbx_update_extension`, `pbx_reset_sip_password`, `pbx_update_contact`, `pbx_set_agent_status`, `pbx_update_cdr_vars`, `pbx_mark_voicemail_read/unread`, `pbx_delete_voicemail`.

---

## Seguridad por capas

Tres candados independientes, **todos OFF por defecto** (arranca en solo lectura):

| Variable | Por defecto | Desbloquea |
|---|---|---|
| `CENTRALITA_ENABLE_CALLS` | `false` | Originar/colgar/transferir/grabar llamadas reales |
| `CENTRALITA_ENABLE_WRITES` | `false` | Editar extensiones/contactos/agentes, borrar buzones… |
| `CENTRALITA_ALLOW_SECRETS` | `false` | Devolver contraseñas SIP/web en claro (si no, se redactan) |

Las tools llevan anotaciones MCP (`readOnlyHint` / `destructiveHint`) para que el cliente agrupe lectura vs. acciones en su panel de permisos.

> Nota: `GET /api/extension` de la plataforma puede devolver contraseñas SIP en claro. Este MCP las redacta por defecto. Trata tu `CENTRALITA_API_KEY` como un secreto sensible.

---

## Instalación

```bash
git clone <este-repo> centralita-vpbx-mcp
cd centralita-vpbx-mcp
npm install
npm run build
```

Copia `.env.example` a `.env` y pon tu `CENTRALITA_API_KEY`.

---

## Uso

### Local (Claude Code / Claude Desktop · stdio)
```bash
npm start              # solo lectura
```
Registro en `claude_desktop_config.json` (o `.mcp.json` de Claude Code):
```json
{
  "mcpServers": {
    "centralita": {
      "command": "node",
      "args": ["/ruta/a/centralita-vpbx-mcp/dist/index.js"],
      "env": {
        "CENTRALITA_API_KEY": "TU_API_KEY",
        "CENTRALITA_ENABLE_CALLS": "false",
        "CENTRALITA_ENABLE_WRITES": "false"
      }
    }
  }
}
```
Para permitir click-to-call, pon `CENTRALITA_ENABLE_CALLS` a `"true"`.

### Remoto (HTTP)
```bash
npm run start:http     # escucha en http://0.0.0.0:8788/mcp
```
Protégelo con `CENTRALITA_MCP_AUTH_TOKEN` (cabecera `Authorization: Bearer <token>`) y ponlo tras HTTPS. Endpoint de salud: `GET /health`.

---

## Validación

```bash
node test-mcp.mjs
```
Comprueba el handshake MCP, lista las 52 tools, hace una lectura real (`pbx_count_calls`) y verifica que el candado de acciones bloquea `pbx_hangup`.

---

## Arquitectura

```
src/
  config.ts        Carga .env + candados de seguridad
  client.ts        Cliente HTTP (X-Api-Key) + descarga binaria
  util.ts          jsonResult, ensureCalls/ensureWrites, fechas, redacción de secretos
  server.ts        Monta el McpServer y registra los 4 módulos
  index.ts         Arranque stdio (local) o HTTP (remoto)
  tools/
    read.ts        Lectura (CDR, grabaciones, extensiones, colas, agentes, contactos, buzones)
    workflow.ts    Atajos/informes (paginado de CDR, informe por extensión, directorio)
    actions.ts     Acciones de llamada (candado CENTRALITA_ENABLE_CALLS)
    write.ts       Escritura de configuración (candado CENTRALITA_ENABLE_WRITES)
```

## Licencia

MIT — ver [`LICENSE`](./LICENSE).