Famxplor Family Travel Activities

Instructions

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