unsplash_search
Search for high-quality photos on Unsplash to enhance country profiles with relevant imagery and proper photographer credits.
Instructions
Search for photos on Unsplash using the given query.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"query": "<query>"
},
"name": "unsplash_search"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| num_results | No | ||
| orientation | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
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)}"