UniRoboSim MCP

English | 简体中文

unirobosim-mcp는 UniRoboSim 증거, 시뮬레이션 상태, 백엔드 카메라 이미지, 그리고 명시적으로 활성화된 시뮬레이션 제어를 MCP 호환 클라이언트에 노출합니다. 서버에는 두 가지 배포 프로필이 있습니다:

• 증거 프로필(기본값): 운영자가 선택한 증거 루트에 대한 제한된 읽기 전용 액세스.

• 제어 프로필(명시적): 이 서버가 생성하고 소유한 시뮬레이터 세션을 위한 증거 도구와 읽기 및 제어 도구.

서버는 다른 애플리케이션이 생성한 세션에는 연결하지 않습니다.

설치

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

--root 대신 UNIROBOSIM_EVIDENCE_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 구성, 시뮬레이션 틱, 배열 모양과 dtype, 그리고 유형별 데이터를 보고합니다. 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에 문서화되어 있습니다.