Update mcp-servers/eventbrite-scraper-mcp/README.md

mcp-servers/eventbrite-scraper-mcp/README.md

@@ -1,331 +1,337 @@
-# Eventbrite Scraper MCP Server
-
-A Model Context Protocol (MCP) server for scraping and searching events from Eventbrite with comprehensive input validation and error handling.
-
-## Overview
-
-This server provides real-time event discovery from Eventbrite through web scraping. It's designed to be lightweight, fast, and robust with built-in security measures to prevent injection attacks and malformed queries.
-
-**Server Type:** Web Scraper
-**Framework:** FastMCP + FastAPI
-**Deployment:** Blaxel, Docker, Local
-**Response Time:** ~2-5 seconds per search
-
-## Features
-
-- ✅ Real-time Eventbrite event searching
-- ✅ Multi-parameter filtering (location, date, price, categories)
-- ✅ Input validation and sanitization
-- ✅ Rate limiting (respectful to Eventbrite servers)
-- ✅ Fallback HTML selectors for robustness
-- ✅ Structured JSON responses
-- ✅ User-Agent rotation
-- ✅ Error handling and logging
-
-## Installation
-
-### Prerequisites
-- Python 3.10+
-- pip or Poetry
-
-### Setup
-
-```bash
-# Clone/navigate to the server directory
-cd eventbrite-scraper-mcp
-
-# Install dependencies
-pip install -e .
-# OR
-poetry install
-```
-
-### Configuration
-
-Create a `.env` file in the root directory:
-
-```env
-# Optional: Configure logging level
-LOG_LEVEL=INFO
-
-# Optional: Request timeout (seconds)
-REQUEST_TIMEOUT=10
-```
-
-## Tools
-
-### `search_eventbrite`
-
-Search and filter events on Eventbrite.
-
-**Parameters:**
-
-| Parameter | Type | Required | Constraints | Description |
-|-----------|------|----------|-------------|-------------|
-| `location` | string | ✅ Yes | 2-100 chars, no special chars | City or region (e.g., "New York", "San Francisco") |
-| `start_date` | string | ❌ No | YYYY-MM-DD format | Filter events from this date onwards |
-| `end_date` | string | ❌ No | YYYY-MM-DD format | Filter events up to this date |
-| `min_price` | float | ❌ No | ≥ 0 | Minimum ticket price filter |
-| `max_price` | float | ❌ No | ≥ 0 | Maximum ticket price filter |
-| `categories` | list[string] | ❌ No | Max 10 items | Event categories (e.g., ["music", "food", "sports"]) |
-
-**Response Structure:**
-
-```json
-{
-  "success": true,
-  "query": {
-    "location": "New York",
-    "start_date": "2025-06-01",
-    "end_date": "2025-06-30",
-    "min_price": 0,
-    "max_price": 100,
-    "categories": []
-  },
-  "events": [
-    {
-      "title": "Summer Music Festival",
-      "date": "2025-06-15",
-      "location": "New York, NY",
-      "venue": "Central Park",
-      "price_min": 25.0,
-      "price_max": 75.0,
-      "is_free": false,
-      "url": "https://www.eventbrite.com/e/...",
-      "source": "Eventbrite",
-      "category": "music"
-    }
-  ],
-  "count": 1,
-  "timestamp": "2025-06-01T12:00:00Z"
-}
-```
-
-## Usage Examples
-
-### Basic Search
-
-```python
-from client import EventbriteScraperClient
-
-client = EventbriteScraperClient()
-
-# Search for all events in a location
-result = await client.search_eventbrite(
-    location="New York"
-)
-```
-
-### Advanced Search with Filters
-
-```python
-# Search with multiple filters
-result = await client.search_eventbrite(
-    location="San Francisco",
-    start_date="2025-07-01",
-    end_date="2025-07-31",
-    min_price=0,
-    max_price=50,
-    categories=["music", "tech"]
-)
-
-# Process results
-for event in result['events']:
-    print(f"{event['title']} - {event['date']} at {event['venue']}")
-```
-
-## Running the Server
-
-### Local Development
-
-```bash
-# Start the server
-python src/server.py
-
-# Server will be available at:
-# http://localhost:8000
-# MCP endpoint: http://localhost:8000/mcp
-```
-
-### Docker
-
-```bash
-# Build container
-docker build -t eventbrite-scraper-mcp .
-
-# Run container
-docker run -p 8000:8000 eventbrite-scraper-mcp
-```
-
-### Blaxel Deployment
-
-```bash
-# Deploy via Blaxel CLI
-blaxel deploy
-
-# Configuration in blaxel.toml:
-# - Function timeout: 900 seconds
-# - Memory: 2048 MB
-# - HTTP trigger: /mcp (public)
-```
-
-## Input Validation
-
-All inputs are validated before processing:
-
-### Location Validation
-- Length: 2-100 characters
-- Blocks path traversal attempts (`../`, `..\\`)
-- Blocks SQL injection patterns
-- Allows spaces and hyphens only
-
-### Date Validation
-- Format: `YYYY-MM-DD`
-- Must be valid calendar dates
-- Supports past, current, and future dates
-
-### Price Validation
-- Must be non-negative numbers
-- Supports floating-point values
-- `max_price` must be ≥ `min_price`
-
-## Architecture
-
-```
-User Request
-    ↓
-Input Validation
-    ↓
-Build Eventbrite URL
-    ↓
-HTTP Request (with User-Agent)
-    ↓
-Parse HTML with BeautifulSoup
-    ↓
-Try Fallback Selectors
-    ↓
-Extract Event Data
-    ↓
-Return JSON Response
-```
-
-## Error Handling
-
-| Error | Status | Solution |
-|-------|--------|----------|
-| Invalid location | 400 | Provide valid 2-100 char location |
-| Invalid date format | 400 | Use YYYY-MM-DD format |
-| Network timeout | 503 | Retry after 10 seconds |
-| No events found | 200 | Returns empty events array |
-| Eventbrite blocked | 429 | Rate limiter activated, wait 60 seconds |
-
-## Performance
-
-- **Average Response Time:** 2-5 seconds
-- **Timeout:** 30 seconds per request
-- **Rate Limiting:** 1 second sleep between requests
-- **Concurrent Requests:** Single-threaded (async compatible)
-- **Memory Usage:** ~50 MB
-
-## Security Measures
-
-✅ **Input Sanitization**
-- Blocks path traversal (`../`)
-- Blocks SQL injection patterns
-- Character whitelist enforcement
-
-✅ **Rate Limiting**
-- 1-second delay between requests
-- Respectful to Eventbrite servers
-
-✅ **User-Agent Rotation**
-- Appears as legitimate browser requests
-
-✅ **Error Suppression**
-- No sensitive information in error messages
-
-## Limitations
-
-⚠️ **Web Scraping Constraints**
-- Depends on Eventbrite HTML structure
-- May break if Eventbrite changes selectors
-- Subject to rate limiting from Eventbrite
-- Cannot access Eventbrite API (requires authentication)
-
-⚠️ **Coverage**
-- Only searches Eventbrite.com
-- Limited to 20 results per location search
-- May not include all event details
-
-## Troubleshooting
-
-### No events returned
-1. Verify location spelling
-2. Check date range validity
-3. Try without category filters
-4. Ensure Eventbrite isn't blocking requests
-
-### Timeout errors
-1. Increase timeout in configuration
-2. Reduce search scope (narrower dates/location)
-3. Check network connectivity
-
-### Invalid JSON responses
-1. Check server logs: `tail -f logs/server.log`
-2. Verify input parameters
-3. Ensure Eventbrite is accessible
-
-## Dependencies
-
-```
-fastmcp >= 2.0.0
-fastapi >= 0.104.0
-uvicorn >= 0.24.0
-requests >= 2.31.0
-beautifulsoup4 >= 4.12.0
-lxml >= 4.9.0
-python-dotenv >= 1.0.0
-```
-
-## Maintenance
-
-### Regular Tasks
-- Monitor HTML selector changes on Eventbrite
-- Update User-Agent strings quarterly
-- Test with latest Python 3.10+ versions
-- Review error logs weekly
-
-### Updating Selectors
-If Eventbrite changes their HTML structure:
-
-1. Open https://www.eventbrite.com/search/
-2. Inspect event card HTML
-3. Update selectors in `src/server.py`
-4. Run tests: `pytest tests/`
-
-## Contributing
-
-To improve this server:
-
-1. Test thoroughly before committing
-2. Add input validation for new parameters
-3. Follow existing error handling patterns
-4. Document new features in this README
-5. Maintain backwards compatibility
-
-## License
-
-Same as parent project (MCP Security Hackathon)
-
-## Support
-
-For issues or questions:
-1. Check the Troubleshooting section above
-2. Review server logs in `logs/`
-3. File an issue in the main repository
-4. Contact the MCP Security team
-
----
-
-**Last Updated:** 2025-06-01
-**Maintainer:** MCP Security Team
+tags:
+  - building-mcp-track-enterprise
+  - building-mcp-track-consumer
+  - building-mcp-track-creative
+    
+----
+# Eventbrite Scraper MCP Server
+
+A Model Context Protocol (MCP) server for scraping and searching events from Eventbrite with comprehensive input validation and error handling.
+
+## Overview
+
+This server provides real-time event discovery from Eventbrite through web scraping. It's designed to be lightweight, fast, and robust with built-in security measures to prevent injection attacks and malformed queries.
+
+**Server Type:** Web Scraper
+**Framework:** FastMCP + FastAPI
+**Deployment:** Blaxel, Docker, Local
+**Response Time:** ~2-5 seconds per search
+
+## Features
+
+- ✅ Real-time Eventbrite event searching
+- ✅ Multi-parameter filtering (location, date, price, categories)
+- ✅ Input validation and sanitization
+- ✅ Rate limiting (respectful to Eventbrite servers)
+- ✅ Fallback HTML selectors for robustness
+- ✅ Structured JSON responses
+- ✅ User-Agent rotation
+- ✅ Error handling and logging
+
+## Installation
+
+### Prerequisites
+- Python 3.10+
+- pip or Poetry
+
+### Setup
+
+```bash
+# Clone/navigate to the server directory
+cd eventbrite-scraper-mcp
+
+# Install dependencies
+pip install -e .
+# OR
+poetry install
+```
+
+### Configuration
+
+Create a `.env` file in the root directory:
+
+```env
+# Optional: Configure logging level
+LOG_LEVEL=INFO
+
+# Optional: Request timeout (seconds)
+REQUEST_TIMEOUT=10
+```
+
+## Tools
+
+### `search_eventbrite`
+
+Search and filter events on Eventbrite.
+
+**Parameters:**
+
+| Parameter | Type | Required | Constraints | Description |
+|-----------|------|----------|-------------|-------------|
+| `location` | string | ✅ Yes | 2-100 chars, no special chars | City or region (e.g., "New York", "San Francisco") |
+| `start_date` | string | ❌ No | YYYY-MM-DD format | Filter events from this date onwards |
+| `end_date` | string | ❌ No | YYYY-MM-DD format | Filter events up to this date |
+| `min_price` | float | ❌ No | ≥ 0 | Minimum ticket price filter |
+| `max_price` | float | ❌ No | ≥ 0 | Maximum ticket price filter |
+| `categories` | list[string] | ❌ No | Max 10 items | Event categories (e.g., ["music", "food", "sports"]) |
+
+**Response Structure:**
+
+```json
+{
+  "success": true,
+  "query": {
+    "location": "New York",
+    "start_date": "2025-06-01",
+    "end_date": "2025-06-30",
+    "min_price": 0,
+    "max_price": 100,
+    "categories": []
+  },
+  "events": [
+    {
+      "title": "Summer Music Festival",
+      "date": "2025-06-15",
+      "location": "New York, NY",
+      "venue": "Central Park",
+      "price_min": 25.0,
+      "price_max": 75.0,
+      "is_free": false,
+      "url": "https://www.eventbrite.com/e/...",
+      "source": "Eventbrite",
+      "category": "music"
+    }
+  ],
+  "count": 1,
+  "timestamp": "2025-06-01T12:00:00Z"
+}
+```
+
+## Usage Examples
+
+### Basic Search
+
+```python
+from client import EventbriteScraperClient
+
+client = EventbriteScraperClient()
+
+# Search for all events in a location
+result = await client.search_eventbrite(
+    location="New York"
+)
+```
+
+### Advanced Search with Filters
+
+```python
+# Search with multiple filters
+result = await client.search_eventbrite(
+    location="San Francisco",
+    start_date="2025-07-01",
+    end_date="2025-07-31",
+    min_price=0,
+    max_price=50,
+    categories=["music", "tech"]
+)
+
+# Process results
+for event in result['events']:
+    print(f"{event['title']} - {event['date']} at {event['venue']}")
+```
+
+## Running the Server
+
+### Local Development
+
+```bash
+# Start the server
+python src/server.py
+
+# Server will be available at:
+# http://localhost:8000
+# MCP endpoint: http://localhost:8000/mcp
+```
+
+### Docker
+
+```bash
+# Build container
+docker build -t eventbrite-scraper-mcp .
+
+# Run container
+docker run -p 8000:8000 eventbrite-scraper-mcp
+```
+
+### Blaxel Deployment
+
+```bash
+# Deploy via Blaxel CLI
+blaxel deploy
+
+# Configuration in blaxel.toml:
+# - Function timeout: 900 seconds
+# - Memory: 2048 MB
+# - HTTP trigger: /mcp (public)
+```
+
+## Input Validation
+
+All inputs are validated before processing:
+
+### Location Validation
+- Length: 2-100 characters
+- Blocks path traversal attempts (`../`, `..\\`)
+- Blocks SQL injection patterns
+- Allows spaces and hyphens only
+
+### Date Validation
+- Format: `YYYY-MM-DD`
+- Must be valid calendar dates
+- Supports past, current, and future dates
+
+### Price Validation
+- Must be non-negative numbers
+- Supports floating-point values
+- `max_price` must be ≥ `min_price`
+
+## Architecture
+
+```
+User Request
+    ↓
+Input Validation
+    ↓
+Build Eventbrite URL
+    ↓
+HTTP Request (with User-Agent)
+    ↓
+Parse HTML with BeautifulSoup
+    ↓
+Try Fallback Selectors
+    ↓
+Extract Event Data
+    ↓
+Return JSON Response
+```
+
+## Error Handling
+
+| Error | Status | Solution |
+|-------|--------|----------|
+| Invalid location | 400 | Provide valid 2-100 char location |
+| Invalid date format | 400 | Use YYYY-MM-DD format |
+| Network timeout | 503 | Retry after 10 seconds |
+| No events found | 200 | Returns empty events array |
+| Eventbrite blocked | 429 | Rate limiter activated, wait 60 seconds |
+
+## Performance
+
+- **Average Response Time:** 2-5 seconds
+- **Timeout:** 30 seconds per request
+- **Rate Limiting:** 1 second sleep between requests
+- **Concurrent Requests:** Single-threaded (async compatible)
+- **Memory Usage:** ~50 MB
+
+## Security Measures
+
+✅ **Input Sanitization**
+- Blocks path traversal (`../`)
+- Blocks SQL injection patterns
+- Character whitelist enforcement
+
+✅ **Rate Limiting**
+- 1-second delay between requests
+- Respectful to Eventbrite servers
+
+✅ **User-Agent Rotation**
+- Appears as legitimate browser requests
+
+✅ **Error Suppression**
+- No sensitive information in error messages
+
+## Limitations
+
+⚠️ **Web Scraping Constraints**
+- Depends on Eventbrite HTML structure
+- May break if Eventbrite changes selectors
+- Subject to rate limiting from Eventbrite
+- Cannot access Eventbrite API (requires authentication)
+
+⚠️ **Coverage**
+- Only searches Eventbrite.com
+- Limited to 20 results per location search
+- May not include all event details
+
+## Troubleshooting
+
+### No events returned
+1. Verify location spelling
+2. Check date range validity
+3. Try without category filters
+4. Ensure Eventbrite isn't blocking requests
+
+### Timeout errors
+1. Increase timeout in configuration
+2. Reduce search scope (narrower dates/location)
+3. Check network connectivity
+
+### Invalid JSON responses
+1. Check server logs: `tail -f logs/server.log`
+2. Verify input parameters
+3. Ensure Eventbrite is accessible
+
+## Dependencies
+
+```
+fastmcp >= 2.0.0
+fastapi >= 0.104.0
+uvicorn >= 0.24.0
+requests >= 2.31.0
+beautifulsoup4 >= 4.12.0
+lxml >= 4.9.0
+python-dotenv >= 1.0.0
+```
+
+## Maintenance
+
+### Regular Tasks
+- Monitor HTML selector changes on Eventbrite
+- Update User-Agent strings quarterly
+- Test with latest Python 3.10+ versions
+- Review error logs weekly
+
+### Updating Selectors
+If Eventbrite changes their HTML structure:
+
+1. Open https://www.eventbrite.com/search/
+2. Inspect event card HTML
+3. Update selectors in `src/server.py`
+4. Run tests: `pytest tests/`
+
+## Contributing
+
+To improve this server:
+
+1. Test thoroughly before committing
+2. Add input validation for new parameters
+3. Follow existing error handling patterns
+4. Document new features in this README
+5. Maintain backwards compatibility
+
+## License
+
+Same as parent project (MCP Security Hackathon)
+
+## Support
+
+For issues or questions:
+1. Check the Troubleshooting section above
+2. Review server logs in `logs/`
+3. File an issue in the main repository
+4. Contact the MCP Security team
+
+---
+
+**Last Updated:** 2025-06-01
+**Maintainer:** MCP Security Team