# 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