media-mcp (Node.js)

中文 | English

基于 MCP 协议的视频增强与图像分割服务，作为 MCP Client-Server 与后端 HTTP Server 交互。

功能

提供以下 MCP Tools：

• create_task - 创建视频增强任务（支持 URL 或本地文件上传）

• get_task_status - 查询任务状态

• enhance_video_sync - 同步增强视频（阻塞等待完成）

• sam3_predict - SAM3 图像分割（支持本地路径、URL 或 Base64 图片）

前置要求

• 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）：

{
  "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：

  env HTTP_API_KEY=your-api-key npx -y @avclabs.ai/media-mcp@latest

或编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "video-enhancement": {
      "command": "npx",
      "args": ["-y", "@avclabs.ai/media-mcp@latest"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

验证安装

重启客户端后，确认工具是否加载成功：

1. 或直接问 AI："你有哪些可用的工具？"

2. 应看到：create_task、get_task_status、enhance_video_sync、sam3_predict

配置项

自定义服务地址

{
  "env": {
    "HTTP_API_BASE_URL": "https://your-endpoint.com",
    "API_KEY": "your-api-key",
    "SAM3_API_BASE_URL": "http://localhost:8001"
  }
}

或通过命令行参数：

npx -y @avclabs.ai/media-mcp@latest --base-url https://your-endpoint.com --api-key your-api-key --sam3-base-url http://localhost:8001

使用示例

配置完成后，用自然语言对 AI 说：

"帮我把这个视频增强到 1080p：https://example.com/video.mp4"

"把我桌面的 video.mp4 提升到 2k 画质"

AI 会自动调用相应工具完成任务。

"帮我分析一下这张图片，找出里面的所有物体：C:\Users\xxx\photo.png"

"用 SAM3 分割这张图片，prompt 是 'find all cars'"

提供的 Tools

create_task

创建视频增强任务（异步）。

返回值：

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

get_task_status

查询任务状态。

返回值：

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

enhance_video_sync

同步增强视频（阻塞等待完成）。

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): 英文文本提示，用于指定要在图片中分割的目标物体。例如 "person"、"car"、"a cat sitting on a sofa"。由于 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 内容示例：

{
  "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]
}

常见问题

拖拽附件后提示找不到文件？

这是 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 或设置 API_KEY"

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 上传失败"

通常是签名不匹配，请确认 HTTP_API_BASE_URL 和 HTTP_API_KEY 正确且有效。

全局安装（可选）

如果你不想每次都用 npx：

npm install -g @avclabs.ai/media-mcp

然后在配置中使用 "command": "media-mcp" 配合 "args": ["--api-key", "your-api-key"] 。

License

MIT License - 详见 LICENSE 文件