Servidor de protocolo de contexto de modelo para Home Assistant

El servidor utiliza el protocolo MCP para compartir el acceso a una instancia local de Home Assistant con una aplicación LLM.

Un potente puente entre su instancia de Home Assistant y los Modelos de Aprendizaje de Lenguaje (LLM), que permite el control y la monitorización del lenguaje natural de sus dispositivos domésticos inteligentes mediante el Protocolo de Contexto de Modelo (MCP). Este servidor proporciona una API integral para gestionar todo su ecosistema de Home Assistant, desde el control de dispositivos hasta la administración del sistema.

Características

• 🎮 Control de dispositivos : controla cualquier dispositivo Home Assistant mediante lenguaje natural

• 🔄 Actualizaciones en tiempo real : Obtenga actualizaciones instantáneas a través de eventos enviados por el servidor (SSE)

• 🤖 Gestión de automatización : crea, actualiza y gestiona automatizaciones

• 📊 Monitoreo de estado : rastrea y consulta los estados del dispositivo

• 🔐 Seguro : Autenticación basada en tokens y limitación de velocidad

• Compatible con dispositivos móviles : funciona con cualquier cliente compatible con HTTP

Related MCP server: Home Assistant MCP

Actualizaciones en tiempo real con SSE

El servidor incluye un potente sistema de Eventos Enviados por el Servidor (SSE) que proporciona actualizaciones en tiempo real desde su instancia de Home Assistant. Esto le permite:

• 🔄 Obtenga cambios de estado instantáneos para cualquier dispositivo

• 📡 Supervisar los desencadenadores y ejecuciones de automatización

• 🎯 Suscríbete a dominios o entidades específicas

• 📊 Realizar un seguimiento de las llamadas de servicio y las ejecuciones de scripts

Ejemplo rápido de SSE

const eventSource = new EventSource(
  'http://localhost:3000/subscribe_events?token=YOUR_TOKEN&domain=light'
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Update received:', data);
};

Consulte SSE_API.md para obtener la documentación completa del sistema SSE.

Tabla de contenido

• Características principales

• Prerrequisitos

• Instalación

  • Configuración básica

  • Configuración de Docker (recomendada)

• Configuración

• Desarrollo

• Referencia de API

  • Control de dispositivos

  • Gestión de complementos

  • Gestión de paquetes

  • Gestión de la automatización

• Integración del lenguaje natural

• Solución de problemas

• Estado del proyecto

• Contribuyendo

• Recursos

• Licencia

Características principales

Funcionalidad principal 🎮

• Control de dispositivos inteligentes

  • 💡 Luces : Brillo, temperatura de color, color RGB

  • 🌡️ Clima : Temperatura, modos HVAC, modos de ventilador, humedad

  • 🚪 Cubiertas : Control de posición e inclinación

  • 🔌 Interruptores : Control de encendido/apagado

  • 🚨 Sensores y contactos : Monitoreo de estado

  • 🎵 Reproductores multimedia : Control de reproducción, volumen, selección de fuente

  • 🌪️ Ventiladores : Velocidad, oscilación, dirección

  • 🔒 Cerraduras : Control de bloqueo/desbloqueo

  • 🧹 Aspiradoras : Arrancar, parar, volver a la base

  • 📹 Cámaras : Detección de movimiento, instantáneas

Gestión del sistema 🛠️

• Gestión de complementos

  • Explorar los complementos disponibles

  • Instalar/desinstalar complementos

  • Iniciar/detener/reiniciar complementos

  • Gestión de versiones

  • Acceso a la configuración

• Gestión de paquetes (HACS)

  • Integración con la tienda comunitaria de Home Assistant

  • Admite múltiples tipos de paquetes:

    • Integraciones personalizadas

    • Temas de interfaz

    • Scripts de Python

    • Aplicaciones AppDaemon

    • Aplicaciones NetDaemon

  • Control de versiones y actualizaciones

  • Gestión de repositorios

• Gestión de la automatización

  • Crear y editar automatizaciones

  • Opciones de configuración avanzadas:

    • Múltiples tipos de disparadores

    • Condiciones complejas

    • Secuencias de acción

    • Modos de ejecución

  • Duplicar y modificar automatizaciones existentes

  • Habilitar o deshabilitar reglas de automatización

  • Activar la automatización manualmente

Características de la arquitectura 🏗️

• Organización inteligente

  • Agrupación de dispositivos por área y piso

  • Monitoreo y consulta del estado

  • Conciencia del contexto inteligente

  • Acceso a datos históricos

• Arquitectura robusta

  • Manejo integral de errores

  • Validación estatal

  • Integración segura de API

  • Seguridad de tipos de TypeScript

  • Amplia cobertura de pruebas

Prerrequisitos

• Node.js 20.10.0 o superior

• Gestor de paquetes NPM

• Docker Compose para la contenedorización

• Ejecución de la instancia de Home Assistant

• Token de acceso de larga duración de Home Assistant ( Cómo obtener el token )

• HACS instalado para funciones de gestión de paquetes

• Acceso de supervisor para la gestión de complementos

Instalación

Configuración básica

# Clone the repository
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
cd homeassistant-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuración de Docker (recomendada)

El proyecto incluye soporte para Docker para una fácil implementación y entornos consistentes en diferentes plataformas.

1. Clonar el repositorio:

   git clone https://github.com/jango-blockchained/homeassistant-mcp.git
   cd homeassistant-mcp

2. Configurar el entorno:

   cp .env.example .env

   Edite el archivo .env con la configuración de Home Assistant:

   # Home Assistant Configuration
   HASS_HOST=http://homeassistant.local:8123
   HASS_TOKEN=your_home_assistant_token
   HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket
   
   # Server Configuration
   PORT=3000
   NODE_ENV=production
   DEBUG=false

3. Construya y ejecute con Docker Compose:

   # Build and start the containers
   docker compose up -d
   
   # View logs
   docker compose logs -f
   
   # Stop the service
   docker compose down

4. Verifique la instalación: El servidor debería estar ejecutándose en http://localhost:3000 . Puede verificar el estado del punto final en http://localhost:3000/health .

5. Actualizar la aplicación:

   # Pull the latest changes
   git pull
   
   # Rebuild and restart the containers
   docker compose up -d --build

Configuración de Docker

La configuración de Docker incluye:

• Construcción en varias etapas para un tamaño de imagen óptimo

• Controles de salud para la monitorización de contenedores

• Montaje de volumen para la configuración del entorno

• Reinicio automático del contenedor en caso de fallo

• Puerto 3000 expuesto para acceso a API

Variables de entorno de Docker Compose

Todas las variables de entorno se pueden configurar en el archivo .env . Se admiten las siguientes variables:

• HASS_HOST : URL de su instancia de Home Assistant

• HASS_TOKEN : Token de acceso de larga duración para Home Assistant

• HASS_SOCKET_URL : URL de WebSocket para Home Assistant

• PORT : Puerto del servidor (predeterminado: 3000)

• NODE_ENV : Entorno (producción/desarrollo)

• DEBUG : Habilitar el modo de depuración (verdadero/falso)

Configuración

Variables de entorno

# Home Assistant Configuration
HASS_HOST=http://homeassistant.local:8123  # Your Home Assistant instance URL
HASS_TOKEN=your_home_assistant_token       # Long-lived access token
HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket  # WebSocket URL

# Server Configuration
PORT=3000                # Server port (default: 3000)
NODE_ENV=production     # Environment (production/development)
DEBUG=false            # Enable debug mode

# Test Configuration
TEST_HASS_HOST=http://localhost:8123  # Test instance URL
TEST_HASS_TOKEN=test_token           # Test token

Archivos de configuración

1. Desarrollo : Copiar .env.example a .env.development

2. Producción : Copiar .env.example a .env.production

3. Prueba : Copiar .env.example a .env.test

Agregar a Claude Desktop (u otros clientes)

Para usar su nuevo servidor MCP de Home Assistant, puede agregar Claude Desktop como cliente. Agregue lo siguiente a la configuración. Tenga en cuenta que esto ejecutará el MCP dentro de Claude y no funciona con el método Docker.

{
  "homeassistant": {
    "command": "node",
    "args": [<path/to/your/dist/folder>]
    "env": {
      NODE_ENV=development
      HASS_HOST=http://homeassistant.local:8123
      HASS_TOKEN=your_home_assistant_token
      PORT=3000
      HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket
      LOG_LEVEL=debug
    }
  }
}

Referencia de API

Control de dispositivos

Controles de entidad comunes

{
  "tool": "control",
  "command": "turn_on",  // or "turn_off", "toggle"
  "entity_id": "light.living_room"
}

Control de luz

{
  "tool": "control",
  "command": "turn_on",
  "entity_id": "light.living_room",
  "brightness": 128,
  "color_temp": 4000,
  "rgb_color": [255, 0, 0]
}

Gestión de complementos

Lista de complementos disponibles

{
  "tool": "addon",
  "action": "list"
}

Instalar complemento

{
  "tool": "addon",
  "action": "install",
  "slug": "core_configurator",
  "version": "5.6.0"
}

Administrar el estado del complemento

{
  "tool": "addon",
  "action": "start",  // or "stop", "restart"
  "slug": "core_configurator"
}

Gestión de paquetes

Lista de paquetes HACS

{
  "tool": "package",
  "action": "list",
  "category": "integration"  // or "plugin", "theme", "python_script", "appdaemon", "netdaemon"
}

Instalar paquete

{
  "tool": "package",
  "action": "install",
  "category": "integration",
  "repository": "hacs/integration",
  "version": "1.32.0"
}

Gestión de la automatización

Crear automatización

{
  "tool": "automation_config",
  "action": "create",
  "config": {
    "alias": "Motion Light",
    "description": "Turn on light when motion detected",
    "mode": "single",
    "trigger": [
      {
        "platform": "state",
        "entity_id": "binary_sensor.motion",
        "to": "on"
      }
    ],
    "action": [
      {
        "service": "light.turn_on",
        "target": {
          "entity_id": "light.living_room"
        }
      }
    ]
  }
}

Automatización duplicada

{
  "tool": "automation_config",
  "action": "duplicate",
  "automation_id": "automation.motion_light"
}

Funciones principales

Gestión del Estado

GET /api/state
POST /api/state

Gestiona el estado actual del sistema.

Ejemplo de solicitud:

POST /api/state
{
  "context": "living_room",
  "state": {
    "lights": "on",
    "temperature": 22
  }
}

Actualizaciones de contexto

POST /api/context

Actualiza el contexto actual con nueva información.

Ejemplo de solicitud:

POST /api/context
{
  "user": "john",
  "location": "kitchen",
  "time": "morning",
  "activity": "cooking"
}

Puntos finales de acción

Ejecutar acción

POST /api/action

Ejecuta una acción especificada con los parámetros dados.

Ejemplo de solicitud:

POST /api/action
{
  "action": "turn_on_lights",
  "parameters": {
    "room": "living_room",
    "brightness": 80
  }
}

Acciones por lotes

POST /api/actions/batch

Ejecuta múltiples acciones en secuencia.

Ejemplo de solicitud:

POST /api/actions/batch
{
  "actions": [
    {
      "action": "turn_on_lights",
      "parameters": {
        "room": "living_room"
      }
    },
    {
      "action": "set_temperature",
      "parameters": {
        "temperature": 22
      }
    }
  ]
}

Funciones de consulta

Obtener acciones disponibles

GET /api/actions

Devuelve una lista de todas las acciones disponibles.

Ejemplo de respuesta:

{
  "actions": [
    {
      "name": "turn_on_lights",
      "parameters": ["room", "brightness"],
      "description": "Turns on lights in specified room"
    },
    {
      "name": "set_temperature",
      "parameters": ["temperature"],
      "description": "Sets temperature in current context"
    }
  ]
}

Consulta de contexto

GET /api/context?type=current

Recupera información de contexto.

Ejemplo de respuesta:

{
  "current_context": {
    "user": "john",
    "location": "kitchen",
    "time": "morning",
    "activity": "cooking"
  }
}

Eventos de WebSocket

El servidor admite actualizaciones en tiempo real a través de conexiones WebSocket.

// Client-side connection example
const ws = new WebSocket('ws://localhost:3000/ws');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received update:', data);
};

Eventos apoyados

• state_change : Se emite cuando cambia el estado del sistema

• context_update : se emite cuando se actualiza el contexto

• action_executed : Se emite cuando se completa una acción

• error : se emite cuando ocurre un error

Ejemplo de datos de evento:

{
  "event": "state_change",
  "data": {
    "previous_state": {
      "lights": "off"
    },
    "current_state": {
      "lights": "on"
    },
    "timestamp": "2024-03-20T10:30:00Z"
  }
}

Manejo de errores

Todos los puntos finales devuelven códigos de estado HTTP estándar:

• 200: Éxito

• 400: Solicitud incorrecta

• 401: No autorizado

• 403: Prohibido

• 404: No encontrado

• 500: Error interno del servidor

Formato de respuesta de error:

{
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "Missing required parameter: room",
    "details": {
      "missing_fields": ["room"]
    }
  }
}

Limitación de velocidad

La API implementa una limitación de velocidad para evitar abusos:

• 100 solicitudes por minuto por IP para puntos finales regulares

• 1000 solicitudes por minuto por IP para conexiones WebSocket

Cuando se excede el límite de velocidad, el servidor devuelve:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "reset_time": "2024-03-20T10:31:00Z"
  }
}

Ejemplo de uso

Usando curl

# Get current state
curl -X GET \
  http://localhost:3000/api/state \
  -H 'Authorization: ApiKey your_api_key_here'

# Execute action
curl -X POST \
  http://localhost:3000/api/action \
  -H 'Authorization: ApiKey your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "turn_on_lights",
    "parameters": {
      "room": "living_room",
      "brightness": 80
    }
  }'

Usando JavaScript

// Execute action
async function executeAction() {
  const response = await fetch('http://localhost:3000/api/action', {
    method: 'POST',
    headers: {
      'Authorization': 'ApiKey your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      action: 'turn_on_lights',
      parameters: {
        room: 'living_room',
        brightness: 80
      }
    })
  });
  
  const data = await response.json();
  console.log('Action result:', data);
}

Desarrollo

# Development mode with hot reload
npm run dev

# Build project
npm run build

# Production mode
npm run start

# Run tests
npx jest --config=jest.config.cjs

# Run tests with coverage
npx jest --coverage

# Lint code
npm run lint

# Format code
npm run format

Solución de problemas

Problemas comunes

1. Versión de Node.js (

   • Solución: Actualizar a Node.js 20.10.0+ GXP38

2. Problemas de conexión

   • Verificar que Home Assistant se esté ejecutando

   • Comprobar la accesibilidad HASS_HOST

   • Validar permisos de token

   • Asegúrese de la conexión WebSocket para actualizaciones en tiempo real

3. Problemas de gestión de complementos

   • Verificar el acceso del supervisor

   • Comprobar la compatibilidad de los complementos

   • Validar los recursos del sistema

4. Problemas de integración de HACS

   • Verificar la instalación de HACS

   • Comprobar el estado de la integración de HACS

   • Validar el acceso al repositorio

5. Problemas de automatización

   • Verificar la disponibilidad de la entidad

   • Comprobar las condiciones de activación

   • Validar llamadas de servicio

   • Supervisar los registros de ejecución

Estado del proyecto

✅ Completo

• Acceso a entidades, pisos y áreas

• Control de dispositivos (luces, clima, cubiertas, interruptores, contactos)

• Sistema de gestión de complementos

• Gestión de paquetes a través de HACS

• Configuración de automatización avanzada

• Gestión básica del estado

• Manejo de errores y validación

• Contenedorización de Docker

• Configuración de prueba de Jest

• Integración con TypeScript

• Gestión de variables ambientales

• Integración de la API de Home Assistant

• Documentación del proyecto

🚧 En progreso

• Implementación de WebSocket para actualizaciones en tiempo real

• Funciones de seguridad mejoradas

• Optimización de la organización de herramientas

• Optimización del rendimiento

• Integración del contexto de recursos

• Generación de documentación de API

• Integración de escritorio multiplataforma

• Recuperación avanzada de errores

• Pruebas de indicaciones personalizadas

• Integración mejorada con macOS

• Mejoras en la seguridad de tipos

• Ampliación de la cobertura de pruebas

Contribuyendo

1. Bifurcar el repositorio

2. Crear una rama de características

3. Implementa tus cambios

4. Agregar pruebas para nuevas funcionalidades

5. Asegúrese de que todas las pruebas pasen

6. Enviar una solicitud de extracción

Recursos

• Documentación de MCP

• Documentos del Asistente del Hogar

• API REST de alta disponibilidad

• Documentación de HACS

• Documentación de TypeScript

Licencia

Licencia MIT - Ver archivo LICENCIA