# 🏠 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](https://github.com/astral-sh/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
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**macOS/Linux:**

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### Configuración del Proyecto

**1. Clonar el repositorio:**

```powershell
git clone https://github.com/CrisDeCrisis/mcp-domotica-backend.git
cd mcp-domotica-backend
```

**2. Sincronizar dependencias:**

```powershell
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:**

```powershell
uv run servers/mcp_rooms.py
```

**Servidor de Gestión de Dispositivos:**

```powershell
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:

| 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í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** - [GitHub](https://github.com/CrisDeCrisis)
- **Vega, Tobías Joaquín** - [GitHub](https://github.com/Tobias-Vega)

---

## 🎓 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