UniRoboSim MCP

English | 简体中文

unirobosim-mcp は、UniRoboSim のエビデンス、シミュレーション状態、バックエンドカメラ画像、および明示的に有効化されたシミュレーション制御を、MCP 互換クライアントに公開します。このサーバーには2つのデプロイプロファイルがあります:

• エビデンスプロファイル（デフォルト）: オペレーターが選択したエビデンスルートへの読み取り専用・制限付きアクセス。

• 制御プロファイル（明示的）: エビデンスツールに加えて、このサーバーが作成・所有するシミュレーターセッションに対する読み取り・制御ツール。

このサーバーは、他のアプリケーションが作成したセッションにはアタッチしません。

インストール

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 構成、シミュレーション tick、配列の形状とデータ型、および型固有のデータを報告します。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 に文書化されています。