Berghain Events MCP Server

# 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