TimeVerse HyperFrames MCP

将 HyperFrames CLI（HTML/CSS/JS 转视频渲染引擎）包装为 MCP 工具服务，让 AI Agent 可以直接：

• 创建/初始化视频项目
• 实时预览 HTML 视频（热重载）
• 渲染为 MP4/WebM
• 检查语法完整性
• 文本转语音 / 音频转录
• 检测运行环境、性能基准测试

架构概览

MCP 客户端（如 TimeVerseStudio）
        │  (stdio 协议)
        ▼
┌─────────────────────────────────────┐
│       server.py (FastMCP)           │
│  ┌─ 后台预热 npx 缓存（首次启动）   │
│  └─ 注册 13 个 MCP 工具              │
└────────────┬────────────────────────┘
             │
    ┌────────┼────────────┬──────────┐
    ▼        ▼            ▼          ▼
  init.py  render.py  media.py   system.py
  lint.py  preview.py
             │
             ▼
┌─────────────────────────────┐
│  cli_executor.py             │
│  ┌─ 优先全局 hyperframes    │
│  │  回退 npx hyperframes    │
│  ├─ 超时/错误处理           │
│  └─ 环境检测 / lint 解析    │
└────────────┬────────────────┘
             │
             ▼
    hyperframes CLI (npx)

前置依赖

依赖	要求	安装
Python	>= 3.11	brew install python@3.11
Node.js	>= 22	nodejs.org
FFmpeg	任意版本	macOS: brew install ffmpeg / Ubuntu: sudo apt install ffmpeg
HyperFrames	自动通过 npx 获取	无需手动安装

首次运行时会自动通过 npx 下载 hyperframes 包（约 30-60 秒），后续缓存到本地。

可选优化：全局安装 hyperframes 可跳过 npx 下载步骤：

npm install -g hyperframes

安装

方式一：pip 安装（推荐）

pip install -e .

安装后可直接运行：

timeverse-hyperframes-mcp

方式二：uvx 运行（无需安装）

需要先安装 uv：

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# 直接通过 uvx 运行（自动下载依赖并缓存）
uvx timeverse-hyperframes-mcp

方式三：python -m

python -m timeverse_hyperframes_mcp.server

注册到 MCP 客户端

TimeVerseStudio

在 MCP 设置页面点击 JSON 导入，填入以下内容：

{
  "mcpServers": {
    "hyperframes": {
      "description": "HyperFrames MCP — 将 HTML/CSS/JS 渲染为 MP4 视频。支持 init / preview / render / lint / TTS / transcribe",
      "command": "uvx",
      "args": ["timeverse-hyperframes-mcp"]
    }
  }
}

或通过 API 创建：

{
  "name": "hyperframes",
  "server_type": "local",
  "transport": "stdio",
  "command": "uvx",
  "args": "timeverse-hyperframes-mcp",
  "description": "HyperFrames MCP — 将 HTML/CSS/JS 渲染为 MP4 视频"
}

完整示例见 examples/timeverse-integration.json。

其他 MCP 客户端（如 Claude Desktop、Cline 等）

使用相同的 stdio 配置：

• 命令: uvx timeverse-hyperframes-mcp 或 timeverse-hyperframes-mcp
• 传输协议: stdio

可用工具（共 13 个）

项目初始化

工具	对应 CLI	参数	说明
hyperframes_init	npx hyperframes init	project_name (必填), template, video_path, audio_path, parent_dir	创建视频项目，支持 9 种模板
hyperframes_list_templates	—	无参数	列出所有模板及中文描述

支持模板：blank（空白）、warm-grain（暖色颗粒）、play-mode（Play 模式）、swiss-grid（瑞士网格）、vignelli（Vignelli 风格）、decision-tree（决策树）、kinetic-type（动态文字）、product-promo（产品宣传）、nyt-graph（纽约时报数据可视化）

视频渲染

工具	对应 CLI	参数	说明
hyperframes_render	npx hyperframes render	output, fps(24/30/60), quality(draft/standard/high), format(mp4/webm), composition, workers(1-8/auto), gpu, docker, strict, strict_all	渲染为 MP4/WebM，支持 GPU 加速和 Docker 可重现构建

• webm 格式支持透明背景
• 渲染超时默认 10 分钟

实时预览

工具	对应 CLI	参数	说明
hyperframes_preview	npx hyperframes preview	project_dir, port(默认 3002)	启动本地预览服务，热重载，编辑 HTML 即时更新

语法检查

工具	对应 CLI	参数	说明
hyperframes_lint	npx hyperframes lint	project_dir, verbose, json_output	检查 data-composition-id、track 重叠、timeline 注册等问题

媒体处理

工具	对应 CLI	参数	说明
hyperframes_tts	npx hyperframes tts	text (必填), voice, output, project_dir	文本转语音，生成配音文件
hyperframes_list_voices	npx hyperframes tts --list	project_dir	列出所有可用 TTS 语音角色（如 af_nova, bf_emma）
hyperframes_transcribe	npx hyperframes transcribe	input_path (必填), model(tiny/base/small/medium/large), language, output_format, project_dir	音频/视频转录为字幕

系统管理

工具	对应 CLI	参数	说明
hyperframes_doctor	npx hyperframes doctor	project_dir	检测 Node.js / npx / FFmpeg 环境，给出安装指引
hyperframes_info	npx hyperframes info	project_dir	获取 HyperFrames 版本和环境详情
hyperframes_upgrade	npx hyperframes upgrade	check_only, json_output	检查是否有新版本
hyperframes_compositions	npx hyperframes compositions	project_dir	列出项目中的 composition 文件
hyperframes_benchmark	npx hyperframes benchmark	composition, project_dir	运行渲染性能基准测试

典型工作流

flowchart LR
    A[hyperframes_init] --> B[hyperframes_lint]
    B --> C[hyperframes_preview]
    C --> D[修改 HTML/CSS/JS]
    D --> B
    B --> E[hyperframes_render]

1. 创建项目: hyperframes_init(project_name="my-video", template="kinetic-type")
2. 语法检查: hyperframes_lint(project_dir="my-video")
3. 实时预览: hyperframes_preview(project_dir="my-video") → 浏览器中编辑 HTML 即改即现
4. 迭代: 修改 HTML → lint → 预览验证
5. 渲染: hyperframes_render(project_dir="my-video", quality="high") → 输出 MP4

环境变量

变量	说明	默认值
HYPERFRAMES_WORKSPACE_DIR	视频项目工作目录	当前工作目录

特性

• 智能命令解析：优先使用全局安装的 hyperframes，回退到 npx hyperframes
• 后台预热：服务器启动时自动在后台下载 hyperframes npm 缓存，首次调用更快
• 友好错误提示：命令超时或环境缺失时给出清晰的修复指引
• JSON 结构化输出：lint 结果支持 JSON 格式，便于 AI 解析

常见问题

Q: 首次运行很慢？ 首次运行需要 npx 下载 hyperframes 包（约 30-60 秒），后续会缓存。也可以先全局安装 npm install -g hyperframes 跳过 npx 过程。

Q: 提示"未找到 npx"？ 确认已安装 Node.js >= 22。

Q: 渲染失败？ 先运行 hyperframes_doctor 检测环境是否完整，再运行 hyperframes_lint 检查语法。

开发者

• 源码：GitHub
• HyperFrames：https://github.com/heygen-com/hyperframes