# 🧠 MCP: Multi-Agent Control Point

Este proyecto implementa un servidor multi-agente que enruta preguntas del usuario a un modelo LLM o a agentes especializados (como fecha, ubicación, clima o un experto técnico). Incluye una interfaz web sencilla construida con Streamlit para facilitar su uso.

---

```mermaid
graph TD
    GUI[Interfaz Web Streamlit] -->|HTTP| API[API REST FastAPI]
    API --> Router[Router LLM]
    Router --> Fecha[Agente Fecha]
    Router --> Ubicacion[Agente Ubicacion]
    Router --> Clima[Agente Clima]
    Router --> Experto[Agente Experto]
    Clima --> Ubicacion
    Router --> Contexto[Base de datos SQLite]
    API --> Ollama[Wrapper Ollama]

    subgraph Docker
        GUI
        API
    end

    subgraph Sistema Interno
        Router
        Fecha
        Ubicacion
        Clima
        Experto
        Contexto
        Ollama
    end

```

---

## 🚀 Características

- 🌐 Backend con FastAPI
- 🧠 Agentes especializados (fecha, ubicación, clima, experto LLM)
- 🧩 Sistema de agentes extensible y modular con herencia
- ⚙️ Herencia común `AgenteBase` para manejo uniforme de errores y respuestas
- 🤖 Lógica inteligente para que los agentes colaboren entre sí
- 🖥️ Interfaz visual con Streamlit (GUI)
- 🐳 Contenedores Docker para fácil despliegue
- 🔌 Comunicación cliente-servidor lista para red local o remoto

---

## 📁 Estructura del proyecto

```
MCP/
├── core/
│   ├── ollama_wrapper.py       # Encapsula la lógica para interactuar con modelos LLM en Ollama
│   ├── context_loader.py       # Carga contexto adicional desde base de datos u otras fuentes
│   └── router_llm.py           # Router inteligente que decide qué agente usar en base a la consulta
├── agents/                     # Carpeta que contiene todos los agentes disponibles del sistema
├── server/
│   ├── mcp_server.py           # Punto central que gestiona los agentes registrados y el procesamiento de mensajes
│   └── api.py                  # Define la API REST usando FastAPI para comunicación con la GUI u otros clientes
├── gui/
│   ├── app.py                  # Aplicación Streamlit que actúa como interfaz gráfica del sistema
│   └── .streamlit/
│       └── secrets.toml        # Archivo de configuración que contiene la URL del backend para la GUI
├── utils/
│   ├── db_utils.py             # Funciones auxiliares para conectarse y consultar la base de datos SQLite
│   ├── agente_base.py          # Clase base AgenteBase, común a todos los agentes personalizados
│   └── json_parser.py          # Utilidad para dividir respuestas JSON en partes más manejables
├── database/
│   ├── context.db              # Base de datos SQLite con información contextual para los agentes o el LLM
│   ├── comprobar_db.py         # Script que valida la existencia y consistencia de la base de datos
│   └── create_db.py            # Script para generar y poblar la base de datos desde cero
├── config.py                   # Archivo central de configuración del sistema (rutas, modelos, flags, etc.)
├── requirements.txt            # Lista de dependencias de Python necesarias para ejecutar el proyecto
├── Dockerfile.backend          # Dockerfile para construir el contenedor del backend (API + lógica de agentes)
├── Dockerfile.frontend         # Dockerfile para construir el contenedor de la interfaz Streamlit
└── docker-compose.yml          # Archivo para levantar los servicios frontend y backend de forma conjunta

```

---

## ⚙️ Requisitos

- [Docker](https://www.docker.com/)
- [Docker Compose](https://docs.docker.com/compose/)

---

## 🧪 Instalación rápida

### 1. Clona el repositorio

```bash
git clone https://github.com/tu-usuario/MCP.git
cd MCP
```

### 2. Crea archivo de configuración para Streamlit

Dentro del directorio `gui`, crea el archivo:

```
gui/.streamlit/secrets.toml
```

Con el siguiente contenido:

```toml
server_url = "http://backend:8000/process"
```

### 3. Ejecuta con Docker Compose

```bash
docker-compose up --build
```

Esto construirá y levantará dos contenedores:

- Backend en `http://localhost:8000`
- Interfaz gráfica en `http://localhost:8501`

---

## 🌍 Acceso desde otra máquina (opcional)

1. Asegúrate de exponer correctamente los puertos (`8000`, `8501`).
2. Usa la IP de la máquina servidor en lugar de `localhost` en `secrets.toml`.
3. También puedes configurar redes Docker personalizadas para acceso cruzado entre hosts.

---

## 📦 Para producción

Puedes ejecutar solo el backend si deseas integrarlo con otra interfaz:

```bash
docker build -f Dockerfile.backend -t mcp_backend .
docker run -p 8000:8000 mcp_backend
```

---

## ✨ Ejemplo de uso

En la interfaz web, puedes escribir preguntas como:

- `¿Qué día es hoy?`
- `¿Dónde estoy?`
- `¿Qué clima hace?`
- `Explícame qué es Python`

La aplicación decidirá si responder directamente o delegar la pregunta a un agente.

---

## 🛠️ Agentes disponibles

| Agente       | Función                                 |
|--------------|------------------------------------------|
| FECHA        | Devuelve la fecha y hora actuales        |
| UBICACION    | Detecta la ciudad y país mediante IP     |
| CLIMA        | Devuelve el clima en la ubicación actual |

---

## 🔄 Interacción entre agentes

El agente de clima ahora usa directamente el agente de ubicación para determinar coordenadas geográficas (`lat`, `lon`) y ciudad antes de consultar el clima, permitiendo respuestas adaptadas al lugar real del usuario. Esto mejora la modularidad y colaboración entre agentes.

---

## 🧩 Cómo crear un nuevo agente

1. Crea una clase que herede de AgenteBase:

```bash
from agentes.base import AgenteBase

class AgenteEjemplo(AgenteBase):
    patrones = [r"expresiones.*clave", r"otra.*forma.*de.*preguntar"]

    def agente(self) -> dict:
        datos = {"respuesta": "Soy un agente de ejemplo"}
        return {"success": True, "data": datos}
```

2. Especifica los patrones para detectar preguntas relevantes.

3. Implementa `agente()` que devuelve un dict con la clave success y data o error.

4. El agente usará automáticamente el LLM indicado para generar respuestas naturales basadas en su data.

---

## ⚠️ Notas técnicas importantes

- Todos los agentes heredan de AgenteBase, lo que gestiona:

    - Errores estándar

    - Conversión de datos a respuesta natural vía LLM

- El método agente() debe devolver un diccionario estructurado.

- Cada agente especifica qué modelo de LLM utilizar (`llm_simple` o `llm_experto`).

## 📄 Licencia

Este proyecto está licenciado bajo MIT License.

---

## 🙋‍♂️ Autor

Desarrollado por Alejandro Gómez Sierra.