@avclabs.ai/media-mcp
Node.js >=18 · MIT License
FAQ
What if the Agent times out when calling tools?
This is the key problem this project solves. MCP Agents (like Claude, Cursor) typically have a ~60 second timeout limit for a single tool call.
Solutions:
- Priority use async tools: For time-consuming tasks like video enhancement, always use create_task + get_task_status
- Sync tool truncation mechanism: enhance_video_sync has a built-in 50-second truncation limit
- SAM3 truncation mechanism: sam3_predict polls 25 times by default (~50 seconds)
- Adjust SAM3 polling parameters (advanced): Increase polling attempts via environment variable SAM3_POLL_MAX_ATTEMPTS
Can't find file after dragging attachment?
This is a known limitation of stdio MCP. When dragging or uploading attachments via the Agent interface, file paths are usually not automatically passed to the MCP Server.
Solutions:
- Provide path simultaneously (recommended): After dragging the image, supplement the local absolute path in text
- Wait for auto-encoding: Claude may automatically encode the image as base64
- Answer path inquiry: If Claude asks for the image path, reply with the local absolute path
Is there a priority among the three input methods?
There is no strict priority. Claude will automatically choose the most suitable method based on conversation context:
- You provided a local path → use imagePath
- You provided a network link → use imageUrl
- You dragged an attachment without a path → try imageBase64
What image formats are supported?
Common formats are supported: PNG, JPG, JPEG, BMP, WebP, etc. PNG or JPG is recommended.
What if URL image download fails?
Ensure the URL is publicly accessible, no login, Cookie or signature required. If the image is on a service requiring authentication (e.g. private S3 Bucket, login-required image host), please download to local first and then use imagePath.
What if the Base64 image is too large?
If the image is large (e.g. 4K resolution), the base64 encoded data will be very large and may cause slow transfer. Suggestions: 1. Use imagePath instead; 2. Or compress the image before encoding.