Smart Appliance MCP

Un servidor MCP que permite a cualquier cliente LLM compatible con MCP descubrir y controlar electrodomésticos inteligentes en la red local.

La decisión de diseño importante es el enrutamiento basado en adaptadores:

1. discover_devices escanea con todos los adaptadores registrados.

2. Cada dispositivo descubierto almacena su provider.

3. Las llamadas posteriores usan solo deviceId; el servidor busca el dispositivo y enruta el comando al adaptador encontrado durante el descubrimiento.

Eso mantiene simples las indicaciones del cliente. El cliente LLM no necesita saber si un televisor es Roku, Home Assistant, Samsung, LG, Matter u otro.

Herramientas

• discover_devices: encuentra electrodomésticos y los recuerda para esta sesión del servidor.

• diagnose_discovery: explica el estado del descubrimiento y los posibles bloqueadores de red sin pedir a los usuarios que editen configuración técnica.

• list_known_devices: devuelve los dispositivos ya encontrados.

• get_device_controls: muestra las capacidades disponibles para un dispositivo.

• discover_apps: sondea los objetivos de lanzamiento de aplicaciones expuestos por un dispositivo multimedia descubierto.

• search_apps: busca aplicaciones descubiertas por nombre, id de paquete, pistas de categoría y capacidad de lanzamiento.

• pair_device: inicia el emparejamiento de consumidor de una sola vez cuando un proveedor lo requiere.

• complete_pairing: completa el emparejamiento con el código mostrado en el electrodoméstico.

• list_pairings: lista los emparejamientos almacenados localmente.

• remove_pairing: elimina un emparejamiento almacenado localmente.

• control_device: realiza acciones como volumen, navegación, encendido, búsqueda y lanzamiento de aplicaciones.

• search_content: busca aplicaciones instaladas o proveedores de contenido nativos cuando se admite.

• suggest_content: devuelve sugerencias de visualización conscientes del adaptador.

• record_watch_event: recuerda contenido visto, gustado, descartado o iniciado.

• list_watch_history: muestra el historial de visualización local reciente utilizado por las recomendaciones.

• recommend_content: clasifica qué ver a continuación por categoría, novedad, aplicación, historial de visualización y capacidad de lanzamiento de aplicaciones.

• get_device_state: devuelve el estado cuando un adaptador lo admite.

Adaptadores incluidos

• roku: descubre televisores Roku y dispositivos de streaming Roku a través de SSDP y los controla mediante Roku ECP.

• smart_appliance_companion: descubre la aplicación complementaria opcional del lado del televisor a través de mDNS y la usa para listar aplicaciones instaladas y lanzar paquetes.

• google_tv_remote: descubre dispositivos Google TV / Android TV a través de señales mDNS Google Cast y DIAL/SSDP, y luego modela el flujo de emparejamiento normal estilo control remoto.

• home_assistant: puente opcional de electrodomésticos amplio para televisores, luces, interruptores, termostatos y más.

• google_tv: respaldo ADB opcional solo para desarrollo/pruebas. Habilítalo con ENABLE_ADB_ADAPTER=true.

Inicio rápido

npm install
npm run build
npm start

Para desarrollo local:

npm run dev

Configuración del cliente

Compila el proyecto y luego agrega una entrada de servidor como esta a tu cliente MCP:

{
  "mcpServers": {
    "smart-appliance": {
      "command": "node",
      "args": ["/absolute/path/to/smart-appliance-mcp/dist/index.js"]
    }
  }
}

Si usas Home Assistant, incluye:

{
  "env": {
    "HOME_ASSISTANT_URL": "http://homeassistant.local:8123",
    "HOME_ASSISTANT_TOKEN": "your-long-lived-access-token"
  }
}

Para Google TV / Android TV, usa el flujo de emparejamiento de consumidor. El servidor descubre el televisor a través de señales de red local como mDNS _googlecast._tcp.local y DIAL/SSDP, y luego lleva la dirección internamente en el registro del dispositivo descubierto.

El flujo de usuario previsto es:

Discover my smart appliances.
Pair my living room TV.
Complete pairing with code 123456.
Turn the TV volume up.

Los dispositivos Google TV descubiertos usan provider: "google_tv_remote". El estado de emparejamiento se almacena localmente y se enruta a través del mismo registro de adaptadores que cualquier otro proveedor.

El adaptador de control remoto Google TV incluye descubrimiento local, emparejamiento de consumidor, controles remotos en vivo, sondeo de lanzamiento de aplicaciones y ejecución de comandos enrutada por adaptador. El adaptador ADB y la anulación GOOGLE_TV_REMOTE_DEVICES siguen disponibles solo como diagnósticos de desarrollo opcionales, no como configuración normal de usuario.

El descubrimiento de aplicaciones también está intencionalmente basado en adaptadores. En Google TV, discover_apps sondea las superficies de lanzamiento que el televisor expone localmente, como los endpoints DIAL /apps/<name>. Si el televisor no expone una lista de aplicaciones instaladas a través del control remoto de consumidor o las interfaces DIAL, el servidor lo informa claramente en lugar de fingir que un nombre de paquete adivinado o una URL de navegador es una ruta de lanzamiento de aplicación descubierta.

Para la mejor experiencia con Google TV, instala la aplicación complementaria opcional desde companion/google-tv. El complemento se ejecuta en el televisor, anuncia _smart-appliance._tcp.local, lista las aplicaciones instaladas del launcher Leanback con el PackageManager de Android y lanza aplicaciones localmente por nombre de paquete. Esta es la ruta para usuarios normales para aplicaciones como Crunchyroll que no exponen endpoints de lanzamiento DIAL.

Recomendaciones

La capa de recomendaciones prioriza lo local y es consciente del adaptador:

1. El historial de visualización del adaptador se usa primero cuando el dispositivo descubierto puede proporcionarlo.

2. record_watch_event almacena un historial de respaldo local ligero, incluidos aplicación, título, categorías, progreso y estado.

3. recommend_content fusiona el historial del televisor, el historial de respaldo local, un catálogo de contenido proporcionado y filas iniciales.

4. Los resultados se puntúan por novedad, superposición de categorías con visualización reciente, disponibilidad de aplicaciones, capacidad de lanzamiento y estado visto/descartado.

5. La respuesta separa las recommendations frescas de las coincidencias alreadyWatched y dismissed.

6. Cada recomendación incluye userSummary/userReasons para respuestas limpias orientadas al usuario, más campos detallados para planificación interna.

7. Las filas de recomendación accionables incluyen arte y acciones:

   • artwork.thumbnailUrl, posterUrl y backdropUrl para imágenes.

   • actions.preview para avances o clips de vista previa cuando un catálogo proporciona previewUrl/trailerUrl.

   • actions.primary como la acción de ver con un clic, expresada como una carga útil de llamada de herramienta MCP.

8. chatCards y format_recommendation_cards renderizan los mismos resultados para clientes de chat:

   • Las imágenes se incluyen solo cuando el catálogo proporciona arte específico del título.

   • Los enlaces de vista previa usan URLs web normales.

   • Los enlaces de ver/buscar usan URLs mcp://action?... que describen la llamada de herramienta MCP para que el cliente anfitrión la confirme y ejecute.

Si el adaptador actual no puede proporcionar el historial de visualización del televisor, list_watch_history, recommend_content y format_recommendation_cards devuelven un companionPrompt opcional. El protocolo de control remoto de consumidor de Google TV no expone el historial de streaming privado por aplicación, por lo que el historial de contenido exacto requiere una integración de proveedor o una fuente complementaria opcional del lado del televisor.

Los catálogos de proveedores cambian constantemente, por lo que los clientes de producción deben pasar filas de catálogo frescas a recommend_content desde una integración de proveedor, un conector de búsqueda o una fuente de medios propiedad del usuario. El MCP no afirma catálogos en vivo de Netflix/Crunchyroll a menos que un adaptador o conector los proporcione.

Cola de visualización del frontend

Ejecuta una interfaz local para recomendaciones accionables:

npm run ui

Abre http://localhost:5177. La interfaz renderiza la salida de recomendaciones MCP como tarjetas con arte, vista previa, acciones de ver con un clic, filtrado, búsqueda y un panel de ya visto. Usa el botón {} para pegar una respuesta de recommend_content desde cualquier cliente LLM.

Para tarjetas nativas de chat, llama a format_recommendation_cards con las mismas entradas que recommend_content. Devuelve cards más Markdown, usando enlaces en lugar de botones. Por defecto, los enlaces apuntan al endpoint de acción de la interfaz local, así que mantén npm run ui en ejecución:

[Watch on TV](http://127.0.0.1:5177/api/actions/run?payload=...)

Usa linkMode: "mcp_scheme" si un cliente anfitrión admite enlaces mcp://action?... directamente.

Flujo de ejemplo de herramientas

Primero pide al cliente:

Discover my smart appliances.

Luego:

Turn the living room TV volume up.

El servidor MCP maneja el enrutamiento internamente:

const device = registry.getDevice(deviceId);
const adapter = registry.adapterFor(device);
await adapter.control(device, request);

Añadir un nuevo adaptador

Crea una clase que implemente SmartApplianceAdapter:

export class SamsungTizenAdapter implements SmartApplianceAdapter {
  readonly id = "samsung_tizen";
  readonly label = "Samsung Tizen TV";

  async discover(options: DiscoveryOptions): Promise<SmartDevice[]> {
    return [];
  }

  async control(device: SmartDevice, request: ControlRequest) {
    return { ok: true };
  }
}

Luego regístrala en src/index.ts:

registry.register(new SamsungTizenAdapter());

El descubrimiento sigue siendo la fuente de verdad. Una vez que un televisor Samsung se descubre con provider: "samsung_tizen", todos los comandos futuros para ese deviceId se enrutan automáticamente al adaptador Samsung.

Notas

• El descubrimiento en la red local depende de que tu red permita multicast/SSDP.

• Algunos ecosistemas de televisores requieren emparejamiento antes del control; esos adaptadores deberían exponer un flujo de emparejamiento como herramienta o recurso MCP.

• Las recomendaciones de contenido son conscientes del adaptador, pero pueden fortalecerse combinando las capacidades del dispositivo con el contexto de gustos/perfil del cliente LLM anfitrión.