UniRoboSim MCP

English | 简体中文

unirobosim-mcp stellt UniRoboSim-Evidenz, Simulationszustand, Backend-Kamerabilder und explizit aktivierte Simulationssteuerung für MCP-kompatible Clients bereit. Der Server hat zwei Bereitstellungsprofile:

• Evidence-Profil (Standard): eingeschränkter, schreibgeschützter Zugriff auf einen vom Bediener ausgewählten Evidence-Root.

• Control-Profil (explizit): Evidence-Tools sowie Lese- und Steuerungstools für Simulator-Sitzungen, die von diesem Server erstellt und verwaltet werden.

Der Server verbindet sich nicht mit Sitzungen, die von anderen Anwendungen erstellt wurden.

Installation

Python >=3.11,<3.13 wird unterstützt. Installieren Sie Core, dieses Paket und den Adapter, der für das ausgewählte Backend erforderlich ist, in derselben Umgebung.

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

Allgemeine Bereitstellungen verwenden die aktuelle MCP-2.x-Laufzeit. Isaac-Lab-3.0-Umgebungen behalten ihre verifizierten Pydantic- und Uvicorn-Pins bei, installieren Sie dort also den Kompatibilitäts-Extra:

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

Der Extra wählt MCP 1.10.1; er stellt denselben UniRoboSim-Toolkatalog bereit und wurde über das echte stdio-Protokoll mit Isaac Sim 6.0.1 verifiziert.

Related MCP server: gazebo-mcp

Evidence-Profil

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

UNIROBOSIM_EVIDENCE_ROOT kann anstelle von --root verwendet werden:

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

Absolute Pfade, Traversierung, das Umgehen von Symlinks, nicht genehmigte Erweiterungen, übermäßig große Dateien, übermäßige Scans und übermäßige Ergebnisanzahlen werden abgelehnt.

Control-Profil

Control muss explizit aktiviert werden. Lokale Asset-Dateien werden verweigert, es sei denn, ihr übergeordneter Baum ist mit --asset-root auf die Zulassungsliste gesetzt.

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

Read-API

Lese-Tools erfordern eine Sitzungs-ID, aber nicht den Schreib-Lease.

simulation_get_entity meldet den kanonischen Pfad, die Entitätsart, die ursprüngliche MCP-Konfiguration, den Simulationstakt, Array-Formen und -Datentypen sowie typspezifische Daten. include_values=true enthält begrenzte Werte; include_contact=true fügt Kontaktzustand für starre Körper hinzu.

simulation_capture_camera ist kein Desktop- oder Browser-Screenshot. Es ruft das ausgewählte Backend über Camera.read("rgb") auf, validiert den kanonischen [environment,height,width,3]-uint8-Puffer und codiert diesen Puffer als PNG. save_to_evidence=true schreibt das Bild auch unter <root>/screenshots/ und gibt seinen SHA-256-Digest und seine Abmessungen zurück.

Control-API

Alle Mutationen erfordern die undurchsichtige lease_id, die von simulation_create zurückgegeben wird, sowie eine eindeutige command_id.

Die wiederholte Verwendung einer command_id mit identischer Eingabe gibt das zwischengespeicherte Ergebnis mit idempotent_replay=true zurück. Die Wiederverwendung dieser Kennung mit anderer Eingabe wird abgelehnt. Abgelaufene Sitzungen werden automatisch geschlossen. Jede angewendete oder abgelehnte Mutation wird in mcp-control-audit.jsonl geschrieben; Lease-Werte sind vom Prüfprotokoll ausgeschlossen.

Agenten-Betriebsregel

Ein Agent, der das Control-Profil verwendet, muss diese Reihenfolge einhalten:

1. Rufen Sie simulation_list_backends auf und wählen Sie explizit ein verfügbares Backend aus.

2. Rufen Sie simulation_create auf; behalten Sie den zurückgegebenen Lease nur für Schreiboperationen.

3. Fügen Sie alle Entitäten mit eindeutigen Befehlsidentifikatoren hinzu und rufen Sie dann simulation_start auf.

4. Verwenden Sie simulation_scene_snapshot, um kanonische Entitäts- und Kamerapfade zu entdecken.

5. Verwenden Sie simulation_get_entity für gezielten Zustand und simulation_capture_camera für visuelle Überprüfung.

6. Verwenden Sie einen Befehlsidentifikator nur erneut, um dieselbe Schreibanforderung zu wiederholen.

7. Rufen Sie simulation_close für jede erstellte Sitzung auf, einschließlich fehlgeschlagener Arbeitsabläufe.

Der Agent darf die Backend-Unterstützung nicht aus der Verfügbarkeit von Tools ableiten. Nicht unterstützte Simulatorfunktionen werden durch Fähigkeitsverhandlung oder durch den ausgewählten Adapter gemeldet.

Loopback-HTTP

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

Nicht authentifiziertes HTTP ist auf 127.0.0.1, localhost oder ::1 beschränkt. Remote-Bereitstellung erfordert ein authentifiziertes und autorisiertes Gateway. Der Steuerungsmodus darf nicht direkt in einem nicht vertrauenswürdigen Netzwerk bereitgestellt werden.

Programmatische Einbettung

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")

Verifizierung

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

Die Release-Abnahme ruft jedes veröffentlichte MCP-Tool über einen echten In-Process-MCP-Client auf. Zusätzliche Vertragstests decken alle unterstützten Entitätstypen und Befehlsfamilien, Leases, Idempotenz, Ablauf, zugelassene Assets, Ressourcengrenzen, Prüfprotokolle, PNG-Codierung und gespeicherte Screenshot-Evidenz ab. Die native Abnahme wird separat für jeden installierten Simulator-Adapter ausgeführt; ein Feature wird für ein Backend nicht als bestanden gemeldet, es sei denn, dieser native Lauf ist erfolgreich.

Kernverträge und Adapterinstallation sind in UniRoboSim Core dokumentiert.