Labsco
avclabs logo

AVCLabs Media MCP

from avclabs

AVCLabs MCP integrates AI-powered video upscaling, quality enhancement, and SAM3 image segmentation into MCP workflows. It enhances low-resolution videos, cleans noisy footage, and extracts target objects through text prompts.

πŸ”₯πŸ”₯πŸ”₯βœ“ VerifiedAccount requiredNeeds API keys
#automation#git#search#maps#translation

media-mcp (Node.js)

English | δΈ­ζ–‡

A video enhancement, image enhancement/colorization/denoising, and image segmentation service based on the MCP protocol, acting as an MCP Client-Server to interact with backend HTTP Servers.

Features

Provides the following MCP Tools:

Video Enhancement

  • create_task - Create a video enhancement task (supports URL or local file upload)
  • get_task_status - Query task status
  • enhance_video_sync - Synchronously enhance video (blocking wait, truncated at ~50s by default)

Image Enhancement

  • enhance_image_sync - Enhance image quality and optimize faces (supports URL or local file upload)
  • colorize_image_sync - Colorize black-and-white photos (supports URL or local file upload)
  • denoise_image_sync - Remove noise from images (supports URL or local file upload)
  • get_image_task_status - Query image task status (for polling after sync timeout)

Image Segmentation (SAM3)

  • sam3_predict - SAM3 image segmentation (supports local path, URL, or Base64 image)
  • get_sam3_task_status - Query SAM3 task status (for polling after sync timeout)

This project provides both synchronous and asynchronous modes.

Because MCP Agents typically enforce a ~60-second timeout per tool call, tasks with longer processing times (video enhancement) are strongly recommended to use asynchronous mode:

Video Enhancement:

  1. Call create_task to create a task β†’ immediately get task_id
  2. Wait a few seconds, then call get_task_status to query the status
  3. If status is processing, continue waiting and repeat step 2
  4. If status is completed, the task is done and the result contains video_url
  5. If status is failed, the task failed and the result contains error_message

Synchronous Mode (Simple Scenarios)

Video Enhancement:

  • Call enhance_video_sync β†’ the server polls internally
  • Defaults to a maximum wait of 50 seconds
  • If completed within 50 seconds, returns the result directly
  • If not completed within 50 seconds, returns task_id and instructions for the Agent to switch to get_task_status

Image Segmentation (SAM3):

  • Call sam3_predict β†’ the server polls internally
  • Defaults to a maximum wait of 50 seconds (25 attempts Γ— 2-second polling interval)
  • If completed within 50 seconds, returns the segmentation result directly
  • If not completed within 50 seconds, returns a truncation notice indicating the task is still processing

Provided Tools

Video Enhancement

create_task

Create an asynchronous video enhancement task.

Recommended for most use cases. Ideal for longer videos (over 10 seconds) to avoid timeouts and blocking the connection.

ParameterTypeRequiredDefaultDescription
video_sourcestringYes-Video URL or local file path (URL must be publicly accessible, links requiring login or signatures are not supported)
typestringNourlurl or local
resolutionstringNo720p480p, 540p, 720p, 1080p, 2k

Returns:

{
  "success": true,
  "task_id": "xxx",
  "status": "processing"
}

get_task_status

Query video enhancement task status.

The returned status field can be: processing, completed, or failed. If status is processing, you need to wait a few seconds and call this tool again.

ParameterTypeRequired
task_idstringYes

Returns:

{
  "success": true,
  "task_id": "xxx",
  "status": "completed",
  "progress": 100,
  "video_url": "https://...",
  "message": "Task is still processing, please check again later"
}

The message field only appears when status is processing, prompting the Agent to continue waiting.

enhance_video_sync

Synchronously enhance video (blocks until completion).

Best for short videos (estimated processing time < 1 minute). If the task is not completed within 50 seconds, the tool returns early with a task_id, and you need to use get_task_status to continue querying.

ParameterTypeRequiredDefaultDescription
video_sourcestringYes-Video URL or local file path
typestringNourlurl or local
resolutionstringNo720pTarget resolution
poll_intervalnumberNo5Poll interval (seconds)
timeoutnumberNo50Sync wait timeout (seconds), returns early when exceeded

Truncated return example (not completed within 50s):

{
  "success": true,
  "status": "processing",
  "task_id": "xxx",
  "message": "Task is still processing (waited 50 seconds). Please use get_task_status to continue polling.",
  "note": "The synchronous wait for this long-running task has been truncated. Switch to get_task_status polling."
}

Image Enhancement

Three image processing tools are provided, each targeting a specific use case:

ToolFunctionUse Case
enhance_image_syncImage quality enhancement & face optimizationBlurry, low-resolution, or degraded photos
colorize_image_syncBlack-and-white photo colorizationRestoring old B&W photos with realistic colors
denoise_image_syncImage noise removalNoisy/grainy photos taken in low light

All three tools share the same parameters and behavior pattern. They are synchronous β€” the tool blocks until the image is processed or the timeout is reached.

Supported image formats: PNG, JPG, JPEG, BMP, WebP, etc.

Two upload methods:

  1. URL upload: provide a publicly accessible image URL (type: "url")
  2. Local upload: provide a local file path, the MCP Server auto-uploads to TOS object storage (type: "local", max file size: 100MB)

enhance_image_sync

Synchronously enhance an image to improve quality and optimize faces.

The tool internally creates a task and polls for the result. If processing completes within the timeout (default 50s), the result is returned directly. If not, the tool returns early with a task_id β€” use get_image_task_status to continue polling.

ParameterTypeRequiredDefaultDescription
image_sourcestringYes-Image URL or local file path (URL must be publicly accessible, links requiring login or signatures are not supported)
typestringNourlurl or local
scalenumberNo2Enhancement scale multiplier (e.g. 2 for 2x, 4 for 4x upscaling)
poll_intervalnumberNo5Poll interval in seconds
timeoutnumberNo50Sync wait timeout in seconds, returns early when exceeded

Normal completion return:

{
  "success": true,
  "task_id": "xxx",
  "status": "completed",
  "progress": 100,
  "image_url": "https://..."
}

Truncated return (not completed within 50s):

{
  "success": true,
  "status": "processing",
  "task_id": "xxx",
  "message": "Task is still processing (waited 50 seconds). Please use get_image_task_status to continue polling.",
  "note": "The synchronous wait for this long-running task has been truncated. Switch to get_image_task_status polling."
}

colorize_image_sync

Synchronously colorize a black-and-white photo with AI.

Best for old black-and-white photos. The AI will add realistic colors to the image. Supports the same parameters and return format as enhance_image_sync.

ParameterTypeRequiredDefaultDescription
image_sourcestringYes-Image URL or local file path (URL must be publicly accessible, links requiring login or signatures are not supported)
typestringNourlurl or local
poll_intervalnumberNo5Poll interval in seconds
timeoutnumberNo50Sync wait timeout in seconds, returns early when exceeded

Returns: Same format as enhance_image_sync.

denoise_image_sync

Synchronously remove noise from an image.

Best for grainy/noisy photos taken in low-light conditions or with high ISO settings. Supports the same parameters and return format as enhance_image_sync.

ParameterTypeRequiredDefaultDescription
image_sourcestringYes-Image URL or local file path (URL must be publicly accessible, links requiring login or signatures are not supported)
typestringNourlurl or local
poll_intervalnumberNo5Poll interval in seconds
timeoutnumberNo50Sync wait timeout in seconds, returns early when exceeded

Returns: Same format as enhance_image_sync.

get_image_task_status

Query image processing task status. Used to poll for results when a sync tool times out.

The returned status field can be: processing, completed, or failed. If status is processing, wait a few seconds and call this tool again.

ParameterTypeRequired
task_idstringYes

Returns:

{
  "success": true,
  "task_id": "xxx",
  "status": "completed",
  "progress": 100,
  "image_url": "https://...",
  "message": "Task is still processing, please check again later"
}

The message field only appears when status is processing, prompting the Agent to continue waiting.

  1. For most images: Call enhance_image_sync / colorize_image_sync / denoise_image_sync directly β€” the tool handles everything and returns the result
  2. If truncated: The tool returns a task_id, then use get_image_task_status to poll until status becomes completed or failed
  3. If failed: Check the error_message field for details

Image Segmentation (SAM3)

sam3_predict

Analyze an image using the SAM3 segmentation API to generate inference results (masks, boxes, scores).

Parameters:

Image input (choose one, must provide exactly one):

  • imagePath (string): Absolute path of a local image file. Supports common formats (PNG, JPG, JPEG).

    • Example: "C:\\Users\\xxx\\photo.png", "/home/user/images/cat.jpg"
    • Use when: The user explicitly provides a local file path

  • imageUrl (string): Publicly accessible URL of the image.

    • Example: "https://example.com/photo.jpg"
    • Use when: The image is already online and the user provides a link
    • Note: The URL must be publicly accessible. Links requiring login or signatures are not supported

  • imageBase64 (string): Base64-encoded image data.

    • Example: "iVBORw0KGgoAAAANSUhEUgAA..."
    • Use when: The user drags or uploads an image attachment, and the Agent encodes it as base64
    • Note: Large images will produce very large base64 strings, which may slow transmission

Other parameters:

  • prompt (string, required): English text prompt specifying the target object to segment. Since the SAM3 model only accepts English prompts, provide an English description. If the user provides Chinese or other non-English text, the Agent will automatically translate it before calling the tool.

Normal completion return:

After inference completes, returns a JSON string containing three fields:

  • masks: 2D array. Each element is a binary mask (values 0 or 1) with the same dimensions as the input image, marking the pixel-level location of detected objects. The i-th mask corresponds to the i-th detected object instance.

  • boxes: 2D array. Each element is a bounding box in [x1, y1, x2, y2] format, representing the rectangular region of the detected object. x1, y1 are the top-left coordinates; x2, y2 are the bottom-right coordinates.

    Coordinate system: The top-left corner of the image is the origin (0, 0). The x-axis increases to the right, and the y-axis increases downward, in pixels. For example, [120, 80, 300, 450] means the region starts 120px from the left edge and 80px from the top edge, extending to 300px from the left and 450px from the top. Width = x2 - x1 = 180px, Height = y2 - y1 = 370px.

  • scores: 1D array. Each element is a confidence score for the corresponding detection result, ranging from 0 to 1. Higher scores indicate greater model confidence.

Example result JSON:

{
  "masks": [
    [[0, 0, 1, ...], [0, 1, 1, ...], ...],
    [[0, 0, 0, ...], [0, 0, 1, ...], ...]
  ],
  "boxes": [
    [120, 80, 300, 450],
    [400, 200, 600, 500]
  ],
  "scores": [0.95, 0.87]
}

Truncated return example (not completed within 50s):

{
  "success": true,
  "status": "processing",
  "task_id": "xxx",
  "message": "Task is still processing (waited about 50 seconds). Please retry later or record this task_id for manual follow-up.",
  "note": "The synchronous wait for this long-running task has been truncated."
}

get_sam3_task_status

Query SAM3 segmentation task status. Used to poll for results when sam3_predict times out.

The returned status field can be: processing, completed, or failed. If status is processing, wait a few seconds and call this tool again.

ParameterTypeRequired
task_idstringYes

Completed return:

{
  "success": true,
  "task_id": "xxx",
  "status": "completed",
  "result_url": "https://..."
}

Processing return:

{
  "success": true,
  "task_id": "xxx",
  "status": "processing",
  "message": "Task is still processing, please check again later."
}

Failed return:

{
  "success": false,
  "task_id": "xxx",
  "status": "failed",
  "error": "Task failed"
}

File Upload Notes

When type is "local":

  1. File is read locally by the MCP Server
  2. Uploaded directly to TOS object storage via pre-signed URL
  3. Max file size: 100MB