🚀 Rablo MCP Server

Servidor MCP (Model Context Protocol) para conectar Claude Desktop con la API de Rablo.

Soporta dos protocolos de comunicación:

• 🔌 WebSocket (wss://) - Bidireccional, ideal para redes locales
• 📡 SSE (https://) - Unidireccional, ideal para hosting en la nube

📦 Instalación y Configuración

Requisitos Previos

• Node.js instalado
• Servidor de Rablo API corriendo (npm start en la raíz del proyecto)
• Claude Desktop instalado

Elegir Protocolo de Comunicación

| Protocolo | Ventajas | Cuándo Usar | |-----------|----------|-------------| | WebSocket | Más rápido, bidireccional | Desarrollo local, VPN, redes privadas | | SSE | Compatible con proxies, HTTPS estándar | Hosting en la nube (Azure, AWS, Render, etc.) |

Recomendación:

• ✅ Usa WebSocket para desarrollo local
• ✅ Usa SSE para producción/hosting remoto

Configuración (5 minutos)

1. Obtener Token JWT

cd rablo-mcp-server
node obtener-token.js

Ingresa tu email y contraseña. Copia el token que se muestra.

2. Configurar Claude Desktop

Elige la configuración según el protocolo:

Opción A: WebSocket (Desarrollo Local)

1. Abre el archivo de configuración:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Añade la configuración del MCP:

{
  "mcpServers": {
    "rablo": {
      "command": "node",
      "args": [
        "RUTA_COMPLETA\\rablo-mcp\\src\\mcp\\client.js"
      ],
      "env": {
        "RABLO_MCP_TOKEN": "tu_token_jwt_aqui",
        "RABLO_MCP_URL": "ws://localhost:3000/mcp"
      }
    }
  }
}

Opción B: SSE (Hosting Remoto/HTTPS)

{
  "mcpServers": {
    "rablo-sse": {
      "command": "node",
      "args": [
        "RUTA_COMPLETA\\rablo-mcp\\src\\mcp\\client-sse.js"
      ],
      "env": {
        "RABLO_MCP_TOKEN": "tu_token_jwt_aqui",
        "RABLO_MCP_URL": "https://rablo-mcp.azure.com"
      }
    }
  }
}

Importante:

• Reemplaza RUTA_COMPLETA con la ruta absoluta al proyecto
• En Windows usa \\ (doble barra invertida)
• Reemplaza tu_token_jwt_aqui con tu token JWT
• Para SSE, usa https:// en lugar de ws://

3. Reiniciar Claude Desktop

1. Cierra Claude Desktop completamente
2. Abre el Administrador de Tareas y termina todos los procesos de Claude
3. Vuelve a abrir Claude Desktop
4. Ve a Settings → Developer → MCP Servers
5. Deberías ver "rablo" con punto verde ✅

🧪 Verificación

En Claude Desktop, pregunta:

¿Qué herramientas de Rablo tienes disponibles?

Claude debería listar 61 herramientas disponibles.

🔄 Diferencias entre Protocolos

WebSocket (ws:// o wss://)

• ✅ Comunicación bidireccional instantánea
• ✅ Más eficiente para alta frecuencia de mensajes
• ❌ Puede tener problemas con proxies/firewalls
• 🎯 Ideal para: Desarrollo local, redes privadas

SSE (https://)

• ✅ Compatible con cualquier proxy/firewall HTTP
• ✅ Funciona con HTTPS estándar
• ✅ Ideal para hosting en la nube
• ❌ Solo servidor → cliente (cliente usa POST)
• 🎯 Ideal para: Azure, AWS, Render, Vercel, etc.

📚 Herramientas Disponibles (61)

🏢 Empresas (Developer Companies)

• developerCompanies_getAll - Listar empresas
• developerCompanies_getById - Ver detalles
• developerCompanies_create - Crear empresa
• developerCompanies_updateById - Actualizar
• developerCompanies_deleteById - Eliminar
• developerCompanies_getTrainingById - Ver IA
• developerCompanies_retrainingAI - Reentrenar IA

👥 Empleados (Company Employees)

• companyEmployees_getAllByCompanyId - Listar
• companyEmployees_getById - Ver detalles
• companyEmployees_create - Crear
• companyEmployees_updateById - Actualizar
• companyEmployees_deleteById - Eliminar
• Y más...

👥 Grupos, 📝 Posiciones, 📋 Formularios, 🔄 Procesos, 📄 Documentos, 📊 Reportes, 🤖 IA, 🔔 Notificaciones...

Ver lista completa en la documentación del servidor.

🔧 Solución de Problemas

MCP aparece apagado (punto rojo 🔴)

Causas comunes:

1. Servidor no corriendo → Ejecuta npm start en la raíz del proyecto
2. Token expirado → Genera uno nuevo con node obtener-token.js
3. Ruta incorrecta → Verifica la ruta absoluta en la configuración
4. Error en JSON → Valida el JSON en https://jsonlint.com

Diagnóstico:

node diagnostico.js TU_TOKEN_JWT

Token expirado

Los tokens JWT expiran después de un tiempo. Para renovar:

node obtener-token.js

Luego actualiza el token en %APPDATA%\Claude\claude_desktop_config.json y reinicia Claude Desktop.

Ver logs del servidor

Si necesitas ver qué está pasando, habilita los logs en app.js:105:

// Descomentar esta línea:
console.log('📨 Mensaje MCP recibido:', JSON.stringify(message, null, 2));

📁 Estructura de Archivos

rablo-mcp/
├── server/
│   ├── index.js                   # Servidor principal (soporta WebSocket y SSE)
│   ├── transport.js               # Transport WebSocket
│   ├── transport-sse.js           # Transport SSE (nuevo)
│   ├── tools.js                   # Definición de 61 herramientas MCP
│   ├── config.js                  # Configuración del servidor
│   └── utils/
│       └── jwt.js                 # Validación de tokens JWT
├── src/
│   └── mcp/
│       ├── client.js              # Cliente MCP WebSocket
│       └── client-sse.js          # Cliente MCP SSE (nuevo)
├── diagnostico.js                 # Script de diagnóstico
├── obtener-token.js              # Obtener JWT token
├── claude_desktop_config.example.json     # Ejemplo WebSocket
├── claude_desktop_config_sse.example.json # Ejemplo SSE (nuevo)
├── .env.example                  # Variables de entorno
└── README.md                     # Esta documentación

🔒 Seguridad

• ⚠️ NO compartas tu archivo claude_desktop_config.json (contiene tu token)
• ⚠️ NO subas tokens a Git
• ✅ Regenera tokens si se exponen
• ✅ Los tokens expiran automáticamente

📖 Documentación Adicional

• INICIO_RAPIDO.md - Guía de inicio rápido
• CONFIGURACION_CLAUDE.md - Configuración detallada y troubleshooting
• Servidor Web: http://localhost:8080/mcp
• API Docs: http://localhost:8080/api-docs

💡 Ejemplos de Uso

# En Claude Desktop:

"Usa el MCP de rablo para obtener las empresas del desarrollador 1"

"Lista los empleados de la empresa 5"

"Crea un nuevo grupo llamado 'Ventas' en la empresa 5"

"Obtén el reporte general de la empresa 10"

🌐 Despliegue en la Nube (SSE)

Para desplegar el servidor MCP en la nube y conectarte usando SSE:

1. Desplegar el servidor

# Subir el servidor a tu servicio favorito
# Azure, AWS, Render, Railway, etc.

# El servidor automáticamente soporta SSE en:
# GET /sse - Conexión SSE
# POST /sse/message - Enviar mensajes

2. Configurar Claude Desktop

Usa la configuración SSE con tu URL de producción:

{
  "mcpServers": {
    "rablo-sse": {
      "command": "node",
      "args": ["RUTA\\client-sse.js"],
      "env": {
        "RABLO_MCP_TOKEN": "tu_token",
        "RABLO_MCP_URL": "https://tu-servidor.azure.com"
      }
    }
  }
}

3. Configuración de Proxy Reverso (opcional)

Si usas nginx o Azure Application Gateway, no necesitas cambios. SSE usa HTTPS estándar.

🆘 Soporte

Si encuentras problemas:

1. Ejecuta el diagnóstico: node diagnostico.js TU_TOKEN
2. Revisa los logs del servidor (terminal donde ejecutaste npm start)
3. Consulta CONFIGURACION_CLAUDE.md
4. Verifica que el token no haya expirado

📝 Actualizar Token

Cuando el MCP deje de funcionar (token expirado):

1. node obtener-token.js
2. Copia el nuevo token
3. Actualiza %APPDATA%\Claude\claude_desktop_config.json
4. Reinicia Claude Desktop

Versión: 1.0.0 Última actualización: Octubre 2025