README.md

metadata

title: Surf Spot Finder — AI-Powered MCP Agent
emoji: 🏄‍♂️
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 5.49.1
app_file: hf_space/app.py
pinned: false
license: mit
tags:
  - mcp-in-action-track-customer
  - building-mcp-track-consumer
short_description: AI surf agent with autonomous reasoning using MCP protocol

🏄‍♂️ Surf Spot Finder - AI Agent (MCP in Action)

AI-powered surf spot recommendations with autonomous reasoning and real-time conditions

This project demonstrates MCP in Action with an intelligent agent that autonomously analyzes surf conditions, reasons about optimal spots, and provides natural language explanations of its decision-making process.

🎬 Demo Video

Watch the Demo Video to see how the MCP server works in action.

🤖 Agent Capabilities

• 🧠 Autonomous Reasoning: AI agent analyzes wave conditions and makes intelligent recommendations
• 🌊 Real-time Conditions: Live wave data from Stormglass API
• 📍 Location Intelligence: Geocoding and distance-based filtering
• 🎯 Multi-factor Scoring: Sophisticated evaluation (waves, wind, swell, skill compatibility)
• 💬 Natural Language: LLM-powered explanations and insights
• 🛡️ Safety-focused: Skill-level appropriate recommendations

🔧 MCP Resources Implementation

Surf spots are exposed as MCP resources following the Model Context Protocol.

Resource

• URI: surf://spots/database
• Content: 22 world-class surf spots with metadata
• Format: JSON

Server Implementation (mcp_server/mcp_server.py)

@server.list_resources()
async def list_resources():
    return [Resource(uri="surf://spots/database", name="Surf Spots Database", ...)]

@server.read_resource()
async def read_resource(uri: str):
    # Returns surf_spots.json content

Client Usage (tools/spot_finder_tool.py)

• Primary: MCP resource access via read_resource()
• Fallback: File I/O for async context compatibility

Testing MCP Resources

python tests/test_mcp_resources.py
# Expected output:
# ✅ Found 1 resource(s)  
# ✅ Loaded 22 surf spots
# 🎉 All tests passed!

🏗️ MCP Architecture

MCP Server (mcp_server/)

Tools Available:

• find_surf_spots - Main orchestration tool with AI reasoning
• surf_llm_agent - LLM-powered analysis and explanations
• get_wave_data - Real-time conditions from Stormglass
• resolve_location - Geocoding and coordinate resolution
• calculate_distance - Distance calculations

HF Space Consumer (hf_space/)

• Gradio Interface: User-friendly web UI
• MCP Client: Communicates with MCP server
• Real-time Demo: Live surf recommendations

🚀 Quick Start

Local Development

# Clone repository
git clone <repo-url>
cd surf-spot-finder-mcp

# Install dependencies
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

# Set API keys (optional - works with fallback)
export STORMGLASS_API_KEY=your_key
export OPENAI_API_KEY=your_key  # For enhanced LLM reasoning

# Quick demo
python scripts/run_local_demo.py

🌊 How It Works

1. User Input: Location + preferences (skill level, board type)
2. Location Resolution: Convert address to coordinates
3. Spot Discovery: Find nearby surf spots from curated database
4. Condition Analysis: Get real-time wave data via Stormglass
5. AI Evaluation: Sophisticated scoring algorithm + LLM reasoning
6. Intelligent Ranking: Sort by compatibility with user preferences
7. Natural Language Output: AI-generated explanations and insights

📊 Evaluation Algorithm

Real-Time Data Sources (Automatic Priority):

• 🥇 Stormglass API → 🥈 Open-Meteo (free fallback)
• 🥇 OpenAI → 🥈 Anthropic → 🥉 OpenRouter → 🔄 Rule-based

Multi-Factor Scoring System (0-100 scale):

1. Wave Conditions (35%):

   • Optimal range matching (spot preferences vs. current height)
   • Skill-level safety adjustments (beginners capped at 2m)
   • Progressive scoring curve with diminishing returns

2. Wind Analysis (25%):

   • Speed compatibility (offshore preferred, onshore penalized)
   • Direction optimization (side-offshore = ideal)
   • Thermal wind pattern recognition

3. Swell Direction (25%):

   • Angular matching to spot's optimal swell window
   • Bathymetry considerations for wave refraction
   • Seasonal swell pattern analysis

4. Skill Compatibility (15%):

   • Break type vs. experience level
   • Hazard assessment (rocks, currents, crowds)
   • Progression opportunity scoring

AI Reasoning Layer:

• Autonomous pattern recognition across multiple conditions
• Natural language explanations of decision-making process
• Local knowledge integration and safety recommendations
• Session timing optimization with weather forecasting

🗺️ Surf Spot Database

Demo Dataset (Current Implementation)

22 World-Class Spots carefully selected for demonstration:

🇪🇸 Spain (8 spots)

• Tarifa, El Palmar, La Barrosa, Sotogrande, Barbate, Cabo Trafalgar, Marbella, Mundaka

🇺🇸 California, USA (4 spots)

• Malibu - Surfrider Beach, Venice Beach, Manhattan Beach, Redondo Beach

🇵🇹 Portugal (4 spots)

• Ericeira - Ribeira d'Ilhas, Carcavelos, Guincho, Peniche - Supertubos

🌍 International (6 spots)

• Hossegor (France), Pipeline (Hawaii), Bells Beach (Australia), Supertubes (South Africa)

Production Scaling Architecture

Current: JSON File (mcp_server/data/surf_spots.json)

• ✅ Perfect for demo and development
• ✅ Easy to understand and modify
• ✅ No external dependencies

Production Deployment Options:

• PostgreSQL/PostGIS: Geospatial queries and advanced filtering
• MongoDB: Flexible schema for evolving spot characteristics
• Redis Cache: Fast lookup with geographic indexing
• API Integration: Real-time spot data from surf databases

Scalability Path:

JSON (22 spots) → Database (1000s spots) → API Federation (global coverage)

The current JSON approach demonstrates the algorithm and architecture while keeping the demo accessible and maintainable for hackathon evaluation.

🧪 Testing

Run Tests

# Test MCP resources
python tests/test_mcp_resources.py

# Test complete workflow
python tests/test_workflow.py

# Run unit tests (if pytest installed)
cd mcp_server
pytest tests/

Test Dependencies

The project includes comprehensive tests for:

• MCP Resources: Resource listing and reading
• MCP Tools: Individual tool functionality
• LLM Integration: AI reasoning components
• API Integration: External service connections

🔧 Configuration

API Keys (All Optional - Intelligent Fallbacks Included):

Wave Data Sources:

• STORMGLASS_API_KEY: Premium marine data → Falls back to Open-Meteo (free)

AI Reasoning Providers (Priority Order):

• OPENAI_API_KEY: GPT-4 analysis (1st choice)
• ANTHROPIC_API_KEY: Claude reasoning (2nd choice)
• OPENROUTER_API_KEY: Multi-model access (3rd choice)
• No API key: Rule-based analysis (always works)

🎯 MCP Hackathon Submission

Track: MCP in Action - Customer
Category: Demonstrates autonomous AI agent behavior

Key Features for Judging:

• ✅ Agent Reasoning: LLM-powered autonomous decision making
• ✅ Real-world Impact: Practical surf recommendations with safety focus
• ✅ MCP Protocol: Proper resource and tool architecture
• ✅ User Experience: Intuitive Gradio interface
• ✅ Documentation: Comprehensive setup and usage docs

🏆 Innovation Highlights

1. Autonomous Agent Behavior: AI reasons about conditions and explains decisions
2. Multi-modal Intelligence: Combines real-time data, spatial analysis, and LLM reasoning
3. MCP Resources: Proper implementation of Model Context Protocol primitives
4. Safety-first Approach: Skill-level appropriate recommendations prevent dangerous situations
5. Flexible Architecture: Direct mode with intelligent fallbacks for reliability

📁 Project Structure

surf-spot-finder-mcp/
├── mcp_server/                    # MCP Server Implementation
│   ├── mcp_server.py             # MCP resource handlers (list_resources, read_resource)
│   ├── tools/                    # MCP Tools
│   │   ├── spot_finder_tool.py  # Main orchestration (uses MCP resources)
│   │   ├── llm_agent_tool.py    # AI reasoning & analysis
│   │   ├── surf_eval_tool.py    # Multi-factor scoring algorithm
│   │   ├── stormglass_tool.py   # Wave data API integration
│   │   ├── location_tool.py     # Geocoding & coordinates
│   │   └── marine_data_tool.py  # Fallback weather data
│   ├── data/                    # Surf spots database
│   │   └── surf_spots.json      # 22 world-class surf spots (exposed via MCP)
│   ├── utils/                   # Utility functions
│   └── tests/                   # Unit & integration tests
│
├── hf_space/                     # Gradio UI
│   ├── app.py                   # Main interface with enhanced UX
│   ├── mcp_client.py            # Direct Mode client
│   └── requirements.txt         # HF Space dependencies
│
├── scripts/                      # Utility scripts
│   ├── run_local_demo.py        # Quick demo launcher
│   └── print_tree.py            # Repository structure visualization
│
├── tests/                        # Root-level integration tests
│   ├── test_mcp_resources.py    # MCP resources validation
│   └── test_workflow.py         # End-to-end workflow testing
│
├── requirements.txt              # Project dependencies
└── README.md                     # This documentation

🤝 Contributing

Built for the Hugging Face MCP Hackathon. Contributions welcome!

📄 License

MIT License - See LICENSE file for details.

---

🏄‍♂️ Find your perfect wave with AI-powered intelligence!

🔮 Future Enhancements

• Modal Serverless Deployment: Planned for production-scale deployment
• Global Spot Database: Integration with surf databases for worldwide coverage
• Forecast Integration: Multi-day weather predictions and session planning
• Community Features: User ratings, photos, and local tips