UniRoboSim MCP

English | 简体中文

unirobosim-mcp предоставляет доступ к данным UniRoboSim, состоянию симуляции, изображениям с камер бэкенда и явно включённому управлению симуляцией для MCP-совместимых клиентов. Сервер имеет два профиля развёртывания:

• Профиль Evidence (по умолчанию): ограниченный доступ только для чтения к корню данных, выбранному оператором.

• Профиль Control (явный): инструменты Evidence плюс инструменты Read и Control для сессий симулятора, созданных и принадлежащих этому серверу.

Сервер не подключается к сессиям, созданным другими приложениями.

Установка

Поддерживается 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 и был проверен через реальный протокол stdio с Isaac Sim 6.0.1.

Related MCP server: gazebo-mcp

Профиль Evidence

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

UNIROBOSIM_EVIDENCE_ROOT может использоваться вместо --root:

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

Абсолютные пути, обход каталогов, выход за пределы символьных ссылок, неутверждённые расширения, слишком большие файлы, чрезмерное сканирование и чрезмерное количество результатов отклоняются.

Профиль Control

Управление должно быть явно включено. Локальные файлы ресурсов запрещены, если их родительское дерево не внесено в белый список с помощью --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 чтения

Инструменты чтения требуют идентификатор сессии, но не лицензию на запись.

simulation_get_entity сообщает канонический путь, тип объекта, исходную конфигурацию MCP, тик симуляции, формы и типы данных массивов, а также данные, специфичные для типа. include_values=true включает ограниченные значения; include_contact=true добавляет состояние контакта твёрдого тела.

simulation_capture_camera — это не снимок экрана рабочего стола или браузера. Он вызывает выбранный бэкенд через Camera.read("rgb"), проверяет канонический буфер uint8 [environment,height,width,3] и кодирует этот буфер в PNG. save_to_evidence=true также записывает изображение в <root>/screenshots/ и возвращает его SHA-256 дайджест и размеры.

API управления

Все изменения требуют непрозрачный lease_id, возвращаемый simulation_create, и уникальный command_id.

Повторное использование command_id с идентичными входными данными возвращает кэшированный результат с idempotent_replay=true. Повторное использование этого идентификатора с другими входными данными отклоняется. Просроченные сессии закрываются автоматически. Каждое применённое или отклонённое изменение записывается в mcp-control-audit.jsonl; значения лицензий исключаются из записи аудита.

Правило работы агента

Агент, использующий профиль Control, должен следовать этой последовательности:

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 для каждой созданной сессии, включая неудачные рабочие процессы.

Агент не должен делать вывод о поддержке бэкенда на основе доступности инструментов. Неподдерживаемые возможности симулятора сообщаются через согласование возможностей или выбранным адаптером.

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