Shaka Packager MCP Server

Shaka Packager MCP 服务

状态：alpha。 分析是目前测试最多的功能。请将其视为可用的原型，而不是生产环境依赖。

已知限制：

• 封装和转换仍在积极开发中
• Docker 和主机环境之间的路径转换可能需要手动配置
• 不同版本之间的接口可能会发生变化

欢迎提交问题报告，这确实很有帮助。

一个 MCP（Model Context Protocol）服务，可将 Shaka Packager 集成到 Claude AI 应用中，用于视频转码、封装和分析。

此服务与 Filesystem MCP 服务配合使用，让 Claude Desktop 能够访问并处理计算机上的视频文件，使 Claude 成为处理媒体任务的强大助手。

功能

• 视频分析：分析视频文件，提取详细的流信息、编解码器、比特率等
• 媒体封装：将视频转换为 HLS 和 DASH 格式以供流式传输，支持点播和直播
• 高级选项：
  • 应用 DRM 加密（Widevine、PlayReady、FairPlay）
  • 配置广告插入标记
  • 在不同格式之间转换（MP4、TS 等）
• 智能路径处理：自动转换 Docker 和主机环境之间的路径
• 完善的错误处理：提供有意义的错误分析和解决建议
• 命令辅助：帮助正确格式化 Shaka Packager 命令，以获得最佳结果
• 交互式文档：内置帮助和示例，引导用户完成复杂操作
• 详细输出：为所有操作提供全面的摘要和执行详情

先决条件

• Python 3.10 或更高版本
• 已安装 Shaka Packager，且可通过 PATH 访问
  • 从 GitHub 下载
  • 或按照这些说明从源代码构建
• 兼容 MCP 的客户端（例如 Claude Desktop）

安装

从源代码安装

该软件包尚未发布到 PyPI，因此请从克隆的仓库安装。

git clone https://github.com/coderjun/shaka-packager-mcp-server.git
cd shaka-packager-mcp-server
pip install -e .

或使用 uv：

git clone https://github.com/coderjun/shaka-packager-mcp-server.git
cd shaka-packager-mcp-server
uv pip install -e .

Claude Desktop 集成

由于 Claude Desktop 不直接支持上传视频文件，我们将采用双服务方案：

1. 使用简化的 filesystem MCP 服务访问计算机上的视频文件
2. 使用 Shaka Packager MCP 服务分析和处理这些视频

第 1 步：设置 MCP Filesystem 服务

使用官方 MCP filesystem 服务，允许 Claude 访问视频文件：

1. 使用 Docker 安装官方 filesystem 服务：

   docker pull mcp/filesystem
   

2. 或者，按照 Filesystem MCP 服务仓库中的说明从源代码构建

步骤 2：查找配置文件

找到 Claude Desktop 配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

如果文件不存在，请创建该文件。

步骤 3：将两个服务添加到配置中

添加以下配置，并确保使用绝对路径：

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=/PATH/TO/VIDEOS/DIRECTORY,dst=/projects/video-drop",
        "mcp/filesystem",
        "/projects"
      ]
    },
    "shaka-packager": {
      "command": "/ABSOLUTE/PATH/TO/uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "/ABSOLUTE/PATH/TO/shaka_packager_mcp.py"
      ],
      "env": {
        "VIDEO_PATH": "/PATH/TO/VIDEOS/DIRECTORY",
        "SHAKA_PACKAGER_PATH": "/PATH/TO/PACKAGER"
      }
    }
  }
}

替换：

• /PATH/TO/VIDEOS/DIRECTORY 为包含视频文件的目录路径
• /ABSOLUTE/PATH/TO/uv 为 uv 可执行文件的完整路径
• /ABSOLUTE/PATH/TO/shaka_packager_mcp.py 为脚本文件的完整路径
• /PATH/TO/PACKAGER 为 Shaka Packager 可执行文件的完整路径

例如：

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=/Users/username/Videos,dst=/projects/video-drop",
        "mcp/filesystem",
        "/projects"
      ]
    },
    "shaka-packager": {
      "command": "/Users/username/.local/bin/uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "/Users/username/Development/shaka-packager-mcp-server/shaka_packager_mcp.py"
      ],
      "env": {
        "VIDEO_PATH": "/Users/username/Videos",
        "SHAKA_PACKAGER_PATH": "/Users/username/.shaka/packager"
      }
    }
  }
}

步骤 4：重启 Claude Desktop

编辑配置文件后，重启 Claude Desktop 以应用更改。

如何使用双服务方案

1. 首先，使用简化版文件系统服务浏览视频文件：

   • 请 Claude“列出我的视频目录中的文件”
   • 找到要分析或处理的视频文件

2. 找到视频文件后，使用其路径调用 Shaka Packager 工具：

   • 分析：“请分析此视频：/Users/username/Videos/example.mp4”
   • 处理：“请将此视频打包为 HLS：/Users/username/Videos/example.mp4”

故障排除

如果遇到问题：

1. 确保两个服务都已使用绝对路径正确配置
2. 确认 Shaka Packager 已安装且可访问
3. 确保为文件系统服务指定的目录存在且包含视频文件
4. 检查 Claude Desktop 日志中的错误：
   • macOS：~/Library/Logs/Claude/mcp*.log
   • Windows：%APPDATA%\Claude\logs\mcp*.log

用法

在 Claude Desktop 中运行文件系统 MCP 服务和 Shaka Packager MCP 服务后：

1. 访问视频文件：

   Please show me the files in my Videos directory
   

2. 找到视频文件：

   Please show me the files in the Movies subdirectory
   

3. 复制要处理的视频的 file:// URI 路径

4. 使用该文件路径调用 Shaka Packager 工具：

   Please analyze this video: file:///Users/username/Videos/my_video.mp4
   

   或

   Please package this video for HLS and DASH streaming: file:///Users/username/Videos/my_video.mp4
   

5. 服务将执行相应的 Shaka Packager 命令，并提供详细的结果摘要

如果知道视频文件的确切位置，也可以直接使用文件路径：

Please analyze this video: /Users/username/Videos/my_video.mp4

工具

服务提供以下工具：

1. analyze_video：检查视频文件，并提供详细的流信息，同时具备智能错误处理功能
2. run_shaka_packager：使用自定义参数执行任意 Shaka Packager 命令，并正确处理路径
3. get_shaka_options：获取可用的命令选项和版本信息
4. get_shaka_documentation：提供使用 Shaka Packager 的完整文档和示例

提示词

服务包含以下提示词模板：

• MP4 转 TS
• HLS 和 DASH 点播打包
• 直播流打包
• 内容加密
• 广告插入准备
• 视频分析
• 命令格式提醒
• 错误解读指南

配置

可以使用环境变量配置服务：

• SHAKA_PACKAGER_PATH：Shaka Packager 可执行文件的路径（强烈建议在 Claude Desktop 中设置）
• VIDEO_PATH：本地视频目录的路径（用于在 Docker 和主机之间转换路径）
• DOCKER_PATH：Docker 容器挂载路径（默认值：“/projects/video-drop”）
• TEMP_DIR：文件上传的自定义临时目录
• LOG_LEVEL：日志级别（DEBUG、INFO、WARNING、ERROR、CRITICAL）
• COMMAND_TIMEOUT：Shaka Packager 命令的超时时间（秒，默认值：300）

可以在以下位置设置这些变量：

1. Claude Desktop 配置文件（建议在此设置 SHAKA_PACKAGER_PATH 和 VIDEO_PATH）
2. 环境变量
3. 与脚本位于同一目录的 .env 文件

.env 文件示例：

SHAKA_PACKAGER_PATH=/usr/local/bin/packager
VIDEO_PATH=/Users/yourusername/Videos
LOG_LEVEL=DEBUG

开发

设置开发环境

# Clone the repository
git clone https://github.com/coderjun/shaka-packager-mcp-server.git
cd shaka-packager-mcp-server

# Install development dependencies with pip
pip install -e ".[dev]"

# Or with uv
uv pip install -e ".[dev]"

运行测试

pytest

代码格式化

black .
isort .

了解代码结构

Shaka Packager MCP 服务的主要组件包括：

• shaka_packager_mcp.py：包含 MCP 工具和提示词的主服务实现
• tests/：用于验证功能的测试套件

此服务旨在与官方 MCP 文件系统服务配合使用，以访问视频文件。

实现中的主要功能

• 稳健的路径处理：自动转换 Docker 和主机环境之间的路径
• 智能错误处理：提供有意义的错误消息和建议
• 命令语法辅助：帮助正确格式化 Shaka Packager 命令
• 文档集成：提供全面的文档和示例

许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。

获取帮助

欢迎使用 AI 代码助手，作者也会这样做。

如果遇到问题或有疑问：

1. 查看本 README 中的故障排除部分
2. 查阅 Shaka Packager 文档
3. 在 Claude 中使用 get_shaka_documentation 工具获取交互式帮助
4. 在 GitHub 上提出问题

致谢

• 感谢 Shaka Packager 提供强大的视频处理能力
• 感谢 Model Context Protocol (MCP) 提供通信框架
• 感谢 Claude 提供 AI 助手能力
• 感谢 Anthropic 开发 Claude 和 MCP 标准