media-mcp (Node.js)

中文 | English

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

功能

提供以下 MCP Tools：

视频增强

• create_task - 创建视频增强任务（支持 URL 或本地文件上传）
• get_task_status - 查询任务状态
• enhance_video_sync - 同步增强视频（阻塞等待，默认50秒截断）

图像分割 (SAM3)

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

配置项

变量名	必填	默认值	说明
API_KEY	是	-	API 认证密钥（视频增强和 SAM3 共用）
HTTP_API_BASE_URL	否	https://mcp.avc.ai/enhance	视频增强服务接口地址
SAM3_API_BASE_URL	否	https://mcp.avc.ai/sam	SAM3 服务接口地址
SAM3_POLL_INTERVAL	否	2000	SAM3 轮询间隔（毫秒）
SAM3_POLL_MAX_ATTEMPTS	否	25	SAM3 最大轮询次数

自定义服务地址

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

或通过命令行参数：

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

推荐的工作流程

本项目提供了同步和异步两种模式。

由于 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 → 服务器内部自动轮询
• 默认最多等待50秒
• 如果50秒内完成，直接返回结果
• 如果50秒未完成，返回 task_id 和提示，让 Agent 切换到 get_task_status 继续查询

图像分割 (SAM3)：

• 调用 sam3_predict → 服务器内部自动轮询
• 默认最多等待50秒（25次 × 2秒轮询间隔）
• 如果50秒内完成，直接返回分割结果
• 如果50秒未完成，返回截断提示，告知任务仍在处理中

使用示例

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

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

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

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

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

AI 会根据任务复杂度自动选择同步或异步工具完成任务。

提供的 Tools

视频增强

create_task

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

推荐使用：适用于绝大多数场景，尤其是时长超过10秒的视频，可避免超时和长时间阻塞连接。

参数	类型	必填	默认值	说明
video_source	string	是	-	视频 URL 或本地文件路径（URL 必须公网可访问，不支持需要登录或签名的链接）
type	string	否

... View full README on GitHub