Flespi MCP Server

Interact with the Flespi telematics platform API for fleet management, device tracking, and telemetry data processing.

GitHub

Flespi MCP Server

MCP Compatible Node.js License: MIT

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:

ClienteSoporteNotas
Claude Desktop✅Configuración local
Claude.ai✅Servidores remotos
Cursor✅Herramientas integradas
VS Code Copilot✅Discovery dinámico
Continue✅Herramientas y recursos
Cline✅Soporte completo

📋 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

🤝 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 LICENSE para detalles.

🙏 Reconocimientos

📞 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

Herramientas

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:

Servidores relacionados