Witzense MCP

MCP-сервер для Open API отслеживания устройств Witzense/JIMI, описанного в API DOCUMENT.pdf.

Извлечённый справочник в Markdown — API DOCUMENT.md. В нём сохранены все 126 страниц PDF в виде разделов страниц, и его легче искать и обрабатывать программно. PDF остаётся исходным источником, а контент, состоящий только из изображений, не встроен в извлечённый Markdown.

Конфигурация

Скопируйте .env.example в локальную конфигурацию окружения и задайте:

• WITZENSE_BASE_URL: по умолчанию — http://open.10000track.com/route/rest.

• WITZENSE_APP_KEY и WITZENSE_APP_SECRET.

• WITZENSE_ACCOUNT и WITZENSE_PASSWORD_MD5 — существующий 32-символьный MD5 пароля учётной записи в нижнем регистре; не передавайте пароль открытым текстом и не хешируйте это значение повторно.

• WITZENSE_EXPIRES_IN: запрос времени жизни токена, от 60 до 7200 секунд.

• WITZENSE_REQUEST_ENCODING: form по умолчанию или json, если назначенный узел требует иного.

Никогда не коммитьте реальные учётные данные и не помещайте их в исходные файлы.

Related MCP server: SORACOM Data Reader MCP

Запуск

npm install
npm run build
npm start

Сервер взаимодействует через MCP stdio. Доступные инструменты включают:

• 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

Специализированные инструменты ориентированы на чтение и используют общий подписанный клиент.

Для интеграций Command Cloud каждое устройство/IMEI Witzense рассматривается как соответствующий актив/транспортное средство Command Cloud. См. specs/commandcloud-mapping.md.

Поведение API

Запросы используют POST /route/rest с общими параметрами, токеном доступа и подписью MD5 в верхнем регистре в кодировке UTF-8. Токены получаются через jimi.oauth.token.get, обновляются через jimi.oauth.token.refresh и кэшируются в памяти.

В PDF перечислены узлы TS, TSP HK, TSP EU и TSP US. Настройте назначенный узел через WITZENSE_BASE_URL; не меняйте код инструментов при переходе между узлами.

Тесты

npm test

Развёртывание сервера

Рабочий процесс репозитория собирает и тестирует pull request'ы, а затем разворачивает /root/WITZENSE-MCP после пуша в main. Настройте секрет GitHub Actions DEPLOY_SSH_KEY с ключом развёртывания, принимаемым root@2.25.109.42.

Храните переменные API Witzense в среде выполнения сервера или в конфигурации MCP-хоста. Они намеренно не входят в рабочий процесс развёртывания или репозиторий.

См. DEPLOYMENT.md с командами начальной настройки первого сервера и смоук-тестирования.