Centralita Vpbx

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.

⚠️ 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

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)

npm start              # solo lectura

Registro en claude_desktop_config.json (o .mcp.json de Claude Code):

{
  "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)

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

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.