UniRoboSim MCP

English | 简体中文

unirobosim-mcp expone la evidencia de UniRoboSim, el estado de simulación, las imágenes de cámara del backend y el control de simulación explícitamente habilitado a clientes compatibles con MCP. El servidor tiene dos perfiles de implementación:

• Perfil de evidencia (predeterminado): acceso acotado y de solo lectura a una raíz de evidencia seleccionada por el operador.

• Perfil de control (explícito): herramientas de evidencia más herramientas de lectura y control para sesiones de simulador creadas y propiedad de este servidor.

El servidor no se adjunta a sesiones creadas por otras aplicaciones.

Instalación

Se admite Python >=3.11,<3.13. Instale Core, este paquete y el adaptador requerido por el backend seleccionado en el mismo entorno.

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

Las implementaciones generales usan el runtime MCP 2.x actual. Los entornos Isaac Lab 3.0 conservan sus pines verificados de Pydantic y Uvicorn, por lo que instale el extra de compatibilidad allí:

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

El extra selecciona MCP 1.10.1; expone el mismo catálogo de herramientas de UniRoboSim y se verificó mediante el protocolo stdio real con Isaac Sim 6.0.1.

Related MCP server: gazebo-mcp

Perfil de evidencia

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

UNIROBOSIM_EVIDENCE_ROOT puede usarse en lugar de --root:

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

Se rechazan rutas absolutas, traversal, enlaces simbólicos que escapan, extensiones no aprobadas, archivos sobredimensionados, escaneos excesivos y recuentos de resultados excesivos.

Perfil de control

El control debe habilitarse explícitamente. Los archivos de activos locales se deniegan a menos que su árbol padre esté en la lista permitida con --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 de lectura

Las herramientas de lectura requieren un ID de sesión pero no el lease de escritura.

simulation_get_entity informa la ruta canónica, el tipo de entidad, la configuración MCP original, el tick de simulación, las formas y tipos de datos de los arreglos, y los datos específicos del tipo. include_values=true incluye valores acotados; include_contact=true agrega el estado de contacto del cuerpo rígido.

simulation_capture_camera no es una captura de pantalla de escritorio o navegador. Llama al backend seleccionado a través de Camera.read("rgb"), valida el búfer uint8 canónico [environment,height,width,3] y lo codifica como PNG. save_to_evidence=true también escribe la imagen bajo <root>/screenshots/ y devuelve su digest SHA-256 y dimensiones.

API de control

Todas las mutaciones requieren el lease_id opaco devuelto por simulation_create y un command_id único.

El uso repetido de un command_id con entrada idéntica devuelve el resultado en caché con idempotent_replay=true. Reutilizar ese identificador con entrada diferente se rechaza. Las sesiones expiradas se cierran automáticamente. Cada mutación aplicada o rechazada se escribe en mcp-control-audit.jsonl; los valores de lease se excluyen del registro de auditoría.

Regla operativa del agente

Un agente que use el perfil de control debe seguir esta secuencia:

1. Llame a simulation_list_backends y seleccione un backend disponible explícitamente.

2. Llame a simulation_create; conserve el lease devuelto solo para operaciones de escritura.

3. Agregue todas las entidades con identificadores de comando únicos y luego llame a simulation_start.

4. Use simulation_scene_snapshot para descubrir rutas canónicas de entidades y cámaras.

5. Use simulation_get_entity para el estado dirigido y simulation_capture_camera para la verificación visual.

6. Reutilice un identificador de comando solo para reintentar la misma solicitud de escritura.

7. Llame a simulation_close para cada sesión creada, incluidos los flujos de trabajo fallidos.

El agente no debe inferir el soporte del backend a partir de la disponibilidad de herramientas. Las capacidades no compatibles del simulador se informan mediante la negociación de capacidades o mediante el adaptador seleccionado.

HTTP de bucle local

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

El HTTP no autenticado está restringido a 127.0.0.1, localhost o ::1. La implementación remota requiere una puerta de enlace autenticada y autorizada. El modo de control no debe exponerse directamente en una red no confiable.

Incrustación programática

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

Verificación

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

La aceptación de la versión llama a cada herramienta MCP publicada a través de un cliente MCP real en proceso. Pruebas de contrato adicionales cubren todos los tipos de entidad y familias de comandos admitidos, leases, idempotencia, expiración, activos permitidos, límites de recursos, registros de auditoría, codificación PNG y evidencia de capturas guardadas. La aceptación nativa se ejecuta por separado para cada adaptador de simulador instalado; una característica no se informa como aprobada para un backend a menos que esa ejecución nativa tenga éxito.

Los contratos centrales y la instalación del adaptador se documentan en UniRoboSim Core.