Berghain Events API & MCP Implementation

Estructura del proyecto

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

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

Licencia

MIT