Smart Bulb MCP Server

Un servidor de Model Context Protocol (MCP) creado con Node.js y TypeScript para controlar bombillas inteligentes por IP. Enta:

• Mock/Bombilla simul: Para pruebas de locas y desaroollo sin hardware físico.

• Bombilla Yeelight/Xiaomi: Usa el puero TCP estándar 5543 (protocolo JSON-RPC de contro local) para controlar bombillas inteligentes físicas reales.

Características

• Onexión por IP: Conecta de forma dinámica a distitas bombillas en tu red loca.

• Control de encendido: Enciede o apaga la bombilla.

• Brillo y opacid: Ajusa el brillo / intensidad de la bombilla de un 1 % a un 100 %.

• Control de color: Establece colores mediante coordenadas RGB o códigos de color hexadecimal.

• Consulas de estado: Obtiens el estado actua de la bombilla en tiempo rea.

Related MCP server: Philips Hue MCP Service

Primers pasos

1. Compilar el servidor

Primero, insta las dendecias y compila los achivos de TypeScript:

# Install dependencies
npm install

# Compile the TypeScript files
npm run build

Los archivos compilados se guardarán en el directo dist/.

2. Ejecución / Desarrollo arro

Puedes ejecutar el servidor mediante entada/salida estádar (Stdio):

# Run the built JS
npm start

# Compile and run in development mode
npm run dev

Configuración con clientes MCP

Para usar este servidor con un cliente MCP (como Claude Desktop o Cursor), añade la configuración del servidor a tu archivo de config.

Para Claude Desktop

Edito tu claude_desktop_config.json (casi normalmente en %APPDATA%\Claude en Windows o ~/Library/Application Support/Claude en macOS):

{
  "mcpServers": {
    "smart-bulb": {
      "command": "node",
      "args": ["D:/Palwinder/mcp-server-bulb/dist/index.js"]
    }
  }
}

Nota: Reempla D:/Perswinder/mcp-server-bulb/dist/index.js con la ruta absoluta a dist/index.js en tu máquina.

Herramientas MCP expuestas

Una vez que el servidor está conectado, el LLM anfitrión tendrá acceso a las siguientes herramientas:

1. connect_bulb

Conecta a una bombilla en una IP especificada.

• Argumentos:

  • ip (string, obligatorio): dirección IP (p. ej., "192.168.1.15" o "127.0.0.1").

  • type (enum ["mock", "yeelight"], por defecto: "mock"): tipo de controlador. Usa "mock" para probar las funciones del servidor sin hardware físico, o "yeelight" para bombillas Yeelight reales.

  • port (number, opcional): puerto a utilizar. Por defecto, 55443 para Yeelight y 9999 para Mock.

2. disconnect_bulb

Desconecta la bombilla actualmente conectada.

• Argumentos: Ninguno.

3. get_bulb_state

Obtiene el estado de conexión, estado de encendido/apagado, porcentaje de brillo/opacid y el color RGB.

• Argumentos: Ninguno.

4. set_bulb_power

Enciende o agapa la bombilla.

• Argumentos:

  • pouer (boolean, obligatorio): true para encerar, false para agapar.

5. set_bulb_brightness

Establece el brolo/opacid de la bombilla.

• Argés:

  • bragtness (number, obligatorio): valore desde 1 a 100.

6. set_bulb_color_egb

Establece el color de la bombilla usando valores RGB.

• Argumentos:

  • r (number, obligatorio): componente rojo 0 - 255.

  • g (number, obligatorio): componente verde 0 - 255.

  • b (number, obligatorio): componente azul 0 - 255.

7. set_bulb_color_hex

Establece el color de la bombilla usando un códigode color hexadecimal.

• Argumentos:

  • hex (string, obligatorio): códigode hexadecimal (p. ej., "#FF0000" o "00FF00").

Cliente de conexión de OpenAI

Hemos creado un envoltorio de cliente (un cliente) en src/open-ai-client.ts que te permit directar prompts aiento directo a OpenAi. Después, OpenAi invocará de forma autónomam las herramintas MCP para llevar a las acciones sobre tu bombilla int.

Configuración y ejecución del cliente

1. Configura tu clave de OpenAi: En Windows (PowerShell):

   $env:OPENAI_API_KEY="your-actual-api-key"

   En macOS/Linux (basa):

   export OPENAI_API_KEY="your-actual-api-key"

2. Ejeecuta el cliente:

   • Modo CLI interactivo:

     npm run client

     Esto abre un terminal. Prueba a escribir:

     Conecta la bombilla mock, enciende la, pon su brillo al 80 % y color amarillo.

   • Modo de comando: Pasa el prompt direct como argumento:

     npm run client -- "connect to the mock bulb, turn it on, and set color to blue"

3. Personalizar el medio (opcional): Por defecto, usa gtp-4o-mini. Puedes cambiarlo configurando la variable de entorno OPENAI_MODEL:

$env:OPENAI_MODEL="gpt-4o"

Detalles de desarrollo y arquitectura

El proyecto tiene una arquitectura:

• src/bulb/interface.ts: Defyne el contrato común (ISmartBulb) y la forma del estado (BulbState).

• src/b ulb/mock.ts: Instancia de bombilla simulada que imita latencia de red y cambios de estado en memoria.

• src/bulb/yeelight.ts: Implementa un analizador de búfer de líneas basado en TCP para enviar y recibir paquete JSON-RPC directamente de las bombillas yeelight WiFi físicas sin dependencias de SDK de terceros.

• src/index.ts: Configura y monta las herramients de @modelcontextprotocol/server, gestionando los estados de conexión y los esquemas de validación.

• src/openai-client.ts: Lans el servidor MCP como subproces o, carg dinamicamente toda sus herramientas, las expose como funciones OpenAi y gestiona el bucle convercional de ejecución de herramientas.

Hecho por Palwinder Singh