get_ad_image

Instructions

Implementation Reference

• meta_ads_mcp/core/images.py:177-227 (handler)

  The main handler function for the get_ad_image tool. Decorated with @mcp.tool(), it retrieves metadata and URL for an uploaded ad image by hash using the Meta Graph API. Validates input, strips the image_hash, ensures account_id format, calls /{account_id}/adimages with the image hash, and returns image metadata (url, dimensions, name, status, etc.) or an error.

  @mcp.tool()
  def get_ad_image(
      account_id: str,
      image_hash: str,
  ) -> dict:
      """
      Retrieve metadata and URL for an uploaded ad image by hash.
  
      Returns the image URL, dimensions, name, and other metadata.
  
      Args:
          account_id: Ad account ID (e.g., 'act_123456789').
          image_hash: Image hash from upload_ad_image.
      """
      if not image_hash or not image_hash.strip():
          return {"error": "image_hash is required.", "blocked_at": "input_validation"}
  
      account_id = ensure_account_id_format(account_id)
      image_hash = image_hash.strip()
  
      api_client._ensure_initialized()
  
      try:
          result = api_client.graph_get(
              f"/{account_id}/adimages",
              fields=["hash", "name", "url", "url_128", "width", "height", "status", "created_time"],
              params={"hashes": f'["{image_hash}"]'},
          )
      except MetaAPIError as e:
          return {"error": f"Meta API error: {e}", "blocked_at": "api_call"}
  
      images = result.get("data", [])
      if not images:
          return {
              "error": f"No image found for hash '{image_hash}'.",
              "blocked_at": "not_found",
          }
  
      img = images[0]
      return {
          "account_id": account_id,
          "image_hash": img.get("hash", image_hash),
          "name": img.get("name"),
          "url": img.get("url"),
          "url_128": img.get("url_128"),
          "width": img.get("width"),
          "height": img.get("height"),
          "status": img.get("status"),
          "created_time": img.get("created_time"),
          "rate_limit_usage_pct": api_client.rate_limits.max_usage_pct,
      }

• tests/test_convenience_wave.py:32-54 (helper)

  Test class for get_ad_image. Verifies the function is callable, registered with @mcp.tool(), and that empty input returns an error.

  class TestGetAdImage:
  
      def test_function_exists(self):
          from meta_ads_mcp.core.images import get_ad_image
          assert callable(get_ad_image)
  
      def test_tool_is_registered(self):
          import inspect
          from meta_ads_mcp.core import images
          source = inspect.getsource(images)
          lines = source.split("\n")
          for i, line in enumerate(lines):
              if "def get_ad_image(" in line:
                  for j in range(max(0, i - 3), i):
                      if "@mcp.tool()" in lines[j] and not lines[j].strip().startswith("#"):
                          return
                  pytest.fail("get_ad_image not registered")
  
      def test_empty_hash_returns_error(self):
          from meta_ads_mcp.core.images import get_ad_image
          result = get_ad_image(account_id="act_123", image_hash="")
          assert "error" in result
          assert result["blocked_at"] == "input_validation"