🏠 Sistema Domótico MCP
Sistema de gestión domótica basado en el Model Context Protocol (MCP) que permite controlar dispositivos inteligentes en diferentes habitaciones mediante servidores especializados. Implementado como una arquitectura de microservicios MCP para gestión eficiente de espacios residenciales y sus dispositivos asociados.
📋 Descripción General
Este proyecto implementa un sistema domótico completo utilizando el Model Context Protocol (MCP) con dos servidores independientes que operan de forma coordinada:
mcp_rooms: Servidor dedicado a la gestión completa de habitaciones (creación, modificación, eliminación y consulta)mcp_devices: Servidor especializado en el control de dispositivos domóticos (luces, termostatos, ventiladores y hornos)
Capacidades del Sistema
El sistema está diseñado para gestionar hasta 6 habitaciones con un máximo de 10 dispositivos por habitación, aplicando reglas de negocio específicas según el tipo de espacio y dispositivo. La persistencia de datos se maneja mediante archivos JSON con sincronización automática entre procesos.
✨ Características Principales
Dispositivos Soportados
El sistema implementa cuatro tipos de dispositivos inteligentes, cada uno con sus propias capacidades de control:
- 💡 Luces: Control binario de encendido/apagado
- 🌡️ Termostatos: Regulación de temperatura en rango de 16°C a 32°C
- 🌀 Ventiladores: Control de velocidad en 6 niveles (0 = apagado, 1-5 = velocidades)
- 🔥 Hornos: Gestión de temperatura (160°C - 240°C), temporizador (0-240 minutos) y estado activo/inactivo
Tipos de Habitaciones
El sistema reconoce cinco categorías de espacios residenciales:
- 🍽️ Comedor: Admite todos los tipos de dispositivos
- 🍳 Cocina: Admite todos los tipos de dispositivos (único espacio donde se permite horno)
- 🚿 Baño: Restricción de seguridad - únicamente luces
- 🛋️ Living: Admite todos los dispositivos excepto horno
- 🛏️ Dormitorio: Admite todos los dispositivos excepto horno
Reglas de Negocio
El sistema implementa las siguientes restricciones para garantizar coherencia y seguridad:
- Límite máximo de 6 habitaciones en el sistema
- Límite máximo de 10 dispositivos por habitación
- Restricción de ubicación: hornos únicamente en cocina
- Restricción de dispositivos: baños limitados a iluminación
- Asignación automática de nombres: numeración incremental para habitaciones duplicadas (ej: "dormitorio", "dormitorio 2")
🚀 Instalación y Configuración
Requisitos del Sistema
- Python: Versión 3.13 o superior
- uv: Gestor de paquetes y entornos virtuales para Python (Astral uv)
Instalación de uv
El proyecto utiliza uv como gestor de dependencias por su velocidad y eficiencia. Si aún no lo tiene instalado:
Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
Configuración del Proyecto
1. Clonar el repositorio:
git clone https://github.com/CrisDeCrisis/mcp-domotica-backend.git
cd mcp-domotica-backend
2. Sincronizar dependencias:
uv sync
Nota: Este comando lee automáticamente el archivo
pyproject.toml, crea el entorno virtual.venve instala todas las dependencias necesarias. No es necesario activar manualmente el entorno virtual al utilizaruv run.
🎮 Ejecución de Servidores
Iniciar Servidores MCP
Cada servidor puede ejecutarse de forma independiente utilizando uv run:
Servidor de Gestión de Habitaciones:
uv run servers/mcp_rooms.py
Servidor de Gestión de Dispositivos:
uv run servers/mcp_devices.py
Nota: El comando
uv runejecuta automáticamente los scripts en el entorno virtual del proyecto, eliminando la necesidad de activación manual del entorno.
📚 Arquitectura del Proyecto
Estructura de Directorios
backend/
├── servers/
│ ├── mcp_rooms.py # Servidor MCP para gestión de habitaciones
│ └── mcp_devices.py # Servidor MCP para gestión de dispositivos
├── models.py # Definición de modelos de datos (Device, Room)
├── storage.py # Capa de persistencia y almacenamiento
├── domotica_data.json # Base de datos JSON para persistencia
├── pyproject.toml # Configuración de proyecto y dependencias
└── README.md # Documentación del proyecto
Componentes del Sistema
- Servidores MCP: Implementan los endpoints del Model Context Protocol para cada dominio (habitaciones y dispositivos)
- Modelos: Clases Python que definen la estructura de datos de habitaciones y dispositivos
- Capa de Almacenamiento: Gestiona la persistencia en JSON con sincronización automática
- Archivo de Datos: Almacenamiento persistente en formato JSON con estado del sistema completo
🔌 API de Herramientas MCP
Servidor de Habitaciones (mcp_rooms)
Proporciona operaciones CRUD completas para la gestión de espacios:
| Herramienta | Descripción |
|---|---|
consultar_habitaciones() | Retorna lista completa de habitaciones |
consultar_habitacion(room_name) | Obtiene información detallada de una habitación |
agregar_habitacion(room_type) | Crea una nueva habitación del tipo especificado |
modificar_habitacion(old_name, new_name) | Actualiza el nombre de una habitación existente |
eliminar_habitacion(room_name) | Elimina una habitación (debe estar vacía) |
Servidor de Dispositivos (mcp_devices)
Proporciona control granular sobre dispositivos inteligentes:
Operaciones Generales
consultar_dispositivos(room_name?)- Obtiene lista de dispositivos (opcional: filtrar por habitación)consultar_dispositivo(device_id)- Obtiene información detallada de un dispositivo específicoagregar_dispositivo(room_name, device_type, initial_state?)- Crea un nuevo dispositivomodificar_dispositivo(device_id, room?, state?)- Actualiza ubicación o estado de un dispositivoeliminar_dispositivo(device_id)- Elimina un dispositivo del sistema
Control de Iluminación
alternar_luz(device_id)- Cambia el estado actual (encendido ↔ apagado)encender_luz(device_id)- Activa la iluminaciónapagar_luz(device_id)- Desactiva la iluminación
Control de Climatización (Termostatos)
ajustar_termostato(device_id, temperature)- Establece temperatura específica (16°C - 32°C)subir_temperatura(device_id, grados?)- Incrementa temperatura (predeterminado: 1°C)bajar_temperatura(device_id, grados?)- Reduce temperatura (predeterminado: 1°C)
Control de Ventilación
ajustar_ventilador(device_id, speed)- Establece velocidad (0: apagado, 1-5: velocidades)apagar_ventilador(device_id)- Detiene el ventilador (velocidad 0)
Control de Hornos
ajustar_horno(device_id, temperature?, timer?, active?)- Configuración completa del hornoencender_horno(device_id)- Activa el horno con temperatura configuradaapagar_horno(device_id)- Desactiva el horno completamenteconfigurar_temporizador_horno(device_id, minutos)- Establece temporizador (0-240 minutos)
📦 Dependencias del Proyecto
El proyecto utiliza las siguientes tecnologías y bibliotecas, definidas en pyproject.toml:
Dependencias Principales
fastapi- Framework web moderno y de alto rendimiento para construcción de APIsuvicorn- Servidor ASGI de alto rendimiento para aplicaciones Python asíncronasmcp[cli]- Implementación del Model Context Protocol con herramientas CLIlangchain- Framework para desarrollo de aplicaciones con modelos de lenguajelangchain-mcp-adapters- Adaptadores de integración entre LangChain y MCPlangchain-ollama- Integración de LangChain con modelos Ollama localeshttpx- Cliente HTTP asíncrono de próxima generaciónpython-dotenv- Gestión de variables de entorno desde archivos .env
💾 Sistema de Persistencia
Mecanismo de Almacenamiento
El sistema implementa persistencia automática mediante archivo JSON (domotica_data.json) con las siguientes características:
- Guardado Automático: Cada modificación del estado se persiste inmediatamente
- Carga al Inicio: El sistema recupera el estado previo al iniciar los servidores
- Estado Inicial: Si no existe archivo de datos, se crea una configuración predeterminada (1 living con 1 luz y 1 termostato)
- Sincronización Multi-proceso: La función
reload()permite sincronizar el estado entre múltiples instancias
Formato de Datos
El archivo JSON mantiene un registro estructurado de:
- Colección completa de habitaciones con sus metadatos
- Inventario de dispositivos con sus configuraciones y estados actuales
- Relaciones entre habitaciones y dispositivos asignados
👨💻 Desarrolladores
🎓 Contexto Académico
Proyecto: Trabajo Práctico Integrador - Sistema Domótico con MCP
Asignatura: Modelos de Aplicación de la Inteligencia Artificial
Docentes:
- Acosta Gabriel
- Flavian Dante
Institución: Instituto Politécnico Formosa
Programa Académico: Tecnicatura Superior en Desarrollo de Software Multiplataforma