UniRoboSim MCP

English | 简体中文

unirobosim-mcp 向兼容 MCP 的客户端暴露 UniRoboSim 证据、仿真状态、后端相机图像，以及显式启用的仿真控制。该服务器具有两种部署配置：

• 证据配置（默认）： 对操作员选定的证据根目录提供有界、只读访问。

• 控制配置（显式）： 在证据工具的基础上，为由此服务器创建并拥有的仿真器会话提供读取和控制工具。

该服务器不会附加到由其他应用程序创建的会话。

安装

支持 Python >=3.11,<3.13。请在同一个环境中安装 Core、本包以及所选后端所需的适配器。

conda create -n unirobosim-mcp python=3.12 pip -y
conda activate unirobosim-mcp

git clone https://github.com/GitHofee/UniRoboSim.git
git clone https://github.com/GitHofee/UniRoboSim-mcp.git
git clone https://github.com/GitHofee/UniRoboSim-mujoco.git  # example backend

python -m pip install ./UniRoboSim ./UniRoboSim-mcp ./UniRoboSim-mujoco

常规部署使用当前的 MCP 2.x 运行时。Isaac Lab 3.0 环境保留其经过验证的 Pydantic 和 Uvicorn 版本锁定，因此请在那里安装兼容性附加包：

python -m pip install './UniRoboSim-mcp[isaaclab]'

该附加包选择 MCP 1.10.1；它暴露相同的 UniRoboSim 工具目录，并已通过 Isaac Sim 6.0.1 的真实 stdio 协议验证。

Related MCP server: gazebo-mcp

证据配置

unirobosim-mcp --root /absolute/path/to/approved/evidence

可以使用 UNROBOSIM_EVIDENCE_ROOT 代替 --root：

export UNIROBOSIM_EVIDENCE_ROOT=/absolute/path/to/approved/evidence
unirobosim-mcp

绝对路径、路径穿越、符号链接逃逸、未经批准的扩展名、过大的文件、过度的扫描以及过多的结果计数均被拒绝。

控制配置

控制必须显式启用。本地资源文件被拒绝，除非其父目录树通过 --asset-root 被列入白名单。

unirobosim-mcp \
  --root /absolute/path/to/approved/evidence \
  --enable-control \
  --asset-root /absolute/path/to/approved/assets \
  --max-sessions 2 \
  --lease-timeout-seconds 300

读取 API

读取工具需要会话 ID，但不需要写入租约。

simulation_get_entity 报告规范路径、实体种类、原始 MCP 配置、仿真节拍、数组形状和数据类型，以及类型特定的数据。include_values=true 包含数值；include_contact=true 添加刚体接触状态。

simulation_capture_camera 不是桌面或浏览器截图。它通过 Camera.read("rgb") 调用所选后端，验证规范的 [environment,height,width,3] uint8 缓冲区，并将该缓冲区编码为 PNG。save_to_evidence=true 还会将图像写入 <root>/screenshots/ 下，并返回其 SHA-256 摘要和尺寸。

控制 API

所有变更操作都需要 simulation_create 返回的不透明 lease_id 以及唯一的 command_id。

重复使用带有相同输入的 command_id 会返回缓存结果，并带有 idempotent_replay=true。使用不同输入重复使用该标识符将被拒绝。过期的会话会自动关闭。每次应用或拒绝的变更操作都会写入 mcp-control-audit.jsonl；租约值被排除在审计记录之外。

代理操作规则

使用控制配置的代理必须遵循以下顺序：

1. 调用 simulation_list_backends 并显式选择一个可用的后端。

2. 调用 simulation_create；仅将返回的租约用于写入操作。

3. 使用唯一的命令标识符添加所有实体，然后调用 simulation_start。

4. 使用 simulation_scene_snapshot 发现规范的实体和相机路径。

5. 使用 simulation_get_entity 获取目标状态，使用 simulation_capture_camera 进行视觉验证。

6. 仅对相同的写入请求重复使用命令标识符。

7. 对每个创建的会话调用 simulation_close，包括失败的流程。

代理不得根据工具可用性推断后端支持。不支持的仿真器能力由能力协商或所选适配器报告。

回环 HTTP

unirobosim-mcp \
  --root /absolute/path/to/approved/evidence \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8766

未经身份验证的 HTTP 仅限于 127.0.0.1、localhost 或 ::1。远程部署需要经过身份验证和授权的网关。控制模式不得直接暴露在不受信任的网络上。

程序化嵌入

from pathlib import Path

from unirobosim_mcp import ControlLimits, EvidenceLimits, SimulationControl, create_server

root = Path("/approved/evidence")
control = SimulationControl(
    root,
    asset_roots=(Path("/approved/assets"),),
    limits=ControlLimits(max_sessions=1, lease_timeout_seconds=120),
)
server = create_server(
    root,
    limits=EvidenceLimits(max_results=50, max_query_items=100),
    control=control,
)
server.run(transport="stdio")

验证

python -m pip install -e '.[dev]'
ruff format --check src tests
ruff check src tests
mypy src
coverage run -m pytest
coverage report

发布验收通过真实的进程内 MCP 客户端调用每个已发布的 MCP 工具。额外的契约测试涵盖所有受支持的实体类型和命令族、租约、幂等性、过期、白名单资产、资源限制、审计记录、PNG 编码以及已保存的截图证据。原生验收针对每个已安装的模拟器适配器单独执行；除非该原生运行成功，否则功能不会报告为后端已通过。

核心契约和适配器安装记录在 UniRoboSim Core 中。