🧠 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.

---

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
• Docker Compose

---

🧪 Instalación rápida

1. Clona el repositorio

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:

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

3. Ejecuta con Docker Compose

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:

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

---

🔄 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:

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.