Metadata-Version: 2.4
Name: vidhex_mcp
Version: 0.3.1
Summary: Video Skill MCP server + agent skill + CLI (install / login / jobs)
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=2.2.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: keyring>=24.0
Provides-Extra: dev
Requires-Dist: pytest>=8.3.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"
Dynamic: license-file

# 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 的登录流程会退化。

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

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

```bash
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` 做启动验证。

## 命令

| 命令 | 说明 |
|------|------|
| `vidhex_mcp install` | 注册 MCP + 部署 skill（默认用户级） |
| `vidhex_mcp install --scope project` | 写入当前项目的 `.mcp.json` 与 skills |
| `vidhex_mcp install --no-skill` | 只注册 MCP，不部署 skill |
| `vidhex_mcp login` | 浏览器授权登录（交互式，由用户执行） |
| `vidhex_mcp logout` | 清除本机登录凭证 |
| `vidhex_mcp status` | 查看登录状态与配置摘要 |
| `vidhex_mcp points` | 查询实时积分余额（`account` 同义） |
| `vidhex_mcp uninstall` | 从配置中移除，并删除已部署的 skill |
| `vidhex_mcp check` | 自检配置并打印摘要 |
| `vidhex_mcp` | 无参数时启动 stdio 服务器（由客户端调用） |

`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 工具。在终端运行：

```bash
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 工具仍可直接调用。

## 升级

```bash
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
