LacyLights MCP Server

Instructions

Implementation Reference

• src/tools/fixture-tools.ts:249-329 (handler)

  Main handler function in FixtureTools class that fetches fixture instances from a specific project or all projects, optionally filters by type, fetches matching fixture definitions, computes summary statistics by type, and extracts capabilities for each fixture.

  async getFixtureInventory(args: z.infer<typeof GetFixtureInventorySchema>) {
    const { projectId, fixtureType, includeDefinitions } =
      GetFixtureInventorySchema.parse(args);
  
    try {
      let fixtures: FixtureInstance[] = [];
      let definitions: FixtureDefinition[] = [];
  
      if (projectId) {
        const project = await this.graphqlClient.getProject(projectId);
        if (!project) {
          throw new Error(`Project with ID ${projectId} not found`);
        }
        fixtures = project.fixtures;
      } else {
        const projects = await this.graphqlClient.getProjects();
        fixtures = projects.flatMap((p) => p.fixtures);
      }
  
      // Filter by fixture type if specified
      if (fixtureType) {
        fixtures = fixtures.filter((f) => f.type === fixtureType);
      }
  
      if (includeDefinitions) {
        definitions = await this.graphqlClient.getFixtureDefinitions();
        if (fixtureType) {
          definitions = definitions.filter((d) => d.type === fixtureType);
        }
      }
  
      const summary = {
        totalFixtures: fixtures.length,
        fixturesByType: fixtures.reduce(
          (acc, f) => {
            const type = f.type || 'UNKNOWN';
            acc[type] = (acc[type] || 0) + 1;
            return acc;
          },
          {} as Record<string, number>,
        ),
        availableDefinitions: definitions.length,
      };
  
      return {
        fixtures: fixtures
          .map((f) => ({
            id: f.id,
            name: f.name,
            description: f.description,
            type: f.type,
            manufacturer: f.manufacturer,
            model: f.model,
          universe: f.universe,
          startChannel: f.startChannel,
          tags: f.tags,
          capabilities: this.extractFixtureCapabilities(f),
          channelCount: f.channelCount,
          modes: [{
            id: 'current',
            name: f.modeName,
            channelCount: f.channelCount,
          }],
        })),
        definitions: includeDefinitions
          ? definitions.map((d) => ({
              id: d.id,
              manufacturer: d.manufacturer,
              model: d.model,
              type: d.type,
              isBuiltIn: d.isBuiltIn,
              channelTypes: d.channels.map((ch) => ch.type),
              modes: d.modes.length,
            }))
          : [],
        summary,
      };
    } catch (error) {
      throw new Error(`Failed to get fixture inventory: ${error}`);
    }
  }

• src/tools/fixture-tools.ts:24-30 (schema)

  Zod input schema defining optional projectId (string), fixtureType (enum of fixture types), and includeDefinitions (boolean, default true). Used to validate and parse arguments before calling the handler.

  const GetFixtureInventorySchema = z.object({
    projectId: z.string().optional(),
    fixtureType: z
      .enum(["LED_PAR", "MOVING_HEAD", "STROBE", "DIMMER", "OTHER"])
      .optional(),
    includeDefinitions: z.boolean().default(true),
  });

• src/index.ts:286-308 (registration)

  Tool registration in ListToolsRequestSchema handler, defining the tool name, description, and JSON input schema matching the Zod schema.

    name: "get_fixture_inventory",
    description:
      "Get available lighting fixtures and their capabilities for a project or globally",
    inputSchema: {
      type: "object",
      properties: {
        projectId: {
          type: "string",
          description: "Optional project ID to filter fixtures",
        },
        fixtureType: {
          type: "string",
          enum: ["LED_PAR", "MOVING_HEAD", "STROBE", "DIMMER", "OTHER"],
          description: "Optional fixture type filter",
        },
        includeDefinitions: {
          type: "boolean",
          default: true,
          description: "Include available fixture definitions",
        },
      },
    },
  },

• src/index.ts:1910-1922 (registration)

  Tool call handler in CallToolRequestSchema switch statement that instantiates FixtureTools and delegates to getFixtureInventory method with parsed args.

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

• src/index.ts:51-51 (registration)

  Instantiation of FixtureTools class instance in LacyLightsMCPServer constructor, passing graphqlClient dependency required by the tool.

  this.fixtureTools = new FixtureTools(this.graphqlClient);