ddg-image-search

Instructions

Implementation Reference

• src/ddg_mcp/server.py:221-283 (handler)

  The handler logic for the 'ddg-image-search' tool within the @server.call_tool() function. It parses input arguments, performs an image search using DuckDuckGo's DDGS.images(), processes the results, and returns interleaved text descriptions and image contents.

  elif name == "ddg-image-search":
      keywords = arguments.get("keywords")
      if not keywords:
          raise ValueError("Missing keywords")
      
      region = arguments.get("region", "wt-wt")
      safesearch = arguments.get("safesearch", "moderate")
      timelimit = arguments.get("timelimit")
      size = arguments.get("size")
      color = arguments.get("color")
      type_image = arguments.get("type_image")
      layout = arguments.get("layout")
      license_image = arguments.get("license_image")
      max_results = arguments.get("max_results", 10)
      
      # Perform search
      ddgs = DDGS()
      results = ddgs.images(
          keywords=keywords,
          region=region,
          safesearch=safesearch,
          timelimit=timelimit,
          size=size,
          color=color,
          type_image=type_image,
          layout=layout,
          license_image=license_image,
          max_results=max_results
      )
      
      # Format results
      formatted_results = f"Image search results for '{keywords}':\n\n"
      
      text_results = []
      image_results = []
      
      for i, result in enumerate(results, 1):
          text_results.append(
              types.TextContent(
                  type="text",
                  text=f"{i}. {result.get('title', 'No title')}\n"
                       f"   Source: {result.get('source', 'Unknown')}\n"
                       f"   URL: {result.get('url', 'No URL')}\n"
                       f"   Size: {result.get('width', 'N/A')}x{result.get('height', 'N/A')}\n"
              )
          )
          
          image_url = result.get('image')
          if image_url:
              image_results.append(
                  types.ImageContent(
                      type="image",
                      url=image_url,
                      alt_text=result.get('title', 'Image search result')
                  )
              )
      
      # Interleave text and image results
      combined_results = []
      for text, image in zip(text_results, image_results):
          combined_results.extend([text, image])
      
      return combined_results

• src/ddg_mcp/server.py:108-127 (registration)

  Registration of the 'ddg-image-search' tool in the @server.list_tools() function, including its name, description, and detailed JSON schema for input parameters.

  types.Tool(
      name="ddg-image-search",
      description="Search the web for images using DuckDuckGo",
      inputSchema={
          "type": "object",
          "properties": {
              "keywords": {"type": "string", "description": "Search query keywords"},
              "region": {"type": "string", "description": "Region code (e.g., wt-wt, us-en, uk-en)", "default": "wt-wt"},
              "safesearch": {"type": "string", "enum": ["on", "moderate", "off"], "description": "Safe search level", "default": "moderate"},
              "timelimit": {"type": "string", "enum": ["d", "w", "m", "y"], "description": "Time limit (d=day, w=week, m=month, y=year)"},
              "size": {"type": "string", "enum": ["Small", "Medium", "Large", "Wallpaper"], "description": "Image size"},
              "color": {"type": "string", "enum": ["color", "Monochrome", "Red", "Orange", "Yellow", "Green", "Blue", "Purple", "Pink", "Brown", "Black", "Gray", "Teal", "White"], "description": "Image color"},
              "type_image": {"type": "string", "enum": ["photo", "clipart", "gif", "transparent", "line"], "description": "Image type"},
              "layout": {"type": "string", "enum": ["Square", "Tall", "Wide"], "description": "Image layout"},
              "license_image": {"type": "string", "enum": ["any", "Public", "Share", "ShareCommercially", "Modify", "ModifyCommercially"], "description": "Image license type"},
              "max_results": {"type": "integer", "description": "Maximum number of results to return", "default": 10},
          },
          "required": ["keywords"],
      },
  ),

• src/ddg_mcp/server.py:111-126 (schema)

  JSON schema defining the input parameters for the 'ddg-image-search' tool, including required 'keywords' and various optional filters.

  inputSchema={
      "type": "object",
      "properties": {
          "keywords": {"type": "string", "description": "Search query keywords"},
          "region": {"type": "string", "description": "Region code (e.g., wt-wt, us-en, uk-en)", "default": "wt-wt"},
          "safesearch": {"type": "string", "enum": ["on", "moderate", "off"], "description": "Safe search level", "default": "moderate"},
          "timelimit": {"type": "string", "enum": ["d", "w", "m", "y"], "description": "Time limit (d=day, w=week, m=month, y=year)"},
          "size": {"type": "string", "enum": ["Small", "Medium", "Large", "Wallpaper"], "description": "Image size"},
          "color": {"type": "string", "enum": ["color", "Monochrome", "Red", "Orange", "Yellow", "Green", "Blue", "Purple", "Pink", "Brown", "Black", "Gray", "Teal", "White"], "description": "Image color"},
          "type_image": {"type": "string", "enum": ["photo", "clipart", "gif", "transparent", "line"], "description": "Image type"},
          "layout": {"type": "string", "enum": ["Square", "Tall", "Wide"], "description": "Image layout"},
          "license_image": {"type": "string", "enum": ["any", "Public", "Share", "ShareCommercially", "Modify", "ModifyCommercially"], "description": "Image license type"},
          "max_results": {"type": "integer", "description": "Maximum number of results to return", "default": 10},
      },
      "required": ["keywords"],
  },