OpenStreetMap MCP Server

Instructions

Implementation Reference

• src/osm_mcp_server/server.py:949-1052 (handler)

  The core handler function for the 'analyze_commute' MCP tool. It performs detailed commute analysis by fetching reverse geocoding for addresses and routing data for multiple transportation modes (car, foot, bike) using the OSMClient, then compiles a comparison of options including distances, durations, and directions.

  @mcp.tool()
  async def analyze_commute(
      home_latitude: float,
      home_longitude: float,
      work_latitude: float,
      work_longitude: float,
      ctx: Context,
      modes: List[str] = ["car", "foot", "bike"],
      depart_at: str = None  # Time in HH:MM format, e.g. "08:30"
  ) -> Dict[str, Any]:
      """
      Perform a detailed commute analysis between home and work locations.
      
      This advanced tool analyzes commute options between two locations (typically home and work),
      comparing multiple transportation modes and providing detailed metrics for each option.
      Includes estimated travel times, distances, turn-by-turn directions, and other commute-relevant
      data. Essential for real estate decisions, lifestyle planning, and workplace relocation analysis.
      
      Args:
          home_latitude: Home location latitude (decimal degrees)
          home_longitude: Home location longitude (decimal degrees)
          work_latitude: Workplace location latitude (decimal degrees)
          work_longitude: Workplace location longitude (decimal degrees)
          modes: List of transportation modes to analyze (options: "car", "foot", "bike")
          depart_at: Optional departure time (format: "HH:MM") for time-sensitive routing
          
      Returns:
          Comprehensive commute analysis with:
          - Summary comparing all transportation modes
          - Detailed route information for each mode
          - Total distance and duration for each option
          - Turn-by-turn directions
      """
      osm_client = ctx.request_context.lifespan_context.osm_client
      
      # Get address information for both locations
      home_info = await osm_client.reverse_geocode(home_latitude, home_longitude)
      work_info = await osm_client.reverse_geocode(work_latitude, work_longitude)
      
      # Get commute information for each mode
      commute_options = []
      
      for mode in modes:
          ctx.info(f"Calculating {mode} route for commute analysis")
          
          # Get route from OSRM
          try:
              route_data = await osm_client.get_route(
                  home_latitude, home_longitude,
                  work_latitude, work_longitude,
                  mode
              )
              
              if "routes" in route_data and len(route_data["routes"]) > 0:
                  route = route_data["routes"][0]
                  
                  # Extract directions
                  steps = []
                  if "legs" in route:
                      for leg in route["legs"]:
                          for step in leg.get("steps", []):
                              steps.append({
                                  "instruction": step.get("maneuver", {}).get("instruction", ""),
                                  "distance": step.get("distance"),
                                  "duration": step.get("duration"),
                                  "name": step.get("name", "")
                              })
                  
                  commute_options.append({
                      "mode": mode,
                      "distance_km": round(route.get("distance", 0) / 1000, 2),
                      "duration_minutes": round(route.get("duration", 0) / 60, 1),
                      "directions": steps
                  })
          except Exception as e:
              ctx.warning(f"Error getting {mode} route: {str(e)}")
              commute_options.append({
                  "mode": mode,
                  "error": str(e)
              })
      
      # Sort by duration (fastest first)
      commute_options.sort(key=lambda x: x.get("duration_minutes", float("inf")))
      
      return {
          "home": {
              "coordinates": {
                  "latitude": home_latitude,
                  "longitude": home_longitude
              },
              "address": home_info.get("display_name", "Unknown location")
          },
          "work": {
              "coordinates": {
                  "latitude": work_latitude,
                  "longitude": work_longitude
              },
              "address": work_info.get("display_name", "Unknown location")
          },
          "commute_options": commute_options,
          "fastest_option": commute_options[0]["mode"] if commute_options else None,
          "depart_at": depart_at
      }