Berghain Events MCP Server

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