analyze_fixture_capabilities

Instructions

Implementation Reference

• src/tools/fixture-tools.ts:331-386 (handler)

  Main handler function that fetches fixtures, extracts capabilities, performs analysis based on type (color_mixing, positioning, effects, general), and returns structured results with summary.

  async analyzeFixtureCapabilities(
    args: z.infer<typeof AnalyzeFixtureCapabilitiesSchema>,
  ) {
    const { fixtureId, fixtureIds, analysisType } =
      AnalyzeFixtureCapabilitiesSchema.parse(args);
  
    try {
      let targetFixtures: FixtureInstance[] = [];
  
      if (fixtureId) {
        // Get fixture from any project (we'll need to search)
        const projects = await this.graphqlClient.getProjects();
        for (const project of projects) {
          const fixture = project.fixtures.find((f) => f.id === fixtureId);
          if (fixture) {
            targetFixtures = [fixture];
            break;
          }
        }
      } else if (fixtureIds) {
        const projects = await this.graphqlClient.getProjects();
        targetFixtures = projects
          .flatMap((p) => p.fixtures)
          .filter((f) => fixtureIds.includes(f.id));
      } else {
        throw new Error("Either fixtureId or fixtureIds must be provided");
      }
  
      if (targetFixtures.length === 0) {
        throw new Error("No fixtures found with the provided IDs");
      }
  
      const analysis = targetFixtures.map((fixture) => {
        const capabilities = this.extractFixtureCapabilities(fixture);
  
        switch (analysisType) {
          case "color_mixing":
            return this.analyzeColorCapabilities(fixture, capabilities);
          case "positioning":
            return this.analyzePositioningCapabilities(fixture, capabilities);
          case "effects":
            return this.analyzeEffectCapabilities(fixture, capabilities);
          default:
            return this.analyzeGeneralCapabilities(fixture, capabilities);
        }
      });
  
      return {
        analysisType,
        fixtures: analysis,
        summary: this.generateCapabilitySummary(analysis, analysisType),
      };
    } catch (error) {
      throw new Error(`Failed to analyze fixture capabilities: ${error}`);
    }
  }

• src/tools/fixture-tools.ts:32-38 (schema)

  Zod input schema defining parameters: single fixtureId or array fixtureIds, optional analysisType (defaults to general). Used for validation in handler.

  const AnalyzeFixtureCapabilitiesSchema = z.object({
    fixtureId: z.string().optional(),
    fixtureIds: z.array(z.string()).optional(),
    analysisType: z
      .enum(["color_mixing", "positioning", "effects", "general"])
      .default("general"),
  });

• src/index.ts:309-333 (registration)

  Tool registration in ListToolsRequestHandler: defines name, description, and inputSchema matching the Zod schema.

  {
    name: "analyze_fixture_capabilities",
    description:
      "Analyze specific fixtures to understand their lighting capabilities",
    inputSchema: {
      type: "object",
      properties: {
        fixtureId: {
          type: "string",
          description: "Single fixture ID to analyze",
        },
        fixtureIds: {
          type: "array",
          items: { type: "string" },
          description: "Multiple fixture IDs to analyze",
        },
        analysisType: {
          type: "string",
          enum: ["color_mixing", "positioning", "effects", "general"],
          default: "general",
          description: "Type of capability analysis",
        },
      },
    },
  },

• src/index.ts:1924-1938 (registration)

  Handler dispatch in CallToolRequestHandler: routes calls to FixtureTools.analyzeFixtureCapabilities method.

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

• src/tools/fixture-tools.ts:388-439 (helper)

  Core helper that extracts capability flags (color, movement, effects, etc.) from fixture channels. Used by all analysis types.

  private extractFixtureCapabilities(fixture: FixtureInstance) {
    // Use mode-specific channels if available, otherwise fall back to definition channels
    let channelTypes: string[];
    let channelCount: number;
    
    // Debug info (temporarily embedded in response)
    const debugInfo = {
      fixtureName: fixture.name,
      hasMode: !!fixture.modeName,
      modeName: fixture.modeName,
      modeChannelCount: fixture.channelCount,
      modeChannelsLength: fixture.channels?.length,
      definitionChannelsLength: fixture.channels.length
    };
    
    if (fixture.channels && fixture.channels.length > 0) {
      // Use mode-specific channels
      channelTypes = fixture.channels.map((ch: any) => ch.type);
      channelCount = fixture.channelCount;
    } else {
      // Fall back to fixture channels
      channelTypes = fixture.channels.map((ch) => ch.type);
      channelCount = fixture.channels.length;
    }
  
    return {
      hasColor: channelTypes.some((t) =>
        ["RED", "GREEN", "BLUE", "WHITE", "AMBER", "UV"].includes(t),
      ),
      hasRGB: ["RED", "GREEN", "BLUE"].every((color) =>
        channelTypes.includes(color as any),
      ),
      hasWhite: channelTypes.includes("WHITE" as any),
      hasAmber: channelTypes.includes("AMBER" as any),
      hasUV: channelTypes.includes("UV" as any),
      hasMovement: channelTypes.some((t) => ["PAN", "TILT"].includes(t)),
      hasPan: channelTypes.includes("PAN" as any),
      hasTilt: channelTypes.includes("TILT" as any),
      hasIntensity: channelTypes.includes("INTENSITY" as any),
      hasZoom: channelTypes.includes("ZOOM" as any),
      hasFocus: channelTypes.includes("FOCUS" as any),
      hasGobo: channelTypes.includes("GOBO" as any),
      hasColorWheel: channelTypes.includes("COLOR_WHEEL" as any),
      hasStrobe: channelTypes.includes("STROBE" as any),
      hasEffects: channelTypes.includes("EFFECT" as any),
      hasMacros: channelTypes.includes("MACRO" as any),
      channelTypes: channelTypes,
      channelCount: channelCount,
      // Temporary debug info
      _debug_extractCapabilities: debugInfo,
    };
  }