rbxstudio-mcp 1.14.3 → 2.1.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.
Files changed (8) hide show
  1. package/dist/index.js +102 -400
  2. package/dist/index.js.map +1 -1
  3. package/dist/tools/index.d.ts +37 -0
  4. package/dist/tools/index.d.ts.map +1 -1
  5. package/dist/tools/index.js +93 -0
  6. package/dist/tools/index.js.map +1 -1
  7. package/package.json +1 -1
  8. package/studio-plugin/plugin.luau +512 -2
package/dist/index.js CHANGED
@@ -27,7 +27,7 @@ class RobloxStudioMCPServer {
27
27
  constructor() {
28
28
  this.server = new Server({
29
29
  name: 'rbxstudio-mcp',
30
- version: '1.14.0',
30
+ version: '2.0.0',
31
31
  }, {
32
32
  capabilities: {
33
33
  tools: {},
@@ -41,41 +41,6 @@ class RobloxStudioMCPServer {
41
41
  this.server.setRequestHandler(ListToolsRequestSchema, async () => {
42
42
  return {
43
43
  tools: [
44
- // Instance Hierarchy Tools (NOT local filesystem - these operate on Roblox Studio instances)
45
- {
46
- name: 'get_file_tree',
47
- description: 'Get the Roblox instance hierarchy tree from Roblox Studio. Returns game instances (Parts, Scripts, Models, Folders, etc.) as a tree structure. NOTE: This operates on Roblox Studio instances, NOT local filesystem files.',
48
- inputSchema: {
49
- type: 'object',
50
- properties: {
51
- path: {
52
- type: 'string',
53
- description: 'Roblox instance path to start from using dot notation (e.g., "game.Workspace", "game.ServerScriptService"). Defaults to game root if empty.',
54
- default: ''
55
- }
56
- }
57
- }
58
- },
59
- {
60
- name: 'search_files',
61
- description: 'Search for Roblox instances by name, class type, or script content. NOTE: This searches Roblox Studio instances, NOT local filesystem files.',
62
- inputSchema: {
63
- type: 'object',
64
- properties: {
65
- query: {
66
- type: 'string',
67
- description: 'Search query - instance name, class type (e.g., "Script", "Part"), or Lua code pattern'
68
- },
69
- searchType: {
70
- type: 'string',
71
- enum: ['name', 'type', 'content'],
72
- description: 'Type of search: "name" for instance names, "type" for class names, "content" for script source code',
73
- default: 'name'
74
- }
75
- },
76
- required: ['query']
77
- }
78
- },
79
44
  // Studio Context Tools
80
45
  {
81
46
  name: 'get_place_info',
@@ -98,30 +63,6 @@ class RobloxStudioMCPServer {
98
63
  }
99
64
  }
100
65
  },
101
- {
102
- name: 'search_objects',
103
- description: 'Find instances by name, class, or properties',
104
- inputSchema: {
105
- type: 'object',
106
- properties: {
107
- query: {
108
- type: 'string',
109
- description: 'Search query'
110
- },
111
- searchType: {
112
- type: 'string',
113
- enum: ['name', 'class', 'property'],
114
- description: 'Type of search to perform',
115
- default: 'name'
116
- },
117
- propertyName: {
118
- type: 'string',
119
- description: 'Property name when searchType is "property"'
120
- }
121
- },
122
- required: ['query']
123
- }
124
- },
125
66
  // Property & Instance Tools
126
67
  {
127
68
  name: 'get_instance_properties',
@@ -137,38 +78,6 @@ class RobloxStudioMCPServer {
137
78
  required: ['instancePath']
138
79
  }
139
80
  },
140
- {
141
- name: 'get_instance_children',
142
- description: 'Get child instances and their class types from a Roblox parent instance',
143
- inputSchema: {
144
- type: 'object',
145
- properties: {
146
- instancePath: {
147
- type: 'string',
148
- description: 'Roblox instance path using dot notation (e.g., "game.Workspace", "game.ServerScriptService")'
149
- }
150
- },
151
- required: ['instancePath']
152
- }
153
- },
154
- {
155
- name: 'search_by_property',
156
- description: 'Find objects with specific property values',
157
- inputSchema: {
158
- type: 'object',
159
- properties: {
160
- propertyName: {
161
- type: 'string',
162
- description: 'Name of the property to search'
163
- },
164
- propertyValue: {
165
- type: 'string',
166
- description: 'Value to search for'
167
- }
168
- },
169
- required: ['propertyName', 'propertyValue']
170
- }
171
- },
172
81
  {
173
82
  name: 'get_class_info',
174
83
  description: 'Get available properties/methods for Roblox classes',
@@ -294,100 +203,6 @@ class RobloxStudioMCPServer {
294
203
  required: ['className', 'parent']
295
204
  }
296
205
  },
297
- {
298
- name: 'create_object_with_properties',
299
- description: 'Create a new Roblox object instance with initial properties',
300
- inputSchema: {
301
- type: 'object',
302
- properties: {
303
- className: {
304
- type: 'string',
305
- description: 'Roblox class name (e.g., "Part", "Script", "Folder")'
306
- },
307
- parent: {
308
- type: 'string',
309
- description: 'Path to the parent instance (e.g., "game.Workspace")'
310
- },
311
- name: {
312
- type: 'string',
313
- description: 'Optional name for the new object'
314
- },
315
- properties: {
316
- type: 'object',
317
- description: 'Properties to set on creation'
318
- }
319
- },
320
- required: ['className', 'parent']
321
- }
322
- },
323
- {
324
- name: 'mass_create_objects',
325
- description: 'Create multiple objects at once (basic, without properties)',
326
- inputSchema: {
327
- type: 'object',
328
- properties: {
329
- objects: {
330
- type: 'array',
331
- items: {
332
- type: 'object',
333
- properties: {
334
- className: {
335
- type: 'string',
336
- description: 'Roblox class name'
337
- },
338
- parent: {
339
- type: 'string',
340
- description: 'Path to the parent instance'
341
- },
342
- name: {
343
- type: 'string',
344
- description: 'Optional name for the object'
345
- }
346
- },
347
- required: ['className', 'parent']
348
- },
349
- description: 'Array of objects to create'
350
- }
351
- },
352
- required: ['objects']
353
- }
354
- },
355
- {
356
- name: 'mass_create_objects_with_properties',
357
- description: 'Create multiple objects at once with initial properties',
358
- inputSchema: {
359
- type: 'object',
360
- properties: {
361
- objects: {
362
- type: 'array',
363
- items: {
364
- type: 'object',
365
- properties: {
366
- className: {
367
- type: 'string',
368
- description: 'Roblox class name'
369
- },
370
- parent: {
371
- type: 'string',
372
- description: 'Path to the parent instance'
373
- },
374
- name: {
375
- type: 'string',
376
- description: 'Optional name for the object'
377
- },
378
- properties: {
379
- type: 'object',
380
- description: 'Properties to set on creation'
381
- }
382
- },
383
- required: ['className', 'parent']
384
- },
385
- description: 'Array of objects to create with properties'
386
- }
387
- },
388
- required: ['objects']
389
- }
390
- },
391
206
  {
392
207
  name: 'delete_object',
393
208
  description: 'Delete a Roblox object instance',
@@ -402,192 +217,6 @@ class RobloxStudioMCPServer {
402
217
  required: ['instancePath']
403
218
  }
404
219
  },
405
- // Smart Duplication Tools
406
- {
407
- name: 'smart_duplicate',
408
- description: 'Smart duplication with automatic naming, positioning, and property variations',
409
- inputSchema: {
410
- type: 'object',
411
- properties: {
412
- instancePath: {
413
- type: 'string',
414
- description: 'Path to the instance to duplicate'
415
- },
416
- count: {
417
- type: 'number',
418
- description: 'Number of duplicates to create'
419
- },
420
- options: {
421
- type: 'object',
422
- properties: {
423
- namePattern: {
424
- type: 'string',
425
- description: 'Name pattern with {n} placeholder (e.g., "Button{n}")'
426
- },
427
- positionOffset: {
428
- type: 'array',
429
- items: { type: 'number' },
430
- minItems: 3,
431
- maxItems: 3,
432
- description: 'X, Y, Z offset per duplicate'
433
- },
434
- rotationOffset: {
435
- type: 'array',
436
- items: { type: 'number' },
437
- minItems: 3,
438
- maxItems: 3,
439
- description: 'X, Y, Z rotation offset per duplicate'
440
- },
441
- scaleOffset: {
442
- type: 'array',
443
- items: { type: 'number' },
444
- minItems: 3,
445
- maxItems: 3,
446
- description: 'X, Y, Z scale multiplier per duplicate'
447
- },
448
- propertyVariations: {
449
- type: 'object',
450
- description: 'Property name to array of values'
451
- },
452
- targetParents: {
453
- type: 'array',
454
- items: { type: 'string' },
455
- description: 'Different parent for each duplicate'
456
- }
457
- }
458
- }
459
- },
460
- required: ['instancePath', 'count']
461
- }
462
- },
463
- {
464
- name: 'mass_duplicate',
465
- description: 'Perform multiple smart duplications at once',
466
- inputSchema: {
467
- type: 'object',
468
- properties: {
469
- duplications: {
470
- type: 'array',
471
- items: {
472
- type: 'object',
473
- properties: {
474
- instancePath: {
475
- type: 'string',
476
- description: 'Path to the instance to duplicate'
477
- },
478
- count: {
479
- type: 'number',
480
- description: 'Number of duplicates to create'
481
- },
482
- options: {
483
- type: 'object',
484
- properties: {
485
- namePattern: {
486
- type: 'string',
487
- description: 'Name pattern with {n} placeholder'
488
- },
489
- positionOffset: {
490
- type: 'array',
491
- items: { type: 'number' },
492
- minItems: 3,
493
- maxItems: 3,
494
- description: 'X, Y, Z offset per duplicate'
495
- },
496
- rotationOffset: {
497
- type: 'array',
498
- items: { type: 'number' },
499
- minItems: 3,
500
- maxItems: 3,
501
- description: 'X, Y, Z rotation offset per duplicate'
502
- },
503
- scaleOffset: {
504
- type: 'array',
505
- items: { type: 'number' },
506
- minItems: 3,
507
- maxItems: 3,
508
- description: 'X, Y, Z scale multiplier per duplicate'
509
- },
510
- propertyVariations: {
511
- type: 'object',
512
- description: 'Property name to array of values'
513
- },
514
- targetParents: {
515
- type: 'array',
516
- items: { type: 'string' },
517
- description: 'Different parent for each duplicate'
518
- }
519
- }
520
- }
521
- },
522
- required: ['instancePath', 'count']
523
- },
524
- description: 'Array of duplication operations'
525
- }
526
- },
527
- required: ['duplications']
528
- }
529
- },
530
- // Calculated Property Tools
531
- {
532
- name: 'set_calculated_property',
533
- description: 'Set properties using mathematical formulas and variables',
534
- inputSchema: {
535
- type: 'object',
536
- properties: {
537
- paths: {
538
- type: 'array',
539
- items: { type: 'string' },
540
- description: 'Array of instance paths to modify'
541
- },
542
- propertyName: {
543
- type: 'string',
544
- description: 'Name of the property to set'
545
- },
546
- formula: {
547
- type: 'string',
548
- description: 'Mathematical formula (e.g., "Position.magnitude * 2", "index * 50")'
549
- },
550
- variables: {
551
- type: 'object',
552
- description: 'Additional variables for the formula'
553
- }
554
- },
555
- required: ['paths', 'propertyName', 'formula']
556
- }
557
- },
558
- // Relative Property Tools
559
- {
560
- name: 'set_relative_property',
561
- description: 'Modify properties relative to their current values',
562
- inputSchema: {
563
- type: 'object',
564
- properties: {
565
- paths: {
566
- type: 'array',
567
- items: { type: 'string' },
568
- description: 'Array of instance paths to modify'
569
- },
570
- propertyName: {
571
- type: 'string',
572
- description: 'Name of the property to modify'
573
- },
574
- operation: {
575
- type: 'string',
576
- enum: ['add', 'multiply', 'divide', 'subtract', 'power'],
577
- description: 'Mathematical operation to perform'
578
- },
579
- value: {
580
- description: 'Value to use in the operation'
581
- },
582
- component: {
583
- type: 'string',
584
- enum: ['X', 'Y', 'Z'],
585
- description: 'Specific component for Vector3/UDim2 properties'
586
- }
587
- },
588
- required: ['paths', 'propertyName', 'operation', 'value']
589
- }
590
- },
591
220
  // Script Management Tools (for Roblox Studio scripts - NOT local files)
592
221
  {
593
222
  name: 'get_script_source',
@@ -1139,6 +768,95 @@ class RobloxStudioMCPServer {
1139
768
  }
1140
769
  }
1141
770
  }
771
+ },
772
+ // ============================================
773
+ // VIEWPORTFRAME RENDERING (Visual feedback)
774
+ // ============================================
775
+ {
776
+ name: 'render_object_view',
777
+ description: `Render an object as an image from any angle using ViewportFrame. This is the PRIMARY tool for visual feedback - use it whenever you need to "see" what you've created or verify visual appearance.
778
+
779
+ Works in ANY Studio state (Edit/Play/Run) - no CaptureService limitations!
780
+ Instant rendering with full control over camera, lighting, and background.
781
+
782
+ Use cases:
783
+ - Verify visual appearance of created objects
784
+ - Generate thumbnails/previews
785
+ - Debug positioning and orientation
786
+ - Iterate on visual designs
787
+ - Show users what their objects look like
788
+
789
+ Available camera angles: front, back, left, right, top, bottom, iso (isometric), iso_front, iso_back, low_angle, high_angle
790
+ Or provide custom angles with pitch/yaw/roll in degrees.
791
+
792
+ Lighting presets: bright (3-point lighting), studio (flat/even), dark (dramatic), default (ambient only)`,
793
+ inputSchema: {
794
+ type: 'object',
795
+ properties: {
796
+ instancePath: {
797
+ type: 'string',
798
+ description: 'Path to the object to render (e.g., "game.Workspace.Model1")',
799
+ },
800
+ angle: {
801
+ description: 'Camera angle - use preset string or custom object with pitch/yaw/roll/distance',
802
+ oneOf: [
803
+ {
804
+ type: 'string',
805
+ enum: ['front', 'back', 'left', 'right', 'top', 'bottom', 'iso', 'iso_front', 'iso_back', 'low_angle', 'high_angle'],
806
+ },
807
+ {
808
+ type: 'object',
809
+ properties: {
810
+ pitch: { type: 'number', description: 'Pitch angle in degrees' },
811
+ yaw: { type: 'number', description: 'Yaw angle in degrees' },
812
+ roll: { type: 'number', description: 'Roll angle in degrees' },
813
+ distance: { type: 'number', description: 'Camera distance from object' },
814
+ },
815
+ },
816
+ ],
817
+ },
818
+ resolution: {
819
+ type: 'object',
820
+ properties: {
821
+ width: { type: 'number', description: 'Image width (64-2048, default: 512)' },
822
+ height: { type: 'number', description: 'Image height (64-2048, default: 512)' },
823
+ },
824
+ description: 'Render resolution',
825
+ },
826
+ lighting: {
827
+ type: 'string',
828
+ enum: ['default', 'bright', 'studio', 'dark', 'showcase', 'dramatic', 'flat'],
829
+ description: 'Lighting preset to use (default: bright)',
830
+ },
831
+ background: {
832
+ type: 'string',
833
+ enum: ['transparent', 'grid', 'solid'],
834
+ description: 'Background style (default: transparent)',
835
+ },
836
+ autoDistance: {
837
+ type: 'boolean',
838
+ description: 'Automatically calculate camera distance to fit object (default: true)',
839
+ },
840
+ },
841
+ required: ['instancePath'],
842
+ },
843
+ },
844
+ // ============================================
845
+ // EXECUTE LUA TOOL (Run arbitrary Lua code)
846
+ // ============================================
847
+ {
848
+ name: 'execute_lua',
849
+ description: 'Execute arbitrary Lua/Luau code in Roblox Studio. This is a powerful tool that runs code directly in the Studio plugin context with access to all services, Instance constructors, and the full Roblox API. Use this for complex operations that would require multiple tool calls, debugging, prototyping, or any task that\'s easier to express in code. Returns the result of the last expression.',
850
+ inputSchema: {
851
+ type: 'object',
852
+ properties: {
853
+ code: {
854
+ type: 'string',
855
+ description: 'The Lua/Luau code to execute. Has access to: game, workspace, all services (Players, ReplicatedStorage, etc.), Instance constructors (Vector3, CFrame, Color3, etc.), and helper function getInstanceByPath(path). Return a value to get it back in the response.'
856
+ }
857
+ },
858
+ required: ['code']
859
+ }
1142
860
  }
1143
861
  ]
1144
862
  };
@@ -1147,25 +865,14 @@ class RobloxStudioMCPServer {
1147
865
  const { name, arguments: args } = request.params;
1148
866
  try {
1149
867
  switch (name) {
1150
- // File System Tools
1151
- case 'get_file_tree':
1152
- return await this.tools.getFileTree(args?.path || '');
1153
- case 'search_files':
1154
- return await this.tools.searchFiles(args?.query, args?.searchType || 'name');
1155
868
  // Studio Context Tools
1156
869
  case 'get_place_info':
1157
870
  return await this.tools.getPlaceInfo();
1158
871
  case 'get_services':
1159
872
  return await this.tools.getServices(args?.serviceName);
1160
- case 'search_objects':
1161
- return await this.tools.searchObjects(args?.query, args?.searchType || 'name', args?.propertyName);
1162
873
  // Property & Instance Tools
1163
874
  case 'get_instance_properties':
1164
875
  return await this.tools.getInstanceProperties(args?.instancePath);
1165
- case 'get_instance_children':
1166
- return await this.tools.getInstanceChildren(args?.instancePath);
1167
- case 'search_by_property':
1168
- return await this.tools.searchByProperty(args?.propertyName, args?.propertyValue);
1169
876
  case 'get_class_info':
1170
877
  return await this.tools.getClassInfo(args?.className);
1171
878
  // Project Tools
@@ -1182,25 +889,8 @@ class RobloxStudioMCPServer {
1182
889
  // Object Creation/Deletion Tools
1183
890
  case 'create_object':
1184
891
  return await this.tools.createObject(args?.className, args?.parent, args?.name);
1185
- case 'create_object_with_properties':
1186
- return await this.tools.createObjectWithProperties(args?.className, args?.parent, args?.name, args?.properties);
1187
- case 'mass_create_objects':
1188
- return await this.tools.massCreateObjects(args?.objects);
1189
- case 'mass_create_objects_with_properties':
1190
- return await this.tools.massCreateObjectsWithProperties(args?.objects);
1191
892
  case 'delete_object':
1192
893
  return await this.tools.deleteObject(args?.instancePath);
1193
- // Smart Duplication Tools
1194
- case 'smart_duplicate':
1195
- return await this.tools.smartDuplicate(args?.instancePath, args?.count, args?.options);
1196
- case 'mass_duplicate':
1197
- return await this.tools.massDuplicate(args?.duplications);
1198
- // Calculated Property Tools
1199
- case 'set_calculated_property':
1200
- return await this.tools.setCalculatedProperty(args?.paths, args?.propertyName, args?.formula, args?.variables);
1201
- // Relative Property Tools
1202
- case 'set_relative_property':
1203
- return await this.tools.setRelativeProperty(args?.paths, args?.propertyName, args?.operation, args?.value, args?.component);
1204
894
  // Script Management Tools
1205
895
  case 'get_script_source':
1206
896
  return await this.tools.getScriptSource(args?.instancePath, args?.startLine, args?.endLine);
@@ -1270,6 +960,18 @@ class RobloxStudioMCPServer {
1270
960
  // Screenshot Tool
1271
961
  case 'capture_screenshot':
1272
962
  return await this.tools.captureScreenshot(args?.maxWidth, args?.maxHeight);
963
+ // ViewportFrame Rendering
964
+ case 'render_object_view':
965
+ return await this.tools.renderObjectView(args?.instancePath, {
966
+ angle: args?.angle,
967
+ resolution: args?.resolution,
968
+ lighting: args?.lighting,
969
+ background: args?.background,
970
+ autoDistance: args?.autoDistance,
971
+ });
972
+ // Execute Lua Tool
973
+ case 'execute_lua':
974
+ return await this.tools.executeLua(args?.code);
1273
975
  default:
1274
976
  throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
1275
977
  }