Country Explorer MCP Server

Instructions

Implementation Reference

• server.py:26-30 (handler)

  MCP tool handler function for 'unsplash_search'. This is the entry point decorated with @mcp.tool(), which registers and executes the tool logic by delegating to UnsplashSearcher.
  @mcp.tool() def unsplash_search(query: str, num_results: int = 10, orientation: Optional[str] = None) -> str: """Search for photos on Unsplash using the given query.""" searcher = UnsplashSearcher() return searcher.search_photos(query, num_results, orientation)
• server.py:26-30 (registration)

  Registration of the 'unsplash_search' tool using FastMCP's @mcp.tool() decorator.
  @mcp.tool() def unsplash_search(query: str, num_results: int = 10, orientation: Optional[str] = None) -> str: """Search for photos on Unsplash using the given query.""" searcher = UnsplashSearcher() return searcher.search_photos(query, num_results, orientation)
• unsplash_searcher.py:15-97 (helper)

  Core implementation of the Unsplash photo search logic in the UnsplashSearcher class's search_photos method, which handles API calls, error handling, and result formatting.
  def search_photos(self, query: str, num_results: int = 10, orientation: Optional[str] = None) -> str: """ Search for photos on Unsplash using the given query. Args: query: Search term for photos num_results: Number of photos to return (1-30, default: 10) orientation: Filter by orientation - 'landscape', 'portrait', or 'squarish' (optional) Returns: JSON string containing search results with photo URLs and metadata """ if not self.api_key: return "Error: UNSPLASH_API_KEY environment variable not set. Please add your Unsplash API key to your .env file." # Validate num_results parameter num_results = max(1, min(30, num_results)) # Build the API URL url = f"{self.base_url}/search/photos" headers = { "Authorization": f"Client-ID {self.api_key}", "Accept-Version": "v1" } params = { "query": query, "per_page": num_results } # Add orientation filter if specified if orientation and orientation.strip() and orientation.lower() in ['landscape', 'portrait', 'squarish']: params["orientation"] = orientation.lower() try: response = requests.get(url, headers=headers, params=params) response.raise_for_status() data = response.json() # Format the results for better readability results = { "total": data.get("total", 0), "total_pages": data.get("total_pages", 0), "photos": [] } for photo in data.get("results", []): photo_info = { "id": photo.get("id"), "description": photo.get("description", "No description"), "alt_description": photo.get("alt_description", "No alt description"), "width": photo.get("width"), "height": photo.get("height"), "color": photo.get("color"), "likes": photo.get("likes"), "urls": { "raw": photo.get("urls", {}).get("raw"), "full": photo.get("urls", {}).get("full"), "regular": photo.get("urls", {}).get("regular"), "small": photo.get("urls", {}).get("small"), "thumb": photo.get("urls", {}).get("thumb") }, "user": { "name": photo.get("user", {}).get("name"), "username": photo.get("user", {}).get("username"), "portfolio_url": photo.get("user", {}).get("portfolio_url") }, "links": { "html": photo.get("links", {}).get("html"), "download": photo.get("links", {}).get("download") } } results["photos"].append(photo_info) return json.dumps(results, indent=2) except requests.exceptions.RequestException as e: return f"Error making request to Unsplash API: {str(e)}" except json.JSONDecodeError as e: return f"Error parsing response from Unsplash API: {str(e)}" except Exception as e: return f"Unexpected error: {str(e)}"