Famxplor Family Travel Activities

Instructions

Retrieves family activities that are geographically close to the specified location.

Args:
    latitude (float): Latitude of the location.
    longitude (float): Longitude of the location.
    max_dist (float): Maximum distance from the provided coordinates in meters.
    user_query (str): The precise user's query for which activities are being searched. Used to return relevant activities.

Returns:
    str: A formatted string containing the information of the family activities. Each activity has a title, more info URL, image URL, and location.

Implementation Reference

• server.py:60-91 (handler)

  The main handler function for the 'search_family_activities' tool. It takes lat, lon, max_dist, user_query; calls the Famxplor API; handles response; formats activities using the helper; returns formatted string.

  async def search_family_activities(lat: float, lon: float, max_dist: float, user_query: str) -> str:
      """
      Retrieves family activities that are geographically close to the specified location.
  
      Args:
          latitude (float): Latitude of the location.
          longitude (float): Longitude of the location.
          max_dist (float): Maximum distance from the provided coordinates in meters.
          user_query (str): The precise user's query for which activities are being searched. Used to return relevant activities.
  
      Returns:
          str: A formatted string containing the information of the family activities. Each activity has a title, more info URL, image URL, and location.
      """
      logging.info(f"search_family_activities lat={lat} lon={lon} max_dist={max_dist} user_query='{user_query}'")
  
      url = f"{CONFIG.api_base}/v1/nearest-activities"
      params = {
          "lat": lat,
          "lon": lon,
          "max_distance": max_dist
      }
      data = await make_famxplor_request(url, params)
  
      if not data or "activities" not in data:
          return "Unable to fetch activities."
  
      if not data["activities"]:
          return "No activities found for this location."
  
      activities = [format_activity(activity) for activity in data["activities"]]
      return "\n---\n".join(activities)

• server.py:59-59 (registration)

  Registers the search_family_activities function as an MCP tool using the FastMCP @mcp.tool() decorator.

  @mcp.tool()

• server.py:61-72 (schema)

  Docstring schema defining input arguments (lat, lon, max_dist, user_query) and output format for the tool.

  """
  Retrieves family activities that are geographically close to the specified location.
  
  Args:
      latitude (float): Latitude of the location.
      longitude (float): Longitude of the location.
      max_dist (float): Maximum distance from the provided coordinates in meters.
      user_query (str): The precise user's query for which activities are being searched. Used to return relevant activities.
  
  Returns:
      str: A formatted string containing the information of the family activities. Each activity has a title, more info URL, image URL, and location.
  """

• server.py:50-58 (helper)

  Helper function to format a single activity dictionary into a multi-line string with title, URL, image, location.

  def format_activity(activity: dict) -> str:
      """Format an activity into a readable string."""
      return (
          f"Title: {activity.get('title', 'No title')}\n"
          f"More info URL: {activity.get('url', 'No URL')}\n"
          f"Image URL: {activity.get('img_url', 'No image')}\n"
          f"Location: ({activity.get('lat', 0)}, {activity.get('lon', 0)})\n"
      )

• server.py:32-48 (helper)

  Helper function to make authenticated POST requests to the Famxplor API, handling errors and returning JSON or None.

  async def make_famxplor_request(url: str, json: Any) -> dict[str, Any] | None:
      """Make a request to the Famxplor API with proper error handling."""
      headers = {
          "User-Agent": USER_AGENT,
          "Accept": "application/json",
          "api-key": CONFIG.api_key,
      }
      async with httpx.AsyncClient() as client:
          try:
              response = await client.post(url, headers=headers, timeout=30.0, json=json)
              response.raise_for_status()
              return response.json()
          except Exception as e:
              print(f"Error during Famxplor API request: {e}", file=sys.stderr)
              traceback.print_exc(file=sys.stderr)
              return None