iwsdk-runtime MCP server exposes the public tools described on this page. The installed CLI is the authority for the current tool list, descriptions, required fields, accepted values, and limits:npx iwsdk mcp inspect npx iwsdk mcp inspect --tool scene_render_file
| Group | Purpose |
|---|---|
xr_* | Control XR sessions, tracked poses, input mode, controller input, and emulated hand interactions. |
browser_* | Capture, inspect, and interact with the current application, profile the host browser, read diagnostics, reload the page, and mute the tab. |
Scene file and Editor | Validate, compose, open, inspect, and capture native scene files. |
Runtime scene | Inspect the live application hierarchy, transforms, and render statistics. |
asset_render_preview | Render one model asset in isolation. |
ui_* | Discover UIKitML assets, render previews, and inspect live panels. |
ecs_* | Inspect and modify ECS execution and state. |
| Tool | Purpose |
|---|---|
xr_get_session_status | Get XR session and device status. |
xr_accept_session | Accept an offered XR session. |
xr_end_session | End the active XR session. |
xr_get_transform | Read a tracked device’s position and orientation. |
xr_set_transform | Set a tracked device’s position or orientation. |
xr_look_at | Orient a device toward a world-space target. |
xr_animate_to | Animate a device toward a position or orientation. |
xr_set_input_mode | Switch between controller and hand input. |
xr_set_connected | Connect or disconnect a controller or hand. |
xr_get_select_value | Read a trigger or pinch value. |
xr_set_select_value | Set a trigger or pinch value for held interactions. |
xr_select | Dispatch a complete select press and release. |
xr_get_gamepad_state | Read controller buttons and axes. |
xr_set_gamepad_state | Set controller button or axis values. |
xr_get_device_state | Read the complete emulated device state. |
xr_set_device_state | Apply partial device state, or reset it when state is omitted. |
xr_get_session_status and call xr_accept_session when the application is offering a session.world.player). -Z is forward and +Y is up. See XR origin.| Tool | Purpose |
|---|---|
xr_run_sequence | Run a complete hand interaction, such as a press, pinch-grab, carry, set-down, or gesture, in one call. |
xr_cancel_sequence | Stop a running sequence. |
xr_list_targets | List the target names that xr_run_sequence steps accept, with each target’s box center and size. |
xr_set_hand_pose | Shape a hand with a built-in IWER pose such as point, fist, or thumbs-up, optionally per finger and faded over duration. |
xr_get_hand_state | Read the pose, pinch, and XR-origin positions of the wrist, grip, grasp point, and fingertips. |
xr_microgesture | Swipe or tap the thumb along the index finger. The application sees the hand gamepad’s microgesture buttons. |
xr_set_input_mode with hand first. These tools come from IWER and drive the emulated hands the way a person moves them, so your application’s real poke, pinch, and grab code reacts.xr_run_sequence performs each move as one smooth reach. The head turns toward the target, and the body leans or steps closer when the target is out of reach. The result lists the select events the application saw, step times, press contact times, warnings, and the final hand state.dryRun: true to check a plan without moving anything.xr_cancel_sequence to stop it sooner.presses[0].contactMs is 800 or more.npx @iwsdk/cli xr run-sequence --input-json \
'{"device":"hand-right","steps":[{"target":"counter-button","press":{}}]}'
xr_list_targets resolves target names in the live scene:PokeInteractable, RayInteractable, OneHandGrabbable, TwoHandsGrabbable, or DistanceGrabbable, by Object3D name, such as Map Pin 1.id inside those entities, such as counter-button. Hidden elements are left out.target also accepts a scene node ID, any Object3D name, or a UUID. Targets that share a name are listed under their scene node ID. A press goes to the face toward the body, or to a named face such as { "name": ..., "face": "top" }. A grab goes to the middle of the object, and setting a held object down goes to the top of the target.xr_set_select_value or a sequence step’s pinch.xr_set_transform and xr_animate_to also place a hand by a point on it (anchor: index-tip, grasp, or wrist) and orient it by direction ({"fingers":"forward", "thumb":"up"}) or "auto".xr_set_hand_pose, xr_set_select_value, xr_animate_to, and xr_select reply after their duration has passed, so their default timeout grows by that duration.world.player. The two agree in the emulator, but targeted sequences have not been verified on a physical device. Check one press on the device before you rely on target names.| Tool | Purpose |
|---|---|
browser_screenshot | Capture the current application and return the local image path as screenshotPath. |
browser_snapshot | List the current application’s interactive elements, useful text, and canvas regions with refs. |
browser_interact | Run a batch of one to ten Playwright actions against the current application. |
browser_profile | Start, check, or stop a desktop-browser performance profile. |
browser_get_console_logs | Read console calls and other structured browser diagnostics. |
browser_reload_page | Reload only the current application surface. |
browser_set_muted | Turn all audio in the managed browser tab off or back on. |
browser_screenshot has no target parameter. Use scene_screenshot when you need an Editor image.browser_screenshot writes the image to a local temporary file and returns its path as screenshotPath, without inline base64 data. Optional parameters select png or jpeg, set JPEG quality from 20 to 100, capture the full document, or capture one element by a ref returned from browser_snapshot.browser_snapshot returns a bounded, accessibility-first list. Each element includes a ref, role, name, text, visibility, state, and visible bounds. The result also includes a snapshot ID, application identity, and a truncated flag.| Parameter | Type | Required | Description |
|---|---|---|---|
maxNodes | integer | No | 1–1000 elements; defaults to 200 |
maxTextLength | integer | No | 16–1000 characters per name or text field |
rootRef | string | No | Restrict the snapshot to an existing element ref |
browser_interact. Semantic locators can identify an element by testId, role and optional name, or exact text. Page coordinates are available for 2D input. Add canvasRef to make coordinates relative to a canvas.click, doubleClick, hover, pointerMove, pointerDown, pointerUp, wheel, fill, type, clear, press, check, uncheck, select, scroll, drag, keyDown, keyUp, and wait. Keyboard actions target the current application, including its runtime frame in the managed workspace.press is atomic. To hold a key for frame-sampled controls, keep keyDown, a duration-only wait, and keyUp in the same batch:{
"steps": [
{ "action": "keyDown", "key": "KeyW" },
{ "action": "wait", "durationMs": 500 },
{ "action": "keyUp", "key": "KeyW" }
]
}
wait accepts durationMs from 0 through 12,000, must fit the remaining batch budget, and cannot be combined with state, text, path, or loadState.wait step can wait for element state, load state, or an expected application path. It does not start navigation.browser_command_busy: The command queue is full.browser_command_queue_timeout: The request expired while waiting, and the browser was left running.browser_command_timeout: The active operation exceeded its budget, so IWSDK closed the managed browser and relaunches it lazily.browser_command_aborted: Queued work was cleared after another active operation timed out. Retry it against the relaunched browser.browser_profile starts, inspects, or stops a bounded desktop-browser performance profile for the current application:| Parameter | Type | Required | Description |
|---|---|---|---|
action | string | Yes | start, status, or stop |
mode | string | No | interaction, rendering, or trace when starting |
maxDurationMs | integer | No | 1,000–60,000; defaults to 30,000 and auto-stops safely |
profileId | string | No | Require this active profile when stopping |
requestAnimationFrame intervals, long tasks, and interaction marks.interaction mode includes event-timing observations alongside frame timing.rendering mode omits event timing and concentrates on frame and long-task behavior.trace mode adds a bounded Playwright trace artifact under .iwsdk/artifacts/browser/ to the interaction-oriented measurements.summary.collection fields state which collectors ran. Profiles are uncalibrated host-browser diagnostics, not measurements for a target device. Results report classification: "host-browser-diagnostic", calibrated: false, and targetDevice: null.browser_get_console_logs accepts optional count, level, pattern, and since filters. Returned diagnostics can include console calls, uncaught page errors, failed requests, dialogs, downloads, popups, and frame navigation.count at 200, and enforce a bounded response size.browser_reload_page returns the reloaded application URL, page ID, and tab generation.browser_set_muted and the speaker button in the Runtime and Editor bar of the workspace share one dev-session state:| Parameter | Type | Required | Description |
|---|---|---|---|
muted | boolean | Yes | true mutes the tab; false turns its audio back on |
muted property still reports the value page code set.runtime_get_status reports it as browser.audioMuted. Two rare cases are not covered: media that plays automatically inside a declarative shadow root, and a detached media element that automatically plays a srcObject stream. The result is { "muted": <boolean> }. The equivalent CLI command is iwsdk browser set-muted --muted <true|false>.public/scenes/*.iwsdk.scene.json with file tools, then use these MCP tools to validate and inspect the files. MCP does not provide the public scene-document mutation tools found in earlier experimental contracts.| Tool | Purpose |
|---|---|
scene_get_capabilities | Read the native scene format and editor capabilities. Pass full: true for the expanded contract. |
scene_render_file | Validate and render a detached scene file without changing the active Editor document. |
scene_flatten_file | Resolve imports and write one import-free scene file. |
scene_open | Open an existing, import-free scene file in Editor. |
scene_get_state | Read the active file, selection, hashes, diagnostics, dirty or conflict state, runtime readiness, and render statistics. |
scene_select | Replace the Editor selection with the supplied nodeIds array. |
scene_set_preview_visibility | Apply preview-only visibility, context, ghosting, locking, solo, or saved-arrangement operations. |
scene_set_camera | Set a named, stepped, orbit, perspective, or orthographic Editor camera. |
scene_screenshot | Capture the native scene with explicit camera and size options. |
scene_measure_image_regions | Measure named regions when you already have a valid captureToken. |
iwsdk.scene.v1. Node content can be a group, asset, instance, or pattern. Scene resources currently describe prefabs. Asset nodes refer to asset identifiers supplied by the project manifest, including identifiers for procedural Three.js assets.scene_capture_review operation that issues the trusted captureToken required by scene_measure_image_regions. Do not present region measurement as a runnable end-to-end public workflow unless another supported integration has already supplied a valid, session-bound token.scene_render_file first, scene_flatten_file second, and scene_open only on the flattened output. Configure the application to load that flat output through iwsdk.config.json. A successful flatten proves sourceRuntimeHash === outputRuntimeHash; it does not imply that source-document, composed-document, and runtime hashes are the same. See Workflows.scene_open requires an existing file under public/scenes/ that ends in .iwsdk.scene.json. Symbolic links are resolved first: a link can point to another file under public/scenes/, but not outside it, and public/scenes/ itself must resolve inside the project. Opening changes the active document and reconnects the editor session. It never creates a file.scene_render_file accepts path and the optional view (a canonical view such as front, top, or quarter), viewId (an exact saved authoring view), width, and height. A valid result includes source, composed, and runtime hashes, resolved dependencies, camera metadata, render metadata, screenshotSha256, and a local screenshotPath. An invalid result includes structured diagnostics and no screenshot.scene_flatten_file refuses sources, imports, and output outside public/scenes/ after resolving symbolic links. When you omit outputPath, it writes <source>.flat.iwsdk.scene.json. It refuses to replace an existing destination, including in-place output, unless overwrite is true.scene_screenshot writes the PNG to a local temporary file and returns screenshotPath with the active file, hashes, camera, renderer environment, visible node IDs, validation diagnostics, and render statistics.| Tool | Purpose |
|---|---|
scene_get_render_stats | Read runtime renderer counters, scene bounds, resource counts, and scene asset, environment, light, and material summaries. |
scene_get_runtime_hierarchy | Traverse the live application Object3D hierarchy. |
scene_get_object_transform | Read local and global transforms by runtime UUID or native scene node ID. |
scene_get_render_stats returns calls, triangles, points, lines, geometries, textures, programs, meshCount, materialCount, shadowCasters, worldBounds, framingBounds, environment, sceneAssets, sceneEnvironment, sceneLights, and sceneMaterials. Editor-only fields such as objectCount, nodeCount, geometryCount, visibleNodeIds, and frameTimeSamplesMs come from Editor state or capture results, not this runtime tool. scene_get_object_transform also reports the position relative to the XR origin, which can be passed to xr_look_at.sceneEnvironment.background reports what is behind the scene, or null when none of these types applies:type | Fields |
|---|---|
dome-gradient | sky, equator, ground (authored arrays), intensity, elevationDeg, azimuthDeg, dither |
dome-texture | src, intensity, blurriness, rotation |
gradient | topColor, bottomColor, exponent: a background texture with the older scene gradient marker |
color | color |
transparent | None: no background and clear alpha 0, as in an AR session |
sceneEnvironment.imageBasedLighting is { type: 'ibl-gradient', sky, equator, ground, intensity }, { type: 'ibl-texture', src, intensity, rotation }, { type: 'room', intensity, sigma, texture } for an environment texture with the older room IBL marker, or null. An IBLTexture with src: 'room' reports ibl-texture. A DomeGradient is hidden during AR passthrough, so an AR session reports transparent even when the level root has one.sceneEnvironment.domeFades lists every node with a DomeFade, sorted by nodeId, with start, end, meshCount, skippedMaterials, active, and inactiveReason (no-dome-gradient, dome-texture-active, ar-session, no-meshes, or null while it fades).sceneEnvironment.groundShadows is { contactShadows, shadowCatchers }, the number of ContactShadow and ShadowCatcher meshes in the scene. Both are runtime-only meshes, so framingBounds and sceneAssets[].meshCount leave them out, while worldBounds and the total meshCount include them.asset_render_preview renders one glTF or procedural manifest asset in isolation without modifying the open scene. The result persists one labeled contact sheet to screenshotPath and returns geometry diagnostics without embedding image bytes. Use ui_render_preview for UIKitML assets.| Parameter | Type | Required | Default | Minimum | Maximum | Description |
|---|---|---|---|---|---|---|
assetId | string | Yes | - | - | - | Manifest id of the model |
views | string[] | No | 5 views | 1 | 6 | Ordered canonical views |
mode | string | No | material | - | - | material or neutral clay |
focus | string | No | - | - | 512 | Exact named part or named hierarchy path |
width | number | No | 640 | 320 | 2048 | Composite width in pixels |
height | number | No | 480 | 240 | 2048 | Composite height in pixels |
background | string | No | #202226 | - | - | Three.js-compatible background color |
focus after the contact sheet exposes a suspicious part. The full asset remains rendered so attachment context is preserved.| Tool | Purpose |
|---|---|
ui_list_assets | List UIKitML assets available to the project. |
ui_render_preview | Render a UIKitML preview without inserting it into a scene. |
ui_inspect | Inspect the live UIKitML document of one panel entity in the running application. |
ui_list_assets and ui_render_preview for asset discovery and visual preview. Make persistent project changes through the project’s source files. Use ui_inspect for the current state of a panel in the running application.ecs_find_entities or iwsdk scene runtime-hierarchy, then pass its entity index to ui_inspect. For manifest-backed panels, search by the authored panel namePattern. The PanelDocument component identifies legacy PanelUI entities only.selector to list every element with a stable ID in document order, or narrow the result with an existing UIKit selector: #id, .class, or descendant combinations of those selectors, up to 16 selector parts.| Parameter | Type | Required | Default | Maximum | Description |
|---|---|---|---|---|---|
entityIndex | integer | Yes | - | - | ECS entity that owns the live panel |
selector | string | No | all stable IDs | 512 chars, 16 parts | UIKit ID, class, or descendant selector |
properties | string[] | No | common live state | 20 | Computed UIKit property names to include |
limit | integer | No | 50 | 50 | Maximum matching elements |
ui_inspect only observes. It does not click or change the UI. UIKit descendants remain UIKit components rather than synthetic ECS entities. Inspection traverses at most 10,000 objects, and oversized documents fail with an error.npx @iwsdk/cli ui inspect --input-json \
'{"entityIndex":14,"selector":"#counter-button"}'
| Tool | Purpose |
|---|---|
ecs_pause | Pause ECS system updates while the render loop continues. |
ecs_resume | Resume ECS system updates with a capped first-frame delta. |
ecs_step | Advance a fixed number of ECS frames while paused. |
ecs_query_entity | Read component data for an entity index. |
ecs_find_entities | Find entities by components or an object-name pattern. |
ecs_list_systems | List systems, priorities, pause state, configuration keys, and query counts. |
ecs_list_components | List registered component schemas. |
ecs_toggle_system | Pause or resume one system by name. |
ecs_set_component | Set one component field after inspecting its schema and current value. |
ecs_snapshot | Store a labeled snapshot of ECS entity and component state. |
ecs_diff | Compare two labeled snapshots. |
ecs_pause before ecs_step, and call ecs_resume when deterministic inspection is complete.ecs_snapshot retains two labels by default. Pass capacity from 2 through 20 to configure a larger rolling window for the current runtime. Its result lists the active capacity, stored labels, and any label evicted by that capture.ecs_set_component edits to DomeGradient and IBLGradient apply on the next frame. DomeTexture and IBLTexture apply an edit only once _needsUpdate is set to true, so include it in the same call.expectedTab precondition added by the CLI. Supply the tab identity returned by current state when a sequence must fail instead of acting on a stale or reloaded tab.| Claim | Use this evidence |
|---|---|
Native scene layout or framing | scene_screenshot, with captureMode: render to omit Editor overlays or captureMode: editor to include selection and editing overlays |
Validation, dirty, conflict, file, or runtime-readiness diagnostics | scene_get_state |
Application behavior, system-driven motion, or input results | browser_screenshot and browser_get_console_logs |
Live application hierarchy or transform | scene_get_runtime_hierarchy and scene_get_object_transform |
Deterministic ECS state change | ecs_snapshot, ecs_diff, and targeted entity queries |
scene_get_state. A runtime screenshot is not a substitute for either source.