🧠 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

1. Ve a la consola AWS Bedrock
2. Navega a "Model access"
3. 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

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

Modelos soportados

🎯 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"

1. Ve a AWS Bedrock Console → Model access
2. Solicita acceso al modelo específico
3. 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

1. Fork el repositorio
2. Crea una rama para tu feature: git checkout -b feature/nueva-funcionalidad
3. Commit tus cambios: git commit -am 'Añadir nueva funcionalidad'
4. Push a la rama: git push origin feature/nueva-funcionalidad
5. 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

• 📖 Documentación AWS Bedrock
• 🔗 Model Context Protocol
• 🤖 Anthropic Claude API
• 🛡️ AWS IAM Best Practices
• ⚛️ React Documentation
• 🐍 Flask Documentation

📄 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