Witzense MCP

Servidor MCP para la API abierta de seguimiento de dispositivos Witzense/JIMI descrita en API DOCUMENT.pdf.

La referencia Markdown extraída es API DOCUMENT.md. Conserva las 126 páginas del PDF como secciones de página y es más fácil de buscar y procesar programáticamente. El PDF sigue siendo la fuente original, y el contenido solo de imágenes no está incrustado en la extracción de Markdown.

Configuración

Copia .env.example a una configuración de entorno local y establece:

• WITZENSE_BASE_URL: por defecto http://open.10000track.com/route/rest.

• WITZENSE_APP_KEY y WITZENSE_APP_SECRET.

• WITZENSE_ACCOUNT y WITZENSE_PASSWORD_MD5 — el MD5 existente de 32 caracteres en minúsculas de la contraseña de la cuenta; no proporciones texto plano y no vuelvas a aplicar hash a este valor.

• WITZENSE_EXPIRES_IN: solicitud de duración del token, de 60 a 7200 segundos.

• WITZENSE_REQUEST_ENCODING: form por defecto, o json si el nodo asignado lo requiere.

Nunca confirmes credenciales reales ni las coloques en archivos fuente.

Related MCP server: SORACOM Data Reader MCP

Ejecución

npm install
npm run build
npm start

El servidor se comunica a través de MCP stdio. Las herramientas disponibles incluyen:

• call_witzense_method

• list_witzense_child_accounts

• list_witzense_devices

• get_witzense_device

• get_witzense_device_locations

• list_witzense_account_locations

• get_witzense_track

• get_witzense_mileage

• get_witzense_shared_location_url

• list_witzense_alarms

• get_witzense_parking_report

• get_witzense_trips_report

• get_witzense_fence_duration_report

• get_witzense_obd_data

• get_witzense_obd_faults

• get_witzense_rfid_reports

• get_witzense_tag_location

• list_witzense_geofences

• get_witzense_geofence

• list_witzense_device_groups

• get_witzense_media_urls

• get_witzense_live_url

• get_witzense_rtmp_url

Las herramientas dedicadas están orientadas a lectura y utilizan el cliente firmado compartido.

Para integraciones con Command Cloud, cada dispositivo/IMEI de Witzense se trata como el activo/vehículo correspondiente de Command Cloud. Consulta specs/commandcloud-mapping.md.

Comportamiento de la API

Las solicitudes usan POST /route/rest con parámetros comunes, un token de acceso y una firma MD5 UTF-8 en mayúsculas. Los tokens se obtienen mediante jimi.oauth.token.get, se renuevan mediante jimi.oauth.token.refresh y se almacenan en caché en memoria.

El PDF enumera los nodos TS, TSP HK, TSP EU y TSP US. Configura el nodo asignado mediante WITZENSE_BASE_URL; no cambies el código de las herramientas al moverte entre nodos.

Pruebas

npm test

Despliegue del servidor

El flujo de trabajo del repositorio compila y prueba las solicitudes de extracción, y luego despliega /root/WITZENSE-MCP después de un push a main. Configura el secreto de GitHub Actions DEPLOY_SSH_KEY con la clave de despliegue aceptada por root@2.25.109.42.

Mantén las variables de la API de Witzense en el entorno de ejecución del servidor o en la configuración del host MCP. Intencionalmente no forman parte del flujo de trabajo de despliegue ni del repositorio.

Consulta DEPLOYMENT.md para los comandos de arranque inicial del servidor y pruebas de humo.