Roblox Studio MCP Server

Instructions

Implementation Reference

• src/tools/index.ts:142-156 (handler)

  The main execution logic for the 'get_project_structure' tool. Makes an HTTP request to the Roblox Studio bridge endpoint '/api/project-structure' with optional parameters path, maxDepth, and scriptsOnly, then formats and returns the response as MCP content.

  async getProjectStructure(path?: string, maxDepth?: number, scriptsOnly?: boolean) {
    const response = await this.client.request('/api/project-structure', { 
      path, 
      maxDepth, 
      scriptsOnly 
    });
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(response, null, 2)
        }
      ]
    };
  }

• src/index.ts:202-224 (schema)

  The input schema and metadata definition for the MCP tool, listed in the ListToolsRequestSchema response. Defines parameters, descriptions, and defaults.

    name: 'get_project_structure',
    description: 'Get complete game hierarchy. IMPORTANT: Use maxDepth parameter (default: 3) to explore deeper levels of the hierarchy. Set higher values like 5-10 for comprehensive exploration',
    inputSchema: {
      type: 'object',
      properties: {
        path: {
          type: 'string',
          description: 'Optional path to start from (defaults to workspace root)',
          default: ''
        },
        maxDepth: {
          type: 'number',
          description: 'Maximum depth to traverse (default: 3). RECOMMENDED: Use 5-10 for thorough exploration. Higher values provide more complete structure',
          default: 3
        },
        scriptsOnly: {
          type: 'boolean',
          description: 'Show only scripts and script containers',
          default: false
        }
      }
    }
  },

• src/index.ts:672-673 (registration)

  Tool call dispatching in the CallToolRequestSchema handler. Routes incoming tool calls to the RobloxStudioTools.getProjectStructure method.

  case 'get_project_structure':
    return await this.tools.getProjectStructure((args as any)?.path, (args as any)?.maxDepth, (args as any)?.scriptsOnly);

• src/http-server.ts:267-273 (registration)

  HTTP proxy endpoint registration for direct HTTP calls to the tool from the Roblox Studio plugin bridge.

  app.post('/mcp/get_project_structure', async (req, res) => {
    try {
      const result = await tools.getProjectStructure(req.body.path, req.body.maxDepth, req.body.scriptsOnly);
      res.json(result);
    } catch (error) {
      res.status(500).json({ error: error instanceof Error ? error.message : 'Unknown error' });
    }