内容
# 腾讯视频下载器 MCP 服务器
一个基于 Model Context Protocol (MCP) 的服务器，使 AI 助手能够搜索、获取信息和下载腾讯视频。
## 功能特性
- **解析视频 URL**：从腾讯视频 URL 中提取标题、时长、描述和上传日期
- **画质选择**：获取可用的画质选项（1080P、720P、480P 等）
- **视频下载**：按指定画质下载视频
- **格式转换**：自动将视频转换为标准 MP4 (H.264) 格式
- **进度追踪**：实时下载进度反馈
- **错误处理**：包含可操作建议的结构化错误消息
## 前置要求
安装前请确保具备以下条件：
- **Go 1.26.1 或更高版本**：[下载 Go](https://golang.org/dl/)
- **yt-dlp**：视频下载必需
```bash
pip install yt-dlp
# 或从 https://github.com/yt-dlp/yt-dlp/releases 下载
```
- **ffmpeg**：视频格式转换必需
```bash
# Ubuntu/Debian
sudo apt install ffmpeg
# macOS
brew install ffmpeg
# Windows
# 从 https://ffmpeg.org/download.html 下载
```
## 安装
### 从源码安装
```bash
git clone <repository-url>
cd mcp
go build -o tencent-video-mcp ./cmd/tencent-video-mcp
sudo mv tencent-video-mcp /usr/local/bin/
```
### 使用 Go Install
```bash
go install ./cmd/tencent-video-mcp@latest
```
## 配置
### 1. 创建配置文件
复制示例配置：
```bash
cp config.yaml.example config.yaml
```
### 2. 配置凭据
编辑 `config.yaml` 或设置环境变量：
```yaml
tencent_video:
username: "${TENCENT_VIDEO_USERNAME}"
password: "${TENCENT_VIDEO_PASSWORD}"
```
### 3. 设置环境变量
```bash
export TENCENT_VIDEO_USERNAME="your_username"
export TENCENT_VIDEO_PASSWORD="your_password"
```
### 4. （可选）配置工具路径
如果 yt-dlp 或 ffmpeg 不在 PATH 中：
```yaml
tools:
ytdlp_path: "/path/to/yt-dlp"
ffmpeg_path: "/path/to/ffmpeg"
```
## 使用
### 启动服务器
服务器通过 stdio 通信，适合与 MCP 客户端集成：
```bash
tencent-video-mcp [config.yaml]
```
如果未指定配置文件，默认使用当前目录下的 `config.yaml`。
## MCP 工具
### parse_video_url
解析腾讯视频 URL 并提取基本信息。
**参数：**
- `url` (string, 必需)：腾讯视频 URL
**示例：**
```json
{
"url": "https://v.qq.com/x/cover/..."
}
```
**响应：**
```json
{
"title": "视频标题",
"duration": "10:25",
"description": "视频描述...",
"upload_date": "2024-01-15",
"url": "https://v.qq.com/..."
}
```
### get_video_qualities
获取视频的可用画质选项。
**参数：**
- `url` (string, 必需)：腾讯视频 URL
**响应：**
```json
{
"qualities": [
{
"id": "137",
"label": "1080P",
"resolution": "1080P",
"is_default": true
},
{
"id": "136",
"label": "720P",
"resolution": "720P",
"is_default": false
}
],
"default_index": 0,
"url": "https://v.qq.com/..."
}
```
### download_video
按指定画质下载视频并转换为 MP4 格式。
**参数：**
- `url` (string, 必需)：腾讯视频 URL
- `quality` (string, 可选)：画质级别（如 "1080P"、"720P"），默认为最高可用画质
- `output_path` (string, 必需)：保存视频的本地文件路径
**示例：**
```json
{
"url": "https://v.qq.com/x/cover/...",
"quality": "1080P",
"output_path": "/path/to/video.mp4"
}
```
**响应：**
```json
{
"success": true,
"file_path": "/path/to/video.mp4"
}
```
## 错误处理
所有错误包含：
- **错误代码**：错误类型的数字代码
- **错误类型**：错误类别（InputValidationError、AuthenticationError 等）
- **消息**：详细的问题描述
- **建议**：解决问题的可操作建议
- **上下文**：额外的调试信息
### 错误代码
| 范围 | 类型 |
|------|------|
| 1000-1999 | 输入验证错误 |
| 2000-2999 | 身份验证错误 |
| 3000-3999 | 下载错误 |
| 4000-4999 | 转换错误 |
| 5000-5999 | 配置错误 |
## 与 AI 助手集成
### Claude Desktop
在 `~/.claude_desktop_config.json` (macOS/Linux) 或 `%APPDATA%\Claude\claude_desktop_config.json` (Windows) 中添加：
```json
{
"mcpServers": {
"tencent-video": {
"command": "/path/to/tencent-video-mcp",
"args": ["/path/to/config.yaml"],
"env": {
"TENCENT_VIDEO_USERNAME": "your_username",
"TENCENT_VIDEO_PASSWORD": "your_password"
}
}
}
}
```
### Cline (VS Code)
在 VS Code 设置中配置 MCP 服务器路径和参数。
### 其他 MCP 客户端
任何支持 MCP 协议的 AI 客户端都可以使用此服务器。
## 开发
### 运行测试
```bash
go test ./... -v
```
### 运行特定测试
```bash
go test ./internal/services/... -v
```
### 构建
```bash
go build -o bin/tencent-video-mcp ./cmd/tencent-video-mcp
```
## 故障排除
### yt-dlp 未找到
```
Error: yt-dlp is not installed or not accessible
```
**解决方案**：使用 pip 安装 yt-dlp 或从 GitHub 下载二进制文件。
### ffmpeg 未找到
```
Error: ffmpeg is not installed or not accessible
```
**解决方案**：使用系统包管理器安装 ffmpeg。
### 身份验证失败
```
Error: Login failure - check your credentials
```
**解决方案**：验证您的腾讯视频用户名和密码是否正确。
### 下载失败
```
Error: Download failed - network issue
```
**解决方案**：检查网络连接并确保视频可公开访问。
## 项目结构
```
mcp/
├── cmd/tencent-video-mcp/main.go # 入口点
├── pkg/types/ # 共享数据类型
├── internal/
│ ├── config/ # 配置层
│ ├── errors/ # 错误处理
│ ├── external/
│ │ ├── cmdrunner/ # 命令执行器
│ │ ├── ytdlp/ # yt-dlp 包装器
│ │ └── ffmpeg/ # ffmpeg 包装器
│ ├── services/
│ │ ├── parser.go # 视频解析服务
│ │ ├── downloader.go # 下载服务
│ │ └── converter.go # 格式转换服务
│ └── mcpserver/ # MCP 服务器
│ ├── server.go # JSON-RPC 2.0 服务器
│ ├── tools.go # 工具定义
│ └── handlers.go # 工具处理器
├── config.yaml.example # 配置示例
└── README.md # 本文档
```
## 什么是 MCP？
**Model Context Protocol (MCP)** 是 Anthropic 推出的开放协议，用于标准化 AI 助手与外部工具、数据源和服务之间的通信。
### MCP 的优势
- **一次实现，多处使用**：同一个 MCP 服务器可以被 Claude Desktop、Cline、Continue.dev 等多种 AI 客户端使用
- **标准化接口**：统一的协议，无需为每个 AI 助手单独开发
- **双向通信**：支持请求和通知
- **传输层无关**：可通过 stdio、HTTP 等多种方式传输
本服务器完整实现了 MCP 协议，因此可以被任何支持 MCP 的 AI 客户端直接调用。
## 许可证
MIT License - 详见 LICENSE 文件
## 贡献
欢迎贡献！请提交 issue 或 pull request。
