generate_act_cues
Generate lighting cue suggestions for theatrical acts using script analysis. Input project details, act number, and script text to create tailored cue lists for enhanced stage lighting design.
Instructions
Generate cue suggestions for an entire act based on script analysis
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| actNumber | Yes | Act number to generate cues for | |
| cueListName | No | Optional name for the cue list | |
| existingScenes | No | Optional existing scene IDs to reference | |
| projectId | Yes | Project ID to work with | |
| scriptText | Yes | Script text for the act |
Input Schema (JSON Schema)
{
"properties": {
"actNumber": {
"description": "Act number to generate cues for",
"type": "number"
},
"cueListName": {
"description": "Optional name for the cue list",
"type": "string"
},
"existingScenes": {
"description": "Optional existing scene IDs to reference",
"items": {
"type": "string"
},
"type": "array"
},
"projectId": {
"description": "Project ID to work with",
"type": "string"
},
"scriptText": {
"description": "Script text for the act",
"type": "string"
}
},
"required": [
"projectId",
"actNumber",
"scriptText"
],
"type": "object"
}
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, );