suggest_channel_assignment

Instructions

Implementation Reference

• src/tools/fixture-tools.ts:936-1023 (handler)

  The primary handler function for the 'suggest_channel_assignment' MCP tool. Parses input schema, retrieves project channel map, finds contiguous available channel blocks for each fixture specification, computes assignments sequentially or by grouping strategy, and returns suggested channel ranges with summary and recommendations.

  async suggestChannelAssignment(
    args: z.infer<typeof SuggestChannelAssignmentSchema>,
  ) {
    const {
      projectId,
      fixtureSpecs,
      universe,
      startingChannel,
      groupingStrategy,
    } = SuggestChannelAssignmentSchema.parse(args);
  
    try {
      const channelMap = await this.getChannelMap({ projectId, universe });
      const universeData = channelMap.universes.find(
        (u: any) => u.universe === universe,
      );
  
      if (!universeData) {
        throw new Error(`Universe ${universe} not found in project`);
      }
  
      const assignments = [];
      let currentChannel = startingChannel;
  
      for (const spec of fixtureSpecs) {
        // Estimate channel count (default to 4 if not provided)
        const channelCount = spec.channelCount || 4;
  
        // Find next available channel block
        const availableChannel = this.findNextAvailableChannelBlock(
          universeData.channelUsage,
          currentChannel,
          channelCount,
        );
  
        if (availableChannel + channelCount - 1 > 512) {
          throw new Error(
            `Not enough channels available in universe ${universe} for fixture ${spec.name}`,
          );
        }
  
        assignments.push({
          fixtureName: spec.name,
          manufacturer: spec.manufacturer,
          model: spec.model,
          mode: spec.mode,
          startChannel: availableChannel,
          endChannel: availableChannel + channelCount - 1,
          channelCount,
          channelRange: `${availableChannel}-${availableChannel + channelCount - 1}`,
        });
  
        // Update for next fixture based on grouping strategy
        switch (groupingStrategy) {
          case "sequential":
            currentChannel = availableChannel + channelCount;
            break;
          case "by_type":
            // Group similar fixture types together
            currentChannel = availableChannel + channelCount;
            break;
          case "by_function":
            // Group by function (e.g., all wash lights together)
            currentChannel = availableChannel + channelCount;
            break;
        }
      }
  
      return {
        projectId,
        universe,
        groupingStrategy,
        assignments,
        summary: {
          totalFixtures: assignments.length,
          channelsUsed: assignments.reduce((sum, a) => sum + a.channelCount, 0),
          startChannel: assignments[0]?.startChannel,
          endChannel: assignments[assignments.length - 1]?.endChannel,
        },
        recommendations: this.generateChannelRecommendations(
          assignments,
          universeData,
        ),
      };
    } catch (error) {
      throw new Error(`Failed to suggest channel assignment: ${error}`);
    }
  }

• src/tools/fixture-tools.ts:85-110 (schema)

  Zod schema defining input validation for the suggest_channel_assignment tool, including projectId, fixtureSpecs array with details, universe, startingChannel, and groupingStrategy.

  const SuggestChannelAssignmentSchema = z.object({
    projectId: z.string().describe("Project ID"),
    fixtureSpecs: z
      .array(
        z.object({
          name: z.string(),
          manufacturer: z.string(),
          model: z.string(),
          mode: z.string().optional(),
          channelCount: z
            .number()
            .optional()
            .describe("Number of channels (if known)"),
        }),
      )
      .describe("List of fixtures to assign channels for"),
    universe: z.number().default(1).describe("Universe to assign channels in"),
    startingChannel: z
      .number()
      .default(1)
      .describe("Channel to start assignments from"),
    groupingStrategy: z
      .enum(["sequential", "by_type", "by_function"])
      .default("sequential")
      .describe("How to group fixture assignments"),
  });