vidhex_mcp

Video Skill 的 MCP 服务器 —— 通过 API 网关提供视频超分（2x/3x/4x）与任务进度查询， 并附带 agent skill 和 vidhex_mcp CLI（install / login / status / points）。 以 stdio 方式接入 Claude Code 等 MCP 客户端。

一句话安装（可复制给智能体）

运行 pip install vidhex_mcp && vidhex_mcp install --api-url <网关地址> --api-key vsk_live_xxx，把 vidhex_mcp 注册为 stdio MCP 服务器并部署 video-skill skill；重启 Claude Code 后运行 vidhex_mcp login 完成授权，用 vidhex_mcp --version 确认已是最新版本。

网关和密钥已经配置过时，可以简化为：

运行 pip install vidhex_mcp && vidhex_mcp install，完成后重启客户端并运行 vidhex_mcp login 授权。

为什么推荐 pip / uv tool，而不是 uvx

0.2.0 起安装不只是注册 MCP 服务器，还会部署 agent skill；skill 需要通过 Bash 调用 vidhex_mcp status / vidhex_mcp login。pip install 与 uv tool install 会把 vidhex_mcp 放进 PATH，而 uvx vidhex_mcp install 只在 uvx 的临时环境里执行， CLI 不会出现在 PATH，skill 的登录流程会退化。

# 推荐：隔离安装，CLI 常驻 PATH
uv tool install vidhex_mcp
vidhex_mcp install --api-url https://your-gateway --api-key vsk_live_xxx

只想接入 MCP 工具、不需要 skill 和本机 login 时，才用：

uvx vidhex_mcp install --api-url https://your-gateway --api-key vsk_live_xxx

install 会完成五件事：

1. 识别当前是 uvx / pip 脚本 / python -m 启动，生成可执行且不依赖 PATH 的启动命令；
2. 合并写入用户级 ~/.claude.json（--scope project 时写项目 .mcp.json）， 其他 MCP 服务器原样保留；
3. 把包内的 video-skill skill 部署到 ~/.claude/skills/video-skill/ （--scope project 时为 <项目>/.claude/skills/video-skill/，--no-skill 可跳过）；
4. 把 --api-key / --api-url 存进 ~/.video_skill/config.json（权限 600）， MCP 配置里只写网关地址，不重复保存密钥；
5. 用生成的条目跑一次 --check 做启动验证。

命令

install 常用参数：

• --api-key vsk_live_...：写入本地凭证文件
• --api-url https://...：网关地址
• --command "vidhex_mcp"：覆盖自动探测的启动命令
• --dry-run：只打印将写入的配置
• --no-verify：跳过启动验证
• --no-skill：不部署 agent skill
• --force：配置文件损坏时先备份（.bak）再重建

配置来源

按优先级从高到低读取：

1. 环境变量 VIDEO_SKILL_API_KEY / VIDEO_SKILL_API_URL / VIDEO_SKILL_AUTH_URL
2. ~/.video_skill/config.json（install 写入的位置）
3. 内置默认值（授权服务地址有默认值，网关地址必须显式配置）

本地登录

登录是 CLI 命令，不是 MCP 工具。在终端运行：

vidhex_mcp login

它会打开浏览器完成授权，凭证保存在系统钥匙串（Windows 凭据管理器 / macOS Keychain / Linux Secret Service）。MCP 服务器与 CLI 共用同一份凭证；登录后当前 MCP 进程最多 15 秒内即可读到新凭证，若客户端仍提示未登录，重新加载窗口或重启客户端即可。

API Key 仍然必需：它用于网关鉴权；登录提供的是计费身份（user_token），两者不能互相替代。

Agent Skill

SKILL.md 与 references/ 随本包分发，install 会自动部署。skill 只描述当前开放的 两个工具（video_super_resolution / check_job_status），并明确要求登录、退出、余额 通过 CLI 完成。没有部署 skill 时，MCP 工具仍可直接调用。

升级

pip install --upgrade vidhex_mcp     # 或 uv tool upgrade vidhex_mcp
vidhex_mcp install                   # 刷新 MCP 配置，并重新部署 skill
vidhex_mcp --version                 # 确认版本

然后重启 Claude Code（或重新加载窗口），让 MCP 服务器进程换上新版本。 只升级包、不重新运行 install 的话，~/.claude/skills/video-skill/ 里仍是旧 skill。

Windows 上如果 MCP 服务器正在运行，升级可能因 vidhex_mcp.exe 被占用而报 “拒绝访问 (os error 5)”——先退出客户端再升级；使用 uvx 方式安装则不受影响。

许可证

MIT