download_polyhaven_asset

Instructions

Download and import a Polyhaven asset into Blender.

Parameters:
- asset_id: The ID of the asset to download
- asset_type: The type of asset (hdris, textures, models)
- resolution: The resolution to download (e.g., 1k, 2k, 4k)
- file_format: Optional file format (e.g., hdr, exr for HDRIs; jpg, png for textures; gltf, fbx for models)

Returns a message indicating success or failure.

Implementation Reference

• src/server.py:560-616 (handler)

  The primary handler function for the 'download_polyhaven_asset' tool. Decorated with @mcp.tool(), it defines the input schema via parameters, proxies the request to Blender's internal command, and formats the response with type-specific messages.

  @mcp.tool()
  def download_polyhaven_asset(
      ctx: Context,
      asset_id: str,
      asset_type: str,
      resolution: str = "1k",
      file_format: str = None,
  ) -> str:
      """
      Download and import a Polyhaven asset into Blender.
  
      Parameters:
      - asset_id: The ID of the asset to download
      - asset_type: The type of asset (hdris, textures, models)
      - resolution: The resolution to download (e.g., 1k, 2k, 4k)
      - file_format: Optional file format (e.g., hdr, exr for HDRIs; jpg, png for textures; gltf, fbx for models)
  
      Returns a message indicating success or failure.
      """
      try:
          blender = get_blender_connection()
          result = blender.send_command(
              "download_polyhaven_asset",
              {
                  "asset_id": asset_id,
                  "asset_type": asset_type,
                  "resolution": resolution,
                  "file_format": file_format,
              },
          )
  
          if "error" in result:
              return f"Error: {result['error']}"
  
          if result.get("success"):
              message = result.get(
                  "message", "Asset downloaded and imported successfully"
              )
  
              # Add additional information based on asset type
              if asset_type == "hdris":
                  return f"{message}. The HDRI has been set as the world environment."
              elif asset_type == "textures":
                  material_name = result.get("material", "")
                  maps = ", ".join(result.get("maps", []))
                  return (
                      f"{message}. Created material '{material_name}' with maps: {maps}."
                  )
              elif asset_type == "models":
                  return f"{message}. The model has been imported into the current scene."
              else:
                  return message
          else:
              return f"Failed to download asset: {result.get('message', 'Unknown error')}"
      except Exception as e:
          logger.error(f"Error downloading Polyhaven asset: {str(e)}")
          return f"Error downloading Polyhaven asset: {str(e)}"

• src/server.py:561-567 (schema)

  Input schema defined by the function parameters: asset_id (str), asset_type (str), resolution (str, default '1k'), file_format (str, optional).

  def download_polyhaven_asset(
      ctx: Context,
      asset_id: str,
      asset_type: str,
      resolution: str = "1k",
      file_format: str = None,
  ) -> str:

• src/server.py:560-560 (registration)

  The @mcp.tool() decorator registers the function as an MCP tool, using the function name as the tool name.

  @mcp.tool()

• src/server.py:693-715 (helper)

  A prompt template that guides the AI on when and how to use the download_polyhaven_asset tool for different asset types.

  @mcp.prompt()
  def asset_creation_strategy() -> str:
      """Defines the preferred strategy for creating assets in Blender"""
      return """When creating 3D content in Blender, always start by checking if PolyHaven is available:
  
      0. Before anything, always check the scene from get_scene_info()
      1. First use get_polyhaven_status() to verify if PolyHaven integration is enabled.
  
      2. If PolyHaven is enabled:
         - For objects/models: Use download_polyhaven_asset() with asset_type="models"
         - For materials/textures: Use download_polyhaven_asset() with asset_type="textures"
         - For environment lighting: Use download_polyhaven_asset() with asset_type="hdris"
  
      3. If PolyHaven is disabled or when falling back to basic tools:
         - create_object() for basic primitives (CUBE, SPHERE, CYLINDER, etc.)
         - set_material() for basic colors and materials
  
      Only fall back to basic creation tools when:
      - PolyHaven is disabled
      - A simple primitive is explicitly requested
      - No suitable PolyHaven asset exists
      - The task specifically requires a basic material/color
      """