robot-mcp-server

robot-mcp-server

中文文档

一款更完善的机器人控制 MCP 服务，面向大模型、Agent 系统和自动化平台，可统一控制 Unitree 机器人和 DJI Tello 无人机。

改进内容

与原始版本相比，本项目现已成为更实用的工程基线，而不再是一个最小化原型：

• 同时支持 mock 和 hardware 后端，无需真实设备即可验证工作流
• 新增统一配置层，支持环境变量和 CLI 覆盖配置
• 新增健康检查、状态检查、能力发现和全局紧急停止工具
• 内置适用于常见机器人工作流的例程模板
• 新增轻量级序列执行器，客户端可在单个请求中提交多个内置例程
• 强化适配器，提供更严格的参数验证和连接状态保护
• 修复缺失的依赖声明、脆弱的启动流程和不稳定的相对导入
• 新增单元测试和本地演示，便于验证和回归检查

项目结构

.
├── 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

安装

要求：

• Python 3.10+
• Windows PowerShell 或任何可运行 Python 的终端

安装依赖：

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

默认包含：

• mcp
• djitellopy

如果要连接真实的 Unitree 硬件，还需安装对应的 SDK：

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

快速开始

推荐使用 mock 模式启动：

.\run.ps1

或：

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

使用 HTTP 传输启动：

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

连接真实硬件：

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

建议先在 mock 模式下验证工作流，再切换到 hardware 模式。

环境变量

变量	默认值	描述
ROBOT_MCP_BACKEND	mock	后端模式：mock / hardware
ROBOT_MCP_TRANSPORT	stdio	传输方式：stdio / streamable-http
ROBOT_MCP_HTTP_HOST	127.0.0.1	HTTP 绑定主机
ROBOT_MCP_HTTP_PORT	8000	HTTP 端口
ROBOT_MCP_LOG_LEVEL	INFO	日志级别
ROBOT_MCP_UNITREE_TIMEOUT_SECONDS	10	Unitree 连接超时时间
ROBOT_MCP_DEFAULT_TAKEOFF_HEIGHT	1.2	DJI 默认起飞高度，单位为米
ROBOT_MCP_TELLO_HOST	empty	指定的 Tello 主机

可用的 MCP 工具

通用工具：

• server_status
• list_robot_capabilities
• list_robot_routines
• run_routine_sequence
• health_check
• emergency_stop_all

Unitree 工具：

• 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)

说明：

• velocity 范围：-3.0 ~ 3.0 米/秒
• duration 范围：0.1 ~ 30.0 秒

DJI 工具：

• 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)

说明：

• height 范围：0.2 ~ 10.0 米
• 省略 height 时，将使用配置的默认值

内置例程

为节省客户端开发时间，服务包含多个组合操作：

• unitree_move_and_stop 如有需要则建立连接，执行一次移动并自动停止
• unitree_out_and_back 向前移动、返回并停止，完成简单的往返巡逻
• unitree_pulse_patrol 重复短时移动／暂停循环，适用于轻量级巡逻场景
• unitree_inspection_sweep 执行简短的巡检例程，包括向前移动、在检查点停止并返回
• dji_takeoff_hover_land 起飞、悬停指定时长并自动降落
• dji_quick_observe 便捷的观察例程，包括起飞、悬停和降落
• dji_perimeter_scan 轻量级空中扫描例程，包含多个悬停检查点

序列执行器

run_routine_sequence 允许客户端在一次请求中提交多个内置例程和 pause 步骤。

示例：

[
  {
    "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
    }
  }
]

支持的序列操作：

• 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

资源和提示词

除工具外，服务还提供：

• 资源：robot://status/summary
• 提示词：safe_operation_checklist(device)

本地演示

python examples\demo.py

测试

python -m unittest discover -s tests -v

使用提示

• 开发期间优先使用 mock 模式
• 连接真实硬件前调用 health_check
• 执行移动或起飞命令前检查 server_status
• 发生问题时，先使用 emergency_stop_all

已知限制

• Unitree 硬件控制目前仍是轻量级 SDK 集成层，旨在作为扩展起点
• 当前测试主要覆盖 mock 模式；真实硬件行为仍需进行现场集成测试
• 确切的 streamable-http 行为取决于已安装的 mcp 软件包版本

许可证

MIT 许可证