@iwsdk/cli 0.4.2 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/contract.js CHANGED
@@ -33,14 +33,323 @@ const SUPPORTED_AI_TOOLS = [
33
33
  'cursor',
34
34
  'copilot',
35
35
  'codex',
36
+ 'opencode',
36
37
  ];
37
38
  const MCP_CONFIG_TARGETS = {
38
39
  claude: { file: '.mcp.json', jsonKey: 'mcpServers', format: 'json' },
39
40
  cursor: { file: '.cursor/mcp.json', jsonKey: 'mcpServers', format: 'json' },
40
41
  copilot: { file: '.vscode/mcp.json', jsonKey: 'servers', format: 'json' },
41
42
  codex: { file: '.codex/config.toml', jsonKey: null, format: 'toml' },
43
+ opencode: { file: 'opencode.json', jsonKey: 'mcp', format: 'opencode' },
42
44
  };
43
- const RUNTIME_MCP_TOOLS = [
45
+ const VECTOR3_SCHEMA = {
46
+ type: 'array',
47
+ items: { type: 'number' },
48
+ description: '[x, y, z] in meters or degrees depending on the field',
49
+ };
50
+ const SCENE_TRANSFORM_SCHEMA = {
51
+ type: 'object',
52
+ additionalProperties: false,
53
+ description: 'Scene node transform. position is meters, rotationDeg is Euler degrees, scale is a scalar or [x,y,z].',
54
+ properties: {
55
+ position: VECTOR3_SCHEMA,
56
+ rotationDeg: VECTOR3_SCHEMA,
57
+ scale: {
58
+ oneOf: [{ type: 'number' }, VECTOR3_SCHEMA],
59
+ description: 'Uniform scale number or non-uniform [x, y, z] scale',
60
+ },
61
+ },
62
+ };
63
+ const SCENE_CONSTRAINTS_SCHEMA = {
64
+ type: 'object',
65
+ additionalProperties: false,
66
+ properties: {
67
+ lookAt: {
68
+ type: 'object',
69
+ additionalProperties: false,
70
+ properties: {
71
+ target: VECTOR3_SCHEMA,
72
+ mode: {
73
+ type: 'string',
74
+ enum: ['yaw-v1'],
75
+ },
76
+ },
77
+ required: ['target', 'mode'],
78
+ },
79
+ },
80
+ };
81
+ const SCENE_CONTENT_SCHEMA = {
82
+ oneOf: [
83
+ {
84
+ type: 'object',
85
+ additionalProperties: false,
86
+ properties: { type: { type: 'string', enum: ['group'] } },
87
+ required: ['type'],
88
+ },
89
+ {
90
+ type: 'object',
91
+ additionalProperties: false,
92
+ properties: {
93
+ type: { type: 'string', enum: ['asset'] },
94
+ asset: { type: 'string' },
95
+ castShadow: { type: 'boolean' },
96
+ receiveShadow: { type: 'boolean' },
97
+ },
98
+ required: ['type', 'asset'],
99
+ },
100
+ {
101
+ type: 'object',
102
+ additionalProperties: false,
103
+ properties: {
104
+ type: { type: 'string', enum: ['instance'] },
105
+ prefab: { type: 'string' },
106
+ overrides: { type: 'object' },
107
+ },
108
+ required: ['type', 'prefab'],
109
+ },
110
+ {
111
+ type: 'object',
112
+ additionalProperties: false,
113
+ properties: {
114
+ type: { type: 'string', enum: ['pattern'] },
115
+ prefab: { type: 'string' },
116
+ distribution: { type: 'object' },
117
+ overrides: { type: 'object' },
118
+ },
119
+ required: ['type', 'prefab', 'distribution'],
120
+ },
121
+ ],
122
+ };
123
+ const SCENE_NODE_SCHEMA = {
124
+ type: 'object',
125
+ additionalProperties: false,
126
+ description: 'Scene node. Content is discriminated as group, asset, instance, or pattern. Renderable assets, including procedural geometry, are declared in the asset manifest; behavior capabilities such as lights are components.',
127
+ properties: {
128
+ id: { type: 'string', description: 'Stable scene node id.' },
129
+ name: { type: 'string', description: 'Optional display name.' },
130
+ framingRole: {
131
+ type: 'string',
132
+ enum: ['content', 'support'],
133
+ description: 'Camera-framing role. Omission behaves as content; support remains rendered but is excluded from content framing.',
134
+ },
135
+ content: SCENE_CONTENT_SCHEMA,
136
+ transform: SCENE_TRANSFORM_SCHEMA,
137
+ constraints: SCENE_CONSTRAINTS_SCHEMA,
138
+ components: {
139
+ type: 'object',
140
+ description: 'Optional native scene component values keyed by component id.',
141
+ },
142
+ children: {
143
+ type: 'array',
144
+ items: { type: 'object' },
145
+ description: 'Optional nested scene nodes.',
146
+ },
147
+ metadata: { type: 'object' },
148
+ },
149
+ required: ['id'],
150
+ };
151
+ const SCENE_CAMERA_VIEW_SCHEMA = {
152
+ type: 'string',
153
+ enum: [
154
+ 'current',
155
+ 'top',
156
+ 'front',
157
+ 'back',
158
+ 'left',
159
+ 'right',
160
+ 'quarter',
161
+ 'orbit',
162
+ ],
163
+ description: 'Named editor camera view. "current" preserves the active camera.',
164
+ };
165
+ const SCENE_CAMERA_SCHEMA = {
166
+ properties: {
167
+ viewId: {
168
+ type: 'string',
169
+ description: 'Stable id of an exact perspective or orthographic view declared in document.authoring.views.',
170
+ },
171
+ view: SCENE_CAMERA_VIEW_SCHEMA,
172
+ orbitStep: {
173
+ type: 'number',
174
+ description: 'Deterministic 45-degree orbit step when view is "orbit" (0-7 wrap around; negative values are allowed).',
175
+ },
176
+ step: {
177
+ type: 'number',
178
+ description: 'Alias for orbitStep when view is "orbit".',
179
+ },
180
+ position: VECTOR3_SCHEMA,
181
+ lookAt: VECTOR3_SCHEMA,
182
+ fov: {
183
+ type: 'number',
184
+ minimum: 1,
185
+ maximum: 179,
186
+ description: 'Vertical field of view in degrees',
187
+ },
188
+ projection: {
189
+ type: 'string',
190
+ enum: ['perspective', 'orthographic'],
191
+ description: 'Projection for an explicit camera pose. Named built-in views are perspective; saved viewId projections come from the document.',
192
+ },
193
+ orthographicHeight: {
194
+ type: 'number',
195
+ exclusiveMinimum: 0,
196
+ description: 'Vertical world-space span for an explicit orthographic camera. Kept distinct from screenshot pixel height.',
197
+ },
198
+ },
199
+ };
200
+ const SCENE_HASH_SCHEMA = {
201
+ type: 'string',
202
+ pattern: '^sha256:[0-9a-f]{64}$',
203
+ description: 'Canonical sha256:<64 lowercase hex> content hash.',
204
+ };
205
+ const SCENE_DOCUMENT_INPUT_SCHEMA = {
206
+ type: 'object',
207
+ description: 'Complete closed iwsdk.scene.v1 document. Validate against the exported normative scene schema before sending.',
208
+ };
209
+ const SCENE_REVIEW_INPUT_SCHEMA = {
210
+ type: 'object',
211
+ additionalProperties: false,
212
+ description: 'Complete closed iwsdk.scene-review.v1 record. Server validation binds hashes, capabilities, required views, lenses, criteria, correction lineage, and persisted capture evidence to the active scene. Waivers are representable but cannot be persisted without a trusted user-approval artifact.',
213
+ required: [
214
+ 'version',
215
+ 'documentHash',
216
+ 'runtimeHash',
217
+ 'capabilityHash',
218
+ 'sourceHashes',
219
+ 'round',
220
+ 'result',
221
+ 'lenses',
222
+ 'featureResults',
223
+ 'waivers',
224
+ 'stop',
225
+ ],
226
+ properties: {
227
+ version: { type: 'string', enum: ['iwsdk.scene-review.v1'] },
228
+ documentHash: SCENE_HASH_SCHEMA,
229
+ runtimeHash: SCENE_HASH_SCHEMA,
230
+ capabilityHash: SCENE_HASH_SCHEMA,
231
+ sourceHashes: { type: 'array', items: SCENE_HASH_SCHEMA },
232
+ round: { type: 'integer', minimum: 0, maximum: 10 },
233
+ previousReview: {
234
+ type: 'object',
235
+ additionalProperties: false,
236
+ properties: {
237
+ path: { type: 'string' },
238
+ reviewSha256: SCENE_HASH_SCHEMA,
239
+ },
240
+ required: ['path', 'reviewSha256'],
241
+ },
242
+ correction: {
243
+ type: 'object',
244
+ additionalProperties: false,
245
+ properties: {
246
+ path: { type: 'string' },
247
+ correctionSha256: SCENE_HASH_SCHEMA,
248
+ },
249
+ required: ['path', 'correctionSha256'],
250
+ },
251
+ result: {
252
+ type: 'string',
253
+ enum: ['pass', 'accepted-with-gaps', 'fail'],
254
+ },
255
+ lenses: { type: 'array', items: { type: 'object' } },
256
+ featureResults: { type: 'array', items: { type: 'object' } },
257
+ waivers: { type: 'array', items: { type: 'object' } },
258
+ stop: { type: 'object' },
259
+ },
260
+ };
261
+ const SCENE_REVIEW_CAMERA_INPUT_SCHEMA = {
262
+ type: 'object',
263
+ additionalProperties: false,
264
+ properties: {
265
+ projection: {
266
+ type: 'string',
267
+ enum: ['perspective', 'orthographic'],
268
+ },
269
+ position: VECTOR3_SCHEMA,
270
+ target: VECTOR3_SCHEMA,
271
+ fov: { type: 'number', exclusiveMinimum: 0 },
272
+ height: { type: 'number', exclusiveMinimum: 0 },
273
+ },
274
+ required: ['projection', 'position', 'target'],
275
+ };
276
+ const SCENE_BATCH_REVIEW_CAPTURE_SCHEMA = {
277
+ type: 'object',
278
+ additionalProperties: false,
279
+ description: 'One compact persisted capture entry returned by scene_capture_review_set.',
280
+ properties: {
281
+ lens: {
282
+ type: 'string',
283
+ enum: ['layout', 'geometry', 'final'],
284
+ },
285
+ id: { type: 'string' },
286
+ view: { type: 'string' },
287
+ path: { type: 'string' },
288
+ screenshotSha256: SCENE_HASH_SCHEMA,
289
+ width: { type: 'integer', minimum: 1, maximum: 4096 },
290
+ height: { type: 'integer', minimum: 1, maximum: 4096 },
291
+ camera: SCENE_REVIEW_CAMERA_INPUT_SCHEMA,
292
+ rendererEnvironment: { type: 'object' },
293
+ visibleNodeIds: { type: 'array', items: { type: 'string' } },
294
+ nodeMaskRegions: {
295
+ type: 'object',
296
+ additionalProperties: {
297
+ type: 'array',
298
+ items: { type: 'number' },
299
+ minItems: 4,
300
+ maxItems: 4,
301
+ },
302
+ },
303
+ },
304
+ required: [
305
+ 'lens',
306
+ 'id',
307
+ 'view',
308
+ 'path',
309
+ 'screenshotSha256',
310
+ 'width',
311
+ 'height',
312
+ 'camera',
313
+ 'rendererEnvironment',
314
+ 'visibleNodeIds',
315
+ ],
316
+ };
317
+ const SCENE_REVIEW_EVIDENCE_LINK_SCHEMA = {
318
+ type: 'object',
319
+ additionalProperties: false,
320
+ properties: {
321
+ path: {
322
+ type: 'string',
323
+ description: 'Exact workspace-relative immutable artifact path.',
324
+ },
325
+ sha256: SCENE_HASH_SCHEMA,
326
+ },
327
+ required: ['path', 'sha256'],
328
+ };
329
+ const SCENE_OBJECT_INSPECTION_ASSESSMENT_SCHEMA = {
330
+ type: 'object',
331
+ additionalProperties: false,
332
+ properties: {
333
+ id: {
334
+ type: 'string',
335
+ description: 'Exact declared criterion text, or exact part/contact id, from objectInspection.',
336
+ },
337
+ status: { type: 'string', enum: ['pass', 'fail'] },
338
+ evidenceRefs: {
339
+ type: 'array',
340
+ minItems: 1,
341
+ items: { type: 'string' },
342
+ description: 'Capture ids from the supplied persisted capture set.',
343
+ },
344
+ observation: {
345
+ type: 'string',
346
+ pattern: '\\S',
347
+ description: 'Concrete visual observation explaining the status against the declared criterion.',
348
+ },
349
+ },
350
+ required: ['id', 'status', 'evidenceRefs', 'observation'],
351
+ };
352
+ const ALL_RUNTIME_MCP_TOOLS = [
44
353
  // =============================================================================
45
354
  // Session Management
46
355
  // =============================================================================
@@ -425,10 +734,12 @@ const RUNTIME_MCP_TOOLS = [
425
734
  // =============================================================================
426
735
  {
427
736
  name: 'browser_screenshot',
428
- description: 'Capture a screenshot of the browser. Returns the image directly.',
737
+ description: 'Capture the managed application runtime. If the workspace editor is visible, switches to the runtime before capturing.',
429
738
  inputSchema: {
430
739
  type: 'object',
431
740
  properties: {},
741
+ required: [],
742
+ additionalProperties: false,
432
743
  },
433
744
  },
434
745
  // =============================================================================
@@ -587,225 +898,1412 @@ const RUNTIME_MCP_TOOLS = [
587
898
  },
588
899
  },
589
900
  // =============================================================================
590
- // Framework-Specific Tools (IWSDK or any framework with FRAMEWORK_MCP_RUNTIME)
901
+ // Managed Workspace Tools
591
902
  // =============================================================================
592
903
  {
593
- name: 'scene_get_hierarchy',
594
- description: 'Get the Three.js scene hierarchy as a JSON tree. Returns object names, UUIDs, and entity indices where available. Requires IWSDK or a framework that provides FRAMEWORK_MCP_RUNTIME.',
904
+ name: 'workspace_get_state',
905
+ description: 'Get explicit managed-workspace status for the browser bridge, editor command/viewport readiness, application runtime frame, IWER availability, observable XR session state, selected scene path, scene session id, and dirty state.',
906
+ inputSchema: {
907
+ type: 'object',
908
+ properties: {},
909
+ },
910
+ },
911
+ {
912
+ name: 'workspace_set_view',
913
+ description: 'Set the visible managed IWSDK workspace view. This changes UI presentation only; tool routing remains semantic and deterministic.',
595
914
  inputSchema: {
596
915
  type: 'object',
597
916
  properties: {
598
- parentId: {
917
+ view: {
599
918
  type: 'string',
600
- description: 'UUID of parent Object3D to start from. Defaults to scene root if omitted.',
601
- },
602
- maxDepth: {
603
- type: 'number',
604
- description: 'Maximum depth to traverse (default: 5). Use to limit context size.',
919
+ enum: ['runtime', 'editor'],
920
+ description: 'Workspace view to show',
605
921
  },
606
922
  },
923
+ required: ['view'],
607
924
  },
608
925
  },
609
926
  {
610
- name: 'scene_get_object_transform',
611
- description: 'Get local and global transforms of an Object3D. Includes positionRelativeToXROrigin which can be used directly with xr_look_at tool. Requires IWSDK or a framework that provides FRAMEWORK_MCP_RUNTIME.',
927
+ name: 'workspace_open_scene',
928
+ description: 'Open a scene file from public/scenes in the managed IWSDK workspace editor.',
612
929
  inputSchema: {
613
930
  type: 'object',
614
931
  properties: {
615
- uuid: {
932
+ path: {
616
933
  type: 'string',
617
- description: 'UUID of the Object3D (get this from scene_get_hierarchy)',
934
+ description: 'Scene file path under public/scenes, ending in .iwsdk.scene.json',
618
935
  },
619
936
  },
620
- required: ['uuid'],
937
+ required: ['path'],
621
938
  },
622
939
  },
623
940
  // =============================================================================
624
- // ECS Debugging (IWSDK — requires FRAMEWORK_MCP_RUNTIME)
941
+ // Native Scene Composition Editor Tools
625
942
  // =============================================================================
626
943
  {
627
- name: 'ecs_pause',
628
- description: 'Pause ECS system updates. The render loop continues (XR session stays alive, screenshots still work) but no systems tick. Use ecs_step to advance individual frames while paused. Requires FRAMEWORK_MCP_RUNTIME.',
944
+ name: 'scene_list_files',
945
+ description: 'List IWSDK scene JSON files available under public/scenes in the managed workspace.',
629
946
  inputSchema: {
630
947
  type: 'object',
631
- properties: {},
948
+ properties: {
949
+ query: {
950
+ type: 'string',
951
+ description: 'Optional case-insensitive scene path filter',
952
+ },
953
+ },
632
954
  },
633
955
  },
634
956
  {
635
- name: 'ecs_resume',
636
- description: 'Resume ECS system updates after pausing. The first frame after resume uses a capped delta to avoid physics explosions. Requires FRAMEWORK_MCP_RUNTIME.',
957
+ name: 'scene_open',
958
+ description: 'Open an existing IWSDK scene JSON file from public/scenes in the managed workspace editor.',
637
959
  inputSchema: {
638
960
  type: 'object',
639
- properties: {},
961
+ properties: {
962
+ path: {
963
+ type: 'string',
964
+ description: 'Scene file path under public/scenes, ending in .iwsdk.scene.json',
965
+ },
966
+ },
967
+ required: ['path'],
640
968
  },
641
969
  },
642
970
  {
643
- name: 'ecs_step',
644
- description: 'Advance N ECS frames with a fixed timestep while paused. Must call ecs_pause first. Useful for frame-by-frame debugging. Requires FRAMEWORK_MCP_RUNTIME.',
971
+ name: 'scene_render_file',
972
+ description: 'Validate, compose, and render an IWSDK scene JSON file without opening it in the live editor. Invalid files return structured diagnostics and no PNG; valid files return hashes, render metadata, and PNG image data.',
645
973
  inputSchema: {
646
974
  type: 'object',
975
+ additionalProperties: false,
647
976
  properties: {
648
- count: {
649
- type: 'number',
650
- description: 'Number of frames to advance (1-120, default: 1)',
977
+ path: {
978
+ type: 'string',
979
+ description: 'Existing scene file path under public/scenes, ending in .iwsdk.scene.json',
651
980
  },
652
- delta: {
653
- type: 'number',
654
- description: 'Fixed timestep in seconds for each frame (default: 1/72 ≈ 0.0139, matching Quest refresh rate)',
981
+ view: {
982
+ ...SCENE_CAMERA_VIEW_SCHEMA,
983
+ },
984
+ viewId: {
985
+ type: 'string',
986
+ description: 'Stable id of an exact camera declared in document.authoring.views. Use this, not view, for names such as "hero".',
655
987
  },
988
+ width: { type: 'number', minimum: 1 },
989
+ height: { type: 'number', minimum: 1 },
656
990
  },
991
+ required: ['path'],
657
992
  },
658
993
  },
659
994
  {
660
- name: 'ecs_query_entity',
661
- description: 'Get all component data for an entity. Use entityIndex from scene_get_hierarchy or ecs_find_entities. Returns serialized component values including vectors, entity refs, and Object3D references. Requires FRAMEWORK_MCP_RUNTIME.',
995
+ name: 'scene_flatten_file',
996
+ description: 'Resolve an authoring-only imported scene into one editable, runtime-loadable scene file. The write is refused unless runtime semantics are unchanged.',
662
997
  inputSchema: {
663
998
  type: 'object',
999
+ additionalProperties: false,
664
1000
  properties: {
665
- entityIndex: {
666
- type: 'number',
667
- description: 'Entity index (get this from scene_get_hierarchy or ecs_find_entities)',
1001
+ path: {
1002
+ type: 'string',
1003
+ description: 'Import-bearing source scene path under public/scenes',
668
1004
  },
669
- components: {
670
- type: 'array',
671
- items: { type: 'string' },
672
- description: 'Optional list of component IDs to include. If omitted, returns all components on the entity.',
1005
+ outputPath: {
1006
+ type: 'string',
1007
+ description: 'Flat destination under public/scenes. Defaults to <source>.flat.iwsdk.scene.json.',
1008
+ },
1009
+ overwrite: {
1010
+ type: 'boolean',
1011
+ description: 'Allow replacing an existing destination, including an explicit in-place flatten.',
673
1012
  },
674
1013
  },
675
- required: ['entityIndex'],
1014
+ required: ['path'],
676
1015
  },
677
1016
  },
678
1017
  {
679
- name: 'ecs_find_entities',
680
- description: 'Find entities by component composition and/or name. Returns entity indices and component lists. Use the returned entityIndex values with ecs_query_entity for detailed inspection. Requires FRAMEWORK_MCP_RUNTIME.',
1018
+ name: 'scene_get_state',
1019
+ description: 'Get the active scene file, selection, source/composed/runtime hashes, validation diagnostics, dirty or conflict state, runtime readiness, and current render statistics.',
1020
+ inputSchema: {
1021
+ type: 'object',
1022
+ additionalProperties: false,
1023
+ properties: {},
1024
+ },
1025
+ },
1026
+ {
1027
+ name: 'scene_create',
1028
+ description: 'Create a new IWSDK scene JSON file under public/scenes and open it in the managed workspace editor by default.',
681
1029
  inputSchema: {
682
1030
  type: 'object',
683
1031
  properties: {
684
- withComponents: {
685
- type: 'array',
686
- items: { type: 'string' },
687
- description: 'Component IDs that entities must have (AND logic)',
688
- },
689
- withoutComponents: {
690
- type: 'array',
691
- items: { type: 'string' },
692
- description: 'Component IDs that entities must NOT have',
693
- },
694
- namePattern: {
1032
+ path: {
695
1033
  type: 'string',
696
- description: 'Regex pattern to match against entity Object3D name (case-insensitive)',
1034
+ description: 'Scene file path under public/scenes, ending in .iwsdk.scene.json',
697
1035
  },
698
- limit: {
699
- type: 'number',
700
- description: 'Maximum number of results (1-50, default: 50)',
1036
+ overwrite: {
1037
+ type: 'boolean',
1038
+ description: 'Replace an existing scene file when true',
1039
+ },
1040
+ open: {
1041
+ type: 'boolean',
1042
+ description: 'Open the newly-created scene in the editor. Defaults to true.',
701
1043
  },
702
1044
  },
1045
+ required: ['path'],
703
1046
  },
704
1047
  },
705
1048
  {
706
- name: 'ecs_list_systems',
707
- description: 'List all registered ECS systems with name, priority, pause state, config keys, and query entity counts. Requires FRAMEWORK_MCP_RUNTIME.',
1049
+ name: 'scene_get_capabilities',
1050
+ description: 'Get a compact canonical hash-bound editor capability summary. Pass full:true only when the complete component schemas and compatibility payload are needed.',
708
1051
  inputSchema: {
709
1052
  type: 'object',
710
- properties: {},
1053
+ additionalProperties: false,
1054
+ properties: {
1055
+ full: {
1056
+ type: 'boolean',
1057
+ description: 'Include complete registered component schemas. Defaults to false.',
1058
+ },
1059
+ },
711
1060
  },
712
1061
  },
713
1062
  {
714
- name: 'ecs_list_components',
715
- description: 'List all registered ECS components with their field schemas (type, default). Requires FRAMEWORK_MCP_RUNTIME.',
1063
+ name: 'scene_list_assets',
1064
+ description: 'List assets available to the native IWSDK scene editor, including ids, names, URIs, and bounds metadata when present.',
716
1065
  inputSchema: {
717
1066
  type: 'object',
718
- properties: {},
1067
+ properties: {
1068
+ query: {
1069
+ type: 'string',
1070
+ description: 'Optional case-insensitive asset id/name filter',
1071
+ },
1072
+ },
719
1073
  },
720
1074
  },
721
1075
  {
722
- name: 'ecs_toggle_system',
723
- description: 'Pause or resume a specific ECS system by name. Use ecs_list_systems to discover system names. Requires FRAMEWORK_MCP_RUNTIME.',
1076
+ name: 'scene_search_project_assets',
1077
+ description: 'Search static .gltf and .glb model files available under the current workspace public directory. This is a project-local provider and is distinct from scene_list_assets.',
724
1078
  inputSchema: {
725
1079
  type: 'object',
1080
+ additionalProperties: false,
726
1081
  properties: {
727
- name: {
1082
+ query: {
728
1083
  type: 'string',
729
- description: "System class name (e.g. 'OrbSystem', 'RobotSystem')",
730
- },
731
- paused: {
732
- type: 'boolean',
733
- description: 'Set to true to pause, false to resume. If omitted, toggles current state.',
1084
+ description: 'Optional case-insensitive filter over suggested id, name, URI, and workspace path.',
734
1085
  },
735
1086
  },
736
- required: ['name'],
737
1087
  },
738
1088
  },
739
1089
  {
740
- name: 'ecs_set_component',
741
- description: 'Set a component field value on an entity. Scalars use setValue (with validation), vectors accept arrays. Use ecs_query_entity to inspect current values first. Requires FRAMEWORK_MCP_RUNTIME.',
1090
+ name: 'scene_import_project_asset',
1091
+ description: 'Import one URI returned by scene_search_project_assets into the current scene resources through a hash-checked, preflighted transaction. The import is one undo entry and rejects unknown project paths, duplicate URIs, and id collisions.',
742
1092
  inputSchema: {
743
1093
  type: 'object',
1094
+ additionalProperties: false,
744
1095
  properties: {
745
- entityIndex: {
746
- type: 'number',
747
- description: 'Entity index (from ecs_find_entities or scene_get_hierarchy)',
1096
+ uri: {
1097
+ type: 'string',
1098
+ description: 'Exact project URI returned by scene_search_project_assets.',
748
1099
  },
749
- componentId: {
1100
+ id: {
750
1101
  type: 'string',
751
- description: "Component ID (e.g. 'Orb', 'RobotMood', 'Transform')",
1102
+ description: 'Optional scene asset id. Defaults to the provider suggested id.',
752
1103
  },
753
- field: {
1104
+ name: {
754
1105
  type: 'string',
755
- description: "Field name within the component (e.g. 'orbitSpeed', 'mood')",
1106
+ description: 'Optional display name. Defaults to the project filename without its extension.',
756
1107
  },
757
- value: {
758
- description: 'New value. Scalars: number/string/boolean. Vectors: array of numbers (e.g. [1,2,3] for Vec3).',
1108
+ bounds: {
1109
+ type: 'object',
1110
+ additionalProperties: false,
1111
+ description: 'Optional model-space bounds in meters.',
1112
+ properties: {
1113
+ min: VECTOR3_SCHEMA,
1114
+ max: VECTOR3_SCHEMA,
1115
+ },
1116
+ required: ['min', 'max'],
759
1117
  },
760
1118
  },
761
- required: ['entityIndex', 'componentId', 'field', 'value'],
1119
+ required: ['uri'],
762
1120
  },
763
1121
  },
764
1122
  {
765
- name: 'ecs_snapshot',
766
- description: 'Capture a snapshot of all ECS entity/component state. Stores up to 2 snapshots. Use with ecs_diff to compare. Requires FRAMEWORK_MCP_RUNTIME.',
1123
+ name: 'scene_list_component_schemas',
1124
+ description: 'List typed component schemas available to the native IWSDK scene editor. Use this before adding or editing component payloads so scene JSON uses typed component props.',
767
1125
  inputSchema: {
768
1126
  type: 'object',
769
1127
  properties: {
770
- label: {
1128
+ query: {
771
1129
  type: 'string',
772
- description: 'Label for this snapshot (default: auto-generated). Use to reference in ecs_diff.',
1130
+ description: 'Optional case-insensitive component id/name/description filter',
773
1131
  },
774
1132
  },
775
1133
  },
776
1134
  },
777
1135
  {
778
- name: 'ecs_diff',
779
- description: 'Compare two ECS snapshots. Shows added/removed/changed entities and field-level diffs. Requires FRAMEWORK_MCP_RUNTIME.',
1136
+ name: 'scene_get_document',
1137
+ description: 'Get the current native IWSDK scene JSON document from the editor page.',
1138
+ inputSchema: {
1139
+ type: 'object',
1140
+ properties: {},
1141
+ },
1142
+ },
1143
+ {
1144
+ name: 'scene_get_hierarchy',
1145
+ description: 'Get the current native IWSDK scene document hierarchy from the editor page. Returns native scene node ids, not Object3D UUIDs.',
780
1146
  inputSchema: {
781
1147
  type: 'object',
782
1148
  properties: {
783
- from: {
1149
+ parentId: {
784
1150
  type: 'string',
785
- description: "Label of the 'before' snapshot",
1151
+ description: 'Scene node id of the parent to start from. Defaults to scene root if omitted.',
786
1152
  },
787
- to: {
1153
+ maxDepth: {
1154
+ type: 'number',
1155
+ description: 'Maximum depth to traverse (default: 5). Use to limit context size.',
1156
+ },
1157
+ },
1158
+ },
1159
+ },
1160
+ {
1161
+ name: 'scene_get_selection',
1162
+ description: 'Get the current native scene editor selection.',
1163
+ inputSchema: {
1164
+ type: 'object',
1165
+ properties: {},
1166
+ },
1167
+ },
1168
+ {
1169
+ name: 'scene_select',
1170
+ description: 'Select one or more scene node ids in the native editor.',
1171
+ inputSchema: {
1172
+ type: 'object',
1173
+ properties: {
1174
+ nodeIds: {
1175
+ type: 'array',
1176
+ items: { type: 'string' },
1177
+ description: 'Scene node ids to select. Pass [] to clear selection.',
1178
+ },
1179
+ },
1180
+ required: ['nodeIds'],
1181
+ },
1182
+ },
1183
+ {
1184
+ name: 'scene_add_node',
1185
+ description: 'Add a group, asset, instance, pattern, light, or component-bearing node to the native scene JSON document. Procedural geometry must first be declared as an asset.',
1186
+ inputSchema: {
1187
+ type: 'object',
1188
+ properties: {
1189
+ node: {
1190
+ ...SCENE_NODE_SCHEMA,
1191
+ },
1192
+ parentId: {
788
1193
  type: 'string',
789
- description: "Label of the 'after' snapshot",
1194
+ description: 'Optional parent scene node id',
1195
+ },
1196
+ index: {
1197
+ type: 'number',
1198
+ description: 'Optional insertion index within the parent children',
790
1199
  },
791
1200
  },
792
- required: ['from', 'to'],
1201
+ required: ['node'],
793
1202
  },
794
1203
  },
795
- ];
796
- const RUNTIME_TOOL_TO_METHOD = {
797
- xr_get_session_status: 'get_session_status',
798
- xr_accept_session: 'accept_session',
799
- xr_end_session: 'end_session',
800
- xr_get_transform: 'get_transform',
801
- xr_set_transform: 'set_transform',
802
- xr_look_at: 'look_at',
803
- xr_animate_to: 'animate_to',
804
- xr_set_input_mode: 'set_input_mode',
805
- xr_set_connected: 'set_connected',
806
- xr_get_select_value: 'get_select_value',
807
- xr_set_select_value: 'set_select_value',
808
- xr_select: 'select',
1204
+ {
1205
+ name: 'scene_remove_node',
1206
+ description: 'Remove a node from the native scene JSON document.',
1207
+ inputSchema: {
1208
+ type: 'object',
1209
+ properties: {
1210
+ nodeId: { type: 'string', description: 'Scene node id to remove' },
1211
+ },
1212
+ required: ['nodeId'],
1213
+ },
1214
+ },
1215
+ {
1216
+ name: 'scene_duplicate_node',
1217
+ description: 'Duplicate a node and its children in the native scene editor.',
1218
+ inputSchema: {
1219
+ type: 'object',
1220
+ properties: {
1221
+ nodeId: { type: 'string', description: 'Scene node id to duplicate' },
1222
+ newNodeId: {
1223
+ type: 'string',
1224
+ description: 'Optional id for the duplicated root node',
1225
+ },
1226
+ parentId: {
1227
+ type: 'string',
1228
+ description: 'Optional parent id for the duplicate. Defaults to the original parent.',
1229
+ },
1230
+ },
1231
+ required: ['nodeId'],
1232
+ },
1233
+ },
1234
+ {
1235
+ name: 'scene_set_transform',
1236
+ description: 'Replace the transform for a native scene node.',
1237
+ inputSchema: {
1238
+ type: 'object',
1239
+ properties: {
1240
+ nodeId: { type: 'string', description: 'Scene node id' },
1241
+ transform: SCENE_TRANSFORM_SCHEMA,
1242
+ },
1243
+ required: ['nodeId', 'transform'],
1244
+ },
1245
+ },
1246
+ {
1247
+ name: 'scene_set_framing_role',
1248
+ description: 'Set a native scene node camera-framing role to content or support as one undoable patch. Use scene_apply_transaction for hash-checked review corrections.',
1249
+ inputSchema: {
1250
+ type: 'object',
1251
+ additionalProperties: false,
1252
+ properties: {
1253
+ nodeId: { type: 'string', description: 'Scene node id' },
1254
+ framingRole: {
1255
+ type: 'string',
1256
+ enum: ['content', 'support'],
1257
+ description: 'content participates in automatic framing; support remains rendered but is excluded.',
1258
+ },
1259
+ },
1260
+ required: ['nodeId', 'framingRole'],
1261
+ },
1262
+ },
1263
+ {
1264
+ name: 'scene_apply_patch',
1265
+ description: 'Apply one native scene JSON patch operation with undo support. Replacement and transactions must use their dedicated hash-checked tools.',
1266
+ inputSchema: {
1267
+ type: 'object',
1268
+ properties: {
1269
+ patch: {
1270
+ type: 'object',
1271
+ description: 'ScenePatch operation such as addNode/removeNode, updateContent/updateConstraints, setEnvironment/setAuthoring, add/update/remove Asset, Material, Prefab, or AuthoringView. Resource references are validated on the resulting document.',
1272
+ },
1273
+ },
1274
+ required: ['patch'],
1275
+ },
1276
+ },
1277
+ {
1278
+ name: 'scene_apply_transaction',
1279
+ description: 'Stage ordered scene patches, validate and preflight the complete candidate, then commit them atomically as one undo entry. Any failure leaves the live document unchanged.',
1280
+ inputSchema: {
1281
+ type: 'object',
1282
+ additionalProperties: false,
1283
+ properties: {
1284
+ patches: {
1285
+ type: 'array',
1286
+ items: { type: 'object' },
1287
+ minItems: 1,
1288
+ description: 'Ordered scene patches. Supports node, asset, material, prefab, environment, authoring, and authoring-view operations.',
1289
+ },
1290
+ expectedBaseDocumentHash: {
1291
+ oneOf: [SCENE_HASH_SCHEMA, { type: 'null' }],
1292
+ description: 'Required optimistic-concurrency hash. Null is accepted only for a blank new scene.',
1293
+ },
1294
+ candidateDocumentHash: {
1295
+ ...SCENE_HASH_SCHEMA,
1296
+ description: 'Optional caller-computed integrity assertion. When omitted, the editor computes and returns the canonical candidate hash.',
1297
+ },
1298
+ correction: {
1299
+ type: 'object',
1300
+ additionalProperties: false,
1301
+ description: 'Required only after scene_begin_review freezes the draft. Binds one correction to the exact current immutable review and defect.',
1302
+ properties: {
1303
+ kind: {
1304
+ type: 'string',
1305
+ enum: ['scene', 'resource', 'camera', 'contract'],
1306
+ },
1307
+ defectTags: {
1308
+ type: 'array',
1309
+ minItems: 1,
1310
+ items: { type: 'string' },
1311
+ },
1312
+ reason: { type: 'string' },
1313
+ previousReview: {
1314
+ type: 'object',
1315
+ additionalProperties: false,
1316
+ properties: {
1317
+ path: { type: 'string' },
1318
+ reviewSha256: SCENE_HASH_SCHEMA,
1319
+ },
1320
+ required: ['path', 'reviewSha256'],
1321
+ },
1322
+ },
1323
+ required: ['kind', 'defectTags', 'previousReview'],
1324
+ },
1325
+ ownershipMode: {
1326
+ type: 'string',
1327
+ enum: ['replace-new'],
1328
+ description: 'Materialization ownership. merge-under-root is not yet supported.',
1329
+ },
1330
+ },
1331
+ required: ['patches', 'expectedBaseDocumentHash'],
1332
+ },
1333
+ },
1334
+ {
1335
+ name: 'scene_replace_document',
1336
+ description: 'Atomically replace the complete editor document after the required base-hash concurrency check, any optional candidate-hash integrity assertion, validation, detached resource/runtime preflight, and commit. Creates one undo entry.',
1337
+ inputSchema: {
1338
+ type: 'object',
1339
+ additionalProperties: false,
1340
+ properties: {
1341
+ document: SCENE_DOCUMENT_INPUT_SCHEMA,
1342
+ expectedBaseDocumentHash: {
1343
+ oneOf: [SCENE_HASH_SCHEMA, { type: 'null' }],
1344
+ description: 'Required optimistic-concurrency hash. Null is accepted only for a blank new scene.',
1345
+ },
1346
+ candidateDocumentHash: {
1347
+ ...SCENE_HASH_SCHEMA,
1348
+ description: 'Optional caller-computed integrity assertion. When omitted, the editor computes and returns the canonical document hash.',
1349
+ },
1350
+ ownershipMode: {
1351
+ type: 'string',
1352
+ enum: ['replace-new'],
1353
+ },
1354
+ },
1355
+ required: ['document', 'expectedBaseDocumentHash'],
1356
+ },
1357
+ },
1358
+ {
1359
+ name: 'scene_look_at',
1360
+ description: 'Yaw a scene node so it faces a target point while preserving pitch and roll.',
1361
+ inputSchema: {
1362
+ type: 'object',
1363
+ properties: {
1364
+ nodeId: { type: 'string', description: 'Node to orient' },
1365
+ target: VECTOR3_SCHEMA,
1366
+ },
1367
+ required: ['nodeId', 'target'],
1368
+ },
1369
+ },
1370
+ {
1371
+ name: 'scene_validate',
1372
+ description: 'Validate the current native scene JSON document and return structured issues with paths and suggested fixes where available.',
1373
+ inputSchema: {
1374
+ type: 'object',
1375
+ properties: {},
1376
+ },
1377
+ },
1378
+ {
1379
+ name: 'scene_save',
1380
+ description: 'Save the current native scene JSON document from the editor page to disk.',
1381
+ inputSchema: {
1382
+ type: 'object',
1383
+ properties: {},
1384
+ },
1385
+ },
1386
+ {
1387
+ name: 'scene_undo',
1388
+ description: 'Undo the most recent native scene editor command.',
1389
+ inputSchema: {
1390
+ type: 'object',
1391
+ properties: {},
1392
+ },
1393
+ },
1394
+ {
1395
+ name: 'scene_redo',
1396
+ description: 'Redo the most recently undone native scene editor command.',
1397
+ inputSchema: {
1398
+ type: 'object',
1399
+ properties: {},
1400
+ },
1401
+ },
1402
+ {
1403
+ name: 'scene_set_preview_visibility',
1404
+ description: 'Change editor-only preview visibility without modifying or saving the scene document. Supports recursive hide/show, ghosting, locking, context, solo, reset, and named local arrangements.',
1405
+ inputSchema: {
1406
+ type: 'object',
1407
+ additionalProperties: false,
1408
+ properties: {
1409
+ mode: {
1410
+ type: 'string',
1411
+ enum: [
1412
+ 'apply-arrangement',
1413
+ 'context',
1414
+ 'ghost',
1415
+ 'hide',
1416
+ 'lock',
1417
+ 'reset',
1418
+ 'save-arrangement',
1419
+ 'show',
1420
+ 'solo',
1421
+ 'uncontext',
1422
+ 'unghost',
1423
+ 'unlock',
1424
+ ],
1425
+ },
1426
+ nodeIds: {
1427
+ type: 'array',
1428
+ items: { type: 'string' },
1429
+ description: 'Scene node ids affected by the preview operation. Solo accepts at most one.',
1430
+ },
1431
+ recursive: {
1432
+ type: 'boolean',
1433
+ description: 'Apply the operation to descendants. Defaults to true for hierarchy visibility operations.',
1434
+ },
1435
+ name: {
1436
+ type: 'string',
1437
+ description: 'Arrangement name for save-arrangement or apply-arrangement.',
1438
+ },
1439
+ },
1440
+ required: ['mode'],
1441
+ },
1442
+ },
1443
+ {
1444
+ name: 'scene_get_logs',
1445
+ description: 'Get native scene editor logs.',
1446
+ inputSchema: {
1447
+ type: 'object',
1448
+ properties: {
1449
+ count: {
1450
+ type: 'number',
1451
+ description: 'Maximum number of recent logs to return',
1452
+ },
1453
+ level: {
1454
+ type: 'string',
1455
+ enum: ['info', 'warn', 'error'],
1456
+ description: 'Optional log level filter',
1457
+ },
1458
+ },
1459
+ },
1460
+ },
1461
+ {
1462
+ name: 'scene_set_camera',
1463
+ description: 'Set the native scene editor camera to a built-in view, exact saved authoring viewId, or explicit perspective/orthographic pose.',
1464
+ inputSchema: {
1465
+ type: 'object',
1466
+ properties: SCENE_CAMERA_SCHEMA.properties,
1467
+ },
1468
+ },
1469
+ {
1470
+ name: 'scene_screenshot',
1471
+ description: 'Capture a native scene editor screenshot. Supports exact saved authoring viewId cameras, current/top/front/back/left/right/quarter/orbit views, and explicit perspective/orthographic poses.',
1472
+ inputSchema: {
1473
+ type: 'object',
1474
+ properties: {
1475
+ ...SCENE_CAMERA_SCHEMA.properties,
1476
+ width: {
1477
+ type: 'number',
1478
+ minimum: 1,
1479
+ maximum: 4096,
1480
+ description: 'Optional screenshot width in pixels',
1481
+ },
1482
+ height: {
1483
+ type: 'number',
1484
+ minimum: 1,
1485
+ maximum: 4096,
1486
+ description: 'Optional screenshot height in pixels',
1487
+ },
1488
+ captureMode: {
1489
+ type: 'string',
1490
+ enum: ['render', 'editor'],
1491
+ description: 'render (default) excludes editor-only grid, selection, transform, component-helper, and orientation overlays; editor includes them for UI diagnostics.',
1492
+ },
1493
+ },
1494
+ },
1495
+ },
1496
+ {
1497
+ name: 'ui_list_assets',
1498
+ description: 'List UIKitML assets available in the project asset manifest. Use a returned asset id with ui_render_preview or a PanelUI component config.',
1499
+ inputSchema: {
1500
+ type: 'object',
1501
+ additionalProperties: false,
1502
+ properties: {
1503
+ query: {
1504
+ type: 'string',
1505
+ description: 'Optional case-insensitive filter over UIKitML asset ids and names.',
1506
+ },
1507
+ },
1508
+ },
1509
+ },
1510
+ {
1511
+ name: 'ui_render_preview',
1512
+ description: 'Render one UIKitML asset from the project asset manifest in isolation against a plain background. Use this to inspect panel layout without the surrounding scene.',
1513
+ inputSchema: {
1514
+ type: 'object',
1515
+ additionalProperties: false,
1516
+ properties: {
1517
+ assetId: {
1518
+ type: 'string',
1519
+ description: 'Manifest id of an AssetType.UIKitML entry. Discover ids with ui_list_assets.',
1520
+ },
1521
+ width: {
1522
+ type: 'number',
1523
+ minimum: 1,
1524
+ maximum: 4096,
1525
+ description: 'Preview width in pixels. Defaults to 512.',
1526
+ },
1527
+ height: {
1528
+ type: 'number',
1529
+ minimum: 1,
1530
+ maximum: 4096,
1531
+ description: 'Preview height in pixels. Defaults to 512.',
1532
+ },
1533
+ background: {
1534
+ type: 'string',
1535
+ description: 'Three.js-compatible background color. Defaults to #202226.',
1536
+ },
1537
+ },
1538
+ required: ['assetId'],
1539
+ },
1540
+ },
1541
+ {
1542
+ name: 'scene_compare_screenshots',
1543
+ description: 'Capture two native scene editor screenshots and report byte identity. This is not a perceptual image comparison.',
1544
+ inputSchema: {
1545
+ type: 'object',
1546
+ properties: {
1547
+ first: {
1548
+ type: 'object',
1549
+ description: 'First camera request. Accepts the same fields as scene_screenshot.',
1550
+ properties: {
1551
+ ...SCENE_CAMERA_SCHEMA.properties,
1552
+ captureMode: {
1553
+ type: 'string',
1554
+ enum: ['render', 'editor'],
1555
+ description: 'render excludes editor-only overlays; editor includes them.',
1556
+ },
1557
+ },
1558
+ },
1559
+ second: {
1560
+ type: 'object',
1561
+ description: 'Second camera request. Accepts the same fields as scene_screenshot.',
1562
+ properties: {
1563
+ ...SCENE_CAMERA_SCHEMA.properties,
1564
+ captureMode: {
1565
+ type: 'string',
1566
+ enum: ['render', 'editor'],
1567
+ description: 'render excludes editor-only overlays; editor includes them.',
1568
+ },
1569
+ },
1570
+ },
1571
+ width: {
1572
+ type: 'number',
1573
+ minimum: 1,
1574
+ maximum: 4096,
1575
+ description: 'Optional screenshot width in pixels',
1576
+ },
1577
+ height: {
1578
+ type: 'number',
1579
+ minimum: 1,
1580
+ maximum: 4096,
1581
+ description: 'Optional screenshot height in pixels',
1582
+ },
1583
+ },
1584
+ required: ['first', 'second'],
1585
+ },
1586
+ },
1587
+ {
1588
+ name: 'scene_begin_review',
1589
+ description: 'Freeze the current saved draft scene as formal review round 0. After this one-way boundary, every scene or camera change requires an adjacent immutable review and authorized correction.',
1590
+ inputSchema: {
1591
+ type: 'object',
1592
+ additionalProperties: false,
1593
+ properties: {
1594
+ scenePath: {
1595
+ type: 'string',
1596
+ description: 'Scene file path under public/scenes, ending in .iwsdk.scene.json.',
1597
+ },
1598
+ expectedDocumentHash: {
1599
+ ...SCENE_HASH_SCHEMA,
1600
+ description: 'Canonical hash returned by scene_save for the exact draft to freeze.',
1601
+ },
1602
+ runtimePreflightReceipt: {
1603
+ ...SCENE_REVIEW_EVIDENCE_LINK_SCHEMA,
1604
+ description: 'Exact current passing receipt returned by scene_runtime_preflight.receipt.',
1605
+ },
1606
+ },
1607
+ required: [
1608
+ 'scenePath',
1609
+ 'expectedDocumentHash',
1610
+ 'runtimePreflightReceipt',
1611
+ ],
1612
+ },
1613
+ },
1614
+ {
1615
+ name: 'scene_set_review_lens',
1616
+ description: 'Set the editor-only layout, geometry, or final review lens without changing the scene document.',
1617
+ inputSchema: {
1618
+ type: 'object',
1619
+ additionalProperties: false,
1620
+ properties: {
1621
+ lens: {
1622
+ type: 'string',
1623
+ enum: ['layout', 'geometry', 'final'],
1624
+ },
1625
+ },
1626
+ required: ['lens'],
1627
+ },
1628
+ },
1629
+ {
1630
+ name: 'scene_capture_review',
1631
+ description: 'Capture review evidence bound to document/runtime/capability hashes, exact normalized reviewCamera and resolution, active lens, logs, feature state, visibility metadata, and measured renderer statistics. The server registers the PNG internally; the response omits base64 imageData unless includeImageData:true is explicitly requested.',
1632
+ inputSchema: {
1633
+ type: 'object',
1634
+ additionalProperties: false,
1635
+ properties: {
1636
+ ...SCENE_CAMERA_SCHEMA.properties,
1637
+ width: {
1638
+ type: 'integer',
1639
+ minimum: 1,
1640
+ maximum: 4096,
1641
+ },
1642
+ height: {
1643
+ type: 'integer',
1644
+ minimum: 1,
1645
+ maximum: 4096,
1646
+ },
1647
+ featureState: {
1648
+ type: 'object',
1649
+ description: 'Caller-provided feature-state metadata recorded with the capture.',
1650
+ },
1651
+ includeImageData: {
1652
+ type: 'boolean',
1653
+ description: 'Return the full base64 PNG in imageData. Defaults to false because captureToken is sufficient for persistence.',
1654
+ },
1655
+ },
1656
+ required: ['width', 'height'],
1657
+ },
1658
+ },
1659
+ {
1660
+ name: 'scene_persist_review_capture',
1661
+ description: 'Persist a server-issued, session-bound capture returned by scene_capture_review under the active scene review directory. The server resolves captureToken to its registered PNG bytes and trusted capture facts, then writes immutable PNG plus metadata; an exact repeat is idempotent and capture fields cannot be relabeled.',
1662
+ inputSchema: {
1663
+ type: 'object',
1664
+ additionalProperties: false,
1665
+ properties: {
1666
+ captureId: {
1667
+ type: 'string',
1668
+ pattern: '^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$',
1669
+ description: 'Stable evidence id used in the review capture entry.',
1670
+ },
1671
+ captureToken: {
1672
+ ...SCENE_HASH_SCHEMA,
1673
+ description: 'Session-bound token returned by scene_capture_review.captureToken.',
1674
+ },
1675
+ },
1676
+ required: ['captureId', 'captureToken'],
1677
+ },
1678
+ },
1679
+ {
1680
+ name: 'scene_measure_image_regions',
1681
+ description: 'Measure aligned declared-reference and render-capture regions using linear-sRGB luma percentiles, mean OKLab color, and highlight/shadow footprints. Returns raw diagnostics and deltas, never a universal similarity pass.',
1682
+ inputSchema: {
1683
+ type: 'object',
1684
+ additionalProperties: false,
1685
+ properties: {
1686
+ captureToken: {
1687
+ ...SCENE_HASH_SCHEMA,
1688
+ description: 'Trusted token returned by scene_capture_review.',
1689
+ },
1690
+ referenceId: {
1691
+ type: 'string',
1692
+ description: 'ID of a hash-bound reference declared in authoring.composition.input.references.',
1693
+ },
1694
+ regions: {
1695
+ type: 'array',
1696
+ minItems: 1,
1697
+ maxItems: 64,
1698
+ items: {
1699
+ type: 'object',
1700
+ additionalProperties: false,
1701
+ properties: {
1702
+ id: { type: 'string' },
1703
+ referenceRegion: {
1704
+ type: 'array',
1705
+ minItems: 4,
1706
+ maxItems: 4,
1707
+ items: { type: 'number', minimum: 0, maximum: 1 },
1708
+ description: 'Normalized [x, y, width, height].',
1709
+ },
1710
+ renderRegion: {
1711
+ type: 'array',
1712
+ minItems: 4,
1713
+ maxItems: 4,
1714
+ items: { type: 'number', minimum: 0, maximum: 1 },
1715
+ description: 'Aligned normalized render region. Defaults to referenceRegion.',
1716
+ },
1717
+ },
1718
+ required: ['id', 'referenceRegion'],
1719
+ },
1720
+ },
1721
+ },
1722
+ required: ['captureToken', 'referenceId', 'regions'],
1723
+ },
1724
+ },
1725
+ {
1726
+ name: 'scene_capture_review_set',
1727
+ description: 'Capture and immutably persist a complete requested set of saved authoring views across review lenses in one call. Lens switching is automatic, PNG bytes stay server-side, and the response contains only compact schema-ready capture metadata for scene_finalize_review.',
1728
+ inputSchema: {
1729
+ type: 'object',
1730
+ additionalProperties: false,
1731
+ properties: {
1732
+ width: {
1733
+ type: 'integer',
1734
+ minimum: 1,
1735
+ maximum: 4096,
1736
+ description: 'Default capture width for the set.',
1737
+ },
1738
+ height: {
1739
+ type: 'integer',
1740
+ minimum: 1,
1741
+ maximum: 4096,
1742
+ description: 'Default capture height for the set.',
1743
+ },
1744
+ captures: {
1745
+ type: 'array',
1746
+ minItems: 1,
1747
+ maxItems: 32,
1748
+ items: {
1749
+ type: 'object',
1750
+ additionalProperties: false,
1751
+ properties: {
1752
+ id: {
1753
+ type: 'string',
1754
+ pattern: '^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$',
1755
+ },
1756
+ lens: {
1757
+ type: 'string',
1758
+ enum: ['layout', 'geometry', 'final'],
1759
+ },
1760
+ viewId: {
1761
+ type: 'string',
1762
+ description: 'Exact id from document.authoring.views; arbitrary built-in cameras are not accepted as immutable review evidence.',
1763
+ },
1764
+ width: { type: 'integer', minimum: 1, maximum: 4096 },
1765
+ height: { type: 'integer', minimum: 1, maximum: 4096 },
1766
+ featureState: { type: 'object' },
1767
+ },
1768
+ required: ['id', 'lens', 'viewId'],
1769
+ },
1770
+ },
1771
+ },
1772
+ required: ['width', 'height', 'captures'],
1773
+ },
1774
+ },
1775
+ {
1776
+ name: 'scene_record_object_inspection',
1777
+ description: 'Record immutable server-issued inspection evidence for one identity-critical feature. Every required view needs geometry and final captures with the complete subject and declared context visible; form criteria must cite geometry evidence and material response must cite final evidence. Validates persisted capture provenance and complete silhouette, proportions, parts, negative-space, contacts, and material-response coverage. The server derives pass/fail and binds the artifact to current document, runtime, and capability hashes.',
1778
+ inputSchema: {
1779
+ type: 'object',
1780
+ additionalProperties: false,
1781
+ properties: {
1782
+ scenePath: {
1783
+ type: 'string',
1784
+ description: 'Scene file path under public/scenes, ending in .iwsdk.scene.json.',
1785
+ },
1786
+ expectedDocumentHash: SCENE_HASH_SCHEMA,
1787
+ capabilityHash: SCENE_HASH_SCHEMA,
1788
+ featureId: {
1789
+ type: 'string',
1790
+ description: 'Exact id of an identityCritical feature with objectInspection.',
1791
+ },
1792
+ captures: {
1793
+ type: 'array',
1794
+ minItems: 1,
1795
+ maxItems: 32,
1796
+ items: SCENE_BATCH_REVIEW_CAPTURE_SCHEMA,
1797
+ },
1798
+ results: {
1799
+ type: 'object',
1800
+ additionalProperties: false,
1801
+ properties: {
1802
+ silhouette: {
1803
+ type: 'array',
1804
+ items: SCENE_OBJECT_INSPECTION_ASSESSMENT_SCHEMA,
1805
+ },
1806
+ proportions: {
1807
+ type: 'array',
1808
+ items: SCENE_OBJECT_INSPECTION_ASSESSMENT_SCHEMA,
1809
+ },
1810
+ parts: {
1811
+ type: 'array',
1812
+ items: SCENE_OBJECT_INSPECTION_ASSESSMENT_SCHEMA,
1813
+ },
1814
+ negativeSpace: {
1815
+ type: 'array',
1816
+ items: SCENE_OBJECT_INSPECTION_ASSESSMENT_SCHEMA,
1817
+ },
1818
+ contacts: {
1819
+ type: 'array',
1820
+ items: SCENE_OBJECT_INSPECTION_ASSESSMENT_SCHEMA,
1821
+ },
1822
+ materialResponse: {
1823
+ type: 'array',
1824
+ items: SCENE_OBJECT_INSPECTION_ASSESSMENT_SCHEMA,
1825
+ },
1826
+ },
1827
+ required: [
1828
+ 'silhouette',
1829
+ 'proportions',
1830
+ 'parts',
1831
+ 'negativeSpace',
1832
+ 'contacts',
1833
+ 'materialResponse',
1834
+ ],
1835
+ },
1836
+ },
1837
+ required: [
1838
+ 'scenePath',
1839
+ 'expectedDocumentHash',
1840
+ 'capabilityHash',
1841
+ 'featureId',
1842
+ 'captures',
1843
+ 'results',
1844
+ ],
1845
+ },
1846
+ },
1847
+ {
1848
+ name: 'scene_finalize_review',
1849
+ description: 'Finalize and immutably save a review from batch capture metadata plus human lens and visual judgments. The SDK fills revision/source hashes, evaluates every deterministic criterion, derives the overall result, validates exact evidence, and routes failures to continue-refining; callers cannot guess deterministic statuses or force a passing result.',
1850
+ inputSchema: {
1851
+ type: 'object',
1852
+ additionalProperties: false,
1853
+ properties: {
1854
+ round: { type: 'integer', minimum: 0, maximum: 10 },
1855
+ captures: {
1856
+ type: 'array',
1857
+ minItems: 1,
1858
+ items: SCENE_BATCH_REVIEW_CAPTURE_SCHEMA,
1859
+ },
1860
+ lensResults: {
1861
+ type: 'array',
1862
+ minItems: 1,
1863
+ items: {
1864
+ type: 'object',
1865
+ additionalProperties: false,
1866
+ properties: {
1867
+ lens: {
1868
+ type: 'string',
1869
+ enum: ['layout', 'geometry', 'final'],
1870
+ },
1871
+ status: {
1872
+ type: 'string',
1873
+ enum: ['pass', 'partial', 'fail', 'not-applicable'],
1874
+ },
1875
+ },
1876
+ required: ['lens', 'status'],
1877
+ },
1878
+ },
1879
+ visualResults: {
1880
+ type: 'array',
1881
+ items: {
1882
+ type: 'object',
1883
+ additionalProperties: false,
1884
+ properties: {
1885
+ feature: { type: 'string' },
1886
+ criterion: { type: 'string' },
1887
+ status: {
1888
+ type: 'string',
1889
+ enum: ['pass', 'partial', 'fail', 'not-applicable'],
1890
+ },
1891
+ evidenceRefs: {
1892
+ type: 'array',
1893
+ items: { type: 'string' },
1894
+ },
1895
+ observation: { type: 'string' },
1896
+ },
1897
+ required: ['feature', 'criterion', 'status', 'observation'],
1898
+ },
1899
+ },
1900
+ previousReview: {
1901
+ type: 'object',
1902
+ additionalProperties: false,
1903
+ properties: {
1904
+ path: { type: 'string' },
1905
+ reviewSha256: SCENE_HASH_SCHEMA,
1906
+ },
1907
+ required: ['path', 'reviewSha256'],
1908
+ },
1909
+ correction: {
1910
+ type: 'object',
1911
+ additionalProperties: false,
1912
+ properties: {
1913
+ path: { type: 'string' },
1914
+ correctionSha256: SCENE_HASH_SCHEMA,
1915
+ },
1916
+ required: ['path', 'correctionSha256'],
1917
+ },
1918
+ openDefectTags: { type: 'array', items: { type: 'string' } },
1919
+ stopReason: {
1920
+ type: 'string',
1921
+ enum: [
1922
+ 'continue-refining',
1923
+ 'round-limit',
1924
+ 'repeated-defect',
1925
+ 'oscillation',
1926
+ 'plateau',
1927
+ 'missing-input',
1928
+ 'representation-gap',
1929
+ ],
1930
+ },
1931
+ },
1932
+ required: ['round', 'captures', 'lensResults'],
1933
+ },
1934
+ },
1935
+ {
1936
+ name: 'scene_save_review',
1937
+ description: 'Validate and immutably persist one complete iwsdk.scene-review.v1 record against the active scene document, capability hash, required review contract, persisted PNG evidence, and adjacent immutable correction lineage. Round 0 is initial; every higher round must link by exact path and SHA-256 to round-1. Exact repeats are idempotent. Waivers are refused until a trusted user-approval artifact exists.',
1938
+ inputSchema: {
1939
+ type: 'object',
1940
+ additionalProperties: false,
1941
+ properties: { review: SCENE_REVIEW_INPUT_SCHEMA },
1942
+ required: ['review'],
1943
+ },
1944
+ },
1945
+ {
1946
+ name: 'scene_list_reviews',
1947
+ description: 'List validated review record summaries for the active scene. The current flag requires matching document, runtime, capability, schema, and persisted evidence integrity.',
1948
+ inputSchema: {
1949
+ type: 'object',
1950
+ additionalProperties: false,
1951
+ properties: {},
1952
+ },
1953
+ },
1954
+ {
1955
+ name: 'scene_get_review',
1956
+ description: 'Get one complete immutable review record for the active scene by an exact workspace-relative path returned by scene_list_reviews.',
1957
+ inputSchema: {
1958
+ type: 'object',
1959
+ additionalProperties: false,
1960
+ properties: {
1961
+ path: {
1962
+ type: 'string',
1963
+ description: 'Exact workspace-relative review path returned by scene_list_reviews.',
1964
+ },
1965
+ },
1966
+ required: ['path'],
1967
+ },
1968
+ },
1969
+ {
1970
+ name: 'scene_runtime_preflight',
1971
+ description: 'Before formal review, reload and compare the selected editor scene with the live app runtime, then persist a content-addressed receipt required by scene_begin_review. Separately reports scene binding, camera/framing presentation, warnings, structural counts, and host-browser frame diagnostics. The default response is compact; host measurements are never presented as calibrated Quest performance.',
1972
+ inputSchema: {
1973
+ type: 'object',
1974
+ additionalProperties: false,
1975
+ properties: {
1976
+ warmupFrames: {
1977
+ type: 'integer',
1978
+ minimum: 0,
1979
+ maximum: 600,
1980
+ description: 'Frames excluded before measurement. Defaults to 10.',
1981
+ },
1982
+ sampleFrames: {
1983
+ type: 'integer',
1984
+ minimum: 1,
1985
+ maximum: 600,
1986
+ description: 'Measured host-browser frames. Defaults to 60.',
1987
+ },
1988
+ detail: {
1989
+ type: 'string',
1990
+ enum: ['compact', 'full'],
1991
+ description: 'Compact response by default; full returns the complete persisted report inline.',
1992
+ },
1993
+ },
1994
+ },
1995
+ },
1996
+ {
1997
+ name: 'scene_publish',
1998
+ description: 'Publish the active saved scene against one exact current immutable passing review. Reloads the live app runtime, proves document/runtime hash parity, representative node content, resources, transforms and components, a nonblank canvas, and a clean scene/shader/WebGL/material log window, then persists an immutable runtime-proof report. Refuses dirty, stale, mismatched, waived, or unproven scenes.',
1999
+ inputSchema: {
2000
+ type: 'object',
2001
+ additionalProperties: false,
2002
+ properties: {
2003
+ reviewPath: {
2004
+ type: 'string',
2005
+ description: 'Exact current immutable review path returned by scene_list_reviews.',
2006
+ },
2007
+ representativeNodeIds: {
2008
+ type: 'array',
2009
+ items: { type: 'string' },
2010
+ description: 'Optional additional authored node ids whose live content, resources, transforms, and components must match. Required review feature nodeRefs are always included.',
2011
+ },
2012
+ detail: {
2013
+ type: 'string',
2014
+ enum: ['compact', 'full'],
2015
+ description: 'Compact returns status, hashes, failed checks, warnings, and artifact path. Full also returns the complete persisted proof inline.',
2016
+ },
2017
+ },
2018
+ required: ['reviewPath'],
2019
+ },
2020
+ },
2021
+ {
2022
+ name: 'scene_get_render_stats',
2023
+ description: 'Get measured scene structure (world bounds, object/node/mesh/geometry/material counts and visible node ids) plus raw renderer calls, triangles, points, lines, textures, programs, shadow casters, frame-time samples, and renderer environment. Returns available:false when no measurement bridge is installed.',
2024
+ inputSchema: {
2025
+ type: 'object',
2026
+ properties: {},
2027
+ },
2028
+ },
2029
+ // =============================================================================
2030
+ // Framework-Specific Tools (IWSDK or any framework with FRAMEWORK_MCP_RUNTIME)
2031
+ // =============================================================================
2032
+ {
2033
+ name: 'scene_get_runtime_hierarchy',
2034
+ description: 'Get the live Three.js Object3D hierarchy from the app runtime, including names, UUIDs, object types, native scene node ids, asset ids, primitive descriptors, and ECS entity indices. Use scene_get_hierarchy for the native scene document in the editor.',
2035
+ inputSchema: {
2036
+ type: 'object',
2037
+ properties: {
2038
+ parentId: {
2039
+ type: 'string',
2040
+ description: 'Object3D UUID to start from. Defaults to the runtime scene root if omitted.',
2041
+ },
2042
+ maxDepth: {
2043
+ type: 'number',
2044
+ description: 'Maximum depth to traverse (default: 5). Use to limit context size.',
2045
+ },
2046
+ },
2047
+ },
2048
+ },
2049
+ {
2050
+ name: 'scene_get_object_transform',
2051
+ description: 'Get local and global transforms of an Object3D by Object3D UUID or native scene node id. Includes positionRelativeToXROrigin which can be used directly with xr_look_at tool. Requires IWSDK or a framework that provides FRAMEWORK_MCP_RUNTIME.',
2052
+ inputSchema: {
2053
+ type: 'object',
2054
+ properties: {
2055
+ uuid: {
2056
+ type: 'string',
2057
+ description: 'UUID of the Object3D (get this from scene_get_runtime_hierarchy, not the native editor scene hierarchy)',
2058
+ },
2059
+ nodeId: {
2060
+ type: 'string',
2061
+ description: 'Native scene node id (get this from scene_get_hierarchy when using the native scene editor)',
2062
+ },
2063
+ },
2064
+ },
2065
+ },
2066
+ // =============================================================================
2067
+ // ECS Debugging (IWSDK — requires FRAMEWORK_MCP_RUNTIME)
2068
+ // =============================================================================
2069
+ {
2070
+ name: 'ecs_pause',
2071
+ description: 'Pause ECS system updates. The render loop continues (XR session stays alive, screenshots still work) but no systems tick. Use ecs_step to advance individual frames while paused. Requires FRAMEWORK_MCP_RUNTIME.',
2072
+ inputSchema: {
2073
+ type: 'object',
2074
+ properties: {},
2075
+ },
2076
+ },
2077
+ {
2078
+ name: 'ecs_resume',
2079
+ description: 'Resume ECS system updates after pausing. The first frame after resume uses a capped delta to avoid physics explosions. Requires FRAMEWORK_MCP_RUNTIME.',
2080
+ inputSchema: {
2081
+ type: 'object',
2082
+ properties: {},
2083
+ },
2084
+ },
2085
+ {
2086
+ name: 'ecs_step',
2087
+ description: 'Advance N ECS frames with a fixed timestep while paused. Must call ecs_pause first. Useful for frame-by-frame debugging. Requires FRAMEWORK_MCP_RUNTIME.',
2088
+ inputSchema: {
2089
+ type: 'object',
2090
+ properties: {
2091
+ count: {
2092
+ type: 'number',
2093
+ description: 'Number of frames to advance (1-120, default: 1)',
2094
+ },
2095
+ delta: {
2096
+ type: 'number',
2097
+ description: 'Fixed timestep in seconds for each frame (default: 1/72 ≈ 0.0139, matching Quest refresh rate)',
2098
+ },
2099
+ },
2100
+ },
2101
+ },
2102
+ {
2103
+ name: 'ecs_query_entity',
2104
+ description: 'Get all component data for an entity. Use entityIndex from ecs_find_entities. Returns serialized component values including vectors, entity refs, and Object3D references. Requires FRAMEWORK_MCP_RUNTIME.',
2105
+ inputSchema: {
2106
+ type: 'object',
2107
+ properties: {
2108
+ entityIndex: {
2109
+ type: 'number',
2110
+ description: 'Entity index (get this from ecs_find_entities)',
2111
+ },
2112
+ components: {
2113
+ type: 'array',
2114
+ items: { type: 'string' },
2115
+ description: 'Optional list of component IDs to include. If omitted, returns all components on the entity.',
2116
+ },
2117
+ },
2118
+ required: ['entityIndex'],
2119
+ },
2120
+ },
2121
+ {
2122
+ name: 'ecs_find_entities',
2123
+ description: 'Find entities by component composition and/or name. Returns entity indices and component lists. Use the returned entityIndex values with ecs_query_entity for detailed inspection. Requires FRAMEWORK_MCP_RUNTIME.',
2124
+ inputSchema: {
2125
+ type: 'object',
2126
+ properties: {
2127
+ withComponents: {
2128
+ type: 'array',
2129
+ items: { type: 'string' },
2130
+ description: 'Component IDs that entities must have (AND logic)',
2131
+ },
2132
+ withoutComponents: {
2133
+ type: 'array',
2134
+ items: { type: 'string' },
2135
+ description: 'Component IDs that entities must NOT have',
2136
+ },
2137
+ namePattern: {
2138
+ type: 'string',
2139
+ description: 'Regex pattern to match against entity Object3D name (case-insensitive)',
2140
+ },
2141
+ limit: {
2142
+ type: 'number',
2143
+ description: 'Maximum number of results (1-50, default: 50)',
2144
+ },
2145
+ },
2146
+ },
2147
+ },
2148
+ {
2149
+ name: 'ecs_list_systems',
2150
+ description: 'List all registered ECS systems with name, priority, pause state, config keys, and query entity counts. Requires FRAMEWORK_MCP_RUNTIME.',
2151
+ inputSchema: {
2152
+ type: 'object',
2153
+ properties: {},
2154
+ },
2155
+ },
2156
+ {
2157
+ name: 'ecs_list_components',
2158
+ description: 'List all registered ECS components with their field schemas (type, default). Requires FRAMEWORK_MCP_RUNTIME.',
2159
+ inputSchema: {
2160
+ type: 'object',
2161
+ properties: {},
2162
+ },
2163
+ },
2164
+ {
2165
+ name: 'ecs_toggle_system',
2166
+ description: 'Pause or resume a specific ECS system by name. Use ecs_list_systems to discover system names. Requires FRAMEWORK_MCP_RUNTIME.',
2167
+ inputSchema: {
2168
+ type: 'object',
2169
+ properties: {
2170
+ name: {
2171
+ type: 'string',
2172
+ description: "System class name (e.g. 'OrbSystem', 'RobotSystem')",
2173
+ },
2174
+ paused: {
2175
+ type: 'boolean',
2176
+ description: 'Set to true to pause, false to resume. If omitted, toggles current state.',
2177
+ },
2178
+ },
2179
+ required: ['name'],
2180
+ },
2181
+ },
2182
+ {
2183
+ name: 'ecs_set_component',
2184
+ description: 'Set a component field value on an entity. Scalars use setValue (with validation), vectors accept arrays. Use ecs_query_entity to inspect current values first. Requires FRAMEWORK_MCP_RUNTIME.',
2185
+ inputSchema: {
2186
+ type: 'object',
2187
+ properties: {
2188
+ entityIndex: {
2189
+ type: 'number',
2190
+ description: 'Entity index (from ecs_find_entities)',
2191
+ },
2192
+ componentId: {
2193
+ type: 'string',
2194
+ description: "Component ID (e.g. 'Orb', 'RobotMood', 'Transform')",
2195
+ },
2196
+ field: {
2197
+ type: 'string',
2198
+ description: "Field name within the component (e.g. 'orbitSpeed', 'mood')",
2199
+ },
2200
+ value: {
2201
+ description: 'New value. Scalars: number/string/boolean. Vectors: array of numbers (e.g. [1,2,3] for Vec3).',
2202
+ },
2203
+ },
2204
+ required: ['entityIndex', 'componentId', 'field', 'value'],
2205
+ },
2206
+ },
2207
+ {
2208
+ name: 'ecs_snapshot',
2209
+ description: 'Capture a snapshot of all ECS entity/component state. Stores up to 2 snapshots. Use with ecs_diff to compare. Requires FRAMEWORK_MCP_RUNTIME.',
2210
+ inputSchema: {
2211
+ type: 'object',
2212
+ properties: {
2213
+ label: {
2214
+ type: 'string',
2215
+ description: 'Label for this snapshot (default: auto-generated). Use to reference in ecs_diff.',
2216
+ },
2217
+ },
2218
+ },
2219
+ },
2220
+ {
2221
+ name: 'ecs_diff',
2222
+ description: 'Compare two ECS snapshots. Shows added/removed/changed entities and field-level diffs. Requires FRAMEWORK_MCP_RUNTIME.',
2223
+ inputSchema: {
2224
+ type: 'object',
2225
+ properties: {
2226
+ from: {
2227
+ type: 'string',
2228
+ description: "Label of the 'before' snapshot",
2229
+ },
2230
+ to: {
2231
+ type: 'string',
2232
+ description: "Label of the 'after' snapshot",
2233
+ },
2234
+ },
2235
+ required: ['from', 'to'],
2236
+ },
2237
+ },
2238
+ ];
2239
+ const SCENE_MCP_TOOL_NAMES = [
2240
+ 'scene_open',
2241
+ 'scene_render_file',
2242
+ 'scene_flatten_file',
2243
+ 'scene_get_state',
2244
+ 'scene_get_capabilities',
2245
+ 'scene_screenshot',
2246
+ 'scene_select',
2247
+ 'scene_set_camera',
2248
+ 'scene_set_preview_visibility',
2249
+ 'scene_measure_image_regions',
2250
+ ];
2251
+ const APP_RUNTIME_SCENE_MCP_TOOL_NAMES = [
2252
+ 'scene_get_render_stats',
2253
+ 'scene_get_runtime_hierarchy',
2254
+ 'scene_get_object_transform',
2255
+ ];
2256
+ const PUBLIC_SCENE_MCP_TOOL_NAME_SET = new Set([
2257
+ ...SCENE_MCP_TOOL_NAMES,
2258
+ ...APP_RUNTIME_SCENE_MCP_TOOL_NAMES,
2259
+ ]);
2260
+ const REMOVED_WORKSPACE_MCP_TOOL_NAME_SET = new Set([
2261
+ 'workspace_get_state',
2262
+ 'workspace_set_view',
2263
+ 'workspace_open_scene',
2264
+ ]);
2265
+ const EXPECTED_TAB_SCHEMA = {
2266
+ type: 'object',
2267
+ additionalProperties: false,
2268
+ description: 'Optional stale-state precondition. Pass the _tab object from an earlier result; the call fails if that browser tab has reloaded or changed.',
2269
+ properties: {
2270
+ id: { type: 'string', description: 'Browser tab id from result._tab.id' },
2271
+ generation: {
2272
+ type: 'number',
2273
+ minimum: 1,
2274
+ description: 'Browser tab generation from result._tab.generation',
2275
+ },
2276
+ },
2277
+ required: ['id', 'generation'],
2278
+ };
2279
+ function withExpectedTabPrecondition(schema) {
2280
+ return {
2281
+ ...schema,
2282
+ properties: {
2283
+ ...(schema.properties ?? {}),
2284
+ expectedTab: EXPECTED_TAB_SCHEMA,
2285
+ },
2286
+ };
2287
+ }
2288
+ const RUNTIME_MCP_TOOLS = ALL_RUNTIME_MCP_TOOLS.filter((tool) => (!tool.name.startsWith('scene_') ||
2289
+ PUBLIC_SCENE_MCP_TOOL_NAME_SET.has(tool.name)) &&
2290
+ !REMOVED_WORKSPACE_MCP_TOOL_NAME_SET.has(tool.name)).map((tool) => ({
2291
+ ...tool,
2292
+ inputSchema: withExpectedTabPrecondition(tool.inputSchema),
2293
+ }));
2294
+ const RUNTIME_TOOL_TO_METHOD = {
2295
+ xr_get_session_status: 'get_session_status',
2296
+ xr_accept_session: 'accept_session',
2297
+ xr_end_session: 'end_session',
2298
+ xr_get_transform: 'get_transform',
2299
+ xr_set_transform: 'set_transform',
2300
+ xr_look_at: 'look_at',
2301
+ xr_animate_to: 'animate_to',
2302
+ xr_set_input_mode: 'set_input_mode',
2303
+ xr_set_connected: 'set_connected',
2304
+ xr_get_select_value: 'get_select_value',
2305
+ xr_set_select_value: 'set_select_value',
2306
+ xr_select: 'select',
809
2307
  xr_get_gamepad_state: 'get_gamepad_state',
810
2308
  xr_set_gamepad_state: 'set_gamepad_state',
811
2309
  xr_get_device_state: 'get_device_state',
@@ -813,10 +2311,11 @@ const RUNTIME_TOOL_TO_METHOD = {
813
2311
  browser_screenshot: 'screenshot',
814
2312
  browser_get_console_logs: 'get_console_logs',
815
2313
  browser_reload_page: 'reload_page',
816
- scene_get_hierarchy: 'get_scene_hierarchy',
2314
+ scene_get_render_stats: 'get_render_stats',
2315
+ scene_get_runtime_hierarchy: 'get_scene_hierarchy',
817
2316
  scene_get_object_transform: 'get_object_transform',
818
2317
  };
819
- const RUNTIME_CLI_PATHS = {
2318
+ const ALL_RUNTIME_CLI_PATHS = {
820
2319
  xr_get_session_status: ['xr', 'status'],
821
2320
  xr_accept_session: ['xr', 'enter'],
822
2321
  xr_end_session: ['xr', 'exit'],
@@ -836,7 +2335,59 @@ const RUNTIME_CLI_PATHS = {
836
2335
  xr_set_device_state: ['xr', 'set-device-state'],
837
2336
  browser_get_console_logs: ['browser', 'logs'],
838
2337
  browser_reload_page: ['browser', 'reload'],
2338
+ workspace_get_state: ['workspace', 'state'],
2339
+ workspace_set_view: ['workspace', 'set-view'],
2340
+ workspace_open_scene: ['workspace', 'open-scene'],
2341
+ scene_list_files: ['scene', 'files'],
2342
+ scene_open: ['scene', 'open'],
2343
+ scene_render_file: ['scene', 'render-file'],
2344
+ scene_flatten_file: ['scene', 'flatten'],
2345
+ scene_get_state: ['scene', 'state'],
2346
+ scene_create: ['scene', 'create'],
2347
+ scene_get_capabilities: ['scene', 'capabilities'],
2348
+ scene_set_preview_visibility: ['scene', 'set-preview-visibility'],
2349
+ scene_list_assets: ['scene', 'assets'],
2350
+ scene_search_project_assets: ['scene', 'search-project-assets'],
2351
+ scene_import_project_asset: ['scene', 'import-project-asset'],
2352
+ scene_list_component_schemas: ['scene', 'component-schemas'],
2353
+ scene_get_document: ['scene', 'document'],
839
2354
  scene_get_hierarchy: ['scene', 'hierarchy'],
2355
+ scene_get_selection: ['scene', 'selection'],
2356
+ scene_select: ['scene', 'select'],
2357
+ scene_add_node: ['scene', 'add-node'],
2358
+ scene_remove_node: ['scene', 'remove-node'],
2359
+ scene_duplicate_node: ['scene', 'duplicate-node'],
2360
+ scene_set_transform: ['scene', 'set-transform'],
2361
+ scene_set_framing_role: ['scene', 'set-framing-role'],
2362
+ scene_apply_patch: ['scene', 'apply-patch'],
2363
+ scene_apply_transaction: ['scene', 'apply-transaction'],
2364
+ scene_replace_document: ['scene', 'replace-document'],
2365
+ scene_look_at: ['scene', 'look-at'],
2366
+ scene_validate: ['scene', 'validate'],
2367
+ scene_save: ['scene', 'save'],
2368
+ scene_undo: ['scene', 'undo'],
2369
+ scene_redo: ['scene', 'redo'],
2370
+ scene_get_logs: ['scene', 'logs'],
2371
+ scene_set_camera: ['scene', 'set-camera'],
2372
+ scene_screenshot: ['scene', 'screenshot'],
2373
+ ui_list_assets: ['ui', 'assets'],
2374
+ ui_render_preview: ['ui', 'render-preview'],
2375
+ scene_compare_screenshots: ['scene', 'compare-screenshots'],
2376
+ scene_begin_review: ['scene', 'begin-review'],
2377
+ scene_set_review_lens: ['scene', 'set-review-lens'],
2378
+ scene_capture_review: ['scene', 'capture-review'],
2379
+ scene_measure_image_regions: ['scene', 'measure-image-regions'],
2380
+ scene_persist_review_capture: ['scene', 'persist-review-capture'],
2381
+ scene_capture_review_set: ['scene', 'capture-review-set'],
2382
+ scene_record_object_inspection: ['scene', 'record-object-inspection'],
2383
+ scene_finalize_review: ['scene', 'finalize-review'],
2384
+ scene_save_review: ['scene', 'save-review'],
2385
+ scene_list_reviews: ['scene', 'reviews'],
2386
+ scene_get_review: ['scene', 'review'],
2387
+ scene_runtime_preflight: ['scene', 'runtime-preflight'],
2388
+ scene_publish: ['scene', 'publish'],
2389
+ scene_get_render_stats: ['scene', 'render-stats'],
2390
+ scene_get_runtime_hierarchy: ['scene', 'runtime-hierarchy'],
840
2391
  scene_get_object_transform: ['scene', 'transform'],
841
2392
  ecs_pause: ['ecs', 'pause'],
842
2393
  ecs_resume: ['ecs', 'resume'],
@@ -850,8 +2401,42 @@ const RUNTIME_CLI_PATHS = {
850
2401
  ecs_snapshot: ['ecs', 'snapshot'],
851
2402
  ecs_diff: ['ecs', 'diff'],
852
2403
  };
2404
+ const RUNTIME_MCP_TOOL_NAME_SET = new Set(RUNTIME_MCP_TOOLS.map((tool) => tool.name));
2405
+ const RUNTIME_CLI_PATHS = Object.fromEntries(Object.entries(ALL_RUNTIME_CLI_PATHS).filter(([name]) => RUNTIME_MCP_TOOL_NAME_SET.has(name)));
2406
+ const SCENE_EDITOR_MCP_TOOL_NAMES = [
2407
+ 'scene_get_capabilities',
2408
+ 'scene_get_state',
2409
+ 'scene_select',
2410
+ 'scene_set_camera',
2411
+ 'scene_screenshot',
2412
+ 'scene_set_preview_visibility',
2413
+ 'scene_measure_image_regions',
2414
+ 'ui_list_assets',
2415
+ 'ui_render_preview',
2416
+ ];
2417
+ const SCENE_FILE_MCP_TOOL_NAMES = [
2418
+ 'scene_open',
2419
+ 'scene_render_file',
2420
+ 'scene_flatten_file',
2421
+ ];
2422
+ const PROJECT_ASSET_MCP_TOOL_NAMES = [];
2423
+ const REVIEW_EVIDENCE_MCP_TOOL_NAMES = [];
2424
+ const WORKSPACE_MCP_TOOL_NAMES = [];
2425
+ const EDITOR_TARGET_MCP_TOOL_NAME_SET = new Set([
2426
+ ...SCENE_EDITOR_MCP_TOOL_NAMES,
2427
+ ...SCENE_FILE_MCP_TOOL_NAMES,
2428
+ ...PROJECT_ASSET_MCP_TOOL_NAMES,
2429
+ ...REVIEW_EVIDENCE_MCP_TOOL_NAMES,
2430
+ ...WORKSPACE_MCP_TOOL_NAMES,
2431
+ ]);
2432
+ const APP_TARGET_MCP_TOOL_NAME_SET = new Set(['browser_screenshot']);
853
2433
  const RUNTIME_OPERATIONS = RUNTIME_MCP_TOOLS.map((tool) => {
854
2434
  const cliPath = RUNTIME_CLI_PATHS[tool.name];
2435
+ const target = EDITOR_TARGET_MCP_TOOL_NAME_SET.has(tool.name)
2436
+ ? { role: 'editor' }
2437
+ : APP_TARGET_MCP_TOOL_NAME_SET.has(tool.name)
2438
+ ? { role: 'app' }
2439
+ : undefined;
855
2440
  return {
856
2441
  id: cliPath ? cliPath.join('.') : tool.name,
857
2442
  domain: cliPath?.[0] ?? 'misc',
@@ -859,6 +2444,7 @@ const RUNTIME_OPERATIONS = RUNTIME_MCP_TOOLS.map((tool) => {
859
2444
  cliPath: cliPath ?? ['misc', tool.name],
860
2445
  mcpName: tool.name,
861
2446
  wsMethod: RUNTIME_TOOL_TO_METHOD[tool.name] ?? tool.name,
2447
+ ...(target ? { target } : {}),
862
2448
  description: tool.description,
863
2449
  inputSchema: tool.inputSchema,
864
2450
  };
@@ -869,6 +2455,48 @@ function getRuntimeOperationByToolName(toolName) {
869
2455
  function getRuntimeOperationByCliPath(domain, action) {
870
2456
  return RUNTIME_OPERATIONS.find((operation) => operation.domain === domain && operation.action === action);
871
2457
  }
2458
+ function resolveRuntimeOperationRequest(operation, params) {
2459
+ const required = operation.inputSchema.required ?? [];
2460
+ if (required.length > 0) {
2461
+ if (!isRecord(params)) {
2462
+ throw new Error(`${operation.mcpName} requires an object with parameter${required.length === 1 ? '' : 's'}: ${required.join(', ')}`);
2463
+ }
2464
+ const missing = required.filter((name) => !Object.prototype.hasOwnProperty.call(params, name));
2465
+ if (missing.length > 0) {
2466
+ throw new Error(`${operation.mcpName} requires parameter${missing.length === 1 ? '' : 's'}: ${missing.join(', ')}`);
2467
+ }
2468
+ }
2469
+ const paramsRecord = isRecord(params) ? params : null;
2470
+ const expectedTab = paramsRecord?.expectedTab;
2471
+ if (expectedTab !== undefined &&
2472
+ (!isRecord(expectedTab) ||
2473
+ typeof expectedTab.id !== 'string' ||
2474
+ !Number.isInteger(expectedTab.generation) ||
2475
+ expectedTab.generation < 1)) {
2476
+ throw new Error(`${operation.mcpName}.expectedTab requires the { id, generation } object returned as result._tab`);
2477
+ }
2478
+ if (operation.mcpName === 'browser_screenshot' &&
2479
+ paramsRecord != null &&
2480
+ Object.keys(paramsRecord).some((key) => key !== 'expectedTab')) {
2481
+ throw new Error('browser_screenshot does not accept parameters; it always captures the application runtime');
2482
+ }
2483
+ const commandParams = paramsRecord == null
2484
+ ? params
2485
+ : Object.fromEntries(Object.entries(paramsRecord).filter(([key]) => key !== 'expectedTab'));
2486
+ const target = isRecord(expectedTab) &&
2487
+ typeof expectedTab.id === 'string' &&
2488
+ typeof expectedTab.generation === 'number'
2489
+ ? {
2490
+ ...(operation.target ?? {}),
2491
+ pageId: expectedTab.id,
2492
+ tabGeneration: expectedTab.generation,
2493
+ }
2494
+ : operation.target;
2495
+ return { params: commandParams, target };
2496
+ }
2497
+ function isRecord(value) {
2498
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
2499
+ }
872
2500
 
873
- export { INTERNAL_BROWSER_PROBE_METHOD, IWSDK_PROJECT_STATE_DIR, IWSDK_RUNTIME_BROWSER_READY_SCHEMA_VERSION, IWSDK_RUNTIME_LAUNCH_PATH, IWSDK_RUNTIME_LOGS_DIR, IWSDK_RUNTIME_SESSION_PATH, IWSDK_RUNTIME_STATE_DIR, IWSDK_RUNTIME_STATE_SCHEMA_VERSION, MCP_CONFIG_TARGETS, RUNTIME_CLI_PATHS, RUNTIME_MCP_TOOLS, RUNTIME_OPERATIONS, RUNTIME_TOOL_TO_METHOD, SUPPORTED_AI_TOOLS, getRuntimeOperationByCliPath, getRuntimeOperationByToolName, hasRuntimeBrowserCommandReadyContract, isRuntimeBrowserCommandReady };
2501
+ export { APP_RUNTIME_SCENE_MCP_TOOL_NAMES, INTERNAL_BROWSER_PROBE_METHOD, IWSDK_PROJECT_STATE_DIR, IWSDK_RUNTIME_BROWSER_READY_SCHEMA_VERSION, IWSDK_RUNTIME_LAUNCH_PATH, IWSDK_RUNTIME_LOGS_DIR, IWSDK_RUNTIME_SESSION_PATH, IWSDK_RUNTIME_STATE_DIR, IWSDK_RUNTIME_STATE_SCHEMA_VERSION, MCP_CONFIG_TARGETS, PROJECT_ASSET_MCP_TOOL_NAMES, REVIEW_EVIDENCE_MCP_TOOL_NAMES, RUNTIME_CLI_PATHS, RUNTIME_MCP_TOOLS, RUNTIME_OPERATIONS, RUNTIME_TOOL_TO_METHOD, SCENE_EDITOR_MCP_TOOL_NAMES, SCENE_FILE_MCP_TOOL_NAMES, SCENE_MCP_TOOL_NAMES, SUPPORTED_AI_TOOLS, WORKSPACE_MCP_TOOL_NAMES, getRuntimeOperationByCliPath, getRuntimeOperationByToolName, hasRuntimeBrowserCommandReadyContract, isRuntimeBrowserCommandReady, resolveRuntimeOperationRequest };
874
2502
  //# sourceMappingURL=contract.js.map