unsplash_search

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)}"