LLM-MCP Genesis：用大模型驱动的机器人仿真

通过 Model Context Protocol 把 Genesis 物理仿真器暴露给 LLM Agent，让模型能够以多轮对话的方式连续操控同一个仿真场景——搭建场景、规划抓取、执行倒水任务，并观察结果后再决定下一步。

任务域：机械臂抓取杯子并倒水（刚体 + SPH 液体耦合）。

演示

一次完整的对话驱动仿真：Agent 从空场景开始，逐步搭建环境、定位杯子、规划抓取、执行倾倒，每一步都读取上一步的返回值再决定下一步——全程在同一个常驻的物理世界里完成，没有任何一次重启。

案例

以上为 GIF 预览（已加速、降帧、缩放）。原始 mp4 见 docs/media/；完整实验录像归档保留在本地，未纳入版本控制。

核心设计：持久化会话

常规 MCP 工具是无状态的——每次调用都要重建仿真、重开渲染窗口，LLM 无法做连续决策。

本项目的 GenesisSession 让 gs.init() 全局只执行一次、场景与查看器窗口常驻，实体和相机注册在会话字典里。于是 LLM 可以：

create_simulation_scene()          → 建场景（此时先不 build）
add_cup_with_liquid()              → 往同一场景加实体
create_complete_scene_with_sphere()→ 补齐后统一 build
execute_robot_action(...)          → 抓取，观察返回值
debug_robot_grasp_status()         → 发现没夹稳
execute_pour_sequence(...)         → 调整参数后倒水

全程同一个窗口、同一个物理世界。场景的 build() 被延迟到实体添加完毕（Genesis 要求 build 后不能再加实体），由 build_scene_if_needed() 统一处理。

目录结构

mcp_server/          MCP 服务器（项目核心）
  simple_genesis_mcp.py    最终版，1682 行，11 个 tool + 2 个 resource
  start_server_simple.sh   启动脚本
  debug_mcp.py             环境诊断服务器（排查 "Not connected"）
  test_mcp.py              最小化连通性测试
  legacy/                  演化历史，见下文

experiments/         仿真实验脚本（MCP 工具的原型来源）
  01_water_sim/            液体仿真：SPH vs MPM 求解器对比
  02_grasping_franka/      Franka Panda 抓取
  03_grasping_uf850/       UFactory UF850 抓取
  04_ik_study/             IK 与坐标系研究
  05_pouring/              倒水任务
  scenes/                  场景搭建

assets/
  objects/                 杯子等网格资产（obj/mtl/blend）
  robots/uf850/            UF850 URDF + xarm_description 网格

docs/                替换配置、故障排除、演示视频
media/               完整视频归档（已 gitignore，本地保留）

MCP 接口

Tools

Resources：genesis://status/session、genesis://help/persistent

两个关键的运动辅助函数（工具背后的实现）：

• _move_with_fallback() — 优先用 Genesis 的路径规划器，失败则降级为关节空间直接插值，避免规划器报错导致整个工具调用失败

• _move_with_fixed_orientation() — 倒水时锁定腕部以外的姿态，防止 IK 解算把杯口转歪

快速开始

⚠️ 本项目锁定 genesis-world==0.2.1。 请勿直接升级到 Genesis 1.x，先读下面的兼容性说明。

# 1. 环境（Genesis 需要 GPU）
conda create -n genesis310 python=3.10
conda activate genesis310
pip install -r requirements.txt

# 2. 直接跑服务器
cd mcp_server && python simple_genesis_mcp.py

# 3. 或接入 MCP 客户端（Cursor / Claude Desktop）

客户端配置（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "genesis-robotics": {
      "command": "/绝对路径/llm-mcp-genesis/mcp_server/start_server_simple.sh",
      "args": [],
      "env": { "CONDA_DEFAULT_ENV": "genesis310" }
    }
  }
}

完整配置说明见 docs/mcp_setup.md，连接问题见 docs/troubleshooting.md。

资产路径默认按仓库相对定位，也可用 GENESIS_ASSET_DIR 环境变量覆盖。

实验记录

01 液体仿真

对比 SPH 与 MPM 两种求解器模拟杯中水。Water_cup_Success.py 是收敛的配置：dt=2e-3、substeps=100、particle_size=0.002。子步数不足时液体会穿透杯壁。

02 Franka 抓取

Opus_try.py 里的 RobotControlWrapper 把控制频率（20ms）与仿真步长（2ms）解耦，避免每个仿真步都重设目标导致的抖动。grasp-optimization.py 是抓取位姿的搜索实现，后来演化成了 MCP 里的抓取逻辑。

03 UF850 抓取 ⚠️

从 xarm_ros2 把 UFactory 850 的 xacro 展开成 uf850_final.urdf 导入 Genesis。能跑通，但仿真效果较差——关节响应和抓取稳定性都不理想，尚未定位是 URDF 的惯量/摩擦参数问题还是控制增益问题。保留作为后续修复的起点。

04 IK 研究

Robotics_Test.py 梳理 Genesis 中 position/quaternion 的坐标约定；Test_IK_Multi.py 用多链接 IK 约束夹爪保持水平，这是抓取稳定性的关键改进。

05 倒水

渐进式验证：Pouring_No_Liquids.py（空杯先验证轨迹）→ Pouring_Sphere.py（小球代替液体，快得多）→ Pouring_Liquids_IK.py（真 SPH 液体）。

服务器演化历史（mcp_server/legacy/）

保留作为设计过程的记录。注意 V1 和 V2 中 execute_pour_sequence 被重复定义了两次（后者覆盖前者），该问题在最终版中已修复——这也是判断哪个版本是最新的依据。

在此之前还有一版基于 dustland/genesis-mcp 的分层重构（Pydantic 模型 + service 层），设计上更规范，但没有完成，已弃用。

兼容性说明

本项目开发于 genesis-world==0.2.1（2025年5月），并锁定在该版本。

上游此后改名为 Genesis-Embodied-AI/genesis-world，底层编译器从 Taichi 换成自研的 Quadrants，并已发布到 1.x。截至 1.2.3 与本项目的差异核对如下。

会直接报错

相机录制 API 的参数位置变了（影响 experiments/ 下 21 个调用点；MCP 服务器本身不录制视频，不受影响）：

# 0.2.1（本项目的写法）
cam.start_recording()
cam.stop_recording(save_to_filename='out.mp4', fps=60)

# 1.x
cam.start_recording(save_to_filename='out.mp4', fps=60)
cam.stop_recording()          # 不再接受参数

不报错但行为改变

set_quat 的默认值变了（影响 10 个实验脚本 + mcp_server/simple_genesis_mcp.py 的 3 处）：

# 0.2.1:  set_quat(quat, envs_idx=None, *, zero_velocity=True,  unsafe=False)
# 1.x:    set_quat(quat, envs_idx=None, *, zero_velocity=False, relative=True, skip_forward=False)

zero_velocity 默认由 True 变 False；新增的 relative=True 使 quat 改为在用户坐标系下解释，morph 的位姿偏移与惯量对齐会叠加上去。本项目的杯子都是以 gs.morphs.Mesh(..., euler=(-np.pi/2, 0, 0)) 加载后再 set_quat 纠正朝向的，因此升级后杯子朝向需要重新校准。恢复旧语义需显式传 relative=False, zero_velocity=True。

plan_path 默认值变了：resolution 0.01→0.05、timeout 5.0→None、num_waypoints 100→300，ignore_joint_limit 参数被移除。本项目的调用均使用关键字参数，不会报错，但规划出的路径会不同。

物理行为的累积变化（不需改代码，但仿真结果会变）：

未变化（已核对）

gs.init(backend=gs.gpu)、gs.euler_to_quat、quat_to_xyz / quat_to_R、SimOptions(dt, substeps, requires_grad)、SPHOptions(lower_bound, upper_bound, particle_size)、materials.Rigid(rho, friction, needs_coup, coup_friction, coup_restitution)、SPH.Liquid(rho, gamma, sampler='pbs')、morphs.Mesh(convexify, decimate)、inverse_kinematics(link=, pos=, quat=)、Rasterizer / RayTracer —— 均仍可用。

IK 调用全部使用关键字参数，因此 1.x 在 quat 与 init_qpos 之间新增的 local_point 参数不影响本项目。Python 3.10 仍在支持范围内（1.x 要求 >=3.10,<3.14）。

关于 LuisaRender

LuisaRender 是 Genesis 的光线追踪渲染后端，对应 gs.renderers.RayTracer。从源码构建 Genesis 时它需要本地编译（约 2.6G 产物）。本项目绝大多数场景使用 Rasterizer，仅一处用到 RayTracer，因此通过 pip 安装即可，无需自行编译 LuisaRender。1.x 另有自研渲染器 Nyx（独立包 gs-nyx），LuisaRender 降为三条渲染路径之一。

升级路线

若要迁移到 1.x，建议顺序：① 替换 21 处 stop_recording → ② 给 set_quat 补显式参数并重新校准杯子朝向 → ③ 复核 UF850 的 DOF 索引 → ④ 重调液体 substeps 与抓取参数。前两步是机械修改，后两步是本项目参数敏感性的主要工作量。

已知问题

• UF850 仿真质量差（见上）

• 液体仿真对 substeps 极度敏感，参数迁移到新场景时通常需要重调

• 抓取成功率依赖杯子网格的 convexify 设置，凸包简化会丢失杯口结构

License

实验性研究代码。Genesis 采用 Apache-2.0，xarm_description 网格来自 xArm-Developer/xarm_ros2（BSD-3-Clause）。