Servidor MCP OneMap8

Expone una instalación de seguimiento de flotas OneMap8 a Claude, ChatGPT y cualquier otro cliente MCP, para que la gente pueda hacer preguntas en lenguaje natural en lugar de manejar la interfaz de informes:

¿Dónde está el camión 12 ahora mismo? ¿Cuántos kilómetros recorrió la flota de reparto la semana pasada? Envíame por correo el informe de viajes de las furgonetas, de lunes a viernes. ¿Qué vehículos lanzaron alarmas durante la noche?

32 herramientas que cubren toda la superficie de la API: dispositivos, posiciones, los siete tipos de informes, geocercas, conductores, mantenimiento, notificaciones, calendarios, usuarios, permisos y despacho de comandos a dispositivos.

Inicio rápido

npm install && npm run build

Copia .env.example a .env y completa la URL de tu servidor y un token:

cp .env.example .env

Verifica la conexión de extremo a extremo:

npm test

Related MCP server: Enterprise MCP Gateway and Tool Registry

Autenticación

El plugin nunca tiene más acceso que la cuenta de OneMap que tiene detrás. Cualquier dispositivo, grupo o informe que ese usuario pueda ver a través de la interfaz web es exactamente lo que el modelo puede alcanzar: el propio sistema de permisos de OneMap es el que aplica la restricción, y no hay un modelo de privilegios separado que mantener sincronizado.

Dos opciones, configuradas en .env:

• ONEMAP_TOKEN (recomendado): un token de API emitido para la cuenta. Se envía como token de portador. Se puede revocar sin cambiar la contraseña.

• ONEMAP_EMAIL + ONEMAP_PASSWORD: autenticación básica. Funciona, pero deja la contraseña en texto plano en el disco; úsalo solo para empezar.

Conectar un cliente

Claude Desktop / Claude Code (stdio)

Añade a claude_desktop_config.json (o .mcp.json para Claude Code):

{
  "mcpServers": {
    "onemap8": {
      "command": "node",
      "args": ["/absolute/path/to/ai-plugin/dist/stdio.js"],
      "env": {
        "ONEMAP_URL": "https://mcp.onemap8.com/api",
        "ONEMAP_TOKEN": "your-token-here",
        "ONEMAP_ALLOW_COMMANDS": "false"
      }
    }
  }
}

Conector remoto / ChatGPT (HTTP)

npm run start:http

Sirve Streamable HTTP en POST /mcp (comprobación de estado en /health). Se ejecuta sin estado: un servidor nuevo por petición, sin nada compartido entre llamadas, por lo que un solo despliegue puede atender a muchos usuarios.

Con ONEMAP_HTTP_PASSTHROUGH_AUTH=true (el valor predeterminado), la cabecera Authorization: Bearer <token> de cada petición suministra el token de OneMap de ese llamante, de modo que cada usuario queda limitado a sus propios permisos en lugar de compartir una cuenta de servicio.

Antes de exponerlo públicamente:

• Termina TLS delante del proceso: los tokens viajan en las cabeceras.

• Establece ONEMAP_ALLOWED_ORIGINS si se conectarán clientes basados en navegador; los orígenes no listados serán rechazados.

• Esto no implementa OAuth. O bien lo pones detrás de una puerta de enlace que lo haga, o entrega a cada usuario un token de API de OneMap para que lo pegue en su cliente.

Salvaguardas

Los permisos de la propia cuenta son la frontera de seguridad real. Estas opciones son la segunda capa: limitan lo que el modelo puede hacer con esa cuenta, que es una cuestión distinta de lo que la cuenta puede hacer.

Dos herramientas requieren además un argumento explícito confirm: true, además de las opciones anteriores: onemap_send_command y onemap_delete_positions.

Sobre los comandos de dispositivo en concreto: onemap_send_command llega al hardware físico: inmovilizadores de motor, cerraduras de puertas, relés. Habilitarlo significa que un modelo de lenguaje está a una llamada de detener un vehículo. Está activado por defecto porque pediste toda la superficie, pero considera ONEMAP_ALLOW_COMMANDS=false para cualquier despliegue al que puedan acceder usuarios que no seas tú, y deja el envío de comandos a la propia interfaz de los operadores.

Informes programados

La API de OneMap no tiene un endpoint de programación recurrente. Puede enviar un informe por correo una vez, bajo petición: onemap_report con delivery: "mail" llama a /reports/{type}/mail, y el servidor envía la hoja de cálculo por correo de forma asíncrona al propietario de la cuenta.

Para que se repita, se necesita un programador externo que llame a lo mismo con una cadencia:

Para cualquier cosa de la que dependa un negocio, usa la primera opción. El prompt schedule_recurring_report guía en la elección del informe y los parámetros, lo ejecuta una vez para que puedas comprobar el resultado y luego expone ambas opciones.

Una versión en n8n sería aproximadamente: Disparador de programa → Petición HTTP GET {ONEMAP_URL}/reports/trips/mail con deviceId, from, to y una cabecera Authorization: Bearer.

Referencia de herramientas

Estado de la flota — onemap_list_devices, onemap_get_device, onemap_list_groups, onemap_live_positions, onemap_position_history, onemap_get_event, onemap_geocode, onemap_whoami, onemap_statistics, onemap_audit_log

Informes — onemap_report (ruta, eventos, viajes, paradas, resumen, geocercas, combinado × json/xlsx/mail), onemap_report_devices_xlsx

Configuración — onemap_geofences, onemap_drivers, onemap_maintenance, onemap_calendars, onemap_notifications, onemap_computed_attributes, onemap_orders (cada una acepta una action: list/get/create/update/delete)

Comandos — onemap_command_types, onemap_saved_commands, onemap_send_command

Administración — onemap_manage_device, onemap_manage_group, onemap_users, onemap_permissions, onemap_share, onemap_send_notification, onemap_session_token, onemap_stream_url, onemap_server_settings, onemap_delete_positions

Notas de diseño

Dos decisiones que conviene conocer al ampliar esto:

• Los nombres se resuelven a identificadores en el servidor. Las herramientas aceptan deviceNames: ["Truck 12"] y buscan el identificador, porque los usuarios dicen nombres y los modelos adivinan identificadores. Los nombres ambiguos se rechazan con los candidatos listados en lugar de resolverse a una suposición: elegir el vehículo equivocado en silencio es peor que fallar.

• Una herramienta de informes, no ocho. Los siete endpoints de informes solo se diferencian por el segmento de ruta, por lo que son una sola herramienta con un discriminador report. Las listas de herramientas cortas mejoran notablemente la precisión de selección del modelo; el mismo razonamiento reduce el CRUD de entidades a una herramienta por acción.

Los períodos con nombre (period: "lastWeek") también se resuelven en el servidor (las semanas empiezan en lunes), porque la aritmética de fechas es una fuente fiable de errores silenciosos del modelo.

Dos peculiaridades de la API que conviene conocer antes de tocar estas rutas de código, ambas encontradas probando contra el servidor real en lugar de leer la especificación:

• GET /session ignora Authorization: Bearer. Informa sobre la sesión de cookie y responde 404 cuando no hay ninguna. Los clientes con token deben pasar ?token=, que OneMapClient.getSessionUser() hace solo como respaldo; eso coloca la credencial en el registro de acceso del servidor, por lo que nunca es el primer intento.

• id en /positions significa id de posición, no id de dispositivo, y deviceId requiere un from/to explícito. Por tanto, la "última posición" es GET /positions sin parámetros, filtrada en el cliente. Pasar un id de dispositivo como id produce un 500 (NullPointerException) del servidor.

Desarrollo

npm run dev        # tsc --watch
npm test           # build + smoke tests against a mock API
npm run inspect    # MCP Inspector against the stdio server

test/smoke.mjs levanta una API OneMap falsa y conduce el servidor real a través de un cliente MCP en memoria, cubriendo la resolución de nombres, la expansión de períodos, la codificación de consultas de matrices, el envío de correo y todas las salvaguardas.