内容
# ROSClaw-Native MoveIt2 MCP 服务器
[](https://docs.ros.org)
[](https://www.python.org/)
[](https://opensource.org/licenses/Apache-2.0)
[](https://modelcontextprotocol.io/)
> 生产级别的 MoveIt2 运动规划 MCP 服务器，适用于 ROSClaw 操作系统集成。
> **"教一次，随处体现。分享技能，塑造现实。"**
[中文文档](README.zh.md) | [文档](https://docs.rosclaw.org/moveit2-mcp)
---
## 概述
`rosclaw-moveit2-mcp` 是一个 ROSClaw-Native MCP（模型上下文协议）服务器，用于桥接大型语言模型（LLMs）与 MoveIt2 运动规划，适用于机器人臂。它实现了 6 个 ROSClaw-Native 标准，用于生产级别的实体 AI 应用。
### 主要功能
- **异步 ROS 2 操作**：非阻塞操作客户端，支持 async/await
- **飞轮就绪响应**：结构化 JSON，用于数据飞轮摄入
- **数字孪生防火墙**：基于 MuJoCo 的安全验证，执行前验证
- **优雅抢占**：主动任务跟踪，支持取消
- **状态感知能力**：本地状态机，防止无效操作
- **语义空间绑定**：TF2 集成，抽象 3D 数学，从 LLM
### 支持的机器人
- Universal Robots UR5/UR5e
- Franka Emika Panda
- Kinova Gen3
- 任何具有 MoveIt2 配置的机器人
---
## 安装
### 先决条件
- ROS 2 Humble 或 Jazzy
- Python 3.10+
- 已安装 MoveIt2
### 从 PyPI 安装
```bash
pip install rosclaw-moveit2-mcp
```
### 从源码安装
```bash
git clone https://github.com/ros-claw/rosclaw-moveit2-mcp.git
cd rosclaw-moveit2-mcp
pip install -e ".[dev]"
```
---
## 快速入门
### 1. 启动 ROS 2 和 MoveIt2
```bash
# 终端 1：启动 ROS 2
source /opt/ros/humble/setup.bash
ros2 launch your_robot_moveit_config demo.launch.py
```
### 2. 启动 MCP 服务器
```bash
# 终端 2：启动 MCP 服务器
rosclaw-moveit2-mcp
```
或使用显式传输：
```bash
python -m rosclaw_moveit2_mcp.server --transport stdio
```
### 3. 配置 MCP 客户端
将以下内容添加到您的 MCP 客户端配置中（例如，Claude Desktop）：
```json
{
"mcpServers": {
"rosclaw-moveit2": {
"command": "rosclaw-moveit2-mcp",
"transportType": "stdio"
}
}
}
```
---
## 可用工具
| 工具 | 描述 | ROSClaw 标准 |
|------|-------------|------------------|
| `moveit_get_state` | 获取当前机器人关节状态 | 状态感知 |
| `moveit_plan_and_execute_pose` | 移动到笛卡尔姿势 | 异步操作 |
| `moveit_plan_and_execute_pose_firewalled` | 移动并进行 MuJoCo 验证 | 防火墙 |
| `moveit_cancel_action` | 取消活动运动 | 抢占 |
| `moveit_lookup_tf_pose` | TF2 语义姿势查询 | TF2 绑定 |
| `moveit_get_active_tasks` | 列出活动运动 | 状态感知 |
---
## 使用示例
### 基本运动规划
```python
# 将末端执行器移动到特定姿势
result = await moveit_plan_and_execute_pose(
x=0.5, y=0.2, z=0.3,
qx=0.0, qy=0.0, qz=0.0, qw=1.0,
target_object_name="Pick up apple",
planning_group="panda_arm"
)
```
### 语义空间绑定
```python
# 使用 TF 帧代替坐标
result = await moveit_plan_and_execute_pose(
x=0, y=0, z=0, # 被 TF 查询覆盖
target_tf_frame="apple_link", # 自动姿势查询
target_object_name="Pick apple from table"
)
```
### 防火墙执行（数字孪生验证）
```python
# 在真实执行前在 MuJoCo 中验证
result = await moveit_plan_and_execute_pose_firewalled(
x=0.5, y=0.2, z=0.3,
target_object_name="Safe pick operation"
)
# 在 result.firewall_validated 中返回验证状态
```
### 取消活动运动
```python
# 抢占正在运行的运动
result = await moveit_cancel_action(
task_id="abc12345"
)
```
---
## ROSClaw-Native 标准
### 1. 异步 ROS 2 操作
使用 `rclpy.action.ActionClient` 的非阻塞操作客户端，支持 async/await：
```python
# 非阻塞执行
result = await moveit_client.plan_and_execute_pose(...)
# 其他操作可以并发运行
```
### 2. 飞轮就绪响应
所有响应都是结构化 JSON，用于数据飞轮摄入：
```json
{
"status": "SUCCEEDED",
"action_id": "abc12345",
"action_type": "plan_and_execute_pose",
"semantic_goal": "Pick up apple",
"timestamp_start": 1234567890.0,
"timestamp_end": 1234567895.0,
"duration_seconds": 5.0,
"pose_target": {...},
"execution": {
"success": true,
"error_code": null,
"error_message": null
},
"safety": {
"firewall_validated": true,
"violations": []
}
}
```
### 3. 防火墙集成
基于 MuJoCo 的验证，执行前验证：
```python
@mujoco_firewall(
model_path="src/rosclaw/specs/panda.xml",
safety_level=SafetyLevel.STRICT
)
async def moveit_plan_and_execute_pose_firewalled(...):
# 仅在 MuJoCo 验证通过时执行
```
### 4. 优雅抢占
取消活动运动，无系统不稳定性：
```python
async def cancel_action(self, task_id: str) -> Dict[str, Any]:
goal_handle = self._active_tasks[task_id]
cancel_future = goal_handle.cancel_goal_async()
cancel_result = await self._await_future(cancel_future)
```
### 5. 状态感知能力
本地状态机，防止无效操作：
```python
if self.state.is_moving:
return MoveItActionResult(
status=ActionStatus.REJECTED,
error_message="Robot is already executing a motion."
)
```
### 6. 语义空间绑定
TF2 集成，抽象 3D 数学，从 LLM：
```python
# LLM 只提供语义帧名称
pose = await lookup_tf_pose("kitchen_table", "base_link")
# 不需要四元数数学！
```
---
## 架构
```
┌─────────────────────────────────────────────────────────────┐
│ LLM 代理（Claude 等） │
└─────────────────────────────────────────────────────────────┘
│ MCP 协议
▼
┌─────────────────────────────────────────────────────────────┐
│ ROSClaw-Native MoveIt2 MCP 服务器 │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ 异步操作客户端 │ │ 状态机 │ │ TF2 语义绑定 │ │
│ │ │ │ │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ 飞轮 JSON 响应 │ │ 防火墙验证 │ │ 抢占支持 │ │
│ │ │ │ │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│ ROS 2 操作
▼
┌─────────────────────────────────────────────────────────────┐
│ MoveIt2 运动规划器 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 物理机器人臂 │
└─────────────────────────────────────────────────────────────┘
```
---
## 配置
### 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `ROS_NAMESPACE` | `` | ROS 命名空间前缀 |
| `MOVEIT_PLANNING_GROUP` | `panda_arm` | 默认规划组 |
| `FIREWALL_MODEL_PATH` | `panda.xml` | MuJoCo 验证模型 |
| `FIREWALL_SAFETY_LEVEL` | `STRICT` | 安全验证级别 |
### 机器人配置
创建 `robot_config.yaml`：
```yaml
planning_groups:
- name: panda_arm
base_link: panda_link0
end_effector: panda_hand
joint_limits:
panda_joint1:
min: -2.8973
max: 2.8973
firewall:
model_path: "models/panda.xml"
safety_level: STRICT
collision_pairs:
- ["panda_hand", "obstacles"]
```
---
## 开发
### 设置开发环境
```bash
git clone https://github.com/ros-claw/rosclaw-moveit2-mcp.git
cd rosclaw-moveit2-mcp
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate
# 安装开发依赖
pip install -e ".[dev]"
```
### 运行测试
```bash
# 运行所有测试
pytest
# 运行覆盖率测试
pytest --cov=rosclaw_moveit2_mcp --cov-report=term-missing
# 运行特定测试
pytest tests/test_firewall.py -v
```
### 代码质量
```bash
# 格式化代码
ruff format .
# 检查 linting
ruff check .
# 类型检查
mypy src/rosclaw_moveit2_mcp
```
---
## 数据飞轮集成
所有操作结果都结构化为自动数据飞轮摄入：
```python
{
"status": "SUCCEEDED",
"semantic_goal": "Pick up apple",
"pose_target": {...},
"trajectory": {...},
"execution": {...},
"safety": {...}
}
```
此数据馈入：
- **技能学习**：VLA 模型训练
- **故障分析**：自动根本原因分析
- **策略改进**：强化学习微调
---
## 安全功能
### 数字孪生防火墙
所有运动在真实执行前都在 MuJoCo 中验证：
```python
@mujoco_firewall(
model_path="panda.xml",
safety_level=SafetyLevel.STRICT
)
```
### 自碰撞预防
MoveIt2 内置的自碰撞检查。
### 关节限制强制执行
ROSClaw 防火墙强制执行的硬件限制。
### 紧急停止
通过 `moveit_cancel_action()` 立即取消。
---
## 故障排除
### 服务器无法启动
```bash
# 检查 ROS 2 环境
echo $ROS_DISTRO
source /opt/ros/humble/setup.bash
# 检查 MoveIt2 是否正在运行
ros2 topic list | grep move_action
```
### 运动规划失败
```bash
# 检查机器人状态
ros2 topic echo /joint_states
# 验证规划组
ros2 service call /planning_scene moveit_msgs/srv/GetPlanningScene
```
### TF 查询失败
```bash
# 检查 TF 树
ros2 run tf2_tools view_frames
# 回声特定变换
ros2 topic echo /tf
```
---
## 贡献
我们欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取指南。
### 开发工作流
1. 分叉仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 打开拉取请求
---
## 相关项目
- [rosclaw-nav2-mcp](https://github.com/ros-claw/rosclaw-nav2-mcp) - 导航 MCP 服务器
- [rosclaw-firewall](https://github.com/ros-claw/rosclaw-firewall) - 数字孪生防火墙
- [sdk_to_mcp](https://github.com/ros-claw/sdk_to_mcp) - SDK 到 MCP 生成器
- [mjlab-mcp-server](https://github.com/ros-claw/mjlab-mcp-server) - MuJoCo Lab MCP 服务器
---
## 引用
如果您在研究中使用 ROSClaw，请引用：
```bibtex
@software{rosclaw_moveit2_mcp,
title = {ROSClaw-Native MoveIt2 MCP 服务器},
author = {{ROSClaw Team}},
year = {2025},
url = {https://github.com/ros-claw/rosclaw-moveit2-mcp}
}
```
---
## 许可证
该项目根据 Apache License 2.0 许可 - 参见 [LICENSE](LICENSE) 获取详细信息。
---
## 支持
- 📖 [文档](https://docs.rosclaw.org/moveit2-mcp)
- 🐛 [问题跟踪器](https://github.com/ros-claw/rosclaw-moveit2-mcp/issues)
- 💬 [讨论](https://github.com/ros-claw/rosclaw-moveit2-mcp/discussions)
---
<p align="center">
<strong>ROSClaw - 实体智能操作系统</strong><br>
<em>教一次，随处体现。分享技能，塑造现实。</em>
</p>
