generate_act_cues

Instructions

Implementation Reference

• src/tools/cue-tools.ts:281-359 (handler)

  Main handler function implementing the generate_act_cues tool. Analyzes script text for a specific act, filters scenes by act number, generates lighting recommendations and cue templates for each scene using RAG service, computes timing/mood analysis, and returns structured cue suggestions with act-level insights.

  async generateActCues(args: z.infer<typeof GenerateActCuesSchema>) {
    const {
      projectId: _projectId,
      actNumber,
      scriptText,
      existingScenes: _existingScenes,
      cueListName,
    } = GenerateActCuesSchema.parse(args);
  
    try {
      // Analyze the script for this act
      const scriptAnalysis = await this.ragService.analyzeScript(scriptText);
  
      // Filter scenes for this act (assuming scene numbers indicate acts)
      const actScenes = scriptAnalysis.scenes.filter((scene) => {
        const sceneNum = parseFloat(scene.sceneNumber);
        return Math.floor(sceneNum) === actNumber;
      });
  
      if (actScenes.length === 0) {
        throw new Error(
          `No scenes found for Act ${actNumber} in the provided script`,
        );
      }
  
      // Generate cue suggestions for each scene in the act
      const cueTemplates = await Promise.all(
        actScenes.map(async (scene, _index) => {
          const recommendations =
            await this.ragService.generateLightingRecommendations(
              scene.content,
              scene.mood,
              ["LED_PAR", "MOVING_HEAD"], // Default fixture types
            );
  
          return {
            sceneNumber: scene.sceneNumber,
            cueName: `Cue ${scene.sceneNumber}`,
            description: scene.title || `Scene ${scene.sceneNumber}`,
            mood: scene.mood,
            timeOfDay: scene.timeOfDay,
            location: scene.location,
            lightingCues: scene.lightingCues,
            suggestedTiming: {
              fadeIn: this.calculateFadeTime(scene.mood, "in"),
              fadeOut: this.calculateFadeTime(scene.mood, "out"),
              autoFollow: scene.lightingCues.some(
                (cue) =>
                  cue.toLowerCase().includes("auto") ||
                  cue.toLowerCase().includes("follow"),
              ),
            },
            colorSuggestions: recommendations.colorSuggestions,
            intensityLevel: recommendations.intensityLevels,
          };
        }),
      );
  
      return {
        actNumber,
        totalScenes: actScenes.length,
        suggestedCueListName: cueListName || `Act ${actNumber} Cues`,
        cueTemplates,
        actAnalysis: {
          overallMood: this.determineActMood(actScenes),
          keyMoments: this.identifyKeyMoments(actScenes),
          transitionTypes: this.analyzeTransitions(actScenes),
          estimatedDuration: this.estimateActDuration(cueTemplates),
        },
        recommendations: {
          preShowChecks: this.generatePreShowChecklist(cueTemplates),
          criticalCues: this.identifyCriticalCues(cueTemplates),
          backupPlans: this.suggestBackupPlans(cueTemplates),
        },
      };
    } catch (error) {
      throw new Error(`Failed to generate act cues: ${error}`);
    }
  }

• src/tools/cue-tools.ts:38-44 (schema)

  Zod input validation schema defining parameters: projectId (string), actNumber (number), scriptText (string), existingScenes (optional array of strings), cueListName (optional string). Used for parsing args in the handler.

  const GenerateActCuesSchema = z.object({
    projectId: z.string(),
    actNumber: z.number(),
    scriptText: z.string(),
    existingScenes: z.array(z.string()).optional(),
    cueListName: z.string().optional(),
  });

• src/index.ts:2268-2280 (registration)

  Dispatch handler in MCP call_tool request that invokes cueTools.generateActCues for tool name 'generate_act_cues'.

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

• src/index.ts:1224-1254 (registration)

  Tool registration in MCP list_tools response: defines name 'generate_act_cues', description, and inputSchema matching the handler schema.

    name: "generate_act_cues",
    description:
      "Generate cue suggestions for an entire act based on script analysis",
    inputSchema: {
      type: "object",
      properties: {
        projectId: {
          type: "string",
          description: "Project ID to work with",
        },
        actNumber: {
          type: "number",
          description: "Act number to generate cues for",
        },
        scriptText: {
          type: "string",
          description: "Script text for the act",
        },
        existingScenes: {
          type: "array",
          items: { type: "string" },
          description: "Optional existing scene IDs to reference",
        },
        cueListName: {
          type: "string",
          description: "Optional name for the cue list",
        },
      },
      required: ["projectId", "actNumber", "scriptText"],
    },
  },

• src/index.ts:57-61 (helper)

  Instantiation of CueTools class instance used for all cue-related tools including generate_act_cues.

  this.cueTools = new CueTools(
    this.graphqlClient,
    this.ragService,
    this.aiLightingService,
  );