Kaltura MCP Server

Instructions

Implementation Reference

• src/kaltura_mcp/tools/media.py:190-255 (handler)

  The main handler function that executes the get_thumbnail_url tool. It validates inputs, retrieves the media entry, constructs a custom thumbnail URL based on width, height, and timestamp parameters, and returns JSON with the result.

  async def get_thumbnail_url(
      manager: KalturaClientManager,
      entry_id: str,
      width: int = 120,
      height: int = 90,
      second: int = 5,
  ) -> str:
      """Get thumbnail URL for a media entry with custom dimensions."""
      if not validate_entry_id(entry_id):
          return json.dumps({"error": "Invalid entry ID format"}, indent=2)
  
      # Validate numeric parameters
      if width <= 0 or width > 4096 or height <= 0 or height > 4096:
          return json.dumps(
              {"error": "Invalid dimensions: width and height must be between 1 and 4096"}, indent=2
          )
  
      if second < 0:
          return json.dumps({"error": "Invalid second parameter: must be non-negative"}, indent=2)
  
      try:
          client = manager.get_client()
      except Exception as e:
          return handle_kaltura_error(e, "get thumbnail URL", {"entry_id": entry_id})
  
      # Get the entry to verify it exists
      entry = client.media.get(entry_id)
  
      # Build thumbnail URL with parameters
      base_url = entry.thumbnailUrl
      if not base_url:
          return json.dumps(
              {
                  "error": "No thumbnail available for this entry",
                  "entryId": entry_id,
              }
          )
  
      # Add parameters for custom thumbnail
      params = []
      if width:
          params.append(f"width={width}")
      if height:
          params.append(f"height={height}")
      if second and entry.mediaType == KalturaMediaType.VIDEO:
          params.append(f"vid_sec={second}")
  
      # Construct URL
      if params:
          separator = "&" if "?" in base_url else "?"
          thumbnail_url = base_url + separator + "&".join(params)
      else:
          thumbnail_url = base_url
  
      return json.dumps(
          {
              "entryId": entry_id,
              "entryName": entry.name,
              "mediaType": safe_serialize_kaltura_field(entry.mediaType),
              "thumbnailUrl": thumbnail_url,
              "width": width,
              "height": height,
              "second": second if entry.mediaType == KalturaMediaType.VIDEO else None,
          },
          indent=2,
      )

• src/kaltura_mcp/server.py:319-344 (registration)

  Registers the 'get_thumbnail_url' tool with the MCP server in the list_tools() function. Includes the tool name, detailed description, and input schema for validation.

  types.Tool(
      name="get_thumbnail_url",
      description="Get video THUMBNAIL/POSTER image. USE WHEN: Displaying video previews, creating galleries, showing video cards, generating custom thumbnails. RETURNS: Image URL with your specified size. EXAMPLES: 'Get thumbnail for video 1_abc123', 'Create 400x300 preview image', 'Get frame from 30 seconds in'. Can capture any frame from video.",
      inputSchema={
          "type": "object",
          "properties": {
              "entry_id": {
                  "type": "string",
                  "description": "Video to get thumbnail from (format: '1_abc123')",
              },
              "width": {
                  "type": "integer",
                  "description": "Thumbnail width in pixels (default: 120)",
              },
              "height": {
                  "type": "integer",
                  "description": "Thumbnail height in pixels (default: 90)",
              },
              "second": {
                  "type": "integer",
                  "description": "Video timestamp in seconds to capture (default: 5)",
              },
          },
          "required": ["entry_id"],
      },
  ),

• src/kaltura_mcp/server.py:322-343 (schema)

  Defines the input schema for the get_thumbnail_url tool, specifying parameters like entry_id (required), width, height, and second with types and descriptions.

  inputSchema={
      "type": "object",
      "properties": {
          "entry_id": {
              "type": "string",
              "description": "Video to get thumbnail from (format: '1_abc123')",
          },
          "width": {
              "type": "integer",
              "description": "Thumbnail width in pixels (default: 120)",
          },
          "height": {
              "type": "integer",
              "description": "Thumbnail height in pixels (default: 90)",
          },
          "second": {
              "type": "integer",
              "description": "Video timestamp in seconds to capture (default: 5)",
          },
      },
      "required": ["entry_id"],
  },

• src/kaltura_mcp/server.py:517-518 (registration)

  Dispatches calls to the get_thumbnail_url handler function in the server's call_tool method.

  elif name == "get_thumbnail_url":
      result = await get_thumbnail_url(kaltura_manager, **arguments)

• src/kaltura_mcp/tools/__init__.py:22-26 (helper)

  Re-exports the get_thumbnail_url function from media.py for use in other modules like server.py.

      get_download_url,
      get_media_entry,
      get_thumbnail_url,
      list_media_entries,
  )