{"_id":"@avclabs.ai/media-mcp","_rev":"4-38caa88a45a53307014d5b42a13518cb","name":"@avclabs.ai/media-mcp","dist-tags":{"latest":"0.2.1"},"versions":{"0.1.0":{"name":"@avclabs.ai/media-mcp","version":"0.1.0","keywords":["mcp","model-context-protocol","video","enhancement","http","client","server","claude","anthropic"],"author":{"name":"Your Name","email":"your.email@example.com"},"license":"MIT","_id":"@avclabs.ai/media-mcp@0.1.0","maintainers":[{"name":"super_bad","email":"wh95hola@gmail.com"},{"name":"tangapple","email":"hb.tang@qq.com"}],"homepage":"https://github.com/avclabs/media-mcp#readme","bugs":{"url":"https://github.com/avclabs/media-mcp/issues"},"bin":{"media-mcp":"dist/server.js"},"dist":{"shasum":"2280bd9a9b95a8fe8436d5da7c90a21dfc13a058","tarball":"https://registry.npmjs.org/@avclabs.ai/media-mcp/-/media-mcp-0.1.0.tgz","fileCount":17,"integrity":"sha512-t5yTPmfCR0ifO4SLahSWV56UXNZ9C5DSVtENbpYPGjI6Zt43zBUTO3hhS1xC4mnvhUGcerTMZslwJeMD2SpApw==","signatures":[{"sig":"MEUCIQDSxSUq9hRKWQmF7miz31Ai6EjNKegnhyicGs6y5iFC0QIgbUYAjZv5Wdm3vTeccBd0bgOFx3XeG7T3TGWlg50zDyY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":64010},"main":"dist/server.js","type":"module","types":"dist/server.d.ts","engines":{"node":">=18.0.0"},"gitHead":"7639e34b1f15dbd70376d866ba766d36a4274b67","mcpName":"io.github.avclabs/media-mcp","scripts":{"dev":"tsc --watch","build":"tsc","prepare":"npm run build","prepublishOnly":"npm run build"},"_npmUser":{"name":"super_bad","email":"wh95hola@gmail.com"},"mcpServer":{"env":{"API_KEY":"your-api-key","HTTP_API_BASE_URL":"https://mcp.avc.ai/enhance","SAM3_API_BASE_URL":"https://mcp.avc.ai/sam"},"args":["-y","@avclabs.ai/media-mcp@latest"],"setup":"需要替换 env.API_KEY 为你的 API Key","command":"npx","description":"视频增强 + SAM3 图像分割 MCP 服务"},"repository":{"url":"git+https://github.com/avclabs/media-mcp.git","type":"git"},"_npmVersion":"10.7.0","description":"MCP Server for video enhancement and image segmentation (SAM3)","directories":{},"_nodeVersion":"18.20.4","dependencies":{"zod":"^3.23.0","axios":"^1.7.0","form-data":"^4.0.5","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.4.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/media-mcp_0.1.0_1778227715485_0.7535068605128354","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@avclabs.ai/media-mcp","version":"0.1.1","keywords":["mcp","model-context-protocol","video","enhancement","http","client","server","claude","anthropic"],"author":{"name":"Your Name","email":"your.email@example.com"},"license":"MIT","_id":"@avclabs.ai/media-mcp@0.1.1","maintainers":[{"name":"super_bad","email":"wh95hola@gmail.com"},{"name":"tangapple","email":"hb.tang@qq.com"}],"homepage":"https://github.com/avclabs/media-mcp#readme","bugs":{"url":"https://github.com/avclabs/media-mcp/issues"},"bin":{"media-mcp":"dist/server.js"},"dist":{"shasum":"6417943611240a8c988340f336cc78545181b7e0","tarball":"https://registry.npmjs.org/@avclabs.ai/media-mcp/-/media-mcp-0.1.1.tgz","fileCount":17,"integrity":"sha512-B4R9RSPZOx86DJbhg7JZeMECGextuPKt8eSKswEz6mGAFs9d3qN43BRN0oCgT06iARUbcKhlGNZOfG5mW87vQw==","signatures":[{"sig":"MEUCIHESY8nAxnIq6WUUIM9RgosAaa4F+oM3g6MJggYJpuMpAiEAoI8QHPN/Cz2aKZigb7MaIGfETrsR4Sbo6/a3DKUyqJo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":64526},"main":"dist/server.js","type":"module","types":"dist/server.d.ts","engines":{"node":">=18.0.0"},"gitHead":"a249f971614747eb92d03fb0a4d8b6e0ab1b5adf","mcpName":"io.github.avclabs/media-mcp","scripts":{"dev":"tsc --watch","build":"tsc","prepare":"npm run build","prepublishOnly":"npm run build"},"_npmUser":{"name":"super_bad","email":"wh95hola@gmail.com"},"mcpServer":{"env":{"API_KEY":"your-api-key","HTTP_API_BASE_URL":"https://mcp.avc.ai/enhance","SAM3_API_BASE_URL":"https://mcp.avc.ai/sam"},"args":["-y","@avclabs.ai/media-mcp@latest"],"setup":"需要替换 env.API_KEY 为你的 API Key","command":"npx","description":"视频增强 + SAM3 图像分割 MCP 服务"},"repository":{"url":"git+https://github.com/avclabs/media-mcp.git","type":"git"},"_npmVersion":"10.7.0","description":"MCP Server for video enhancement and image segmentation (SAM3)","directories":{},"_nodeVersion":"18.20.4","dependencies":{"zod":"^3.23.0","axios":"^1.7.0","form-data":"^4.0.5","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.4.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/media-mcp_0.1.1_1778231081280_0.8826214985460317","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@avclabs.ai/media-mcp","version":"0.2.0","keywords":["mcp","model-context-protocol","video","enhancement","http","client","server","claude","anthropic"],"author":{"name":"Your Name","email":"your.email@example.com"},"license":"MIT","_id":"@avclabs.ai/media-mcp@0.2.0","maintainers":[{"name":"super_bad","email":"wh95hola@gmail.com"},{"name":"tangapple","email":"hb.tang@qq.com"}],"homepage":"https://github.com/avclabs/media-mcp#readme","bugs":{"url":"https://github.com/avclabs/media-mcp/issues"},"bin":{"media-mcp":"dist/server.js"},"dist":{"shasum":"ea96387f7355b9fb7524ac933946a5f628e8db99","tarball":"https://registry.npmjs.org/@avclabs.ai/media-mcp/-/media-mcp-0.2.0.tgz","fileCount":17,"integrity":"sha512-j9R2Ljao+/KCyBoeNVm6vhf1i5mFYAwN525G2hGF9aaLRjsK+RMpXHoQ9vx23dOPAu+znGf98dNMw/ZZv1ogMA==","signatures":[{"sig":"MEUCIDdPBtg0KYJWMeFJa2PbJFepp38logHfuX8ZI9LQY3G7AiEAzMqkVzXVS7Z7tBaPrBeOo5TNBOyfHnbTdYFZspsSU6s=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":74476},"main":"dist/server.js","type":"module","types":"dist/server.d.ts","engines":{"node":">=18.0.0"},"gitHead":"9e42a5d29067f6c1a5b99e88ec289c493c51fe78","mcpName":"io.github.avclabs/media-mcp","scripts":{"dev":"tsc --watch","build":"tsc","prepare":"npm run build","prepublishOnly":"npm run build"},"_npmUser":{"name":"super_bad","email":"wh95hola@gmail.com"},"mcpServer":{"env":{"API_KEY":"your-api-key","HTTP_API_BASE_URL":"https://mcp.avc.ai/enhance","SAM3_API_BASE_URL":"https://mcp.avc.ai/sam"},"args":["-y","@avclabs.ai/media-mcp@latest"],"setup":"需要替换 env.API_KEY 为你的 API Key","command":"npx","description":"视频增强 + SAM3 图像分割 MCP 服务"},"repository":{"url":"git+https://github.com/avclabs/media-mcp.git","type":"git"},"_npmVersion":"10.7.0","description":"MCP Server for video enhancement and image segmentation (SAM3)","directories":{},"_nodeVersion":"18.20.4","dependencies":{"zod":"^3.23.0","axios":"^1.7.0","form-data":"^4.0.5","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.4.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/media-mcp_0.2.0_1778567051620_0.12625825391038736","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"type":"module","name":"@avclabs.ai/media-mcp","version":"0.2.1","description":"MCP Server for video enhancement and image segmentation (SAM3)","mcpName":"io.github.avclabs/media-mcp","main":"dist/server.js","types":"dist/server.d.ts","bin":{"media-mcp":"dist/server.js"},"scripts":{"build":"tsc","dev":"tsc --watch","prepare":"npm run build","prepublishOnly":"npm run build"},"keywords":["mcp","model-context-protocol","video","enhancement","http","client","server","claude","anthropic"],"author":{"name":"Your Name","email":"your.email@example.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/avclabs/media-mcp.git"},"bugs":{"url":"https://github.com/avclabs/media-mcp/issues"},"homepage":"https://github.com/avclabs/media-mcp#readme","dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","axios":"^1.7.0","form-data":"^4.0.5","zod":"^3.23.0"},"devDependencies":{"@types/node":"^20.0.0","typescript":"^5.4.0"},"mcpServer":{"command":"npx","args":["-y","@avclabs.ai/media-mcp@latest"],"env":{"API_KEY":"your-api-key","HTTP_API_BASE_URL":"https://mcp.avc.ai/enhance","SAM3_API_BASE_URL":"https://mcp.avc.ai/sam"},"description":"视频增强 + SAM3 图像分割 MCP 服务","setup":"需要替换 env.API_KEY 为你的 API Key"},"engines":{"node":">=18.0.0"},"_id":"@avclabs.ai/media-mcp@0.2.1","gitHead":"8e477434f2a04ffca49671a1002ec3c207aac244","_nodeVersion":"18.20.4","_npmVersion":"10.7.0","dist":{"integrity":"sha512-Jl1MuMmYMlaXvqYxphRdsDfwCiaeZzXwrz4W2AWYpMjykqfkjQ/ChZ0Q8HYUEPA54adf5EAX3UdGFcREhJViOA==","shasum":"c98eacc61b418591289226fd46de27964733a9eb","tarball":"https://registry.npmjs.org/@avclabs.ai/media-mcp/-/media-mcp-0.2.1.tgz","fileCount":17,"unpackedSize":74535,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFnupW7NAEB7Dg5cQqmWJpJOkjfYR+JrQjr5I8W19ANtAiEA3+ujiZ2UvpCDy2/vqtnm45GTNUYqkPDjMy3DmdjiICs="}]},"_npmUser":{"name":"super_bad","email":"wh95hola@gmail.com"},"directories":{},"maintainers":[{"name":"super_bad","email":"wh95hola@gmail.com"},{"name":"tangapple","email":"hb.tang@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/media-mcp_0.2.1_1779443719966_0.18321178518584347"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-08T08:08:35.361Z","modified":"2026-05-22T09:55:20.239Z","0.1.0":"2026-05-08T08:08:35.626Z","0.1.1":"2026-05-08T09:04:41.408Z","0.2.0":"2026-05-12T06:24:11.766Z","0.2.1":"2026-05-22T09:55:20.101Z"},"bugs":{"url":"https://github.com/avclabs/media-mcp/issues"},"author":{"name":"Your Name","email":"your.email@example.com"},"license":"MIT","homepage":"https://github.com/avclabs/media-mcp#readme","keywords":["mcp","model-context-protocol","video","enhancement","http","client","server","claude","anthropic"],"repository":{"type":"git","url":"git+https://github.com/avclabs/media-mcp.git"},"description":"MCP Server for video enhancement and image segmentation (SAM3)","maintainers":[{"name":"super_bad","email":"wh95hola@gmail.com"},{"name":"tangapple","email":"hb.tang@qq.com"}],"readme":"# media-mcp (Node.js)\n\nEnglish | [中文](https://github.com/avclabs/media-mcp/blob/main/README_CN.md)\n\n[![npm version](https://img.shields.io/npm/v/@avclabs.ai/media-mcp)](https://www.npmjs.com/package/@avclabs.ai/media-mcp)\n[![Node.js >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA video enhancement and image segmentation service based on the MCP protocol, acting as an MCP Client-Server to interact with backend HTTP Servers.\n\n## Features\n\nProvides the following MCP Tools:\n\n**Video Enhancement**\n- `create_task` - Create a video enhancement task (supports URL or local file upload)\n- `get_task_status` - Query task status\n- `enhance_video_sync` - Synchronously enhance video (blocking wait, truncated at ~50s by default)\n\n**Image Segmentation (SAM3)**\n- `sam3_predict` - SAM3 image segmentation (supports local path, URL, or Base64 image)\n\n## Prerequisites\n\n- **Node.js >= 18** (check: `node --version`)\n- **API Key** (required for authentication)\n\n## Lazy Install (Recommended)\n\nIf your AI Agent has a known MCP config path, just copy the line below and send it to your AI:\n\n```\nInstall the npm package @avclabs.ai/media-mcp as an MCP server. My API Key is: sk-xxxxxxxx.\n```\n\nThe AI will automatically:\n1. Detect your MCP client\n2. Find the config file path\n3. Write the correct configuration\n4. Prompt you to restart the client\n\n## Manual Install\n\nNo installation needed. Use `npx` directly in your MCP client config.\n\n### 1. Claude Code (CLI)\n\nRun in Claude Code:\n\n```\n/mcp\n```\n\nCheck the output for the **\"User MCPs\"** section to find the config file path, then edit that file.\n\nCommon paths (if `/mcp` is unavailable):\n- **Windows**: `%USERPROFILE%\\.claude.json`\n- **macOS**: `~/.claude.json`\n- **Linux**: `~/.claude.json`\n- **Legacy/Alternative**: `~/.claude/mcp.json`\n\nPaste this (replace `your-api-key`):\n\n```json\n{\n  \"mcpServers\": {\n    \"video-enhancement\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@avclabs.ai/media-mcp@latest\"],\n      \"env\": {\n        \"API_KEY\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\nSave and run `/mcp` to verify it's loaded.\n\n### 2. Cursor\n\nGo to **Settings > Tools & MCPs > Add New MCP Server**:\n\n- **Name**: `video-enhancement`\n- **Type**: `command`\n- **Command**:\n  ```bash\n  env API_KEY=your-api-key npx -y @avclabs.ai/media-mcp@latest\n  ```\n\nOr edit `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"video-enhancement\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@avclabs.ai/media-mcp@latest\"],\n      \"env\": {\n        \"API_KEY\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\n## Verify Installation\n\nAfter restarting your client, check if the tools are available:\n\n1. Or ask: \"What tools do you have available?\"\n2. You should see: `create_task`, `get_task_status`, `enhance_video_sync`, `sam3_predict`\n\n## Configuration Options\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `API_KEY` | **Yes** | - | API authentication key (shared by video enhancement and SAM3) |\n| `HTTP_API_BASE_URL` | No | `https://mcp.avc.ai/enhance` | Video enhancement service endpoint |\n| `SAM3_API_BASE_URL` | No | `https://mcp.avc.ai/sam` | SAM3 service endpoint |\n| `SAM3_POLL_INTERVAL` | No | `2000` | SAM3 polling interval (milliseconds) |\n| `SAM3_POLL_MAX_ATTEMPTS` | No | `25` | SAM3 maximum polling attempts |\n\n### Custom Endpoint\n\n```json\n{\n  \"env\": {\n    \"HTTP_API_BASE_URL\": \"https://your-endpoint.com\",\n    \"API_KEY\": \"your-api-key\",\n    \"SAM3_API_BASE_URL\": \"https://your-sam3-endpoint.com\"\n  }\n}\n```\n\nOr via CLI args:\n```bash\nnpx -y @avclabs.ai/media-mcp@latest --base-url https://your-endpoint.com --api-key your-api-key --sam3-base-url https://your-sam3-endpoint.com\n```\n\n## Recommended Workflow\n\nThis project provides both **synchronous** and **asynchronous** modes.\n\n**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**:\n\n### Asynchronous Mode (Recommended)\n\n**Video Enhancement:**\n1. Call `create_task` to create a task → immediately get `task_id`\n2. Wait a few seconds, then call `get_task_status` to query the status\n3. If `status` is `processing`, continue waiting and repeat step 2\n4. If `status` is `completed`, the task is done and the result contains `video_url`\n5. If `status` is `failed`, the task failed and the result contains `error_message`\n\n### Synchronous Mode (Simple Scenarios)\n\n**Video Enhancement:**\n- Call `enhance_video_sync` → the server polls internally\n- Defaults to a maximum wait of 50 seconds\n- If completed within 50 seconds, returns the result directly\n- If not completed within 50 seconds, returns `task_id` and instructions for the Agent to switch to `get_task_status`\n\n**Image Segmentation (SAM3):**\n- Call `sam3_predict` → the server polls internally\n- Defaults to a maximum wait of 50 seconds (25 attempts × 2-second polling interval)\n- If completed within 50 seconds, returns the segmentation result directly\n- If not completed within 50 seconds, returns a truncation notice indicating the task is still processing\n\n## Usage Examples\n\nOnce configured, ask your AI agent naturally:\n\n> \"Enhance this video to 1080p: https://example.com/video.mp4\"\n\n> \"Improve the quality of /Users/me/Desktop/video.mp4 to 2k\"\n\n> \"Analyze this image and find all objects: C:\\\\Users\\\\xxx\\\\photo.png\"\n\n> \"Use SAM3 to segment this image, prompt: 'find all cars'\"\n\nThe agent will automatically choose sync or async tools based on task complexity.\n\n## Provided Tools\n\n### Video Enhancement\n\n#### create_task\n\nCreate an asynchronous video enhancement task.\n\n> **Recommended for most use cases.** Ideal for longer videos (over 10 seconds) to avoid timeouts and blocking the connection.\n\n| Parameter | Type | Required | Default | Description |\n|---|---|---|---|---|\n| `video_source` | string | Yes | - | Video URL or local file path (URL must be publicly accessible, links requiring login or signatures are not supported) |\n| `type` | string | No | `url` | `url` or `local` |\n| `resolution` | string | No | `720p` | `480p`, `540p`, `720p`, `1080p`, `2k` |\n\n**Returns:**\n```json\n{\n  \"success\": true,\n  \"task_id\": \"xxx\",\n  \"status\": \"processing\"\n}\n```\n\n#### get_task_status\n\nQuery video enhancement task status.\n\n> 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.\n\n| Parameter | Type | Required |\n|---|---|---|\n| `task_id` | string | Yes |\n\n**Returns:**\n```json\n{\n  \"success\": true,\n  \"task_id\": \"xxx\",\n  \"status\": \"completed\",\n  \"progress\": 100,\n  \"video_url\": \"https://...\",\n  \"message\": \"Task is still processing, please check again later\"\n}\n```\n\nThe `message` field only appears when `status` is `processing`, prompting the Agent to continue waiting.\n\n#### enhance_video_sync\n\nSynchronously enhance video (blocks until completion).\n\n> **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.\n\n| Parameter | Type | Required | Default | Description |\n|---|---|---|---|---|\n| `video_source` | string | Yes | - | Video URL or local file path |\n| `type` | string | No | `url` | `url` or `local` |\n| `resolution` | string | No | `720p` | Target resolution |\n| `poll_interval` | number | No | `5` | Poll interval (seconds) |\n| `timeout` | number | No | `50` | Sync wait timeout (seconds), returns early when exceeded |\n\n**Truncated return example (not completed within 50s):**\n```json\n{\n  \"success\": true,\n  \"status\": \"processing\",\n  \"task_id\": \"xxx\",\n  \"message\": \"Task is still processing (waited 50 seconds). Please use get_task_status to continue polling.\",\n  \"note\": \"The synchronous wait for this long-running task has been truncated. Switch to get_task_status polling.\"\n}\n```\n\n### Image Segmentation (SAM3)\n\n#### sam3_predict\n\nAnalyze an image using the SAM3 segmentation API to generate inference results (masks, boxes, scores).\n\n**Parameters:**\n\nImage input (choose one, must provide exactly one):\n\n- `imagePath` (string): Absolute path of a local image file. Supports common formats (PNG, JPG, JPEG).\n  - Example: `\"C:\\\\Users\\\\xxx\\\\photo.png\"`, `\"/home/user/images/cat.jpg\"`\n  - Use when: The user explicitly provides a local file path\n\n- `imageUrl` (string): Publicly accessible URL of the image.\n  - Example: `\"https://example.com/photo.jpg\"`\n  - Use when: The image is already online and the user provides a link\n  - Note: The URL must be publicly accessible. Links requiring login or signatures are not supported\n\n- `imageBase64` (string): Base64-encoded image data.\n  - Example: `\"iVBORw0KGgoAAAANSUhEUgAA...\"`\n  - Use when: The user drags or uploads an image attachment, and the Agent encodes it as base64\n  - Note: Large images will produce very large base64 strings, which may slow transmission\n\nOther parameters:\n\n- `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.\n\n**Normal completion return:**\n\nAfter inference completes, returns a JSON string containing three fields:\n\n- **`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.\n- **`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.\n\n  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`.\n- **`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.\n\nExample result JSON:\n\n```json\n{\n  \"masks\": [\n    [[0, 0, 1, ...], [0, 1, 1, ...], ...],\n    [[0, 0, 0, ...], [0, 0, 1, ...], ...]\n  ],\n  \"boxes\": [\n    [120, 80, 300, 450],\n    [400, 200, 600, 500]\n  ],\n  \"scores\": [0.95, 0.87]\n}\n```\n\n**Truncated return example (not completed within 50s):**\n```json\n{\n  \"success\": true,\n  \"status\": \"processing\",\n  \"task_id\": \"xxx\",\n  \"message\": \"Task is still processing (waited about 50 seconds). Please retry later or record this task_id for manual follow-up.\",\n  \"note\": \"The synchronous wait for this long-running task has been truncated.\"\n}\n```\n\n## FAQ\n\n### Agent reports timeout when calling tools?\n\nThis is the primary issue this project addresses. MCP Agents (such as Claude, Cursor) typically enforce a ~60-second timeout per tool call. If task processing exceeds this limit, the Agent will error and disconnect.\n\n**Solutions:**\n\n1. **Prefer asynchronous tools**: For video enhancement and other time-consuming tasks, always use `create_task` + `get_task_status`. These tools return instantly on each call and will not trigger timeouts.\n\n2. **Sync tool truncation mechanism**: `enhance_video_sync` has an internal 50-second truncation limit. If the task is not completed within 50 seconds, the tool proactively returns a `task_id` and instructs the Agent to use `get_task_status` to follow up.\n\n3. **SAM3 truncation mechanism**: `sam3_predict` defaults to 25 polling attempts (~50 seconds). If the task is not completed, it returns a truncation notice indicating the task is still processing.\n\n4. **Adjust SAM3 polling parameters** (advanced): If you are confident that SAM3 tasks are usually fast (e.g., under 10 seconds), you can increase polling attempts via environment variable:\n   ```bash\n   SAM3_POLL_MAX_ATTEMPTS=60\n   ```\n   But ensure the total wait time does not exceed your Agent's timeout limit.\n\n### Drag-and-drop attachment says file not found?\n\nThis is a known limitation of stdio MCP. When dragging or uploading an attachment through the Agent interface, the file path is usually not automatically passed to the MCP Server.\n\n**Solutions:**\n\n1. **Provide the path simultaneously** (recommended): After dragging the image, add the local absolute path in your message:\n   > \"Please analyze this image `D:\\\\photos\\\\cat.jpg` and find the cat\"\n\n2. **Wait for auto-encoding**: Claude may automatically encode the image as base64. If successful, no extra action is needed.\n\n3. **Reply to path inquiry**: If Claude asks for the image path, simply reply with the local absolute path.\n\n### Is there a priority among the three input methods?\n\nThere is no strict priority. Claude will automatically choose the most appropriate method based on conversation context:\n\n- You provided a local path → uses `imagePath`\n- You provided a web link → uses `imageUrl`\n- You dragged an attachment without a path → tries `imageBase64`\n\n### What image formats are supported?\n\nCommon formats: PNG, JPG, JPEG, BMP, WebP, etc. PNG or JPG is recommended.\n\n### What if URL image download fails?\n\nEnsure the URL is **publicly accessible**, requiring no login, cookies, or signatures. If the image is on a service requiring authentication (e.g., private S3 Bucket, login-required image host), download it locally first and use `imagePath`.\n\n### What if the base64 image is too large?\n\nIf the image is very large (e.g., 4K resolution), the base64-encoded data will be very large and may slow transmission. Suggestions:\n\n1. Use `imagePath` instead\n2. Or compress the image before encoding\n\n## File Upload Notes\n\nWhen `type` is `\"local\"`:\n1. File is read locally by the MCP Server\n2. Uploaded directly to TOS object storage via pre-signed URL\n3. **Max file size: 100MB**\n\n## Troubleshooting\n\n### \"command not found: npx\"\n\nInstall Node.js >= 18: https://nodejs.org/\n\n### \"Error: --api-key argument or API_KEY environment variable is required\"\n\nYour API Key is missing. Double-check the `env.API_KEY` in your config.\n\n### MCP Server shows red/error in client\n\nCheck logs:\n- **Claude Desktop macOS**: `~/Library/Logs/Claude/mcp*.log`\n- **Claude Desktop Windows**: `%APPDATA%\\Claude\\logs\\mcp*.log`\n- **Cursor**: Output panel > MCP\n\n### \"TOS upload failed\"\n\nUsually a signature mismatch. Ensure your `HTTP_API_BASE_URL` and `API_KEY` are correct and active.\n\n## Global Install (Alternative)\n\nIf you prefer not using `npx` every time:\n\n```bash\nnpm install -g @avclabs.ai/media-mcp\n```\n\nThen use `\"command\": \"media-mcp\"` with `\"args\": [\"--api-key\", \"your-api-key\"]` in your config.\n\n## License\n\nMIT License - See [LICENSE](LICENSE) file for details\n","readmeFilename":"README.md"}