docs: add comprehensive docstrings to all Python files

hf_space/app.py

@@ -1,11 +1,70 @@
+"""
+Surf Spot Finder Gradio Interface - Interactive Web UI.
+
+This module provides a user-friendly Gradio web interface for the Surf Spot
+Finder application. It connects to the MCP server via the mcp_client and
+presents surf spot recommendations with enhanced UX and AI reasoning.
+
+Features:
+    - Interactive location search with autocomplete
+    - Customizable search parameters (radius, skill level, board type)
+    - Real-time surf spot recommendations
+    - AI-powered analysis and explanations
+    - Responsive design with enhanced CSS styling
+    - Loading animations and error handling
+    - Example locations for quick testing
+
+The interface demonstrates MCP in Action by:
+    - Orchestrating multiple MCP tools seamlessly
+    - Presenting AI reasoning in natural language
+    - Providing real-world surf recommendations
+    - Showcasing autonomous agent behavior
+
+UI Components:
+    - Location input with validation
+    - Search radius slider (10-200km)
+    - Number of results selector (1-10)
+    - Skill level dropdown (beginner/intermediate/advanced)
+    - Board type selection (optional)
+    - Results display with scoring breakdown
+    - AI reasoning accordion for detailed analysis
+
+Example Usage:
+    The interface is deployed on Hugging Face Spaces and can be run locally:
+    >>> python app.py  # Starts Gradio server on localhost:7860
+
+Author: Surf Spot Finder Team
+License: MIT
+"""
+
 import gradio as gr
 from mcp_client import find_best_spots
 import os
 import json
 import time
 
-def format_spot_results(results, ai_summary="", ai_reasoning=""):
-    """Format surf spot results for display"""
+def format_spot_results(results, ai_summary: str = "", ai_reasoning: str = "") -> tuple[str, str, str]:
+    """Format surf spot results for rich HTML display.
+    
+    Converts raw surf spot data into formatted HTML with enhanced styling,
+    score visualization, and condition summaries. Includes AI reasoning
+    formatting with markdown conversion and section highlighting.
+    
+    Args:
+        results: List of surf spot dicts with scores and conditions.
+        ai_summary: Brief AI-generated summary (currently unused).
+        ai_reasoning: Detailed AI analysis with markdown formatting.
+        
+    Returns:
+        Tuple containing (formatted_spots_html, ai_summary_html, ai_reasoning_html)
+        
+    Features:
+        - Color-coded scoring (green/yellow/red based on score)
+        - Responsive card layout with spot details
+        - Markdown to HTML conversion for AI reasoning
+        - Section headers with emoji and enhanced styling
+        - Scrollable content for mobile compatibility
+    """
     if not results:
         return "No surf spots found in your area.", "", ""
     
@@ -108,8 +167,31 @@ def format_spot_results(results, ai_summary="", ai_reasoning=""):
     
     return spots_html, ai_summary_html, ai_reasoning_html
 
-def run_surf_finder(location, max_distance, num_spots, skill_level, board_type):
-    """Main function to find surf spots"""
+def run_surf_finder(location: str, max_distance: int, num_spots: int, skill_level: str, board_type: str) -> tuple[str, str]:
+    """Execute surf spot search and return formatted results.
+    
+    Main function that coordinates the surf spot search process,
+    handles user inputs, calls the MCP client, and formats results
+    for display in the Gradio interface.
+    
+    Args:
+        location: User's location string (address, coordinates, place name).
+        max_distance: Search radius in kilometers.
+        num_spots: Number of surf spots to return.
+        skill_level: User's surfing skill level (beginner/intermediate/advanced).
+        board_type: Board preference (shortboard/longboard/funboard/etc).
+        
+    Returns:
+        Tuple of (formatted_results_html, ai_reasoning_html) for display.
+        
+    Process:
+        1. Validates and cleans user inputs
+        2. Builds preferences dictionary
+        3. Calls MCP client with parameters
+        4. Handles errors gracefully with user-friendly messages
+        5. Formats successful results for rich display
+        6. Returns HTML content for Gradio components
+    """
     try:
         import os
         import time

hf_space/mcp_client.py

@@ -1,4 +1,36 @@
-import os, requests
+"""
+MCP Client for Surf Spot Finder - Direct Mode with HTTP Fallback.
+
+This module provides a smart client interface that connects to the MCP server
+using the most appropriate method available. It prioritizes direct Python
+imports for local development and falls back to HTTP for deployed scenarios.
+
+Execution Modes (Priority Order):
+    1. Direct Mode: Local development with direct Python imports (primary)
+    2. HTTP Mode: Communication with deployed FastAPI server (fallback)
+
+The client automatically detects the available mode and provides a unified
+interface for the Gradio UI, ensuring seamless operation across different
+deployment scenarios.
+
+Environment Variables:
+    MCP_SERVER_URL: HTTP server URL (default: http://localhost:8080)
+
+Example:
+    >>> result = find_best_spots(
+    ...     user_location="Málaga, Spain",
+    ...     max_distance_km=50,
+    ...     top_n=3,
+    ...     prefs={"skill_level": "intermediate"}
+    ... )
+    >>> print(f"Found {len(result['results'])} surf spots")
+
+Author: Surf Spot Finder Team
+License: MIT
+"""
+
+import os
+import requests
 import asyncio
 import sys
 from typing import Dict, Any, Optional
@@ -12,24 +44,51 @@ try:
 except ImportError:
     DIRECT_MODE = False
 
-# # MCP Server URL for deployed mode
-# # Default to Modal deployment URL, fallback to local FastAPI server
-# MODAL_URL = os.environ.get("MODAL_URL")
-# BASE = MODAL_URL or os.environ.get("MCP_SERVER_URL", "http://localhost:8080")
-
-# Set to base (local implementation) for now
+# MCP Server URL for HTTP mode
 BASE = os.environ.get("MCP_SERVER_URL", "http://localhost:8080")
-MODAL_URL = os.environ.get("MODAL_URL", None)
 
 def post(path: str, payload: Dict[str, Any], timeout: int = 120) -> Dict[str, Any]:
-    """Make HTTP request to MCP server"""
+    """Make HTTP request to MCP server endpoint.
+    
+    Sends POST request with JSON payload to the configured server endpoint.
+    Used for HTTP mode communication with deployed MCP servers.
+    
+    Args:
+        path: API endpoint path (e.g., "/tools/find_surf_spots").
+        payload: Request data as dictionary.
+        timeout: Request timeout in seconds (default: 120).
+        
+    Returns:
+        Response JSON data as dictionary.
+        
+    Raises:
+        requests.exceptions.RequestException: On HTTP errors or timeouts.
+    """
     url = f"{BASE}{path}"
     resp = requests.post(url, json=payload, timeout=timeout)
     resp.raise_for_status()
     return resp.json()
 
 async def find_best_spots_direct(user_location: str, max_distance_km: int = 50, top_n: int = 3, prefs: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-    """Direct call to MCP server tools (for local development)"""
+    """Direct call to MCP server tools for local development.
+    
+    Uses direct Python imports to call MCP tools without HTTP overhead.
+    This mode provides the fastest execution and best debugging experience
+    for local development and testing.
+    
+    Args:
+        user_location: User's location string (address, coordinates, etc.).
+        max_distance_km: Maximum search radius in kilometers.
+        top_n: Number of top surf spots to return.
+        prefs: User preferences including skill level, board type.
+        
+    Returns:
+        Dict containing surf spot results in standardized format.
+        
+    Note:
+        This function is async and must be called with asyncio.run()
+        or within an existing async context.
+    """
     finder = SurfSpotFinder()
     input_data = SpotFinderInput(
         user_location=user_location,
@@ -62,20 +121,29 @@ async def find_best_spots_direct(user_location: str, max_distance_km: int = 50,
     }
 
 def find_best_spots_http(user_location: str, max_distance_km: int = 50, top_n: int = 3, prefs: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-    """HTTP call to deployed MCP server (Modal or FastAPI)"""
+    """HTTP call to deployed MCP server via FastAPI.
+    
+    Makes HTTP request to a deployed FastAPI server running the MCP tools.
+    Used when direct imports are not available or for deployed scenarios.
+    
+    Args:
+        user_location: User's location string.
+        max_distance_km: Maximum search radius in kilometers.
+        top_n: Number of top surf spots to return.
+        prefs: User preferences dict.
+        
+    Returns:
+        Dict with standardized surf spot results or error information.
+    """
     payload = {
-        "location": user_location,  # Modal endpoint expects "location"
+        "location": user_location,
         "max_distance": max_distance_km,
         "num_spots": top_n,
         "preferences": prefs or {}
     }
     try:
-        # Try Modal endpoint first
-        if MODAL_URL:
-            response = post("", payload)  # Modal URL already points to the specific function
-        else:
-            # Fallback to local FastAPI endpoint
-            response = post("/tool/find_surf_spots", payload)
+        # Call FastAPI endpoint
+        response = post("/tool/find_surf_spots", payload)
             
         if response.get("ok"):
             return {
@@ -99,15 +167,30 @@ def find_best_spots_http(user_location: str, max_distance_km: int = 50, top_n: i
         }
 
 def find_best_spots(user_location: str, max_distance_km: int = 50, top_n: int = 3, prefs: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-    """Main interface - prioritizes Modal serverless deployment for production"""
+    """Main interface for surf spot recommendations with intelligent mode detection.
     
-    # Priority 1: Modal serverless deployment (production)
-    if MODAL_URL:
-        print(f"🚀 Using Modal serverless deployment: {MODAL_URL}")
-        return find_best_spots_http(user_location, max_distance_km, top_n, prefs)
+    Automatically selects the best available execution mode:
+    1. Direct Mode: Local development with direct Python imports
+    2. HTTP Mode: Deployed FastAPI server communication
+    
+    Args:
+        user_location: User's location (address, coordinates, place name).
+        max_distance_km: Search radius in kilometers (default: 50).
+        top_n: Number of results to return (default: 3).
+        prefs: User preferences dict with skill_level, board_type, etc.
+        
+    Returns:
+        Dict containing:
+            - ok: Success boolean
+            - results: List of ranked surf spots
+            - user_location: Resolved coordinates
+            - ai_summary: Brief AI analysis
+            - ai_reasoning: Detailed AI explanations
+            - error: Error message if ok=False
+    """
     
-    # Priority 2: Direct local mode (development)
-    elif DIRECT_MODE:
+    # Priority 1: Direct local mode (development)
+    if DIRECT_MODE:
         print("🏠 Using direct local development mode")
         # Run async function in sync context
         loop = None
@@ -119,7 +202,7 @@ def find_best_spots(user_location: str, max_distance_km: int = 50, top_n: int =
         
         return loop.run_until_complete(find_best_spots_direct(user_location, max_distance_km, top_n, prefs))
     
-    # Priority 3: HTTP fallback
+    # Priority 2: HTTP fallback
     else:
         print("🌐 Using HTTP mode fallback")
         return find_best_spots_http(user_location, max_distance_km, top_n, prefs)

mcp_server/mcp_server.py

@@ -1,8 +1,20 @@
 """
-MCP Server Configuration for Surf Spot Finder
+MCP Server Configuration for Surf Spot Finder.
 
-This module configures the Model Context Protocol server and exposes
-surf spots data as MCP resources.
+This module implements the Model Context Protocol server that exposes
+surf spot data as MCP resources. It provides the core resource handlers
+for listing and reading surf spot information.
+
+The server exposes:
+    - surf://spots/database: 22 world-class surf spots with metadata
+    
+Example:
+    >>> resources = await list_resources()
+    >>> content = await read_resource("surf://spots/database")
+    >>> spots = json.loads(content)["spots"]
+    
+Author: Surf Spot Finder Team
+License: MIT
 """
 
 import json
@@ -67,8 +79,5 @@ async def read_resource(uri: str) -> str:
         raise ValueError(f"Unknown resource URI: {uri}")
 
 
-# Legacy tools listing (keep for backwards compatibility if needed)
-# This was in the old file - we can remove it later
-# @app.get("/tools")
-# def list_tools():
-#     return TOOLS
+# Export server instance for use by other modules
+__all__ = ['server', 'list_resources', 'read_resource']

mcp_server/tools/distance_tool.py

@@ -1,3 +1,33 @@
+"""
+Distance Calculation Tool - Haversine Formula Implementation.
+
+This module provides accurate distance calculations between geographic
+coordinates using the haversine formula for spherical distance calculation.
+It's used for filtering surf spots by proximity to user location.
+
+The haversine formula accounts for the Earth's spherical shape and
+provides distance calculations accurate to within a few meters for
+most surf spot finding applications.
+
+Formula: d = 2r * arcsin(sqrt(sin²(Δφ/2) + cos(φ1) * cos(φ2) * sin²(Δλ/2)))
+Where:
+    - φ is latitude in radians
+    - λ is longitude in radians  
+    - r is Earth's radius (6371 km)
+    - Δφ, Δλ are differences in latitude and longitude
+
+Example:
+    >>> tool = DistanceTool()
+    >>> result = await tool.run({
+    ...     "lat1": 36.72, "lon1": -4.42,  # Málaga
+    ...     "lat2": 36.18, "lon2": -5.92   # Tarifa
+    ... })
+    >>> print(f"Distance: {result['distance_km']:.1f}km")
+
+Author: Surf Spot Finder Team
+License: MIT
+"""
+
 from pydantic import BaseModel
 from typing import Dict, Any
 import math
@@ -5,26 +35,72 @@ import math
 
 class DistanceTool:
     """
-    Placeholder implementation:
-    Computes haversine distance in km.
-    Replace with your real version when ready.
+    Geographic distance calculation tool using haversine formula.
+    
+    Computes spherical distances between coordinate pairs on Earth's surface.
+    Provides accurate results for surf spot proximity filtering and ranking.
+    
+    The haversine formula is well-suited for this use case because:
+        - Accurate for distances up to several hundred kilometers
+        - Computationally efficient
+        - Accounts for Earth's spherical shape
+        - Suitable for surf spot search radii (typically 10-100km)
+    
+    Attributes:
+        Earth radius is set to 6371 km (mean radius)
+        
+    Example:
+        >>> tool = DistanceTool()
+        >>> input_data = {
+        ...     "lat1": 40.7128, "lon1": -74.0060,  # NYC
+        ...     "lat2": 40.7589, "lon2": -73.9851   # Central Park
+        ... }
+        >>> result = await tool.run(input_data)
     """
 
     class DistanceInput(BaseModel):
+        """Input schema for distance calculation.
+        
+        Attributes:
+            lat1: Origin latitude in decimal degrees (-90 to 90).
+            lon1: Origin longitude in decimal degrees (-180 to 180).
+            lat2: Destination latitude in decimal degrees (-90 to 90).
+            lon2: Destination longitude in decimal degrees (-180 to 180).
+        """
         lat1: float
         lon1: float
         lat2: float
         lon2: float
 
     async def run(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
+        """Calculate spherical distance between two coordinate pairs.
+        
+        Implements the haversine formula for accurate distance calculation
+        on Earth's surface. Suitable for surf spot proximity filtering.
+        
+        Args:
+            input_data: Dict containing lat1, lon1, lat2, lon2 coordinates.
+            
+        Returns:
+            Dict with 'distance_km' key containing distance in kilometers.
+            
+        Example:
+            >>> result = await tool.run({
+            ...     "lat1": 36.72, "lon1": -4.42,
+            ...     "lat2": 36.18, "lon2": -5.92
+            ... })
+            >>> print(result["distance_km"])  # 142.3
+        """
         inp = self.DistanceInput(**input_data)
 
-        # Haversine formula (simple but OK)
-        R = 6371  # earth radius in km
+        # Earth's mean radius in kilometers
+        R = 6371
 
+        # Convert latitude and longitude differences to radians
         d_lat = math.radians(inp.lat2 - inp.lat1)
         d_lon = math.radians(inp.lon2 - inp.lon1)
 
+        # Haversine formula calculation
         a = (
             math.sin(d_lat / 2) ** 2
             + math.cos(math.radians(inp.lat1))

mcp_server/tools/llm_agent_tool.py

@@ -1,6 +1,35 @@
 """
-LLM Agent Tool for Surf Spot Finder
-Provides intelligent reasoning and natural language explanations
+LLM Agent Tool for Intelligent Surf Spot Analysis.
+
+This module provides AI-powered reasoning and natural language generation
+for surf spot recommendations. It demonstrates autonomous agent behavior
+by analyzing surf conditions and generating human-like explanations.
+
+The agent supports multiple LLM providers with intelligent fallbacks:
+    1. OpenAI GPT-4 (primary)
+    2. Anthropic Claude (secondary) 
+    3. OpenRouter (multi-model access)
+    4. Rule-based reasoning (always available)
+
+Key capabilities:
+    - Autonomous analysis of surf conditions
+    - Natural language explanation generation
+    - Safety-focused recommendations based on skill level
+    - Multi-factor reasoning about wave, wind, and swell
+    - Contextual advice for different surf scenarios
+
+Example:
+    >>> agent = SurfLLMAgent()
+    >>> input_data = LLMAgentInput(
+    ...     user_location="Tarifa, Spain",
+    ...     user_preferences={"skill_level": "beginner"},
+    ...     surf_spots=evaluated_spots
+    ... )
+    >>> result = await agent.run(input_data)
+    >>> print(result.reasoning)  # AI-generated explanation
+
+Author: Surf Spot Finder Team
+License: MIT
 """
 
 import os
@@ -21,7 +50,14 @@ logger = logging.getLogger(__name__)
 
 
 class LLMAgentInput(BaseModel):
-    """Input schema for LLM agent"""
+    """Input schema for the LLM agent tool.
+    
+    Attributes:
+        user_location: User's location for contextual recommendations.
+        user_preferences: Dict with skill_level, board_type, etc.
+        surf_spots: List of evaluated spots with scores and conditions.
+        reasoning_task: Type of analysis (default: "recommendation").
+    """
     user_location: str = Field(description="User's location")
     user_preferences: Dict[str, Any] = Field(description="User surfing preferences")
     surf_spots: List[Dict[str, Any]] = Field(description="Evaluated surf spots with scores")
@@ -29,7 +65,15 @@ class LLMAgentInput(BaseModel):
 
 
 class LLMAgentOutput(BaseModel):
-    """Output schema for LLM agent"""
+    """Output schema for LLM agent results.
+    
+    Attributes:
+        success: Whether AI analysis completed successfully.
+        summary: Brief recommendation summary (1-2 sentences).
+        reasoning: Detailed AI analysis with explanations.
+        recommendations: List of specific actionable advice.
+        error: Error message if analysis failed.
+    """
     success: bool
     summary: str = ""
     reasoning: str = ""

mcp_server/tools/location_tool.py

@@ -1,6 +1,28 @@
 """
-MCP Tool for Location Services
-Handles geocoding, reverse geocoding, and location parsing
+Location Services Tool for Address Resolution and Geocoding.
+
+This module provides comprehensive location services including:
+    - Address to coordinates conversion (geocoding)
+    - Support for various input formats (addresses, coordinates, place names)
+    - Distance calculations between coordinates
+    - Intelligent parsing of location strings
+
+The tool integrates with Nominatim (OpenStreetMap) for geocoding services
+and includes fallback mechanisms for reliable location resolution.
+
+Supported input formats:
+    - "Málaga, Spain" (city, country)
+    - "123 Main St, New York, NY" (full address)
+    - "36.7156,-4.4044" (decimal coordinates)
+    - "Tarifa Beach" (landmark/place name)
+
+Example:
+    >>> tool = LocationTool()
+    >>> result = tool.run(LocationInput(location_query="Lisbon, Portugal"))
+    >>> print(f"Coordinates: {result.coordinates}")
+
+Author: Surf Spot Finder Team
+License: MIT
 """
 
 from typing import Dict, Optional
@@ -25,14 +47,25 @@ logger = logging.getLogger(__name__)
 # ---------------------- Input / Output Schemas ----------------------
 
 class LocationInput(BaseModel):
-    """Input schema for location tool"""
+    """Input schema for location resolution.
+    
+    Attributes:
+        location_query: Location string in any supported format.
+    """
     location_query: str = Field(
         description="Location name, address, or description (e.g., 'Malaga, Spain')"
     )
 
 
 class LocationOutput(BaseModel):
-    """Output schema for location tool"""
+    """Output schema for location resolution results.
+    
+    Attributes:
+        success: Whether location was successfully resolved.
+        coordinates: Dict with 'lat' and 'lon' keys if successful.
+        formatted_address: Standardized address string from geocoder.
+        error: Error message if resolution failed.
+    """
     success: bool
     coordinates: Optional[Dict[str, float]] = None
     formatted_address: str = ""

mcp_server/tools/marine_data_tool.py

@@ -1,6 +1,32 @@
 """
-Open-Meteo fallback marine data for Surf Spot Finder
-Lightweight version compatible with WaveDataOutput schema
+Open-Meteo Marine Data Tool - Free Reliable Fallback.
+
+This module provides marine and weather data from Open-Meteo APIs
+as a free, reliable fallback when premium services are unavailable.
+It's designed to be compatible with the WaveDataOutput schema.
+
+Data Sources:
+    - Marine API: Wave height, direction, period, swell data
+    - Weather API: Wind speed, direction, gusts
+    
+Features:
+    - No API key required
+    - High availability and reliability
+    - Compatible output format with premium services
+    - Supports both current conditions and forecasts
+    
+Limitations:
+    - Lower resolution than premium APIs
+    - No water temperature data
+    - Reduced forecast accuracy at longer ranges
+    
+Example:
+    >>> api = OpenMeteoMarineAPI()
+    >>> conditions = api.get_current_conditions(36.72, -4.42)
+    >>> print(f"Wave height: {conditions['wave_height']}m")
+
+Author: Surf Spot Finder Team
+License: MIT
 """
 
 import requests
@@ -9,11 +35,37 @@ from typing import Dict, Optional
 
 
 class OpenMeteoMarineAPI:
+    """Open-Meteo marine data client with fallback capabilities.
+    
+    Provides marine and weather data from Open-Meteo's free APIs.
+    Designed as a reliable fallback for premium marine data services.
+    
+    Attributes:
+        BASE_MARINE: Open-Meteo marine API endpoint.
+        BASE_WEATHER: Open-Meteo weather API endpoint.
+    
+    Example:
+        >>> api = OpenMeteoMarineAPI()
+        >>> data = api.get_current_conditions(lat=36.72, lon=-4.42)
+        >>> forecast = api.get_forecast_for_hour(lat, lon, datetime_obj)
+    """
     BASE_MARINE = "https://marine-api.open-meteo.com/v1/marine"
     BASE_WEATHER = "https://api.open-meteo.com/v1/forecast"
 
     def get_current_conditions(self, lat: float, lon: float) -> Dict:
-        """Get real marine + wind data for current time."""
+        """Get current marine and wind conditions.
+        
+        Fetches current wave, wind, and swell data from Open-Meteo APIs.
+        Combines marine and weather data into unified response.
+        
+        Args:
+            lat: Latitude in decimal degrees.
+            lon: Longitude in decimal degrees.
+            
+        Returns:
+            Dict containing wave_height, wind_speed, directions, etc.
+            Compatible with WaveDataOutput schema.
+        """
         marine = self._fetch_marine(lat, lon)
         wind = self._fetch_wind(lat, lon)
 
@@ -32,7 +84,20 @@ class OpenMeteoMarineAPI:
         }
 
     def get_forecast_for_hour(self, lat: float, lon: float, target_datetime: datetime) -> Dict:
-        """Get marine forecast for a specific hour."""
+        """Get marine forecast for specific datetime.
+        
+        Retrieves forecast data for the specified hour from Open-Meteo.
+        Automatically finds the closest available forecast time.
+        
+        Args:
+            lat: Latitude in decimal degrees.
+            lon: Longitude in decimal degrees.
+            target_datetime: Target datetime for forecast data.
+            
+        Returns:
+            Dict with forecast conditions for the specified time.
+            Returns current conditions if forecast unavailable.
+        """
         marine = self._fetch_marine(lat, lon, forecast_days=3)
         wind = self._fetch_wind(lat, lon)
 

mcp_server/tools/spot_finder_tool.py

@@ -1,6 +1,34 @@
 """
-Main Surf Spot Finder Tool
-Orchestrates the complete workflow: location -> spots -> conditions -> evaluation -> ranking
+Main Surf Spot Finder Tool - Complete Workflow Orchestration.
+
+This module provides the primary MCP tool for finding and ranking surf spots.
+It orchestrates the complete workflow from user input to AI-powered recommendations:
+
+1. Location resolution (address/coordinates)
+2. Nearby spot discovery (distance filtering)
+3. Real-time condition analysis (wave/wind data)
+4. Multi-factor evaluation and scoring
+5. AI-powered reasoning and explanations
+
+The tool integrates multiple data sources:
+    - MCP resources for surf spot database
+    - Stormglass API for marine conditions
+    - Nominatim for geocoding
+    - LLM providers for natural language reasoning
+
+Example:
+    >>> finder = SurfSpotFinder()
+    >>> input_data = SpotFinderInput(
+    ...     user_location="Málaga, Spain",
+    ...     max_distance_km=50,
+    ...     top_n=3,
+    ...     user_preferences={"skill_level": "intermediate"}
+    ... )
+    >>> result = await finder.run(input_data)
+    >>> print(f"Found {len(result.spots)} spots")
+    
+Author: Surf Spot Finder Team
+License: MIT
 """
 
 import json
@@ -20,7 +48,14 @@ logger = logging.getLogger(__name__)
 
 
 class SpotFinderInput(BaseModel):
-    """Input schema for spot finder tool"""
+    """Input schema for the surf spot finder tool.
+    
+    Attributes:
+        user_location: User's location as address, city name, or coordinates.
+        max_distance_km: Maximum search radius in kilometers (default: 50).
+        top_n: Number of top-ranked spots to return (default: 3).
+        user_preferences: Dict containing skill_level, board_type, etc.
+    """
     user_location: str = Field(description="User's location (name, address, or coordinates)")
     max_distance_km: float = Field(default=50, description="Maximum distance to search for spots (km)")
     top_n: int = Field(default=3, description="Number of top spots to return")
@@ -28,7 +63,16 @@ class SpotFinderInput(BaseModel):
 
 
 class SpotFinderOutput(BaseModel):
-    """Output schema for spot finder results"""
+    """Output schema for surf spot finder results.
+    
+    Attributes:
+        success: Whether the operation completed successfully.
+        user_location: Resolved coordinates as {"lat": float, "lon": float}.
+        spots: List of ranked surf spots with scores and conditions.
+        ai_summary: Brief AI-generated summary of recommendations.
+        ai_reasoning: Detailed AI analysis and explanations.
+        error: Error message if success is False.
+    """
     success: bool
     user_location: Optional[Dict[str, float]] = None
     spots: List[Dict[str, Any]] = []
@@ -38,7 +82,34 @@ class SpotFinderOutput(BaseModel):
 
 
 class SurfSpotFinder:
-    """Main orchestration tool for finding the best surf spots"""
+    """Main orchestration tool for finding optimal surf spots.
+    
+    This class coordinates the complete surf recommendation workflow by
+    integrating location services, marine data APIs, evaluation algorithms,
+    and AI reasoning to provide ranked surf spot recommendations.
+    
+    The workflow:
+        1. Resolves user location to coordinates
+        2. Filters surf spots by distance
+        3. Fetches real-time wave conditions
+        4. Evaluates each spot using multi-factor scoring
+        5. Generates AI-powered analysis and explanations
+    
+    Attributes:
+        name: Tool identifier for MCP registration.
+        description: Human-readable tool description.
+        location_tool: Service for address/coordinate resolution.
+        stormglass_tool: API client for marine condition data.
+        evaluator: Surf condition evaluation algorithm.
+        llm_agent: AI reasoning and natural language generation.
+        spots_db: Cached surf spot database from MCP resources.
+    
+    Example:
+        >>> finder = SurfSpotFinder()
+        >>> input_data = SpotFinderInput(user_location="Lisbon")
+        >>> result = await finder.run(input_data)
+        >>> print(f"Best spot: {result.spots[0]['name']}")
+    """
     
     name = "find_surf_spots"
     description = "Find and rank the best surf spots near a given location based on current conditions"
@@ -121,7 +192,20 @@ class SurfSpotFinder:
 
 
     def find_nearby_spots(self, user_lat: float, user_lon: float, max_distance_km: float) -> List[Dict[str, Any]]:
-        """Find spots within specified distance of user location"""
+        """Find surf spots within specified distance of user location.
+        
+        Uses haversine formula to calculate spherical distances between
+        user coordinates and each surf spot in the database.
+        
+        Args:
+            user_lat: User's latitude in decimal degrees.
+            user_lon: User's longitude in decimal degrees. 
+            max_distance_km: Maximum search radius in kilometers.
+            
+        Returns:
+            List of surf spots within radius, sorted by distance.
+            Each spot includes original data plus distance_km field.
+        """
         nearby_spots = []
         user_location = (user_lat, user_lon)
         
@@ -139,7 +223,18 @@ class SurfSpotFinder:
         return nearby_spots
     
     async def get_spot_conditions(self, spot: Dict[str, Any]) -> Optional[Dict[str, Any]]:
-        """Get current wave conditions for a spot"""
+        """Get current wave conditions for a specific surf spot.
+        
+        Fetches real-time marine data including wave height, direction,
+        period, wind speed/direction, and tide information.
+        
+        Args:
+            spot: Surf spot dictionary with latitude/longitude.
+            
+        Returns:
+            Dict containing current conditions, or None if fetch fails.
+            Includes wave_height, wave_direction, wind_speed, etc.
+        """
         try:
             # Use the Stormglass tool to get wave data
             from .stormglass_tool import WaveDataInput
@@ -156,7 +251,20 @@ class SurfSpotFinder:
             return None
     
     async def evaluate_spot(self, spot: Dict[str, Any], conditions: Dict[str, Any], user_prefs: Dict[str, Any]) -> Dict[str, Any]:
-        """Evaluate a single spot with current conditions"""
+        """Evaluate a single surf spot using current conditions and user preferences.
+        
+        Applies multi-factor scoring algorithm considering wave conditions,
+        wind analysis, swell direction, and skill compatibility.
+        
+        Args:
+            spot: Surf spot data including location and characteristics.
+            conditions: Current wave/wind conditions from marine APIs.
+            user_prefs: User preferences including skill level, board type.
+            
+        Returns:
+            Dict containing evaluated spot with score, explanation, and
+            breakdown of individual scoring factors.
+        """
         evaluation = await self.evaluator.run({
             "spot": spot,
             "conditions": conditions,
@@ -178,7 +286,21 @@ class SurfSpotFinder:
         }
     
     async def run(self, input_data: SpotFinderInput) -> SpotFinderOutput:
-        """Execute the complete surf spot finding workflow"""
+        """Execute the complete surf spot finding workflow.
+        
+        This is the main entry point that orchestrates all steps of the
+        surf recommendation process from user input to final rankings.
+        
+        Args:
+            input_data: User request containing location, preferences, and filters.
+            
+        Returns:
+            Complete results including ranked spots, AI analysis, and metadata.
+            
+        Raises:
+            No exceptions - all errors are captured in SpotFinderOutput.error
+            for graceful degradation and user-friendly error messages.
+        """
         try:
             # Step 1: Resolve user location
             logger.info(f"Resolving location: {input_data.user_location}")
@@ -273,8 +395,19 @@ class SurfSpotFinder:
             )
 
 
-def create_spot_finder_tool():
-    """Factory function to create the spot finder tool"""
+def create_spot_finder_tool() -> Dict[str, Any]:
+    """Factory function to create the surf spot finder tool.
+    
+    Creates and configures the main MCP tool for surf spot recommendations.
+    Returns tool specification compatible with MCP protocol.
+    
+    Returns:
+        Dict containing tool name, description, schema, and function reference.
+        
+    Example:
+        >>> tool = create_spot_finder_tool()
+        >>> result = await tool["function"](input_data)
+    """
     tool = SurfSpotFinder()
     return {
         "name": tool.name,

mcp_server/tools/stormglass_tool.py

@@ -1,7 +1,31 @@
 """
-MCP Tool — Stormglass Marine Data
-Fetch real marine conditions (wave, swell, wind) with forecast support.
-Includes graceful fallback to Open-Meteo.
+Stormglass Marine Data Tool - Premium Wave and Wind Conditions.
+
+This module provides access to high-quality marine data from the Stormglass API,
+with intelligent fallback to Open-Meteo for reliability. It fetches real-time
+and forecast data including waves, wind, swell, and water temperature.
+
+Data Sources (Priority Order):
+    1. Stormglass API: Premium accuracy, requires API key
+    2. Open-Meteo Marine: Free fallback, always available
+
+Supported Parameters:
+    - Wave height, direction, and period
+    - Wind speed, direction, and gusts
+    - Swell direction and characteristics
+    - Water temperature (Stormglass only)
+    - Forecast data up to 10 days
+
+The tool automatically handles API failures, rate limits, and
+missing API keys by falling back to the free Open-Meteo service.
+
+Example:
+    >>> tool = create_stormglass_tool()["function"]
+    >>> result = tool(WaveDataInput(lat=36.72, lon=-4.42))
+    >>> print(f"Wave height: {result.wave_height}m")
+
+Author: Surf Spot Finder Team
+License: MIT
 """
 
 import os
@@ -18,6 +42,14 @@ from pydantic import BaseModel, Field
 # -------------------------------------------------------
 
 class WaveDataInput(BaseModel):
+    """Input schema for wave data requests.
+    
+    Attributes:
+        lat: Latitude in decimal degrees (-90 to 90).
+        lon: Longitude in decimal degrees (-180 to 180).
+        target_datetime: Optional future datetime for forecast data.
+                        If None, returns current conditions.
+    """
     lat: float = Field(description="Latitude of the surf spot")
     lon: float = Field(description="Longitude of the surf spot")
     target_datetime: Optional[datetime] = Field(
@@ -27,6 +59,20 @@ class WaveDataInput(BaseModel):
 
 
 class WaveDataOutput(BaseModel):
+    """Output schema for marine condition data.
+    
+    Attributes:
+        wave_height: Significant wave height in meters.
+        wave_direction: Wave direction in degrees (0-360).
+        wave_period: Wave period in seconds.
+        wind_speed: Wind speed in meters per second.
+        wind_direction: Wind direction in degrees (0-360).
+        swell_direction: Primary swell direction in degrees.
+        wind_gust: Maximum wind gust speed in m/s.
+        water_temperature: Water temperature in Celsius.
+        timestamp: Data timestamp in ISO format.
+        forecast_target: Target forecast time if applicable.
+    """
     wave_height: float
     wave_direction: float
     wave_period: float

mcp_server/tools/surf_eval_tool.py

@@ -1,3 +1,34 @@
+"""
+Surf Evaluation Tool - Multi-Factor Scoring Algorithm.
+
+This module implements a sophisticated surf condition evaluation system
+that scores surf spots based on multiple environmental factors and user
+preferences. The algorithm considers wave conditions, wind patterns,
+swell direction, and skill compatibility.
+
+Scoring Components (weighted):
+    - Wave Conditions (35%): Height matching and safety
+    - Wind Analysis (25%): Speed and direction optimization  
+    - Swell Direction (25%): Angular matching to optimal window
+    - Skill Compatibility (15%): Break type vs experience level
+
+The scoring system uses normalized 0-100 scales with progressive
+curves that reward optimal conditions while penalizing dangerous
+or suboptimal scenarios.
+
+Example:
+    >>> evaluator = SurfEvaluatorTool()
+    >>> result = await evaluator.run({
+    ...     "spot": surf_spot_data,
+    ...     "conditions": current_wave_data,
+    ...     "prefs": {"skill_level": "intermediate"}
+    ... })
+    >>> print(f"Score: {result['score']}/100")
+
+Author: Surf Spot Finder Team
+License: MIT
+"""
+
 from pydantic import BaseModel
 from typing import Dict, Any, List, Tuple
 import math
@@ -6,16 +37,57 @@ import math
 class SurfEvaluatorTool:
     """
     Advanced surf evaluation tool with multi-factor scoring algorithm.
-    Evaluates surf spots based on wave conditions, wind, and user preferences.
+    
+    This tool implements a comprehensive evaluation system that analyzes
+    surf conditions across multiple dimensions to produce a single score
+    representing the quality and suitability of surfing conditions.
+    
+    The algorithm weighs different factors based on their importance:
+        - Wave conditions: Safety and optimal height ranges
+        - Wind patterns: Offshore vs onshore preferences
+        - Swell direction: Alignment with spot's optimal angles
+        - User skill level: Appropriate difficulty matching
+    
+    All scores are normalized to 0-100 scale for consistency.
+    
+    Attributes:
+        name: Tool identifier for MCP registration.
+        description: Human-readable tool description.
+    
+    Example:
+        >>> evaluator = SurfEvaluatorTool()
+        >>> input_data = SurfEvaluatorTool.SurfEvalInput(
+        ...     spot=spot_data,
+        ...     conditions=wave_conditions,
+        ...     prefs={"skill_level": "beginner"}
+        ... )
+        >>> result = await evaluator.run(input_data.dict())
     """
 
     class SurfEvalInput(BaseModel):
+        """Input schema for surf evaluation.
+        
+        Attributes:
+            spot: Surf spot data including location and characteristics.
+            conditions: Current wave/wind conditions from marine APIs.
+            prefs: User preferences including skill level and board type.
+        """
         spot: Dict[str, Any]
         conditions: Dict[str, Any]
         prefs: Dict[str, Any] = {}
 
     def is_direction_in_range(self, direction: float, direction_range: List[float]) -> bool:
-        """Check if wind/swell direction falls within optimal range for the spot."""
+        """Check if direction falls within optimal range for the surf spot.
+        
+        Handles both normal ranges and those crossing 0° (e.g., 315-45°).
+        
+        Args:
+            direction: Current direction in degrees (0-360).
+            direction_range: [start, end] optimal range in degrees.
+            
+        Returns:
+            True if direction is within the optimal range.
+        """
         if len(direction_range) != 2:
             return False
         
@@ -28,7 +100,18 @@ class SurfEvaluatorTool:
             return start <= direction <= end
 
     def calculate_direction_score(self, direction: float, optimal_range: List[float]) -> float:
-        """Calculate score based on how close direction is to optimal range."""
+        """Calculate score based on direction proximity to optimal range.
+        
+        Uses progressive scoring where perfect alignment = 1.0,
+        and score decreases with angular distance from optimal range.
+        
+        Args:
+            direction: Current direction in degrees.
+            optimal_range: [start, end] optimal range in degrees.
+            
+        Returns:
+            Score between 0.0-1.0 based on direction quality.
+        """
         if not optimal_range or len(optimal_range) != 2:
             return 0.5  # Neutral score if no preference