optimize_scene

Instructions

Implementation Reference

• src/tools/scene-tools.ts:366-395 (handler)

  Main execution logic for the 'optimize_scene' MCP tool. Validates args using OptimizeSceneSchema, retrieves project and scene, and returns optimization status and recommendations (full optimization planned for future).

  async optimizeScene(args: z.infer<typeof OptimizeSceneSchema>) {
    const { sceneId, projectId, optimizationGoals } = OptimizeSceneSchema.parse(args);
  
    try {
      // Get the current scene
      const project = await this.graphqlClient.getProject(projectId);
      if (!project) {
        throw new Error(`Project with ID ${projectId} not found`);
      }
  
      const scene = project.scenes.find(s => s.id === sceneId);
      if (!scene) {
        throw new Error(`Scene with ID ${sceneId} not found`);
      }
  
      // Scene optimization is planned for future implementation
      // Currently returns analysis and recommendations without modifying the scene
      return {
        sceneId,
        sceneName: scene.name,
        originalFixtureCount: scene.fixtureValues.length,
        requestedGoals: optimizationGoals,
        status: 'not_implemented',
        message: 'Scene optimization is planned for future releases. Current implementation provides recommendations only.',
        recommendations: this.getOptimizationRecommendations(optimizationGoals),
      };
    } catch (error) {
      throw new Error(`Failed to optimize scene: ${error}`);
    }
  }

• src/tools/scene-tools.ts:85-89 (schema)

  Zod input schema used for validating arguments in the optimizeScene handler.

  const OptimizeSceneSchema = z.object({
    sceneId: z.string(),
    projectId: z.string(),
    optimizationGoals: z.array(z.enum(['energy_efficiency', 'color_accuracy', 'dramatic_impact', 'technical_simplicity'])).default(['dramatic_impact'])
  });

• src/index.ts:886-916 (registration)

  Registration of 'optimize_scene' tool in the ListTools response, defining name, description, and JSON input schema.

    name: "optimize_scene",
    description: "Optimize an existing scene for specific goals",
    inputSchema: {
      type: "object",
      properties: {
        sceneId: {
          type: "string",
          description: "Scene ID to optimize",
        },
        projectId: {
          type: "string",
          description: "Project ID containing the scene",
        },
        optimizationGoals: {
          type: "array",
          items: {
            type: "string",
            enum: [
              "energy_efficiency",
              "color_accuracy",
              "dramatic_impact",
              "technical_simplicity",
            ],
          },
          default: ["dramatic_impact"],
          description: "Goals for optimization",
        },
      },
      required: ["sceneId", "projectId"],
    },
  },

• src/index.ts:2112-2124 (registration)

  Handler dispatch in CallToolRequestSchema switch statement, calling sceneTools.optimizeScene with parsed arguments.

  case "optimize_scene":
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            await this.sceneTools.optimizeScene(args as any),
            null,
            2,
          ),
        },
      ],
    };

• src/tools/scene-tools.ts:471-508 (helper)

  Private helper method that generates goal-specific optimization recommendations used by the optimizeScene handler.

  private getOptimizationRecommendations(goals: string[]): string[] {
    const recommendations: string[] = [];
  
    for (const goal of goals) {
      switch (goal) {
        case 'energy_efficiency':
          recommendations.push(
            'Use fewer fixtures at higher intensity rather than many at low intensity',
            'Prioritize LED fixtures over traditional tungsten',
            'Consider consolidating similar color washes'
          );
          break;
        case 'color_accuracy':
          recommendations.push(
            'Use fixtures with dedicated white channels',
            'Avoid oversaturated colors that may appear unnatural',
            'Consider color temperature consistency across fixtures'
          );
          break;
        case 'dramatic_impact':
          recommendations.push(
            'Use moving heads for dynamic positioning',
            'Create strong key light with softer fill',
            'Consider backlight for separation and depth'
          );
          break;
        case 'technical_simplicity':
          recommendations.push(
            'Group similar fixtures for easier control',
            'Use preset colors rather than custom mixes',
            'Minimize moving head positioning changes'
          );
          break;
      }
    }
  
    return recommendations;
  }