LIFX MCP Server

Instructions

Implementation Reference

• src/index.ts:283-297 (handler)

  Executes the list_lights tool by calling the LIFX API to fetch lights matching the selector and formatting a detailed text response listing each light's properties.

  case "list_lights": {
    const { token, selector = "all" } = args as { token: string; selector?: string };
    const lights = await makeLIFXRequest(`/lights/${selector}`, { token });
    
    return {
      content: [
        {
          type: "text",
          text: `Found ${lights.length} lights:\n\n${lights.map((light: LIFXLight) => 
            `• ${light.label} (${light.id})\n  Power: ${light.power}\n  Brightness: ${(light.brightness * 100).toFixed(1)}%\n  Color: H:${light.color.hue}° S:${(light.color.saturation * 100).toFixed(1)}% K:${light.color.kelvin}\n  Connected: ${light.connected ? 'Yes' : 'No'}\n  Group: ${light.group.name}\n  Location: ${light.location.name}`
          ).join('\n\n')}`,
        },
      ],
    };
  }

• src/index.ts:142-153 (schema)

  Defines the input schema for the list_lights tool, specifying required LIFX API token and optional selector.

  {
    name: "list_lights",
    description: "Get lights belonging to the authenticated account",
    inputSchema: {
      type: "object",
      properties: {
        token: { type: "string", description: "LIFX API token" },
        selector: { type: "string", description: "Selector for filtering lights (default: 'all')" },
      },
      required: ["token"],
    },
  },

• src/index.ts:142-153 (registration)

  Registers the list_lights tool in the list returned by ListToolsRequestHandler.

  {
    name: "list_lights",
    description: "Get lights belonging to the authenticated account",
    inputSchema: {
      type: "object",
      properties: {
        token: { type: "string", description: "LIFX API token" },
        selector: { type: "string", description: "Selector for filtering lights (default: 'all')" },
      },
      required: ["token"],
    },
  },

• src/index.ts:16-49 (schema)

  TypeScript interface defining the structure of a LIFX light object, used in the handler for type safety and response formatting.

  interface LIFXLight {
    id: string;
    uuid: string;
    label: string;
    connected: boolean;
    power: string;
    color: {
      hue: number;
      saturation: number;
      kelvin: number;
    };
    brightness: number;
    group: {
      id: string;
      name: string;
    };
    location: {
      id: string;
      name: string;
    };
    product: {
      name: string;
      identifier: string;
      company: string;
      capabilities: {
        has_color: boolean;
        has_variable_color_temp: boolean;
        has_ir: boolean;
        has_chain: boolean;
        has_matrix: boolean;
        has_multizone: boolean;
      };
    };
  }

• src/index.ts:72-114 (helper)

  Helper function to make authenticated HTTP requests to the LIFX API, used by the list_lights handler and other tools.

  async function makeLIFXRequest(
    endpoint: string,
    options: {
      method?: string;
      body?: any;
      token: string;
    }
  ): Promise<any> {
    const { method = "GET", body, token } = options;
    
    const url = `${LIFX_API_BASE}${endpoint}`;
    const headers: Record<string, string> = {
      "Authorization": `Bearer ${token}`,
      "User-Agent": USER_AGENT,
    };
  
    if (body && (method === "POST" || method === "PUT")) {
      headers["Content-Type"] = "application/json";
    }
  
    try {
      const response = await fetch(url, {
        method,
        headers,
        body: body ? JSON.stringify(body) : undefined,
      });
  
      if (!response.ok) {
        const errorText = await response.text();
        throw new Error(`LIFX API error: ${response.status} ${response.statusText} - ${errorText}`);
      }
  
      // Some endpoints return empty responses
      const contentType = response.headers.get("content-type");
      if (contentType?.includes("application/json")) {
        return await response.json();
      }
      
      return await response.text();
    } catch (error) {
      throw new Error(`Failed to make LIFX API request: ${error instanceof Error ? error.message : String(error)}`);
    }
  }