search_docker_image
Search Docker Hub for container images by name or query, with customizable result limits, to quickly find relevant Docker images for your projects.
Instructions
Search for Docker images in Docker Hub
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results to return | |
| query | Yes | Image name or search query |
Input Schema (JSON Schema)
{
"description": "Parameters for searching Docker images.",
"properties": {
"limit": {
"default": 5,
"description": "Maximum number of results to return",
"exclusiveMaximum": 50,
"exclusiveMinimum": 0,
"title": "Limit",
"type": "integer"
},
"query": {
"description": "Image name or search query",
"title": "Query",
"type": "string"
}
},
"required": [
"query"
],
"title": "DockerImageSearch",
"type": "object"
}
Implementation Reference
- src/mcp_server_pacman/server.py:80-84 (registration)Registration of the 'search_docker_image' tool in the MCP server, including name, description, and input schema reference.Tool( name="search_docker_image", description="Search for Docker images in Docker Hub", inputSchema=DockerImageSearch.model_json_schema(), ),
- Pydantic model defining the input schema (query and limit) for the search_docker_image tool.class DockerImageSearch(BaseModel): """Parameters for searching Docker images.""" query: Annotated[str, Field(description="Image name or search query")] limit: Annotated[ int, Field( default=5, description="Maximum number of results to return", gt=0, lt=50, ), ]
- src/mcp_server_pacman/server.py:318-337 (handler)Tool handler within @server.call_tool() that validates input using DockerImageSearch model and delegates to search_docker_hub helper, then formats and returns results.elif name == "search_docker_image": try: args = DockerImageSearch(**arguments) logger.debug(f"Validated docker image search args: {args}") except ValueError as e: logger.error(f"Invalid docker image search parameters: {str(e)}") raise McpError(ErrorData(code=INVALID_PARAMS, message=str(e))) logger.info(f"Searching Docker Hub for '{args.query}' (limit={args.limit})") results = await search_docker_hub(args.query, args.limit) logger.info( f"Found {len(results)} results for '{args.query}' on Docker Hub" ) return [ TextContent( type="text", text=f"Search results for '{args.query}' on Docker Hub:\n{json.dumps(results, indent=2)}", ) ]
- Core helper function that performs the HTTP request to Docker Hub's search API, handles errors, parses JSON response, and returns formatted list of image results.@async_cached(http_cache) async def search_docker_hub(query: str, limit: int) -> List[Dict]: """Search Docker Hub for images matching the query.""" async with httpx.AsyncClient() as client: # Use the v2 API for more reliable results response = await client.get( "https://hub.docker.com/v2/search/repositories", params={"query": query, "page_size": limit}, headers={"Accept": "application/json", "User-Agent": DEFAULT_USER_AGENT}, follow_redirects=True, ) if response.status_code != 200: raise McpError( ErrorData( code=INTERNAL_ERROR, message=f"Failed to search Docker Hub - status code {response.status_code}", ) ) try: data = response.json() results = [ { "name": image.get( "repo_name", "" ), # Using repo_name as the name field "description": image.get("description", "") or image.get("short_description", ""), "star_count": image.get("star_count", 0), "pull_count": image.get("pull_count", 0), "is_official": image.get("is_official", False), "updated_at": image.get("last_updated", "") or image.get("updated_at", ""), } for image in data.get("results", [])[:limit] ] return results except Exception as e: raise McpError( ErrorData( code=INTERNAL_ERROR, message=f"Failed to parse Docker Hub search results: {str(e)}", ) )