screenshot_url

Instructions

Implementation Reference

• hermesforge_mcp/server.py:44-114 (handler)

  The screenshot_url tool handler function. It captures a screenshot of a given URL by calling the Hermesforge API, and returns the image as a base64-encoded data URI. Registered via @mcp.tool() decorator on line 44.

  @mcp.tool()
  def screenshot_url(
      url: str,
      width: int = 1280,
      height: int = 800,
      format: str = "png",
      full_page: bool = False,
  ) -> str:
      """
      Capture a screenshot of any web page and return it as a base64-encoded image.
  
      Use this when you need to:
      - See what a website looks like visually
      - Verify a page rendered correctly
      - Capture UI state for debugging or documentation
      - Extract visual information from a web page
  
      Args:
          url: The URL to screenshot (must be publicly accessible)
          width: Viewport width in pixels (default: 1280)
          height: Viewport height in pixels (default: 800)
          format: Image format - 'png' or 'jpeg' (default: 'png')
          full_page: Capture the full page height, not just the viewport (default: False)
  
      Returns:
          Base64-encoded image data with data URI prefix, ready to display.
          Example: "data:image/png;base64,iVBORw0KGgo..."
  
      Rate limits: 10/day free tier. Get a free API key at https://hermesforge.dev/api/keys
      for 100/day. Paid plans available for higher volume.
      """
      params = {
          "url": url,
          "width": width,
          "height": height,
          "format": format,
          "full_page": str(full_page).lower(),
      }
  
      try:
          resp = requests.get(
              f"{API_BASE}/api/screenshot",
              params=params,
              headers=_auth_headers(),
              timeout=30,
          )
      except requests.RequestException as e:
          return f"Error: Could not reach Hermesforge API: {e}"
  
      if resp.status_code == 200:
          img_bytes = resp.content
          b64 = base64.b64encode(img_bytes).decode()
          mime = "image/jpeg" if format == "jpeg" else "image/png"
          return f"data:{mime};base64,{b64}"
      elif resp.status_code == 429:
          try:
              msg = resp.json().get("message", "")
          except Exception:
              msg = ""
          return (
              f"Rate limit reached. {msg} "
              f"Get a free API key at https://hermesforge.dev/api/keys "
              f"or see plans at https://hermesforge.dev/pricing"
          )
      elif resp.status_code == 402:
          return (
              f"Payment required. This endpoint uses x402 micropayments. "
              f"See https://hermesforge.dev/pricing for API key options."
          )
      else:
          return f"Error: API returned {resp.status_code}: {resp.text[:200]}"

• hermesforge_mcp/server.py:44-44 (registration)

  The @mcp.tool() decorator on line 44 registers screenshot_url as an MCP tool with the FastMCP server.

  @mcp.tool()

• hermesforge_mcp/server.py:38-41 (helper)

  Helper function that builds authentication headers using the HERMESFORGE_API_KEY environment variable, used by the screenshot_url handler.

  def _auth_headers() -> dict:
      if API_KEY:
          return {"X-API-Key": API_KEY}
      return {}