@avclabs.ai/media-mcp 0.2.1 → 0.3.0

package/README.md

@@ -6,7 +6,9 @@ English | [中文](https://github.com/avclabs/media-mcp/blob/main/README_CN.md)
 [![Node.js >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A video enhancement and image segmentation service based on the MCP protocol, acting as an MCP Client-Server to interact with backend HTTP Servers.
+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.
+
+> **Release status:** the published npm package (`latest` = `0.2.1`) includes 3 video tools and 2 SAM3 tools. Image enhancement tools are in active development and will ship in an upcoming release — they are documented below for early adopters, but are not part of the published package yet.
 
 ## Features
 
@@ -15,10 +17,17 @@ 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)
+- `enhance_video_sync` - Synchronously enhance video (blocking wait, truncated at ~45s by default)
+
+**Image Enhancement (coming soon — not in the published package yet)**
+- `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)
 
 ## Prerequisites
 
@@ -109,24 +118,28 @@ Or edit `~/.cursor/mcp.json`:
 After restarting your client, check if the tools are available:
 
 1. Or ask: "What tools do you have available?"
-2. You should see: `create_task`, `get_task_status`, `enhance_video_sync`, `sam3_predict`
+2. With the current npm `latest=0.2.1`, you should see `create_task`, `get_task_status`, `enhance_video_sync`, `sam3_predict`, and `get_sam3_task_status`.
+3. Once the image tools ship in an upcoming release, you will additionally see `enhance_image_sync`, `colorize_image_sync`, `denoise_image_sync`, and `get_image_task_status`.
 
 ## Configuration Options
 
 | Variable | Required | Default | Description |
 |---|---|---|---|
-| `API_KEY` | **Yes** | - | API authentication key (shared by video enhancement and SAM3) |
-| `HTTP_API_BASE_URL` | No | `https://mcp.avc.ai/enhance` | Video enhancement service endpoint |
+| `API_KEY` | **Yes** | - | API authentication key (shared by video, image, and SAM3 services) |
+| `HTTP_API_BASE_URL` | No | `https://mcp.avc.ai/enhance` | Shared video and image HTTP service endpoint |
+| `IMAGE_API_BASE_URL` | No | Same as `HTTP_API_BASE_URL` | Optional image endpoint override; omit for the shared production server |
 | `SAM3_API_BASE_URL` | No | `https://mcp.avc.ai/sam` | SAM3 service endpoint |
-| `SAM3_POLL_INTERVAL` | No | `2000` | SAM3 polling interval (milliseconds) |
-| `SAM3_POLL_MAX_ATTEMPTS` | No | `25` | SAM3 maximum polling attempts |
+| `SAM3_POLL_INTERVAL_MS` | No | `2000` | SAM3 polling interval in milliseconds (`SAM3_POLL_INTERVAL` is a deprecated alias) |
+| `SAM3_POLL_MAX_ATTEMPTS` | No | `25` | SAM3 maximum status queries; the time budget is interval × attempts, and whichever limit is hit first truncates the wait |
+
+`IMAGE_API_BASE_URL` is an optional override for pointing image calls at a custom image endpoint. When omitted, image and video calls share the `HTTP_API_BASE_URL` service — the recommended setup for the production server.
 
 ### Custom Endpoint
 
 ```json
 {
   "env": {
-    "HTTP_API_BASE_URL": "https://your-endpoint.com",
+    "HTTP_API_BASE_URL": "https://your-media-endpoint.com",
     "API_KEY": "your-api-key",
     "SAM3_API_BASE_URL": "https://your-sam3-endpoint.com"
   }
@@ -135,9 +148,11 @@ After restarting your client, check if the tools are available:
 
 Or via CLI args:
 ```bash
-npx -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
+npx -y @avclabs.ai/media-mcp@latest --base-url https://your-media-endpoint.com --api-key your-api-key --sam3-base-url https://your-sam3-endpoint.com
 ```
 
+The optional `--image-base-url` flag is available for deployments that intentionally split the public image endpoint; the current npm `latest` release does not use it (image calls share the main endpoint).
+
 ## Recommended Workflow
 
 This project provides both **synchronous** and **asynchronous** modes.
@@ -157,15 +172,15 @@ This project provides both **synchronous** and **asynchronous** modes.
 
 **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`
+- Defaults to a maximum wait of 45 seconds
+- If completed within 45 seconds, returns the result directly
+- If not completed within 45 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
+- Defaults to at most 25 status queries within a ~50-second budget (25 × 2-second interval; whichever limit is reached first ends the wait)
+- If the task completes within the budget, returns the segmentation result directly
+- If not completed within the budget, returns a truncation notice (with `task_id`) indicating the task is still processing
 
 ## Usage Examples
 
@@ -175,6 +190,12 @@ Once configured, ask your AI agent naturally:
 
 > "Improve the quality of /Users/me/Desktop/video.mp4 to 2k"
 
+> "Enhance this image: https://example.com/photo.jpg"
+
+> "Colorize this black-and-white photo: /Users/me/Desktop/old_photo.png"
+
+> "Remove noise from this image: C:\\Users\\xxx\\noisy.jpg"
+
 > "Analyze this image and find all objects: C:\\Users\\xxx\\photo.png"
 
 > "Use SAM3 to segment this image, prompt: 'find all cars'"
@@ -234,27 +255,141 @@ The `message` field only appears when `status` is `processing`, prompting the Ag
 
 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.
+> **Best for short videos (estimated processing time < 1 minute).** If the task is not completed within the default 45-second wait budget, the tool returns early with a `task_id`, and you need to use `get_task_status` to continue querying.
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
 | `video_source` | string | Yes | - | Video URL or local file path |
 | `type` | string | No | `url` | `url` or `local` |
 | `resolution` | string | No | `720p` | Target resolution |
-| `poll_interval` | number | No | `5` | Poll interval (seconds) |
-| `timeout` | number | No | `50` | Sync wait timeout (seconds), returns early when exceeded |
+| `poll_interval` | number | No | `5` | Poll interval (seconds, 0.5-30) |
+| `timeout` | number | No | `45` | Sync wait timeout in seconds (1-45), returns early when exceeded |
 
-**Truncated return example (not completed within 50s):**
+**Truncated return example (not completed within the default 45-second budget):**
 ```json
 {
   "success": true,
   "status": "processing",
   "task_id": "xxx",
-  "message": "Task is still processing (waited 50 seconds). Please use get_task_status to continue polling.",
+  "message": "Task is still processing (waited 45 seconds, 9 status queries). 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:
+
+| Tool | Function | Use Case |
+|---|---|---|
+| `enhance_image_sync` | Image quality enhancement & face optimization | Blurry, low-resolution, or degraded photos |
+| `colorize_image_sync` | Black-and-white photo colorization | Restoring old B&W photos with realistic colors |
+| `denoise_image_sync` | Image noise removal | Noisy/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 45s), the result is returned directly. If not, the tool returns early with a `task_id` — use `get_image_task_status` to continue polling.
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `image_source` | string | Yes | - | Image URL or local file path (URL must be publicly accessible, links requiring login or signatures are not supported) |
+| `type` | string | No | `url` | `url` or `local` |
+| `scale` | number | No | `2` | Enhancement scale multiplier (e.g. `2` for 2x, `4` for 4x upscaling) |
+| `poll_interval` | number | No | `5` | Poll interval in seconds (0.5-30) |
+| `timeout` | number | No | `45` | Sync wait timeout in seconds (1-45), returns early when exceeded |
+
+**Normal completion return:**
+```json
+{
+  "success": true,
+  "task_id": "xxx",
+  "status": "completed",
+  "progress": 100,
+  "image_url": "https://..."
+}
+```
+
+**Truncated return (not completed within the default 45-second budget):**
+```json
+{
+  "success": true,
+  "status": "processing",
+  "task_id": "xxx",
+  "message": "Task is still processing (waited 45 seconds, 9 status queries). 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`.
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `image_source` | string | Yes | - | Image URL or local file path (URL must be publicly accessible, links requiring login or signatures are not supported) |
+| `type` | string | No | `url` | `url` or `local` |
+| `poll_interval` | number | No | `5` | Poll interval in seconds (0.5-30) |
+| `timeout` | number | No | `45` | Sync wait timeout in seconds (1-45), 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`.
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `image_source` | string | Yes | - | Image URL or local file path (URL must be publicly accessible, links requiring login or signatures are not supported) |
+| `type` | string | No | `url` | `url` or `local` |
+| `poll_interval` | number | No | `5` | Poll interval in seconds (0.5-30) |
+| `timeout` | number | No | `45` | Sync wait timeout in seconds (1-45), 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.
+
+| Parameter | Type | Required |
+|---|---|---|
+| `task_id` | string | Yes |
+
+**Returns:**
+```json
+{
+  "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.
+
+#### Recommended Workflow for Image Tools
+
+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
@@ -315,13 +450,85 @@ Example result JSON:
   "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."
+  "message": "Task is still processing (waited 50 seconds, 25 status queries). Please use get_sam3_task_status to continue polling.",
+  "note": "The synchronous wait for this long-running task has been truncated. Switch to task status polling."
+}
+```
+
+**Result download failure (completed task, missing result):**
+If the task completed but the result file could not be downloaded, the tool returns `success: false` with the `task_id` and `status: "completed"`. Use `get_sam3_task_status` with that `task_id` to recover the result. Do not resubmit the task.
+```json
+{
+  "success": false,
+  "task_id": "xxx",
+  "status": "completed",
+  "error": "Failed to download the completed result for task xxx: ...",
+  "note": "The task has completed; only the result download failed. Do not resubmit. Use get_sam3_task_status with this task_id to recover the result."
+}
+```
+
+#### 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.
+
+| Parameter | Type | Required |
+|---|---|---|
+| `task_id` | string | Yes |
+
+**Completed return:**
+```json
+{
+  "success": true,
+  "task_id": "xxx",
+  "status": "completed",
+  "result_url": "https://..."
+}
+```
+
+**Processing return:**
+```json
+{
+  "success": true,
+  "task_id": "xxx",
+  "status": "processing",
+  "message": "Task is still processing, please check again later."
+}
+```
+
+**Failed return:**
+```json
+{
+  "success": false,
+  "task_id": "xxx",
+  "status": "failed",
+  "error": "Task failed"
 }
 ```
 
 ## FAQ
 
+### Is AVCLabs Media MCP free to use?
+
+You get a free quota when you register — no credit card required. Beyond the free quota, pricing is pay-as-you-go credit packs (from $19.95) and monthly subscriptions (from $9.95/month). See https://mcp.avc.ai/pricing/ for the current plans.
+
+### Which AI clients work with it?
+
+Any MCP-compatible client. One-command setup guides are available for Claude Code, Cursor, and Windsurf at https://mcp.avc.ai/docs/ (the package speaks standard MCP stdio, so other agents work by adding the same `npx` config).
+
+### Does it need a GPU or powerful hardware?
+
+No. Video enhancement and SAM3 inference run on AVCLabs' cloud infrastructure. Your machine only runs the lightweight MCP stdio server process (Node.js 18+), so a plain laptop is enough.
+
+### Where do I get an API key?
+
+Register at https://mcp.avc.ai/ and create a key in the dashboard. The key authenticates video enhancement, image tools, and SAM3 segmentation.
+
+### What does `sam3_predict` return?
+
+Pixel-level segmentation masks, bounding boxes, and per-instance confidence scores for the objects described by your text prompt — ready to plug into compositing, annotation, or further analysis.
+
 ### Agent reports timeout when calling tools?
 
 This 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.
@@ -330,15 +537,11 @@ This is the primary issue this project addresses. MCP Agents (such as Claude, Cu
 
 1. **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.
 
-2. **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.
+2. **Sync tool truncation mechanism**: `enhance_video_sync` has an internal 45-second truncation limit (default `timeout`). If the task is not completed within the budget, the tool proactively returns a `task_id` and instructs the Agent to use `get_task_status` to follow up.
 
-3. **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.
+3. **SAM3 truncation mechanism**: `sam3_predict` is bounded by two independent limits derived from its config: at most `SAM3_POLL_MAX_ATTEMPTS` status queries (default 25) and a time budget of `SAM3_POLL_INTERVAL_MS × attempts` (default 25 × 2 s ≈ 50 s). Whichever runs out first truncates the wait; the returned notice carries the `task_id` and the actual elapsed time and query count, and the task keeps running remotely.
 
-4. **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:
-   ```bash
-   SAM3_POLL_MAX_ATTEMPTS=60
-   ```
-   But ensure the total wait time does not exceed your Agent's timeout limit.
+4. **Adjust SAM3 polling parameters** (advanced): The two SAM3 limits are independent, so you can trade interval for attempt count freely (e.g. `SAM3_POLL_INTERVAL_MS=1000` with `SAM3_POLL_MAX_ATTEMPTS=50` still gives a ~50-second budget with twice as many queries). Lower the interval if the task usually finishes in a few seconds and you want quicker completion detection. Invalid explicit values (non-integer or outside the allowed range) abort startup before any task can be submitted. The wait budget covers only status polling after the task is created — source preparation, upload, task submission, and the final result download are not part of it, so the total tool call can take longer than the budget.
 
 ### Drag-and-drop attachment says file not found?
 
@@ -389,7 +592,7 @@ When `type` is `"local"`:
 
 Install Node.js >= 18: https://nodejs.org/
 
-### "Error: --api-key argument or API_KEY environment variable is required"
+### "API key is required: pass --api-key or set the API_KEY environment variable"
 
 Your API Key is missing. Double-check the `env.API_KEY` in your config.
 
@@ -402,7 +605,7 @@ Check logs:
 
 ### "TOS upload failed"
 
-Usually a signature mismatch. Ensure your `HTTP_API_BASE_URL` and `API_KEY` are correct and active.
+Usually a signature mismatch. Ensure your `IMAGE_API_BASE_URL` (or its `HTTP_API_BASE_URL` fallback) and `API_KEY` are correct and active.
 
 ## Global Install (Alternative)
 
@@ -414,6 +617,17 @@ npm install -g @avclabs.ai/media-mcp
 
 Then use `"command": "media-mcp"` with `"args": ["--api-key", "your-api-key"]` in your config.
 
+## Development and Release
+
+This package runs locally in the MCP client and is released through npm; it is not a remote Node daemon. To verify a working tree before publishing:
+
+```bash
+npm ci
+npm run release:verify
+```
+
+Maintainers: see the [release guide](https://github.com/avclabs/media-mcp/blob/main/docs/RELEASE.md) for the current release status, version synchronization, publish order, smoke tests, and the relationship with the portal/backend deployment.
+
 ## License
 
 MIT License - See [LICENSE](LICENSE) file for details