🧠 Bedrock MCP Agent

Agente de AWS Bedrock integrado con Model Context Protocol (MCP)

Una aplicación completa que permite interactuar con los modelos de lenguaje de AWS Bedrock a través de una interfaz web moderna y un backend Python robusto.

🚀 Características

🐍 Backend Python con integración completa a AWS Bedrock
⚛️ Frontend React moderno y responsivo
🤖 Soporte múltiples modelos: Claude 3, Titan, Llama 2, y más
📡 Protocolo MCP para formateo estandarizado de respuestas
⚙️ Configuración flexible de parámetros (temperatura, tokens, región)
💬 Interfaz de chat interactiva con historial de conversaciones
🔄 Scripts de inicio automatizados para Windows, Linux y macOS
📊 Monitoreo en tiempo real del estado del servidor
🛡️ Manejo robusto de errores y logging completo

📁 Estructura del Proyecto

bedrock-mcp-agent/
├── 📄 README.md                 # Documentación del proyecto
├── 🐍 bedrock_mcp_agent.py     # Agente principal de Python
├── 🌐 app.py                   # Servidor Flask backend
├── 🎨 frontend.html            # Interfaz web React
├── 📦 requirements.txt         # Dependencias de Python
├── ⚙️ .env.example             # Plantilla de variables de entorno
├── 🚫 .gitignore               # Archivos excluidos de Git
├── 🚀 start.sh                 # Script de inicio para Linux/macOS
└── 🚀 start.bat                # Script de inicio para Windows

📋 Requisitos Previos

AWS

✅ Cuenta de AWS activa
✅ Acceso habilitado a AWS Bedrock
✅ Credenciales AWS configuradas (IAM user o role)
✅ Permisos para bedrock:InvokeModel y bedrock:ListFoundationModels

Software

✅ Python 3.8 o superior
✅ pip (gestor de paquetes de Python)
✅ Navegador web moderno

⚡ Inicio Rápido

Método 1: Scripts Automatizados (Recomendado)

Para Linux/macOS:

git clone https://github.com/harold-moncaleano/bedrock-mcp-agent.git
cd bedrock-mcp-agent
chmod +x start.sh
./start.sh

Para Windows:

git clone https://github.com/harold-moncaleano/bedrock-mcp-agent.git
cd bedrock-mcp-agent
start.bat

Los scripts automatizados se encargan de:

✅ Verificar Python y pip
✅ Crear el entorno virtual
✅ Instalar dependencias automáticamente
✅ Configurar variables de entorno
✅ Ofrecer opciones de ejecución interactivas

Método 2: Instalación Manual

1. Clonar el repositorio

git clone https://github.com/harold-moncaleano/bedrock-mcp-agent.git
cd bedrock-mcp-agent

2. Crear entorno virtual

python -m venv venv

# Activar entorno virtual
# Linux/macOS:
source venv/bin/activate
# Windows:
venv\Scripts\activate

3. Instalar dependencias

pip install -r requirements.txt

4. Configurar variables de entorno

cp .env.example .env
# Editar .env con tus credenciales AWS

⚙️ Configuración AWS

Opción 1: Variables de entorno (.env)

# Editar archivo .env
AWS_ACCESS_KEY_ID=tu_access_key_id
AWS_SECRET_ACCESS_KEY=tu_secret_access_key
AWS_DEFAULT_REGION=us-east-1

Opción 2: AWS CLI

aws configure

Opción 3: IAM Role (EC2)

Si ejecutas en EC2, el agente usará automáticamente el IAM role de la instancia.

Habilitar modelos en AWS Bedrock

Ve a la consola AWS Bedrock
Navega a "Model access"
Solicita acceso a los modelos:
- ✅ Anthropic Claude 3 Sonnet
- ✅ Anthropic Claude 3 Haiku
- ✅ Amazon Titan Text Premier
- ✅ Meta Llama 2 70B Chat

🚀 Ejecución

Aplicación Web Completa

# Ejecutar servidor Flask
python app.py

# Abrir en navegador
# http://localhost:5000

El servidor Flask:

🌐 Sirve el frontend en la ruta principal /
📡 Expone API REST en /api/*
🔍 Incluye endpoint de salud en /health
📊 Proporciona configuración en /api/config

Solo Backend (Línea de comandos)

# Ejecutar agente directamente
python bedrock_mcp_agent.py

🌐 API Endpoints

Endpoint	Método	Descripción
`/`	GET	Interfaz web principal
`/health`	GET	Estado del servidor y agente
`/api/models`	GET	Lista de modelos disponibles
`/api/chat`	POST	Enviar mensaje a modelo
`/api/config`	GET	Configuración del servidor

Ejemplo de uso de API

// Enviar mensaje
const response = await fetch('http://localhost:5000/api/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model_id: 'anthropic.claude-3-sonnet-20240229-v1:0',
    prompt: '¿Qué es AWS Bedrock?',
    temperature: 0.7,
    max_tokens: 1000
  })
});

🎛️ Configuración Avanzada

Variables de entorno disponibles

Variable	Descripción	Valor por defecto
`AWS_ACCESS_KEY_ID`	ID de clave de acceso AWS	-
`AWS_SECRET_ACCESS_KEY`	Clave secreta AWS	-
`AWS_DEFAULT_REGION`	Región AWS	`us-east-1`
`FLASK_HOST`	Host del servidor Flask	`0.0.0.0`
`FLASK_PORT`	Puerto del servidor Flask	`5000`
`FLASK_DEBUG`	Modo debug	`True`
`SECRET_KEY`	Clave secreta Flask	`bedrock-mcp-*`

Modelos soportados

Modelo	ID	Proveedor	Descripción
Claude 3 Sonnet	`anthropic.claude-3-sonnet-20240229-v1:0`	Anthropic	Balanceado para tareas complejas
Claude 3 Haiku	`anthropic.claude-3-haiku-20240307-v1:0`	Anthropic	Rápido y eficiente
Titan Text Premier	`amazon.titan-text-premier-v1:0`	Amazon	Modelo avanzado de Amazon
Titan Text Express	`amazon.titan-text-express-v1`	Amazon	Modelo rápido de Amazon
Llama 2 70B Chat	`meta.llama2-70b-chat-v1`	Meta	Conversacional de Meta

🎯 Funcionalidades de la Interfaz

Panel de Configuración

🔧 Selector de modelos dinámico desde AWS
🌡️ Control de temperatura (0-1) con slider
🔢 Configuración de tokens máximos (1-4000)
🌍 Selector de región AWS

Chat Interactivo

💬 Historial de conversaciones persistente
⏱️ Indicadores de estado y tiempo de procesamiento
📊 Metadata detallada (tokens, tiempo, ID de request)
🔄 Indicador de estado del servidor en tiempo real

Controles Adicionales

🗑️ Limpiar chat con un clic
🔄 Recargar configuración y modelos
📱 Diseño responsivo para móviles
⚙️ Panel de configuración colapsible

🐛 Solución de Problemas

Error: "Resource not accessible by personal access token"

# Verificar credenciales AWS
aws configure list
# o revisar archivo .env

Error: "Access denied to model"

Ve a AWS Bedrock Console → Model access
Solicita acceso al modelo específico
Espera aprobación (puede tomar minutos)

Error: "Region not supported"

Usa regiones soportadas: us-east-1, us-west-2, eu-west-1, ap-southeast-1

Frontend no conecta con Backend

# Verificar que el servidor esté ejecutándose
curl http://localhost:5000/health

# Revisar logs del servidor
python app.py

Problemas con dependencias

# Reinstalar dependencias
pip install --upgrade -r requirements.txt

# Limpiar caché
pip cache purge

🔐 Seguridad

Mejores Prácticas

⚠️ Nunca commitees credenciales AWS en el código
✅ Usa variables de entorno o AWS IAM roles
✅ Implementa autenticación en producción
✅ Limita permisos IAM al mínimo necesario
✅ Usa HTTPS en producción

Permisos IAM mínimos

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:ListFoundationModels"
      ],
      "Resource": "*"
    }
  ]
}

📊 Monitoreo y Logs

Logs del servidor

# Los logs aparecen automáticamente en consola
python app.py

# Configurar nivel de logging en .env
FLASK_DEBUG=True  # Para logs detallados

Endpoint de salud

curl http://localhost:5000/health

Respuesta ejemplo:

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00",
  "agent_status": "initialized",
  "region": "us-east-1"
}

🚢 Despliegue en Producción

Usando Gunicorn

# Instalar Gunicorn
pip install gunicorn

# Ejecutar en producción
gunicorn -w 4 -b 0.0.0.0:5000 app:app

Docker (opcional)

FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 5000
CMD ["python", "app.py"]

🤝 Contribuir

Fork el repositorio
Crea una rama para tu feature: git checkout -b feature/nueva-funcionalidad
Commit tus cambios: git commit -am 'Añadir nueva funcionalidad'
Push a la rama: git push origin feature/nueva-funcionalidad
Crea un Pull Request

Áreas de contribución

🔧 Nuevos modelos de Bedrock
🎨 Mejoras en la interfaz
📚 Documentación
🧪 Tests unitarios
🔐 Mejoras de seguridad

📚 Recursos Adicionales

📄 Licencia

Este proyecto está bajo la Licencia MIT. Ve el archivo LICENSE para más detalles.

👨‍💻 Autor

Harold Moncaleano

🐙 GitHub: @harold-moncaleano
📧 Email: harold.moncaleano@nuvu.cc
🌐 Proyecto: bedrock-mcp-agent

⭐ ¡Si este proyecto te resulta útil, dale una estrella! ⭐

🆘 Soporte

¿Necesitas ayuda?

🐛 Reporta bugs en Issues
💡 Sugiere features en Discussions
📧 Contacto directo: harold.moncaleano@nuvu.cc

📈 Roadmap

Próximas funcionalidades

🔐 Autenticación de usuarios
💾 Persistencia de conversaciones
📁 Carga de archivos y documentos
🎨 Temas personalizables
📊 Dashboard de métricas
🔌 Plugins y extensiones
🌐 Soporte multiidioma
📱 Aplicación móvil nativa

Integraciones planeadas

🗄️ Base de datos (PostgreSQL/MongoDB)
🔍 Elasticsearch para búsqueda
📊 Grafana para monitoreo
🐳 Docker Compose completo
☸️ Kubernetes deployment
🚀 CI/CD con GitHub Actions