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:

   git clone <repository-url>
   cd berghain-api
   

2. Crear y activar un entorno virtual con uv:

   uv venv
   source .venv/bin/activate  # En Linux/macOS
   # .venv\\Scripts\\activate    # En Windows
   

3. Instalar dependencias con uv:

   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:

     "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):

  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.

  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:

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

   aws ecr create-repository --repository-name berghain-mcp-api --region tu-region-aws
   

3. Construye tu imagen Docker:

   docker build -t berghain-mcp-api .
   

4. Etiqueta tu imagen:

   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:

   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:

   cd terraform 
   

3. Inicializa Terraform:

   terraform init
   

4. Aplica la configuración de Terraform:

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

uv run python mcp_local.py

Esto ejecutará el agente PydanticAI, que intentará conectarse a tu MCP desplegado y realizar la consulta.

Licencia

MIT