机器人控制服务器

机器人mcp服务器

中文文档

用于LLM、代理系统和自动化平台的更完整的机器人控制MCP服务器，对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

快速开始

建议模拟模式启动：

.\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.

环境变量

可用的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许可证