@avclabs.ai/media-mcp 0.2.0 → 0.3.0

package/README_CN.md

@@ -0,0 +1,633 @@
+# media-mcp (Node.js)
+
+[English](https://github.com/avclabs/media-mcp/blob/main/README.md) | 中文
+
+[![npm version](https://img.shields.io/npm/v/@avclabs.ai/media-mcp)](https://www.npmjs.com/package/@avclabs.ai/media-mcp)
+[![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)
+
+基于 MCP 协议的视频增强、图片增强/上色/降噪与图像分割服务，作为 MCP Client-Server 与后端 HTTP Server 交互。
+
+> **发布状态**：当前 npm `latest`（`0.2.1`）包含 3 个视频工具和 2 个 SAM3 工具。图片增强工具正在积极开发中，将在后续版本发布——下文已提前列出供尝鲜参考，但目前尚不包含在已发布的 npm 包中。
+
+## 功能
+
+提供以下 MCP Tools：
+
+**视频增强**
+- `create_task` - 创建视频增强任务（支持 URL 或本地文件上传）
+- `get_task_status` - 查询任务状态
+- `enhance_video_sync` - 同步增强视频（阻塞等待，默认45秒截断）
+
+**图片增强（即将发布，暂不含于已发布的 npm 包）**
+- `enhance_image_sync` - 图片画质增强与人脸优化（支持 URL 或本地文件上传）
+- `colorize_image_sync` - 黑白照片上色（支持 URL 或本地文件上传）
+- `denoise_image_sync` - 图片降噪去噪（支持 URL 或本地文件上传）
+- `get_image_task_status` - 查询图片任务状态（同步工具超时后用于轮询）
+
+**图像分割 (SAM3)**
+- `sam3_predict` - SAM3 图像分割（支持本地路径、URL 或 Base64 图片）
+- `get_sam3_task_status` - 查询 SAM3 任务状态（同步工具超时后用于轮询）
+
+## 前置要求
+
+- **Node.js >= 18** （检查：`node --version`）
+- **API Key** （用于身份认证，请联系服务提供方获取）
+
+## 懒人安装（推荐）
+
+如果你使用的 AI Agent 有确定的 MCP 配置路径，直接复制下面这句发给 AI：
+
+```
+帮我安装 npm 包 @avclabs.ai/media-mcp 作为 MCP server。我的 API Key 是：sk-xxxxxxxx。
+```
+
+AI 会自动完成：
+1. 检测你使用的 MCP 客户端
+2. 找到配置文件路径
+3. 写入正确的配置
+4. 提示你重启客户端
+
+## 手动安装
+
+无需安装，直接在 MCP 客户端配置中使用 `npx` 运行。
+
+### 1. Claude Code（CLI）
+
+在 Claude Code 中运行：
+
+```
+/mcp
+```
+
+查看输出中 **"User MCPs"** 对应的配置文件路径，然后编辑该文件。
+
+常见路径（如果 `/mcp` 不可用）：
+- **Windows**: `%USERPROFILE%\.claude.json`
+- **macOS**: `~/.claude.json`
+- **Linux**: `~/.claude.json`
+- **旧版/备用**: `~/.claude/mcp.json`
+
+粘贴以下内容（将 `your-api-key` 替换为实际 API Key）：
+
+```json
+{
+  "mcpServers": {
+    "video-enhancement": {
+      "command": "npx",
+      "args": ["-y", "@avclabs.ai/media-mcp@latest"],
+      "env": {
+        "API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+保存后运行 `/mcp` 验证是否加载成功。
+
+### 2. Cursor
+
+进入 **设置 > Tools & MCPs > Add New MCP Server**：
+
+- **Name**：`video-enhancement`
+- **Type**：`command`
+- **Command**：
+  ```bash
+  env API_KEY=your-api-key npx -y @avclabs.ai/media-mcp@latest
+  ```
+
+或编辑 `~/.cursor/mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "video-enhancement": {
+      "command": "npx",
+      "args": ["-y", "@avclabs.ai/media-mcp@latest"],
+      "env": {
+        "API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## 验证安装
+
+重启客户端后，确认工具是否加载成功：
+
+1. 或直接问 AI："你有哪些可用的工具？"
+2. 当前 npm `latest=0.2.1` 应看到 `create_task`、`get_task_status`、`enhance_video_sync`、`sam3_predict`、`get_sam3_task_status`。
+3. 图片工具随后续版本发布后，还应能看到 `enhance_image_sync`、`colorize_image_sync`、`denoise_image_sync`、`get_image_task_status`。
+
+## 配置项
+
+| 变量名 | 必填 | 默认值 | 说明 |
+|---|---|---|---|
+| `API_KEY` | **是** | - | API 认证密钥（视频、图片和 SAM3 服务共用） |
+| `HTTP_API_BASE_URL` | 否 | `https://mcp.avc.ai/enhance` | 视频与图片共用的 HTTP 服务接口地址 |
+| `IMAGE_API_BASE_URL` | 否 | 与 `HTTP_API_BASE_URL` 相同 | 可选图片接口覆盖；共享生产服务无需配置 |
+| `SAM3_API_BASE_URL` | 否 | `https://mcp.avc.ai/sam` | SAM3 服务接口地址 |
+| `SAM3_POLL_INTERVAL_MS` | 否 | `2000` | SAM3 轮询间隔（毫秒，`SAM3_POLL_INTERVAL` 为已弃用别名） |
+| `SAM3_POLL_MAX_ATTEMPTS` | 否 | `25` | SAM3 最大状态查询次数；时间预算为 间隔 × 次数，任一限制先耗尽即截断等待 |
+
+`IMAGE_API_BASE_URL` 是可选的图片端点覆盖参数，用于把图片请求指向自定义图片服务。省略时，图片与视频请求共用 `HTTP_API_BASE_URL` 服务——这也是生产服务器的推荐配置。
+
+### 自定义服务地址
+
+```json
+{
+  "env": {
+    "HTTP_API_BASE_URL": "https://your-media-endpoint.com",
+    "API_KEY": "your-api-key",
+    "SAM3_API_BASE_URL": "https://your-sam3-endpoint.com"
+  }
+}
+```
+
+或通过命令行参数：
+```bash
+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
+```
+
+可选的 `--image-base-url` 参数仅用于主动拆分公网图片端点的部署；当前 npm `latest` 版本不使用它（图片请求共用主端点）。
+
+## 推荐的工作流程
+
+本项目提供了**同步**和**异步**两种模式。
+
+**由于 MCP Agent 对单个 tool 调用通常有约 60 秒的超时限制**，处理时间较长的任务（视频增强）强烈建议使用**异步模式**：
+
+### 异步模式（推荐）
+
+**视频增强**：
+1. 调用 `create_task` 创建任务 → 立即获得 `task_id`
+2. 等待几秒后，调用 `get_task_status` 查询状态
+3. 如果 `status` 为 `processing`，继续等待并重复步骤 2
+4. 如果 `status` 为 `completed`，任务完成，结果中包含 `video_url`
+5. 如果 `status` 为 `failed`，任务失败，结果中包含 `error_message`
+
+### 同步模式（简单场景）
+
+**视频增强**：
+- 调用 `enhance_video_sync` → 服务器内部自动轮询
+- 默认最多等待45秒
+- 如果45秒内完成，直接返回结果
+- 如果45秒未完成，返回 `task_id` 和提示，让 Agent 切换到 `get_task_status` 继续查询
+
+**图像分割 (SAM3)**：
+- 调用 `sam3_predict` → 服务器内部自动轮询
+- 默认最多25次状态查询、约50秒时间预算（25次 × 2秒间隔，任一限制先耗尽即截断等待）
+- 如果预算内完成，直接返回分割结果
+- 如果预算内未完成，返回携带 `task_id` 的截断提示，告知任务仍在处理中
+
+## 使用示例
+
+配置完成后，用自然语言对 AI 说：
+
+> "帮我把这个视频增强到 1080p：https://example.com/video.mp4"
+
+> "把我桌面的 video.mp4 提升到 2k 画质"
+
+> "帮我把这张图片画质增强一下：https://example.com/photo.jpg"
+
+> "帮我把这张黑白照片上色：/Users/me/Desktop/old_photo.png"
+
+> "帮我把这张图片降噪去噪：C:\\Users\\xxx\\noisy.jpg"
+
+> "帮我分析这张图片，找出里面的所有物体：C:\\Users\\xxx\\photo.png"
+
+> "用 SAM3 分割这张图片，prompt 是 'find all cars'"
+
+AI 会根据任务复杂度自动选择同步或异步工具完成任务。
+
+## 提供的 Tools
+
+### 视频增强
+
+#### create_task
+
+创建视频增强任务（异步）。
+
+> **推荐使用**：适用于绝大多数场景，尤其是时长超过10秒的视频，可避免超时和长时间阻塞连接。
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| `video_source` | string | 是 | - | 视频 URL 或本地文件路径（URL 必须公网可访问，不支持需要登录或签名的链接） |
+| `type` | string | 否 | `url` | `url` 或 `local` |
+| `resolution` | string | 否 | `720p` | `480p`、`540p`、`720p`、`1080p`、`2k` |
+
+**返回值：**
+```json
+{
+  "success": true,
+  "task_id": "xxx",
+  "status": "processing"
+}
+```
+
+#### get_task_status
+
+查询视频增强任务状态。
+
+> 返回值中的 `status` 字段可能为：`processing`（处理中）、`completed`（已完成）、`failed`（失败）。如果 `status` 为 `processing`，你需要等待几秒后再次调用此工具轮询。
+
+| 参数 | 类型 | 必填 |
+|---|---|---|
+| `task_id` | string | 是 |
+
+**返回值：**
+```json
+{
+  "success": true,
+  "task_id": "xxx",
+  "status": "completed",
+  "progress": 100,
+  "video_url": "https://...",
+  "message": "Task is still processing, please check again later"
+}
+```
+
+其中 `message` 字段只在 `status` 为 `processing` 时出现，提示 Agent 继续等待。
+
+#### enhance_video_sync
+
+同步增强视频（阻塞等待完成）。
+
+> **仅适合短视频（预计处理时间 < 1 分钟）。** 如果任务在默认45秒等待预算内未完成，工具会提前返回并包含 `task_id`，你需要使用 `get_task_status` 继续查询。
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| `video_source` | string | 是 | - | 视频 URL 或本地文件路径 |
+| `type` | string | 否 | `url` | `url` 或 `local` |
+| `resolution` | string | 否 | `720p` | 目标分辨率 |
+| `poll_interval` | number | 否 | `5` | 轮询间隔（秒，0.5-30） |
+| `timeout` | number | 否 | `45` | 同步等待超时时间（秒，1-45），超过后主动返回 |
+
+**截断返回示例（默认45秒预算内未完成）：**
+```json
+{
+  "success": true,
+  "status": "processing",
+  "task_id": "xxx",
+  "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."
+}
+```
+
+### 图片增强
+
+提供三个图片处理工具，分别针对不同场景：
+
+| 工具 | 功能 | 适用场景 |
+|---|---|---|
+| `enhance_image_sync` | 图片画质增强与人脸优化 | 模糊、低分辨率或画质下降的照片 |
+| `colorize_image_sync` | 黑白照片上色 | 为老旧黑白照片恢复真实色彩 |
+| `denoise_image_sync` | 图片降噪去噪 | 弱光环境下拍摄的噪点/颗粒感照片 |
+
+三个工具的参数和行为模式相同，均为**同步**调用——工具会阻塞直到图片处理完成或超时。
+
+**支持的图片格式**：PNG、JPG、JPEG、BMP、WebP 等。
+
+**两种上传方式**：
+1. **URL 上传**：提供公开可访问的图片 URL（`type: "url"`）
+2. **本地上传**：提供本地文件路径，MCP Server 自动上传到 TOS 对象存储（`type: "local"`，最大 100MB）
+
+#### enhance_image_sync
+
+同步增强图片画质并优化人脸。
+
+> 工具内部会创建任务并轮询结果。如果在超时时间内（默认 45 秒）处理完成，直接返回结果；否则提前返回 `task_id`，需用 `get_image_task_status` 继续轮询。
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| `image_source` | string | 是 | - | 图片 URL 或本地文件路径（URL 必须公网可访问，不支持需要登录或签名的链接） |
+| `type` | string | 否 | `url` | `url` 或 `local` |
+| `scale` | number | 否 | `2` | 增强倍数（如 `2` 为 2 倍、`4` 为 4 倍放大） |
+| `poll_interval` | number | 否 | `5` | 轮询间隔（秒，0.5-30） |
+| `timeout` | number | 否 | `45` | 同步等待超时时间（秒，1-45），超过后主动返回 |
+
+**正常完成返回：**
+```json
+{
+  "success": true,
+  "task_id": "xxx",
+  "status": "completed",
+  "progress": 100,
+  "image_url": "https://..."
+}
+```
+
+**截断返回（默认45秒预算内未完成）：**
+```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
+
+同步为黑白照片 AI 上色。
+
+> 适合老旧黑白照片，AI 会为图片添加真实色彩。参数与返回格式与 `enhance_image_sync` 相同。
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| `image_source` | string | 是 | - | 图片 URL 或本地文件路径（URL 必须公网可访问，不支持需要登录或签名的链接） |
+| `type` | string | 否 | `url` | `url` 或 `local` |
+| `poll_interval` | number | 否 | `5` | 轮询间隔（秒，0.5-30） |
+| `timeout` | number | 否 | `45` | 同步等待超时时间（秒，1-45），超过后主动返回 |
+
+**返回值：** 与 `enhance_image_sync` 相同。
+
+#### denoise_image_sync
+
+同步为图片降噪去噪。
+
+> 适合弱光环境或高 ISO 拍摄的噪点/颗粒感照片。参数与返回格式与 `enhance_image_sync` 相同。
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| `image_source` | string | 是 | - | 图片 URL 或本地文件路径（URL 必须公网可访问，不支持需要登录或签名的链接） |
+| `type` | string | 否 | `url` | `url` 或 `local` |
+| `poll_interval` | number | 否 | `5` | 轮询间隔（秒，0.5-30） |
+| `timeout` | number | 否 | `45` | 同步等待超时时间（秒，1-45），超过后主动返回 |
+
+**返回值：** 与 `enhance_image_sync` 相同。
+
+#### get_image_task_status
+
+查询图片处理任务状态。当同步工具超时后，用此工具轮询结果。
+
+> 返回值中的 `status` 字段可能为：`processing`（处理中）、`completed`（已完成）、`failed`（失败）。如果 `status` 为 `processing`，等待几秒后再次调用此工具。
+
+| 参数 | 类型 | 必填 |
+|---|---|---|
+| `task_id` | string | 是 |
+
+**返回值：**
+```json
+{
+  "success": true,
+  "task_id": "xxx",
+  "status": "completed",
+  "progress": 100,
+  "image_url": "https://...",
+  "message": "Task is still processing, please check again later"
+}
+```
+
+其中 `message` 字段只在 `status` 为 `processing` 时出现，提示 Agent 继续等待。
+
+#### 图片工具推荐工作流
+
+1. **大多数图片**：直接调用 `enhance_image_sync` / `colorize_image_sync` / `denoise_image_sync`，工具会完成全部流程并返回结果
+2. **如果被截断**：工具返回 `task_id`，然后用 `get_image_task_status` 轮询，直到 `status` 变为 `completed` 或 `failed`
+3. **如果失败**：查看 `error_message` 字段了解详情
+
+### 图像分割 (SAM3)
+
+#### sam3_predict
+
+使用 SAM3 分割 API 分析图片，生成推理结果（masks、boxes、scores）。
+
+**参数：**
+
+图片输入（三选一，必须提供其中一种）：
+
+- `imagePath` (string): 本地图片的绝对路径。支持常见图片格式（如 PNG、JPG、JPEG）。
+  - 示例：`"C:\\Users\\xxx\\photo.png"`、`"/home/user/images/cat.jpg"`
+  - 适用场景：用户明确提供了本地文件路径
+
+- `imageUrl` (string): 公开可访问的图片 URL。
+  - 示例：`"https://example.com/photo.jpg"`
+  - 适用场景：图片已在网上，用户提供了链接
+  - 注意：URL 必须公开可访问，不支持需要登录或签名的链接
+
+- `imageBase64` (string): Base64 编码的图片数据。
+  - 示例：`"iVBORw0KGgoAAAANSUhEUgAA..."`
+  - 适用场景：用户拖拽或上传了图片附件，Agent 将图片编码为 base64 后传入
+  - 注意：大图片的 base64 数据会比较大，传输时间可能稍长
+
+其他参数：
+
+- `prompt` (string, required): 英文文本提示，用于指定要在图片中分割的目标物体。由于 SAM3 模型仅接受英文 prompt，建议传入英文描述。如果用户提供中文或其他非英文文本，Agent 会自动翻译为英文后调用。
+
+**正常完成返回：**
+
+推理完成后，直接返回 JSON 字符串。该 JSON 包含以下三个字段：
+
+- **`masks`**：二维数组。每个元素是一个与输入图片尺寸相同的二值掩码（取值为 0 或 1），用于标记检测到的物体在图片中的像素级位置。数组中的第 i 个掩码对应第 i 个检测到的物体实例。
+- **`boxes`**：二维数组。每个元素是 `[x1, y1, x2, y2]` 格式的边界框坐标，表示检测到的物体在图片中的矩形区域。`x1`、`y1` 为左上角坐标，`x2`、`y2` 为右下角坐标。
+
+  坐标系说明：以图片左上角为原点 `(0, 0)`，`x` 轴向右增长，`y` 轴向下增长，单位为像素。例如 `[120, 80, 300, 450]` 表示该物体区域从图片左边缘向右 120px、上边缘向下 80px 处开始，延伸至左边缘向右 300px、上边缘向下 450px 处结束，区域宽度为 `x2 - x1 = 180px`，高度为 `y2 - y1 = 370px`。
+- **`scores`**：一维数组。每个元素是对应检测结果的置信度分数，取值范围为 0 到 1。分数越高，表示模型对该检测结果的把握越大。
+
+结果 JSON 内容示例：
+
+```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]
+}
+```
+
+**截断返回示例（预算内未完成）：**
+```json
+{
+  "success": true,
+  "status": "processing",
+  "task_id": "xxx",
+  "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."
+}
+```
+
+**结果下载失败（任务已完成、结果缺失）：**
+任务已完成但结果文件下载失败时，工具返回 `success: false`，同时携带 `task_id` 与 `status: "completed"`。请用该 `task_id` 调用 `get_sam3_task_status` 恢复结果，不要重新提交任务。
+```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
+
+查询 SAM3 分割任务状态。当 `sam3_predict` 超时后，用此工具轮询结果。
+
+> 返回值中的 `status` 字段可能为：`processing`（处理中）、`completed`（已完成）、`failed`（失败）。如果 `status` 为 `processing`，等待几秒后再次调用此工具。
+
+| 参数 | 类型 | 必填 |
+|---|---|---|
+| `task_id` | string | 是 |
+
+**已完成返回：**
+```json
+{
+  "success": true,
+  "task_id": "xxx",
+  "status": "completed",
+  "result_url": "https://..."
+}
+```
+
+**处理中返回：**
+```json
+{
+  "success": true,
+  "task_id": "xxx",
+  "status": "processing",
+  "message": "Task is still processing, please check again later."
+}
+```
+
+**失败返回：**
+```json
+{
+  "success": false,
+  "task_id": "xxx",
+  "status": "failed",
+  "error": "Task failed"
+}
+```
+
+## 常见问题
+
+### AVCLabs Media MCP 是免费的吗？
+
+注册即送免费额度，无需绑定信用卡。超出免费额度后按量付费：积分包（$19.95 起）和月订阅（$9.95/月起）。当前套餐见 https://mcp.avc.ai/pricing/ 。
+
+### 支持哪些 AI 客户端？
+
+任何兼容 MCP 的客户端。Claude Code、Cursor、Windsurf 有一键配置指南：https://mcp.avc.ai/docs/ （本包使用标准 MCP stdio 协议，其他 agent 使用相同的 `npx` 配置即可接入）。
+
+### 需要 GPU 或高性能硬件吗？
+
+不需要。视频增强与 SAM3 推理都在 AVCLabs 云端完成，本机只运行轻量的 MCP stdio 服务进程（Node.js 18+），普通笔记本即可。
+
+### API Key 在哪里获取？
+
+在 https://mcp.avc.ai/ 注册后在控制台创建。同一个 Key 同时用于视频增强、图片工具与 SAM3 分割。
+
+### `sam3_predict` 返回什么？
+
+文本提示所描述目标的像素级分割掩码（masks）、边界框（bounding boxes）和逐实例置信度分数——可直接用于合成、标注或后续分析。
+
+### Agent 调用工具时报超时怎么办？
+
+这是本项目重点解决的问题。MCP Agent（如 Claude、Cursor）对单个 tool 调用通常有约 60 秒的超时限制。如果任务处理时间超过此限制，Agent 会报错并切断连接。
+
+**解决方案：**
+
+1. **优先使用异步工具**：对于视频增强等耗时任务，始终使用 `create_task` + `get_task_status`。这些工具每次调用都是瞬间返回的，不会触发超时。
+
+2. **同步工具的截断机制**：`enhance_video_sync` 已在内部设置了45秒的截断限制（默认 `timeout`）。如果任务未在预算内完成，工具会主动返回 `task_id`，并提示 Agent 使用 `get_task_status` 继续跟进。
+
+3. **SAM3 的截断机制**：`sam3_predict` 受两个独立限制约束：最多 `SAM3_POLL_MAX_ATTEMPTS` 次状态查询（默认25次）和时间预算 `SAM3_POLL_INTERVAL_MS × 次数`（默认 25 × 2秒 ≈ 50秒）。任一限制先耗尽即截断等待；返回的提示携带 `task_id` 以及实际经过时间和查询次数，远端任务继续运行。
+
+4. **调整 SAM3 轮询参数**（高级）：两个限制相互独立，可以自由权衡间隔与次数（例如 `SAM3_POLL_INTERVAL_MS=1000` 配合 `SAM3_POLL_MAX_ATTEMPTS=50`，仍是约50秒预算、但查询频率翻倍）。如果任务通常几秒内完成，调低间隔可以更快发现完成状态。显式配置的非法值（非整数或超出允许范围）会在启动时直接报错退出，不会提交任何任务。等待预算只覆盖任务创建后的状态轮询——源准备、上传、任务提交和最后的结果下载都不计入，因此整个工具调用可能长于预算。
+
+### 拖拽附件后提示找不到文件？
+
+这是 stdio MCP 的已知限制。当通过 Agent 界面拖拽或上传附件时，文件路径通常不会自动传给 MCP Server。
+
+**解决方法：**
+
+1. **同时提供路径**（推荐）：拖拽图片后，在文字中补充说明图片的本地绝对路径：
+   > "请处理这张图片 `D:\\photos\\cat.jpg`，找出里面的猫"
+
+2. **等待自动编码**：Claude 可能会自动将图片编码为 base64 传入。如果成功，无需额外操作。
+
+3. **回答路径询问**：如果 Claude 询问图片路径，直接回复本地绝对路径即可。
+
+### 三种输入方式有优先级吗？
+
+没有严格优先级。Claude 会根据对话上下文自动选择最合适的方式：
+
+- 你提供了本地路径 → 使用 `imagePath`
+- 你提供了网络链接 → 使用 `imageUrl`
+- 你拖拽了附件且没有路径 → 尝试 `imageBase64`
+
+### 支持哪些图片格式？
+
+支持常见格式：PNG、JPG、JPEG、BMP、WebP 等。建议优先使用 PNG 或 JPG。
+
+### URL 图片下载失败怎么办？
+
+确保 URL 是**公开可访问**的，不需要登录、Cookie 或签名。如果图片在需要身份验证的服务上（如私有 S3 Bucket、需要登录的图床），请先下载到本地再使用 `imagePath`。
+
+### Base64 图片太大怎么办？
+
+如果图片很大（如 4K 分辨率），base64 编码后的数据会非常大，可能导致传输变慢。建议：
+
+1. 使用 `imagePath` 代替
+2. 或先将图片压缩后再编码
+
+## 文件上传说明
+
+当 `type` 为 `"local"` 时，MCP Server 会：
+1. 读取本地文件
+2. 通过预签名 URL 直传到 TOS 对象存储
+3. **最大文件大小：100MB**
+
+## 故障排查
+
+### "command not found: npx"
+
+安装 Node.js >= 18：https://nodejs.org/
+
+### "API key is required: pass --api-key or set the API_KEY environment variable"
+
+API Key 缺失，请检查配置中的 `env.API_KEY`。
+
+### MCP Server 在客户端显示红色/错误
+
+查看日志：
+- **Claude Desktop macOS**：`~/Library/Logs/Claude/mcp*.log`
+- **Claude Desktop Windows**：`%APPDATA%\Claude\logs\mcp*.log`
+- **Cursor**：Output 面板 > MCP
+
+### "TOS 上传失败"
+
+通常是签名不匹配，请确认 `IMAGE_API_BASE_URL`（未配置时回落到 `HTTP_API_BASE_URL`）和 `API_KEY` 正确且有效。
+
+## 全局安装（可选）
+
+如果你不想每次都用 `npx`：
+
+```bash
+npm install -g @avclabs.ai/media-mcp
+```
+
+然后在配置中使用 `"command": "media-mcp"` 配合 `"args": ["--api-key", "your-api-key"]` 。
+
+## 开发与发布
+
+本包运行在 MCP 客户端本机，并通过 npm 发布；它不是部署到远程服务器的 Node 常驻进程。发布前验证工作区：
+
+```bash
+npm ci
+npm run release:verify
+```
+
+维护者请查阅[发布指南](https://github.com/avclabs/media-mcp/blob/main/docs/RELEASE.md)了解当前发布状态、版本同步、发布顺序、冒烟测试以及与门户/后端部署的关系。
+
+## License
+
+MIT License - 详见 [LICENSE](LICENSE) 文件

package/config.json

@@ -1,4 +1,5 @@
 {
   "baseUrl": "https://mcp.avc.ai/enhance",
+  "imageBaseUrl": null,
   "sam3BaseUrl": "https://mcp.avc.ai/sam"
 }

package/dist/image-enhancement.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function setupImageEnhancementTools(server: McpServer, baseUrl: string, apiKey: string): void;
+//# sourceMappingURL=image-enhancement.d.ts.map

package/dist/image-enhancement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-enhancement.d.ts","sourceRoot":"","sources":["../src/image-enhancement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA8CpE,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAwEnG"}