MCP Domotica Backend

🏠 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 .venv e instala todas las dependencias necesarias. No es necesario activar manualmente el entorno virtual al utilizar uv 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 run ejecuta 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:

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ífico
• agregar_dispositivo(room_name, device_type, initial_state?) - Crea un nuevo dispositivo
• modificar_dispositivo(device_id, room?, state?) - Actualiza ubicación o estado de un dispositivo
• eliminar_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ón
• apagar_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 horno
• encender_horno(device_id) - Activa el horno con temperatura configurada
• apagar_horno(device_id) - Desactiva el horno completamente
• configurar_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 APIs
• uvicorn - Servidor ASGI de alto rendimiento para aplicaciones Python asíncronas
• mcp[cli] - Implementación del Model Context Protocol con herramientas CLI
• langchain - Framework para desarrollo de aplicaciones con modelos de lenguaje
• langchain-mcp-adapters - Adaptadores de integración entre LangChain y MCP
• langchain-ollama - Integración de LangChain con modelos Ollama locales
• httpx - Cliente HTTP asíncrono de próxima generación
• python-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

• González, Cristian David -
• Vega, Tobías Joaquín -

🎓 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