内容
HandBrake
<p align="center <a href="https.com/casey/img src="https://img.shields.io/badge/just-ready-7c5cfc-square&logo=just&logo" alt="Just"></ <a href="github.com/astral-sh/ruff"><img src="img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
<a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.13+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python"></a>
<a href="https://github.com/PrefectHQ/fastmimg src="https://img.shields.io/badge/FastMCP-3.2-7c5cfc?style=flat-square" alt="FastMCP"></a>
</p>
> 📖 **[安装指南](INSTALL.md)** — 快速开始，手动设置和故障排除
[
[](https://www.docker.com/)
[](https://kubernetes.io/)
[](SECURITY.md)
[](https://github.com/sandraschi/handbrake-mcp/discussions)
一个 **生产就绪**、**FastMCP 3.2.0 兼容** 的服务器，用于使用 HandBrakeCLI 进行专业视频转码。具备 **工业级 SOTA 仪表盘（v13.1）**、企业级 CI/CD 和强大的 127.0.0.1 网络，以实现最大稳定性。
## 快速开始
```powershell
git clone https://github.com/sandraschi/handbrake-mcp
cd hand-mcp
just
```
这将打开一个交互式仪表盘，显示所有可用的命令。运行 `just bootstrap` 以安装依赖项，然后运行 `just serve` 或 `just dev` 以启动。
### 手动设置
如果您没有安装 `just`:
## 功能
### **核心视频处理**
- **专业转码**：在所有主要视频格式（MP4、MKV、AVI、MOV、M4V 等）之间转换
- **批量处理**：使用智能队列管理同时处理多个文件
- **监视文件夹**：使用可配置模式自动处理新视频文件
- **实时进度**：具有详细进度跟踪的实时作业状态更新
- **质量预设**：针对不同用例的 50 多个优化的 HandBrake 预设
- **自定义选项**：使用高级 HandBrake CLI 参数微调编码
### **企业基础设施**
- **CI/CD 流水线**：跨多个平台的自动化测试、构建和部署
- **真实 CLI 集成测试**：使用实际 HandBrakeCLI 调用进行全面测试
- **Docker 支持**：具有安全扫描和监控的多阶段构建
- **Kubernetes 就绪**：用于可扩展生产的完整部署清单
- **监控**：Prometheus 指标、Grafana 仪表盘和健康检查
- **安全**：漏洞扫描、SBOM 生成和安全实践
- **专业文档**：带有 GitHub Pages 部署和版本文档的 MkDocs
- **自动化发布**：变更日志生成、发布验证和社区通知
### **高级文档系统**
- **多行装饰器**：具有综合元数据的自我文档工具
- **多级帮助**：基本、详细和完整文档级别
- **高级帮助**：故障排除、示例和性能优化指南
- **工具搜索**：按名称、描述或类别查找工具
- **系统状态**：实时系统健康和资源监控
### **MCP 2.12.0 兼容性**
- **7 个核心工具**：`transcode_video`、`batch_transcode`、`get_job_status`、`cancel_job`、`get_presets`、`get_loaded_models`、`get_provider_status`
- **5 个帮助工具**：`help`、`multilevel_help`、`advanced_help`、`tool_categories`、`system_status`
- **丰富的文档**：每个工具都包含详细的描述、示例和用法说明
- **交叉引用**：增强可发现性的相关工具和工作流程
### **现代 GitHub 功能**
- **GitHub 讨论**：社区问答和功能讨论
- **GitHub 维基**：综合文档和故障排除指南
- **问题/PR 模板**：专业的错误报告和功能请求
- **社区健康**：自动的过时问题管理和指标
- **安全策略**：负责任的漏洞披露和报告
- **贡献指南**：清晰的开发和贡献指南
- **存储库配置文件**：增强的项目展示和可发现性
## 快速开始
### 先决条件
- **Python 3.8+** - 核心功能所需
- **HandBrakeCLI** - 专业视频转码引擎
- **Git** - 用于克隆存储库
- **（可选）MCPB CLI** - 用于打包分发包
- **（可选）Docker** - 用于容器化部署
- **（可选）Kubernetes** - 用于生产部署
### 安装 HandBrakeCLI
#### Windows
```powershell
# 使用 Windows 包管理器（推荐）
winget install HandBrake.HandBrake.CLI
# 验证安装
HandBrakeCLI --version
```
#### macOS
```bash
# 使用 Homebrew
brew install handbrake
# 验证安装
HandBrakeCLI --version
```
#### Linux (Ubuntu/Debian)
```bash
# 添加 HandBrake PPA
sudo add-apt-repository ppa:stebbins/handbrake-releases
sudo apt update
sudo apt install handbrake-cli
# 验证安装
HandBrakeCLI --version
```
## 🚀 安装和设置
### 1. 先决条件
- **Python 3.12+** - 核心运行时（通过 `uv` 管理，建议使用）。
- **HandBrakeCLI** - 转码引擎。
- **[uv](https://docs.astral.sh/uv/)** - 现代 Python 包和工具管理器。
### 2. 快速部署
您可以使用 `uvx` 直接运行服务器，无需手动安装：
```powershell
uvx handbrake-mcp-stdio
```
### 3. Claude 桌面集成
将以下内容 `claude_desktop_config.json`：
```json
"handbrake-mcp": {
"command":",
"args": "--directory",
:/Dev/repos/handbrake-mcp",
",
"handbrake-mcp-stdio"
]
}
```
## 📊 工业仪表盘（v13.1）
该项目包含一个符合 SOTA 标准的优质仪表盘，用于实时转码管理。
### 启动仪表```powershell
cd web_sota
.\start.bat
```
访问 `http://localhost95` 以访问控制面板。
## 📦 打包和分发
该存储库符合 SOTA 2026 标准，并使用官方验证的 `@anthropic-ai/mcpb` 工作流进行分发。
```powershell
# 生成 .mcpb 分发包
mcpb pack . dist/handbrake-mcp.mcpb
```
### 先决条件
- 安装 [uv](https://docs.astral.sh/uv/)（推荐）
- Python 3.12+
## 🛠️ 用法
### **启动服务器**
#### FastMCP stdio（Claude 默认）
```powershell
uv run python -m handbrake_mcp.server
```
#### FastAPI 服务（用于仪表盘）
```powershell
uv run python -m handbrake_mcp.server --http
```
### **发现可用工具**
服务器包含一个全面的自我文档系统：python
# 获取所有工具的基本帮助
multilevel_help("basic")
# 获取特定工具的详细帮助
help("transcode_video", "detailed")
# 获取综合文档
multilevel_help("full")
# 按功能搜索工具
search_tools("video")
search_tools("batch")
# 按类别浏览工具
tool_categories()
```
### **工业仪表盘**
服务器在 `web_sota` 中包含一个符合 SOTA-v13.1 标准的优质仪表盘。要运行它：bash
cd web
npm install run dev
```
> [!IMPORTANT]
> **Windows 如果您遇到“连接被拒绝”的错误，请确保仪表为连接到 `127.0.0.1不是 `localhost` Windows 系统将 `localhost为 IPv6 `::1`，这可能会绕过后端 IPv4 监听### **核心 MCP 工具**
#### ****
- **`transcode_video`** - 使用专业质量设置进行单文件转码
-_transcode`**文件批量处理，行执行
#### **作业管理**
- **`get_job_status`** - 实时进度监控，附带详细状态 **`cancel_job`** - 立即终止作业并释放资源
#### **配置和发现**
- **`get_presets`** - 列出所有可用的 HandBrake 预设
- **`get_loaded_models`** - MCP 兼容模型发现
- **`get_provider_status`** - 全面的系统健康和能力
#### **帮助和文档**
- **`help`** - 不同详细级别的工具特定帮助
- **`multilevel_help`** - 系统范围的帮助（基本、详细、完整、类别）
- **`advanced_help`** - 高级指南（示例、故障排除、性能）
- **`tool_categories`** - 按功能类别浏览工具
- **`system_status`** - 实时系统健康和资源监控
### **使用示例**
#### **基本视频转码**
```python
# 使用默认设置进行简单转换
result = transcode_video("/videos/input.mp4", "/videos/output.mkv")
# 使用自定义预设进行高质量转换
result = transcode_video(
"/videos/movie.mkv",
"/videos/movie_hq.mp4",
preset="HQ 1080p30"
)
# 自定义编码选项
result = transcode_video(
"/videos/input.avi",
"/videos/output.mp4",
options={"quality": "20", "encoder": "x264"}
)
```
#### **批量处理**
```python
# 处理多个文件
results = batch_transcode([
{
"input_path": "/videos/movie4",
"output_path": "/videos/movie1.mkv",
"preset": "Fast 1080p30"
},
{
"input_path": "/videos/movie2.mp4",
"output_path": "/videos/movie2.mp4"
}
])
# 检查批量作业的进度
for result in results:
status = get_job_status(result.job_id)
print(f"作业 {result.job_id}：{status.status}（{status.progress}％）")
```
#### **作业监控和控制**
```python
# 监控作业进度
job_id = "transcode_2025_01_22_143022"
while True:
status = get_job_status(job_id)
if status.status in ["completed", "failed", "cancelled"]:
print(f"作业完成：{status.status}")
if status.error:
print(f"错误status.error}")
break
print(f"{status.progress}％")
time.sleep(# 取消有问题的作业
cancel_job("job45")
```
#### **系统管理**
```python
# 检查系统健康状况
status = get_provider_status()
print(f"活动作业：{status['active_jobs']}")
print(f"可用预设：{len(status['supported_presets'])}")
# 获取可用预设
presets = get_presets()
fast_presets = [p for p in presets if "Fast" in p]
print(f"快速预设：{fast_presets}")
```
### **高级文档访问**
#### **多级帮助系统**
```python
# 所有工具的基本概述
help_over_help("basic")
# 特定工具的
transcode_help = multilevel_help("detailed", "transcode_video")
# 所有工具的完整文档
full_docs = multilevel_help("full")
# 按类别浏览工具
categories = multilevel_help("categories")
```
#### **类型**
```python
# 用例和最佳实践 = advanced_help("examples")
# 故障排除指南
troubleshooting = advanced_help("troubleshooting")
# 性能优化指南
performance = advanced_help("performance")
# 系统概述
overview = advanced_help("overview")
```
### **自我文档工具**
每个工具都包含可以通过帮助系统访问的综合文档：
```python
# 获取任何工具的完整文档
full_doc = help("transcode_video", "full")
print(full_doc)
```
这将显示：
- 完整的工具描述，包含功能
- 参数文档，包含类型和示例
- 多个使用示例（基本、高级、现实世界）
- 返回值规范
- 重要说明和警告
- 相关工具和工作流程
- 版本信息
## 打包和分发
该存储库使用 SOTA 2026 打包工作流。有关生成分发包的详细信息，请参阅[安装](#installation-options)部分。
## 📖 文档和资源
有关详细的技術指南、标准和高级用法，请参阅本地文档中心：
- **[文档索引](docs/index.md)**：您的主要指南和帮助入口点。
- **[CHANGELOG.md](CHANGELOG.md)**：跟踪版本历史和工业化里程碑。
## 🤝 贡献
欢迎贡献！请遵循我们在内部文档中概述的唯物效率标准开发模式。
## 📜 许可证
该项目在 MIT 许可证下获得许可 - 有关详细信息，请参LICENSE](LICENSE) 文件。
---
**HandBrake MCP | 工业转码控制平面 | 2026**
## 🛡️ 工业质量栈
该项目遵循 **SOTA 14.1** 工业标准，用于高保真代理编排：
- **Python（核心）**：[Ruff](https://astral.sh/ruff) 用于代码检查和格式化。对核心处理程序中的 `print` 语句（`T201`）实行零容忍政策。
- **Webapp（UI）**：[Biome](biomejs.dev毫秒级代码检查执行 `noConsoleLog`。
- **协议兼容性**：强化 `stdout/stderr` 隔离，以确保抗崩溃的 JSON-RPC 通信。
- **自动化**：[Justfile](./justfile)
