# robot-mcp-server

[中文文档](README.zh-CN.md)

A more complete robot-control MCP server for LLMs, agent systems, and automation platforms, with unified control for Unitree robots and DJI Tello drones.

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

## What Was Improved

Compared with the original version, this project is now a more practical engineering baseline instead of a minimal prototype:

- Supports both `mock` and `hardware` backends so workflows can be validated without real devices
- Adds a unified configuration layer with environment-variable and CLI overrides
- Adds health checks, status inspection, capability discovery, and a global emergency-stop tool
- Adds built-in routine templates for common robot workflows
- Adds a lightweight sequence executor so clients can submit multiple built-in routines in one request
- Strengthens adapters with stricter parameter validation and connection-state protection
- Fixes missing dependency declarations, fragile startup flow, and unstable relative imports
- Adds unit tests and a local demo for easier verification and regression checks

## Project Structure

```text
.
├── examples/
│   └── demo.py
├── src/
│   ├── __init__.py
│   ├── config.py
│   ├── dji_adapter.py
│   ├── exceptions.py
│   ├── main.py
│   ├── service.py
│   └── unitree_adapter.py
├── tests/
│   └── test_service.py
├── README.md
├── README.zh-CN.md
├── requirements.txt
└── run.ps1
```

## Installation

Requirements:

- Python 3.10+
- Windows PowerShell or any terminal that can run Python

Install dependencies:

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
```

Included by default:

- `mcp`
- `djitellopy`

If you want to connect to real Unitree hardware, install the corresponding SDK as well:

```powershell
python -m pip install git+https://github.com/unitreerobotics/unitree_sdk2_python.git
```

## Quick Start

Recommended mock-mode startup:

```powershell
.\run.ps1
```

or:

```powershell
python -m src.main --backend mock --transport stdio
```

Start with HTTP transport:

```powershell
.\run.ps1 -Backend mock -Transport streamable-http -Host 127.0.0.1 -Port 8000
```

Connect to real hardware:

```powershell
python -m src.main --backend hardware --transport stdio
```

It is recommended to validate your workflow in `mock` mode before switching to `hardware`.

## Environment Variables

| Variable | Default | Description |
| --- | --- | --- |
| `ROBOT_MCP_BACKEND` | `mock` | Backend mode: `mock` / `hardware` |
| `ROBOT_MCP_TRANSPORT` | `stdio` | Transport: `stdio` / `streamable-http` |
| `ROBOT_MCP_HTTP_HOST` | `127.0.0.1` | HTTP bind host |
| `ROBOT_MCP_HTTP_PORT` | `8000` | HTTP port |
| `ROBOT_MCP_LOG_LEVEL` | `INFO` | Log level |
| `ROBOT_MCP_UNITREE_TIMEOUT_SECONDS` | `10` | Unitree connection timeout |
| `ROBOT_MCP_DEFAULT_TAKEOFF_HEIGHT` | `1.2` | Default DJI takeoff height in meters |
| `ROBOT_MCP_TELLO_HOST` | empty | Specific Tello host |

## Available MCP Tools

Shared tools:

- `server_status`
- `list_robot_capabilities`
- `list_robot_routines`
- `run_routine_sequence`
- `health_check`
- `emergency_stop_all`

Unitree tools:

- `unitree_connect`
- `unitree_move(velocity, duration=1.0)`
- `unitree_stop`
- `unitree_status`
- `unitree_disconnect`
- `unitree_move_and_stop(velocity, duration=1.0)`
- `unitree_out_and_back(velocity, forward_duration=1.0, return_duration=None)`
- `unitree_pulse_patrol(velocity, pulse_duration=0.8, pause_duration=0.3, cycles=3)`
- `unitree_inspection_sweep(velocity=1.0, forward_duration=1.0, checkpoint_pause=0.5, cycles=2)`

Notes:

- `velocity` range: `-3.0 ~ 3.0` m/s
- `duration` range: `0.1 ~ 30.0` seconds

DJI tools:

- `dji_connect`
- `dji_takeoff(height=None)`
- `dji_land`
- `dji_emergency_stop`
- `dji_status`
- `dji_disconnect`
- `dji_takeoff_hover_land(height=None, hover_seconds=3.0)`
- `dji_quick_observe(height=None, hover_seconds=5.0)`
- `dji_perimeter_scan(height=None, hover_seconds=2.0, checkpoints=3)`

Notes:

- `height` range: `0.2 ~ 10.0` meters
- When `height` is omitted, the configured default is used

## Built-in Routines

To save client-side development time, the server includes several composed actions:

- `unitree_move_and_stop`
  Connects if needed, performs one move, and stops automatically
- `unitree_out_and_back`
  Moves forward, returns, and stops for a simple round-trip patrol
- `unitree_pulse_patrol`
  Repeats short move/pause cycles for lightweight patrol scenarios
- `unitree_inspection_sweep`
  Runs a compact inspection routine with forward movement, checkpoint stop, and return movement
- `dji_takeoff_hover_land`
  Takes off, hovers for a configurable duration, and lands automatically
- `dji_quick_observe`
  A convenience observation routine with takeoff, hover, and landing
- `dji_perimeter_scan`
  A lightweight aerial scan routine with multiple hover checkpoints

## Sequence Executor

`run_routine_sequence` lets clients submit several built-in routines and `pause` steps in one request.

Example:

```json
[
  {
    "action": "unitree_move_and_stop",
    "params": {
      "velocity": 1.0,
      "duration": 1.2
    }
  },
  {
    "action": "pause",
    "params": {
      "duration": 1
    }
  },
  {
    "action": "dji_takeoff_hover_land",
    "params": {
      "height": 1.5,
      "hover_seconds": 3
    }
  }
]
```

Supported sequence actions:

- `pause`
- `unitree_move_and_stop`
- `unitree_out_and_back`
- `unitree_pulse_patrol`
- `unitree_inspection_sweep`
- `dji_takeoff_hover_land`
- `dji_quick_observe`
- `dji_perimeter_scan`

## Resources and Prompts

In addition to tools, the server also exposes:

- Resource: `robot://status/summary`
- Prompt: `safe_operation_checklist(device)`

## Local Demo

```powershell
python examples\demo.py
```

## Tests

```powershell
python -m unittest discover -s tests -v
```

## Usage Tips

- Prefer `mock` mode during development
- Call `health_check` before connecting real hardware
- Inspect `server_status` before movement or takeoff commands
- Use `emergency_stop_all` first when something goes wrong

## Known Limits

- Unitree hardware control is still a lightweight SDK integration layer intended as a starting point for extension
- Current tests mainly cover `mock` mode; real hardware behavior still needs on-site integration testing
- Exact `streamable-http` behavior depends on the installed `mcp` package version

## License

[MIT License](LICENSE)