gperezt222/flespi-mcp-server

Flespi MCP Server

Un servidor MCP (Model Context Protocol) para la API completa de Flespi, que permite a los LLMs interactuar con la plataforma de telemática Flespi.

✨ Características Principales

• 🔧 157 herramientas MCP generadas automáticamente desde la API de Flespi
• 🚀 Plug & Play - Compatible con todos los clientes MCP principales
• 📊 API Completa - Acceso a todos los endpoints de Flespi
• 🛡️ Validación robusta - Esquemas tipados con Zod
• 📝 Logging estructurado - Debugging y monitoreo completo
• 🔐 Autenticación segura - Soporte para tokens de Flespi

Características

• API Completa: Expone todos los endpoints de la API de Flespi como herramientas para LLMs
• Autenticación: Soporte completo para tokens de autenticación de Flespi
• Recursos Principales:
  • Devices: Gestión de dispositivos de rastreo
  • Channels: Canales de entrada para protocolos de telemetría
  • Streams: Transmisión de datos hacia sistemas externos
  • Calculators: Motor de análisis e informes
  • Assets: Entidades virtuales para seguimiento multi-dispositivo
  • Plugins: Extensiones de funcionalidad
  • Geofences: Geocercas para análisis geoespacial
  • Groups: Organización y gestión masiva
  • Modems: Envío de SMS y comandos

🚀 Instalación Rápida

# Clonar el repositorio
git clone https://github.com/gperezt222/flespi-mcp-server.git
cd flespi-mcp-server

# Instalar dependencias
npm install

# Probar el servidor
npm test

🔧 Compatibilidad MCP

Este servidor es compatible con todos los clientes MCP principales:

📋 Certificado MCP: Este servidor cumple 100% con la especificación MCP v1.0

Configuración

Obtener Token de Flespi

1. Regístrate en flespi.io
2. Ve a la sección "Tokens" en tu panel de control
3. Crea un nuevo token con los permisos necesarios
4. Copia el token para usarlo en las llamadas a la API

Configuración en tu cliente MCP

Agrega el servidor a tu configuración MCP (ejemplo para Claude Desktop):

{
  "mcpServers": {
    "flespi": {
      "command": "node",
      "args": ["/ruta/a/tu/proyecto/server.js"],
      "cwd": "/ruta/a/tu/proyecto"
    }
  }
}

Uso

Herramientas Disponibles

El servidor expone automáticamente todas las operaciones de la API de Flespi como herramientas MCP. Los nombres de las herramientas siguen el patrón:

flespi_{método}_{recurso}[_{sub-recurso}]

Ejemplos:

• flespi_get_devices - Listar dispositivos
• flespi_post_devices - Crear nuevos dispositivos
• flespi_get_devices_messages - Obtener mensajes de dispositivos
• flespi_put_channels - Actualizar canales
• flespi_delete_streams - Eliminar streams

Herramientas Especiales

• flespi_get_protocols - Obtiene protocolos disponibles, tipos de dispositivos, etc.
• flespi_list_tools - Lista todas las herramientas disponibles con categorización

🔍 157 Herramientas Total

• 155 operaciones de la API de Flespi
• 2 herramientas utilitarias
• 77 parámetros globales con documentación detallada
• 38 selectores especializados con ejemplos de uso

Parámetros Comunes

Todas las herramientas requieren:

• token - Tu token de autenticación de Flespi

Parámetros adicionales según el endpoint:

• Parámetros de ruta (como device_id, channel_id)
• Parámetros de consulta (como fields, limit, offset)
• body - Datos del cuerpo de la petición (para POST/PUT/PATCH)

Ejemplos de Uso

Listar Dispositivos

// Herramienta: flespi_get_devices
{
  "token": "tu_token_aqui",
  "fields": "id,name,ident,enabled"
}

Crear un Nuevo Canal

// Herramienta: flespi_post_channels
{
  "token": "tu_token_aqui",
  "body": {
    "protocol_id": 4,
    "name": "Mi Canal TCP",
    "configuration": {}
  }
}

Obtener Mensajes de un Dispositivo

// Herramienta: flespi_get_devices_messages
{
  "token": "tu_token_aqui",
  "devices.selector": "123456",
  "count": 100,
  "fields": "timestamp,position.latitude,position.longitude,speed"
}

🎯 Ejemplos de Selectores

Los selectores en Flespi permiten filtrar y seleccionar recursos específicos:

Selectores de Dispositivos

// Seleccionar todos los dispositivos
"devices.selector": "all"

// Seleccionar por IDs específicos
"devices.selector": "1,2,3"

// Seleccionar por IMEI
"devices.selector": "configuration.ident=\"123456789012345\""

// Seleccionar por nombre con wildcards
"devices.selector": "name=\"GPS*\""

// Seleccionar dispositivos conectados
"devices.selector": "connected=true"

// Seleccionar por grupo
"devices.selector": "groups.id=1234"

Selectores de Assets

// Seleccionar por nombre
"assets.selector": "name=\"Truck*\""

// Seleccionar por metadata
"assets.selector": "metadata.clientid=4"

// Seleccionar por último dispositivo asignado
"assets.selector": "last.device_id=100"

Casos de Uso Comunes

Gestión de Flota

• Monitorear ubicaciones de vehículos en tiempo real
• Generar informes de actividad
• Configurar geocercas para alertas
• Gestionar dispositivos y sus configuraciones

Análisis de Datos

• Extraer datos históricos de telemetría
• Calcular métricas personalizadas
• Generar informes automáticos
• Detectar patrones de comportamiento

Integración de Sistemas

• Sincronizar datos con sistemas externos
• Automatizar flujos de trabajo
• Crear dashboards personalizados
• Implementar notificaciones

Recursos de Flespi

Documentación

• Documentación de la API
• Flespi Platform
• Flespi Blog

🤝 Contribuir

¡Las contribuciones son bienvenidas! Por favor:

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request

📄 Licencia

Este proyecto está bajo la Licencia MIT - ver el archivo para detalles.

🙏 Reconocimientos

• Flespi por su excelente plataforma de telemática
• Model Context Protocol por el estándar MCP
• Anthropic por Claude y el ecosistema MCP

📞 Soporte

• 📧 Issues: GitHub Issues
• 📖 Documentación: Ver MCP_COMPLIANCE_REPORT.md para detalles técnicos
• 🔧 Testing: Usa npx @modelcontextprotocol/inspector node server.js

Hecho con ❤️ para la comunidad MCP

• Guías de Conocimiento
• Protocolos Soportados
• Tipos de Dispositivos

Herramientas

• flespi.io Panel - Interfaz web
• Toolbox - Herramientas de desarrollo
• MQTT Browser - Cliente MQTT
• Setbox - Configuración de dispositivos

Limitaciones

• Requiere conexión a internet para comunicarse con la API de Flespi
• Sujeto a los límites de tasa de la API de Flespi
• El token debe tener los permisos adecuados para las operaciones solicitadas

Desarrollo

Estructura del Proyecto

.
├── server.js          # Servidor MCP principal
├── package.json       # Dependencias y scripts
├── flespi.json        # Especificación de la API de Flespi
└── README.md          # Este archivo

Ejecutar en Modo Desarrollo

npm run dev

Contribuir

Las contribuciones son bienvenidas. Por favor:

1. Abre un issue para discutir cambios mayores
2. Haz fork del repositorio
3. Crea una rama para tu feature
4. Envía un pull request

Licencia

MIT License - ve el archivo LICENSE para más detalles.

Soporte

Para problemas con este servidor MCP:

• Abre un issue en este repositorio

Para problemas con la API de Flespi:

• Consulta la documentación oficial
• Contacta el soporte de Flespi