Witzense MCP
# Witzense MCP
MCP server for the Witzense/JIMI device tracking Open API described in `API DOCUMENT.pdf`.
The extracted Markdown reference is [API DOCUMENT.md](API%20DOCUMENT.md). It preserves all 126 PDF pages as page sections and is easier to search and process programmatically. The PDF remains the original source, and image-only content is not embedded in the Markdown extraction.
## Configuration
Copy `.env.example` to a local environment configuration and set:
- `WITZENSE_BASE_URL`: defaults to `http://open.10000track.com/route/rest`.
- `WITZENSE_APP_KEY` and `WITZENSE_APP_SECRET`.
- `WITZENSE_ACCOUNT` and `WITZENSE_PASSWORD_MD5` — the account password's existing 32-character lowercase MD5; do not provide plaintext and do not hash this value again.
- `WITZENSE_EXPIRES_IN`: token lifetime request, from 60 to 7200 seconds.
- `WITZENSE_REQUEST_ENCODING`: `form` by default, or `json` if the assigned node requires it.
Never commit real credentials or place them in source files.
## Run
```powershell
npm install
npm run build
npm start
```
The server communicates over MCP stdio. Available tools include:
- `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`
The dedicated tools are read-oriented and use the shared signed client.
For Command Cloud integrations, each Witzense device/IMEI is treated as the corresponding Command Cloud asset/vehicle. See [specs/commandcloud-mapping.md](specs/commandcloud-mapping.md).
## API behavior
Requests use `POST /route/rest` with common parameters, an access token, and an uppercase UTF-8 MD5 signature. Tokens are acquired through `jimi.oauth.token.get`, refreshed through `jimi.oauth.token.refresh`, and cached in memory.
The PDF lists TS, TSP HK, TSP EU, and TSP US nodes. Configure the assigned node through `WITZENSE_BASE_URL`; do not change tool code when moving between nodes.
## Tests
```powershell
npm test
```
## Server deployment
The repository workflow builds and tests pull requests, then deploys `/root/WITZENSE-MCP` after a push to `main`. Configure the GitHub Actions secret `DEPLOY_SSH_KEY` with the deployment key accepted by `root@2.25.109.42`.
Keep the Witzense API variables in the server's runtime environment or MCP host configuration. They are intentionally not part of the deployment workflow or repository.
See [DEPLOYMENT.md](DEPLOYMENT.md) for first-server bootstrap and smoke-test commands.
TDQS
Scored across 23 tools
Most tools target clearly distinct resources or actions, such as devices, geofences, reports, and streaming URLs. A few location/trip-related tools (e.g., get_witzense_mileage vs get_witzense_trips_report, or get_witzense_live_url vs get_witzense_rtmp_url) could cause minor selection confusion, but the descriptions are generally sufficient.
All tools follow a consistent snake_case convention with a clear verb prefix and the witzense domain marker, such as list_witzense_*, get_witzense_*, and call_witzense_method. This creates a predictable pattern across the entire tool set.
At 23 tools, the set is on the heavy side and falls into the 16-25 range that feels bulky for an agent to navigate. The tools do cover a broad telematics domain, but the count is somewhat high rather than tightly scoped.
The tool surface covers a wide range of Witzense capabilities: devices, locations, tracks, reports, geofences, media, alarms, OBD, RFID, and tags. It is mostly read-oriented, but the generic call_witzense_method escape hatch mitigates gaps in dedicated write or management operations.