Content
# yunji-chassis-mcp
This project wraps the Yunji robot chassis TCP Socket API into Hermes-callable MCP tools. It only exposes safety tools, not raw socket commands or arbitrary speed `/api/joy_control`.
## Overall Architecture
```text
Hermes Agent
-> MCP Tool Call
yunji-chassis-mcp
-> TCP Socket Client
Yunji Chassis 192.168.10.140:31001
```
The Python program acts as a TCP client connecting to the Yunji chassis server. Commands are sent as URL-like strings, e.g., `/api/robot_status?uuid=...`, directly encoded in UTF-8 and sent using `sendall`, without appending `\n` or `\r\n`.
## Connection Information
- Chassis IP: `192.168.10.140`
- Chassis Port: `31001`
- Communication Method: TCP Socket
- Client Role: Python TCP Client
- Return Format: JSON object byte stream
## Installation
```bash
cd /path/to/yunji-chassis-mcp
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
```
Windows PowerShell:
```powershell
cd D:\python\project\yunji\yunji-chassis-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```
## Configuration
Default configuration is in `config.yaml`, and an example configuration is in `config.example.yaml`.
```yaml
chassis:
host: "192.168.10.140"
port: 31001
timeout_seconds: 5
reconnect: true
encoding: "utf-8"
append_newline: false
```
`append_newline` is fixed to `false`, do not change it to `true`. Yunji chassis commands cannot append newlines.
## Network Connectivity Test
First, ensure the computer or Ubuntu virtual machine is connected to the same WiFi or network segment as the chassis.
```bash
ping 192.168.10.140
nc -vz 192.168.10.140 31001
```
Windows:
```powershell
Test-NetConnection 192.168.10.140 -Port 31001
```
## Status and Safety Scripts
These scripts do not execute forward, backward, or rotation movements.
```bash
python scripts/test_connection.py
python scripts/test_status.py
python scripts/test_markers.py
python scripts/test_stop_motion.py
```
Emergency software stop script:
```bash
python scripts/emergency_stop.py
```
## Start MCP Server
```bash
python main.py
```
Hermes configuration example:
```yaml
mcp_servers:
yunji_chassis:
command: "python"
args:
- "/path/to/yunji-chassis-mcp/main.py"
```
Adjust `command` and `args` according to the local Hermes version.
## Tool List
| MCP Tool | Yunji API | Description |
| --- | --- | --- |
| `get_chassis_status` | `/api/robot_status` | Query chassis global status |
| `get_robot_info` | `/api/robot_info` | Query robot basic information |
| `list_markers` | `/api/markers/query_list` | Query marker point list |
| `list_marker_brief` | `/api/markers/query_brief` | Query marker summary |
| `count_markers` | `/api/markers/count` | Query current map marker count |
| `get_power_status` | `/api/get_power_status` | Query battery voltage, current, power, and charging status |
| `get_diagnosis_result` | `/api/diagnosis/get_result` | Query chassis self-diagnosis result |
| `get_software_version` | `/api/software/get_version` | Query chassis software version |
| `list_maps` | `/api/map/list` | Query robot existing maps and floors |
| `get_current_map` | `/api/map/get_current_map` | Query current map, floor, and map basic information |
| `list_map_info` | `/api/map/list_info` | Query all map details |
| `get_planned_path` | `/api/get_planned_path` | Query current navigation task's global planned path |
| `make_plan` | `/api/make_plan` | Plan two-point path and return distance, without triggering movement |
| `query_accessible_point` | `/api/map/accessible_point_query` | Query target point nearby accessible points |
| `probe_distance_to_obstacle` | `/api/map/distance_probe` | Query target point to obstacle distance |
| `stop_motion` | `/api/joy_control?linear_velocity=0&angular_velocity=0` | Normal stop |
| `cancel_navigation` | `/api/move/cancel` | Cancel navigation task |
| `soft_estop` | `/api/estop?flag=true` | Enter software emergency stop |
| `release_soft_estop` | `/api/estop?flag=false` | Release software emergency stop |
| `move_forward_small` | `/api/joy_control` | Safely encapsulated small-range forward movement |
| `move_backward_small` | `/api/joy_control` | Safely encapsulated small-range backward movement |
| `turn_left_small` | `/api/joy_control` | Safely encapsulated small-angle left turn |
| `turn_right_small` | `/api/joy_control` | Safely encapsulated small-angle right turn |
| `goto_marker` | `/api/move?marker=xxx` | High-risk marker navigation |
| `goto_location` | `/api/move?location=x,y,theta` | High-risk coordinate navigation |
## Safety Restrictions
- `send_raw_command` is not exposed.
- Directly passing `linear_velocity` and `angular_velocity` with arbitrary speed tools is not exposed.
- Small-range movement maximum linear velocity `0.2 m/s`, maximum angular velocity `0.4 rad/s`, and maximum duration `2s`.
- After small-range movement, a normal stop is automatically sent; in case of an exception, it will try to stop.
- When `estop_state=true`, normal movement and navigation are prohibited.
- When `hard_estop_state=true`, releasing software emergency stop is prohibited.
- When battery power is below `15%`, navigation is prohibited, and only query, stop, cancel navigation, and emergency stop are allowed.
- When `move_status=running`, repeating navigation commands is prohibited; `cancel_navigation` must be called first.
- `goto_marker` and `goto_location` are high-risk tools; Hermes must confirm user-specified targets before calling.
## Why Handle TCP Sticky/ Unsticky Packets
TCP is a byte stream, not guaranteeing one `recv` is a complete JSON. Half JSON, multiple JSONs stuck together, response and notification stuck together, or callback and response mixed together are possible.
This project uses `JsonStreamParser` to maintain the receive buffer, parsing complete JSON objects through bracket levels, string states, and escape states, without relying on newlines or simple `split`.
## Why Not Expose Raw Commands
Raw socket commands can bypass emergency stop, power, speed, duration, and repeated navigation safety restrictions. Hermes can only call encapsulated safety tools, and all movement abilities must pass `safety.py` verification.
## Common Fault Troubleshooting
- Connection failure: Check if the computer or Ubuntu virtual machine is connected to the Yunji chassis WiFi.
- Connection failure: Run `ping 192.168.10.140`.
- Port unreachable: Run `nc -vz 192.168.10.140 31001` or `Test-NetConnection`.
- Request timeout: Check if the chassis service is started, the network is stable, and if there are firewalls blocking.
- Navigation failure: Call `list_markers` to confirm the point exists, then check maps, emergency stop, power, and error codes.
- Unable to release software emergency stop: If `hard_estop_state=true`, manually release hardware emergency stop first.
## Unit Testing
```bash
python -m pytest tests
```
