analyze_cue_structure

Instructions

Implementation Reference

• src/tools/cue-tools.ts:407-459 (handler)

  The core handler function that performs comprehensive analysis of a cue list's structure, including cue numbering, fade timings, scene usage, follow chains, patterns, potential issues, statistics, and optional recommendations. Calls private helper methods for detailed computations.

  async analyzeCueStructure(args: z.infer<typeof AnalyzeCueStructureSchema>) {
    const { cueListId, projectId, includeRecommendations } =
      AnalyzeCueStructureSchema.parse(args);
  
    try {
      const project = await this.graphqlClient.getProject(projectId);
      if (!project) {
        throw new Error(`Project with ID ${projectId} not found`);
      }
  
      const cueList = project.cueLists.find((cl) => cl.id === cueListId);
      if (!cueList) {
        throw new Error(`Cue list with ID ${cueListId} not found`);
      }
  
      const analysis = {
        cueListId,
        name: cueList.name,
        structure: {
          totalCues: cueList.cues.length,
          cueNumbering: this.analyzeCueNumbering(cueList.cues),
          fadeTimings: this.analyzeFadeTimings(cueList.cues),
          sceneUsage: this.analyzeSceneUsage(cueList.cues, project.scenes),
          followStructure: this.analyzeFollowStructure(cueList.cues),
        },
        patterns: {
          commonFadeTimes: this.findCommonFadeTimes(cueList.cues),
          timingPatterns: this.identifyTimingPatterns(cueList.cues),
          sceneTransitions: this.analyzeSceneTransitions(cueList.cues),
        },
        potentialIssues: this.identifyPotentialIssues(cueList.cues),
        statistics: {
          estimatedRuntime: this.estimateSequenceDuration(cueList.cues),
          manualCues: cueList.cues.filter((cue) => !cue.followTime).length,
          autoCues: cueList.cues.filter((cue) => cue.followTime).length,
          averageCueSpacing: this.calculateAverageCueSpacing(cueList.cues),
        },
      };
  
      if (includeRecommendations) {
        (analysis as any).recommendations = {
          numbering: this.recommendNumberingImprovements(cueList.cues),
          timing: this.recommendTimingImprovements(cueList.cues),
          structure: this.recommendStructureImprovements(cueList.cues),
          safety: this.recommendSafetyConsiderations(cueList.cues),
        };
      }
  
      return analysis;
    } catch (error) {
      throw new Error(`Failed to analyze cue structure: ${error}`);
    }
  }

• src/tools/cue-tools.ts:59-63 (schema)

  Zod schema defining the input parameters for the analyze_cue_structure tool: required cueListId and projectId, optional includeRecommendations flag.

  const AnalyzeCueStructureSchema = z.object({
    cueListId: z.string(),
    projectId: z.string(),
    includeRecommendations: z.boolean().default(true),
  });

• src/index.ts:1285-1306 (registration)

  Tool registration in listToolsRequestHandler: defines name, description, and inputSchema matching the zod schema.

    name: "analyze_cue_structure",
    description: "Analyze the structure and timing of a cue list",
    inputSchema: {
      type: "object",
      properties: {
        cueListId: {
          type: "string",
          description: "Cue list ID to analyze",
        },
        projectId: {
          type: "string",
          description: "Project ID containing the cue list",
        },
        includeRecommendations: {
          type: "boolean",
          default: true,
          description: "Include improvement recommendations",
        },
      },
      required: ["cueListId", "projectId"],
    },
  },

• src/index.ts:2296-2308 (registration)

  Tool handler dispatch in callToolRequestHandler: maps tool name to CueTools.analyzeCueStructure method invocation.

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

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

  Instantiation of CueTools class instance used for all cue-related tools, injecting required services.

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