README.md•6.35 kB
# Berghain Events API & MCP Implementation
## Estructura del proyecto
```
berghain-api/
├── app/ # Aplicación principal FastAPI
│ ├── api/ # Rutas de la API
│ ├── core/ # Configuración y componentes centrales
│ ├── db/ # Capa de acceso a datos (DynamoDB)
│ └── main.py # Punto de entrada de la aplicación y FastMCP server
├── scripts/ # Scripts para creación de tabla y carga de datos en DynamoDB
│ ├── create_table.py
│ └── load_data.py
├── events/ # Directorio para los JSON extraídos de Firecrawl
├── Dockerfile # Dockerfile para despliegue
├── requirements.txt # Dependencias del proyecto (para uv)
└── README.md # Este archivo
```
## Requisitos
- Python 3.10+
- uv (para gestión de dependencias y entorno virtual)
- Cuenta de AWS (para DynamoDB y App Runner)
- API Key de Firecrawl
## Instalación
1. Clonar este repositorio:
```bash
git clone <repository-url>
cd berghain-api
```
2. Crear y activar un entorno virtual con `uv`:
```bash
uv venv
source .venv/bin/activate # En Linux/macOS
# .venv\\Scripts\\activate # En Windows
```
3. Instalar dependencias con `uv`:
```bash
uv pip install -r requirements.txt
```
## Proceso Detallado
### 1. Extracción de Datos con Firecrawl
- **Configura el MCP de Firecrawl en Cursor:**
Asegúrate de tener tu API Key de Firecrawl. En la configuración de MCPs de Cursor, añade:
```json
"firecrawl-mcp": {
"command": "npx",
"args": [
"-y",
"firecrawl-mcp"
],
"env": {
"FIRECRAWL_API_KEY": "fc-YOUR_FIRECRAWL_API_KEY"
}
}
```
- **Ejecuta la extracción:**
Usa un agente en Cursor (o una herramienta similar) para llamar al MCP de Firecrawl y pedirle que extraiga los eventos de `https://www.berghain.berlin/en/program/`.
- **Guarda los datos:**
Los datos extraídos deben guardarse como archivos JSON en el directorio `events/`. Por ejemplo, `events/berghain_events_YYYY-MM-DD.json`.
### 2. Carga de Datos a DynamoDB
- **Crea la tabla en DynamoDB:**
El script `scripts/create_table.py` se encarga de esto. Ejecútalo (ajusta los parámetros si es necesario):
```bash
uv run python scripts/create_table.py --table berghain_events --region tu-region-aws
# Para desarrollo local con DynamoDB Local (ej. docker run -p 8000:8000 amazon/dynamodb-local):
# uv run python scripts/create_table.py --table berghain_events --region localhost --endpoint-url http://localhost:8000
```
- **Carga los datos a la tabla:**
El script `scripts/load_data.py` sube los eventos desde los archivos JSON.
```bash
uv run python scripts/load_data.py --table berghain_events --region tu-region-aws --path events
# Para desarrollo local:
# uv run python scripts/load_data.py --table berghain_events --region localhost --endpoint-url http://localhost:8000 --path events
```
Asegúrate de que `app/core/config.py` (importado por `load_data.py`) tenga las configuraciones necesarias si no las pasas como argumentos.
### 3. API con FastAPI y Servidor MCP
- La lógica de la API reside en el directorio `app/`, con los endpoints definidos (e.g., en `app/api/endpoints/events.py`).
- El archivo `app/main.py` está configurado para iniciar la aplicación FastAPI y el servidor FastMCP, exponiendo los endpoints de la API como tools para modelos de IA. Revisa las `custom_maps` en `app/main.py` para ver cómo se mapean las rutas GET a `RouteType.TOOL`.
## Despliegue en AWS
### a. `Dockerfile`
Asegúrate de que tu `Dockerfile` esté configurado correctamente para usar `uv` y ejecutar `app/main.py`:
### b. Construir y Subir Imagen a Amazon ECR (Elastic Container Registry)
1. **Autentica Docker con ECR:**
```bash
aws ecr get-login-password --region tu-region-aws | docker login --username AWS --password-stdin tu-aws-account-id.dkr.ecr.tu-region-aws.amazonaws.com
```
2. **Crea un repositorio en ECR (si no existe):**
```bash
aws ecr create-repository --repository-name berghain-mcp-api --region tu-region-aws
```
3. **Construye tu imagen Docker:**
```bash
docker build -t berghain-mcp-api .
```
4. **Etiqueta tu imagen:**
```bash
docker tag berghain-mcp-api:latest tu-aws-account-id.dkr.ecr.tu-region-aws.amazonaws.com/berghain-mcp-api:latest
```
5. **Sube la imagen a ECR:**
```bash
docker push tu-aws-account-id.dkr.ecr.tu-region-aws.amazonaws.com/berghain-mcp-api:latest
```
Reemplaza `tu-region-aws` y `tu-aws-account-id` con tus valores.
### c. Desplegar Infraestructura con Terraform
1. **Prepara tus archivos de Terraform:**
Asegúrate de tener tus archivos de configuración de Terraform (ej. `main.tf`, `variables.tf`, `outputs.tf`) en un directorio (p.ej., `terraform/`). Estos archivos deben definir los recursos de AWS necesarios, como el servicio de AWS App Runner que usará la imagen de ECR, y la tabla DynamoDB (si Terraform también la gestiona).
Tu configuración de App Runner en Terraform deberá referenciar la imagen subida a ECR.
2. **Navega al directorio de Terraform:**
```bash
cd terraform
```
3. **Inicializa Terraform:**
```bash
terraform init
```
4. **Aplica la configuración de Terraform:**
```bash
terraform apply
```
Revisa el plan y confirma la aplicación. Terraform provisionará los recursos.
5. **Obtén la URL del servicio:**
Una vez aplicado, Terraform debería mostrar las salidas definidas, incluyendo la URL del servicio App Runner. Anota esta URL (ej. `https://<id-servicio>.<region>.awsapprunner.com`).
## Probar la Solución Desplegada
### a. Ajustar Script de Prueba Local (`mcp_local.py`)
Ajusta el archivo `mcp_local.py` en la raíz de tu proyecto
**Importante:** Actualiza la variable `mcp_server_url` en `mcp_local.py` con la URL que obtuviste del output de Terraform.
### b. Ejecutar Prueba
Desde la raíz de tu proyecto (o donde hayas guardado `mcp_local.py`):
```bash
uv run python mcp_local.py
```
Esto ejecutará el agente PydanticAI, que intentará conectarse a tu MCP desplegado y realizar la consulta.
## Licencia
MIT