高德地图

Instructions

Args:
    origin_address (str): Starting point address (e.g. "北京市朝阳区阜通东大街6号")
    destination_address (str): Ending point address (e.g. "北京市海淀区上地十街10号")
    origin_city (Optional[str]): Optional city name for the origin address to improve geocoding accuracy
    destination_city (Optional[str]): Optional city name for the destination address to improve geocoding accuracy
    
Returns:
    Dict[str, Any]: Route information including distance, duration, and turn-by-turn instructions.
    Considers traffic conditions and road restrictions.

Implementation Reference

• amap_mcp_server/server.py:364-422 (handler)

  Main handler function decorated with @mcp.tool(), which geocodes the provided addresses using maps_geo and then calls maps_direction_driving_by_coordinates to get the driving route, adding address info to the result.

  @mcp.tool()
  def maps_direction_driving_by_address(origin_address: str, destination_address: str, origin_city: Optional[str] = None, destination_city: Optional[str] = None) -> Dict[str, Any]:
      """Plans a driving route between two locations using addresses. Unless you have a specific reason to use coordinates, it's recommended to use this tool.
      
      Args:
          origin_address (str): Starting point address (e.g. "北京市朝阳区阜通东大街6号")
          destination_address (str): Ending point address (e.g. "北京市海淀区上地十街10号")
          origin_city (Optional[str]): Optional city name for the origin address to improve geocoding accuracy
          destination_city (Optional[str]): Optional city name for the destination address to improve geocoding accuracy
          
      Returns:
          Dict[str, Any]: Route information including distance, duration, and turn-by-turn instructions.
          Considers traffic conditions and road restrictions.
      """
      try:
          # Convert origin address to coordinates
          origin_result = maps_geo(origin_address, origin_city)
          if "error" in origin_result:
              return {"error": f"Failed to geocode origin address: {origin_result['error']}"}
          
          if not origin_result.get("return") or not origin_result["return"]:
              return {"error": "No geocoding results found for origin address"}
          
          origin_location = origin_result["return"][0].get("location")
          if not origin_location:
              return {"error": "Could not extract coordinates from origin geocoding result"}
          
          # Convert destination address to coordinates
          destination_result = maps_geo(destination_address, destination_city)
          if "error" in destination_result:
              return {"error": f"Failed to geocode destination address: {destination_result['error']}"}
          
          if not destination_result.get("return") or not destination_result["return"]:
              return {"error": "No geocoding results found for destination address"}
          
          destination_location = destination_result["return"][0].get("location")
          if not destination_location:
              return {"error": "Could not extract coordinates from destination geocoding result"}
          
          # Use the coordinates to plan the driving route
          route_result = maps_direction_driving_by_coordinates(origin_location, destination_location)
          
          # Add address information to the result
          if "error" not in route_result:
              route_result["addresses"] = {
                  "origin": {
                      "address": origin_address,
                      "coordinates": origin_location
                  },
                  "destination": {
                      "address": destination_address,
                      "coordinates": destination_location
                  }
              }
          
          return route_result
      except Exception as e:
          return {"error": f"Route planning failed: {str(e)}"}

• amap_mcp_server/server.py:423-476 (helper)

  Core helper function that makes the actual Amap driving direction API call using coordinates, parses the response into structured route data with paths and steps.

  @mcp.tool()
  def maps_direction_driving_by_coordinates(origin: str, destination: str) -> Dict[str, Any]:
      """驾车路径规划 API 可以根据用户起终点经纬度坐标规划以小客车、轿车通勤出行的方案，并且返回通勤方案的数据
      
      Args:
          origin (str): 起点经纬度坐标，格式为"经度,纬度" (例如："116.434307,39.90909")
          destination (str): 终点经纬度坐标，格式为"经度,纬度" (例如："116.434307,39.90909")
          
      Returns:
          Dict[str, Any]: 包含距离、时长和详细导航信息的路线数据
      """
      try:
          response = requests.get(
              "https://restapi.amap.com/v3/direction/driving",
              params={
                  "key": AMAP_MAPS_API_KEY,
                  "origin": origin,
                  "destination": destination
              }
          )
          response.raise_for_status()
          data = response.json()
          
          if data["status"] != "1":
              return {"error": f"Direction Driving failed: {data.get('info') or data.get('infocode')}"}
              
          paths = []
          for path in data["route"]["paths"]:
              steps = []
              for step in path["steps"]:
                  steps.append({
                      "instruction": step.get("instruction"),
                      "road": step.get("road"),
                      "distance": step.get("distance"),
                      "orientation": step.get("orientation"),
                      "duration": step.get("duration")
                  })
              paths.append({
                  "path": path.get("path"),
                  "distance": path.get("distance"),
                  "duration": path.get("duration"),
                  "steps": steps
              })
              
          return {
              "route": {
                  "origin": data["route"]["origin"],
                  "destination": data["route"]["destination"],
                  "paths": paths
              }
          }
      except requests.exceptions.RequestException as e:
          return {"error": f"Request failed: {str(e)}"}

• amap_mcp_server/server.py:44-83 (helper)

  Helper function used for geocoding addresses to coordinates, called twice in the handler for origin and destination.

  @mcp.tool()
  def maps_geo(address: str, city: Optional[str] = None) -> Dict[str, Any]:
      """将详细的结构化地址转换为经纬度坐标。支持对地标性名胜景区、建筑物名称解析为经纬度坐标"""
      try:
          params = {
              "key": AMAP_MAPS_API_KEY,
              "address": address
          }
          if city:
              params["city"] = city
              
          response = requests.get(
              "https://restapi.amap.com/v3/geocode/geo",
              params=params
          )
          response.raise_for_status()
          data = response.json()
          
          if data["status"] != "1":
              return {"error": f"Geocoding failed: {data.get('info') or data.get('infocode')}"}
              
          geocodes = data.get("geocodes", [])
          results = []
          for geo in geocodes:
              results.append({
                  "country": geo.get("country"),
                  "province": geo.get("province"),
                  "city": geo.get("city"),
                  "citycode": geo.get("citycode"),
                  "district": geo.get("district"),
                  "street": geo.get("street"),
                  "number": geo.get("number"),
                  "adcode": geo.get("adcode"),
                  "location": geo.get("location"),
                  "level": geo.get("level")
              })
          return {"return": results}
      except requests.exceptions.RequestException as e:
          return {"error": f"Request failed: {str(e)}"}