timeverse-hyperframes-mcp 0.1.0__py3-none-any.whl

timeverse_hyperframes_mcp/__init__.py

@@ -0,0 +1,23 @@
+"""
+timeverse-hyperframes-mcp — MCP server for HyperFrames
+
+功能简述:
+    MCP 服务器，将 HyperFrames CLI（HTML 转视频渲染引擎）包装为 MCP 工具。
+    支持视频项目初始化、预览、渲染、lint、TTS 等能力。
+    兼容 TimeVerseStudio 的 MCP 注册体系（local/stdio 模式）。
+
+主要工具清单:
+    - hyperframes_init: 创建新的视频项目
+    - hyperframes_render: 渲染视频为 MP4/WebM
+    - hyperframes_preview: 启动本地实时预览
+    - hyperframes_lint: 检查项目语法完整性
+    - hyperframes_doctor: 检测运行环境
+    - hyperframes_tts: 文本转语音
+    - hyperframes_transcribe: 音频/视频转录文字
+
+使用示例:
+    # 作为 stdio MCP 服务器运行
+    python -m timeverse_hyperframes_mcp.server
+"""
+
+__version__ = "0.1.0"

timeverse_hyperframes_mcp/__main__.py

@@ -0,0 +1,4 @@
+"""python -m 入口"""
+from .server import main
+
+main()

timeverse_hyperframes_mcp/cli_executor.py

@@ -0,0 +1,196 @@
+"""
+CLI 执行器 — 统一执行 HyperFrames CLI 命令
+
+功能简述:
+    提供异步执行 npx hyperframes 命令的统一接口。
+    处理命令超时、错误捕获、标准输出解析。
+
+主要方法清单:
+    - run_hyperframes: 执行任意 hyperframes 子命令
+    - check_environment: 检测 ffmpeg / node 环境
+    - parse_lint_output: 解析 lint --json 输出
+    - find_workspace: 查找或创建项目工作目录
+
+使用示例:
+    result = await run_hyperframes(["init", "my-video", "--non-interactive"])
+"""
+
+import asyncio
+import json
+import logging
+import os
+import shutil
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# ==================== 常量定义 ====================
+
+DEFAULT_TIMEOUT = 120  # 默认超时（秒）
+RENDER_TIMEOUT = 600  # 渲染超时（秒）
+WORKSPACE_ENV_VAR = "HYPERFRAMES_WORKSPACE_DIR"
+
+
+# ==================== 核心方法 ====================
+
+async def run_hyperframes(
+    args: list[str],
+    cwd: Optional[str] = None,
+    timeout: int = DEFAULT_TIMEOUT,
+) -> dict:
+    """
+    执行 npx hyperframes <args> 命令
+
+    Args:
+        args: 子命令及参数列表，如 ["init", "my-video", "--non-interactive"]
+        cwd: 工作目录，默认为 WORKSPACE_ENV_VAR 指向的目录或当前目录
+        timeout: 超时秒数
+
+    Returns:
+        {
+            "success": bool,
+            "stdout": str,
+            "stderr": str,
+            "exit_code": int,
+            "command": str
+        }
+
+    Raises:
+        TimeoutError: 命令执行超时
+    """
+    cmd = ["npx", "hyperframes", *args]
+    cmd_str = " ".join(cmd)
+
+    if cwd is None:
+        cwd = os.environ.get(WORKSPACE_ENV_VAR, os.getcwd())
+
+    try:
+        proc = await asyncio.wait_for(
+            asyncio.create_subprocess_exec(
+                *cmd,
+                cwd=cwd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                env={**os.environ, "PAGER": "cat"},
+            ),
+            timeout=timeout,
+        )
+        stdout, stderr = await proc.communicate()
+        stdout_str = stdout.decode("utf-8", errors="replace").strip()
+        stderr_str = stderr.decode("utf-8", errors="replace").strip()
+
+        return {
+            "success": proc.returncode == 0,
+            "stdout": stdout_str,
+            "stderr": stderr_str,
+            "exit_code": proc.returncode or 0,
+            "command": cmd_str,
+        }
+    except asyncio.TimeoutError:
+        raise TimeoutError(f"命令超时（{timeout}s）: {cmd_str}")
+    except FileNotFoundError:
+        return {
+            "success": False,
+            "stdout": "",
+            "stderr": "未找到 npx，请确认 Node.js >= 22 已安装",
+            "exit_code": -1,
+            "command": cmd_str,
+        }
+
+
+async def check_environment() -> dict:
+    """
+    检测运行环境是否满足 HyperFrames 要求
+
+    Returns:
+        {
+            "node_ok": bool, "node_version": str,
+            "ffmpeg_ok": bool, "ffmpeg_version": str,
+            "npx_ok": bool,
+            "all_ok": bool
+        }
+    """
+    checks = {
+        "node_ok": False,
+        "node_version": "",
+        "ffmpeg_ok": False,
+        "ffmpeg_version": "",
+        "npx_ok": False,
+        "all_ok": False,
+    }
+
+    # 检测 Node.js
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            "node", "--version",
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stdout, _ = await proc.communicate()
+        version = stdout.decode("utf-8", errors="replace").strip()
+        checks["node_version"] = version
+        checks["node_ok"] = bool(version) and proc.returncode == 0
+    except FileNotFoundError:
+        checks["node_version"] = "未安装"
+
+    # 检测 npx
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            "npx", "--version",
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stdout, _ = await proc.communicate()
+        checks["npx_ok"] = proc.returncode == 0
+    except FileNotFoundError:
+        pass
+
+    # 检测 ffmpeg
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            "ffmpeg", "-version",
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stdout, _ = await proc.communicate()
+        if proc.returncode == 0:
+            first_line = stdout.decode("utf-8", errors="replace").split("\n")[0].strip()
+            checks["ffmpeg_version"] = first_line
+            checks["ffmpeg_ok"] = True
+    except FileNotFoundError:
+        checks["ffmpeg_version"] = "未安装"
+
+    checks["all_ok"] = checks["node_ok"] and checks["ffmpeg_ok"] and checks["npx_ok"]
+    return checks
+
+
+def parse_lint_json(stdout: str) -> dict:
+    """
+    解析 hyperframes lint --json 输出
+
+    Args:
+        stdout: lint --json 的标准输出
+
+    Returns:
+        解析后的 lint 结果字典，包含 errorCount, warningCount, findings 等字段
+    """
+    try:
+        return json.loads(stdout)
+    except json.JSONDecodeError:
+        return {"error": "无法解析 lint 输出", "raw": stdout}
+
+
+# ==================== 工具函数 ====================
+
+def find_workspace() -> str:
+    """
+    获取工作目录（优先从环境变量读取，否则用当前目录）
+
+    Returns:
+        工作目录绝对路径
+    """
+    workspace = os.environ.get(WORKSPACE_ENV_VAR)
+    if workspace and os.path.isdir(workspace):
+        return workspace
+    return os.getcwd()

timeverse_hyperframes_mcp/server.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""
+timeverse-hyperframes-mcp — MCP 服务器主入口
+
+功能简述:
+    使用 FastMCP 创建 MCP 服务器，将所有 HyperFrames CLI 命令包装为 MCP 工具。
+    通过 stdio 协议与 MCP 客户端（如 TimeVerseStudio）通信。
+
+使用示例:
+    # 直接运行
+    python -m timeverse_hyperframes_mcp.server
+
+    # 或作为 CLI 命令（安装后）
+    timeverse-hyperframes-mcp
+"""
+
+import asyncio
+import logging
+import sys
+
+from mcp.server import FastMCP
+
+from . import __version__
+from .tools import register_all
+
+# ==================== 日志配置 ====================
+
+logging.basicConfig(
+    level=logging.WARNING,
+    format="[%(levelname)s] %(name)s: %(message)s",
+    stream=sys.stderr,
+)
+logger = logging.getLogger(__name__)
+
+# ==================== 创建 MCP 服务器 ====================
+
+mcp = FastMCP(
+    name="timeverse-hyperframes-mcp",
+    instructions="HyperFrames MCP Server — 将 HTML/CSS/JS 渲染为 MP4 视频。支持 init / preview / render / lint / TTS / transcribe 等命令。",
+)
+
+
+# ==================== 注册工具 ====================
+
+register_all(mcp)
+
+
+# ==================== 启动 ====================
+
+def main() -> None:
+    """启动 MCP 服务器（stdio 模式）"""
+    logger.info("启动 timeverse-hyperframes-mcp v%s（stdio 模式）", __version__)
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

timeverse_hyperframes_mcp/tools/__init__.py

@@ -0,0 +1,26 @@
+"""
+HyperFrames MCP 工具模块
+
+功能简述:
+    将所有工具函数注册到 FastMCP 服务器实例。
+    每个子模块的 register_xxx(mcp) 函数负责注册对应的 MCP 工具。
+
+主要方法清单:
+    - register_all(mcp): 注册所有工具到指定 FastMCP 实例
+
+使用示例:
+    from . import register_all
+    register_all(mcp)
+"""
+
+from . import init, render, preview, lint, media, system
+
+
+def register_all(mcp) -> None:
+    """注册所有 HyperFrames MCP 工具"""
+    init.register_tools(mcp)
+    render.register_tools(mcp)
+    preview.register_tools(mcp)
+    lint.register_tools(mcp)
+    media.register_tools(mcp)
+    system.register_tools(mcp)

timeverse_hyperframes_mcp/tools/init.py

@@ -0,0 +1,121 @@
+"""
+hyperframes_init — 视频项目初始化工具
+
+功能简述:
+    封装 npx hyperframes init 命令，支持创建新视频项目。
+    可选择模板、预设示例、附带视频/音频素材。
+
+主要方法清单:
+    - register_tools(mcp): 注册 hyperframes_init / hyperframes_list_templates
+"""
+
+import os
+from typing import Optional
+
+from ..cli_executor import run_hyperframes, find_workspace
+
+# ==================== 常量定义 ====================
+
+AVAILABLE_TEMPLATES = [
+    "blank",
+    "warm-grain",
+    "play-mode",
+    "swiss-grid",
+    "vignelli",
+    "decision-tree",
+    "kinetic-type",
+    "product-promo",
+    "nyt-graph",
+]
+
+
+def register_tools(mcp) -> None:
+    """注册初始化相关的 MCP 工具"""
+
+    @mcp.tool(
+        name="hyperframes_init",
+        description="创建新的 HyperFrames 视频项目。初始化目录结构、安装依赖。"
+    )
+    async def hyperframes_init(
+        project_name: str,
+        template: Optional[str] = None,
+        video_path: Optional[str] = None,
+        audio_path: Optional[str] = None,
+        non_interactive: bool = True,
+        parent_dir: Optional[str] = None,
+    ) -> str:
+        """
+        创建新的 HyperFrames 视频项目
+
+        Args:
+            project_name: 项目目录名称（如 "my-video"）
+            template: 模板名称。可选值：blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph
+            video_path: 附带已有视频文件路径（将自动拷贝到项目中）
+            audio_path: 附带音频文件路径（将自动拷贝并转写）
+            non_interactive: 是否静默模式（默认 True，适合 AI 调用）
+            parent_dir: 父级目录，默认为当前工作空间
+
+        Returns:
+            项目的标准输出信息
+        """
+        args = ["init", project_name]
+
+        if non_interactive:
+            args.append("--non-interactive")
+
+        if template:
+            if template not in AVAILABLE_TEMPLATES:
+                available = ", ".join(AVAILABLE_TEMPLATES)
+                return (
+                    f"❌ 无效模板: {template}\n"
+                    f"可用模板: {available}"
+                )
+            args.extend(["--example", template])
+
+        if video_path:
+            args.extend(["--video", video_path])
+
+        if audio_path:
+            args.extend(["--audio", audio_path])
+
+        workspace = parent_dir or find_workspace()
+        result = await run_hyperframes(args, cwd=workspace)
+
+        if result["success"]:
+            project_dir = os.path.join(workspace, project_name)
+            return (
+                f"✅ 项目创建成功\n"
+                f"   路径: {project_dir}\n"
+                f"   模板: {template or 'blank'}\n"
+                f"{result['stdout']}"
+            )
+        else:
+            return f"❌ 项目创建失败\n{result['stderr']}"
+
+    @mcp.tool(
+        name="hyperframes_list_templates",
+        description="列出 HyperFrames 所有可用的项目模板。"
+    )
+    async def hyperframes_list_templates() -> str:
+        """
+        列出所有可用的项目模板
+
+        Returns:
+            模板列表与说明
+        """
+        templates_info = {
+            "blank": "空项目，从零开始",
+            "warm-grain": "暖色颗粒纹理风格",
+            "play-mode": "Play 模式示例",
+            "swiss-grid": "瑞士网格排版风格",
+            "vignelli": "Vignelli 风格",
+            "decision-tree": "决策树流程图",
+            "kinetic-type": "动态文字排版",
+            "product-promo": "产品宣传视频模板",
+            "nyt-graph": "纽约时报风格数据可视化",
+        }
+        lines = ["📁 HyperFrames 可用模板：\n"]
+        for t in AVAILABLE_TEMPLATES:
+            desc = templates_info.get(t, "")
+            lines.append(f"  - {t}: {desc}")
+        return "\n".join(lines)

timeverse_hyperframes_mcp/tools/lint.py

@@ -0,0 +1,74 @@
+"""
+hyperframes_lint — 项目语法检查工具
+
+功能简述:
+    封装 npx hyperframes lint 命令，验证 composition 语法正确性。
+    检查 data-composition-id、track 重叠、timeline 注册等问题。
+
+主要方法清单:
+    - register_tools(mcp): 注册 hyperframes_lint
+"""
+
+from typing import Optional
+
+from ..cli_executor import run_hyperframes, find_workspace, parse_lint_json
+
+
+def register_tools(mcp) -> None:
+    """注册 lint 相关的 MCP 工具"""
+
+    @mcp.tool(
+        name="hyperframes_lint",
+        description="检查 HyperFrames 项目的语法和结构完整性。建议在 preview/render 前运行。"
+    )
+    async def hyperframes_lint(
+        project_dir: Optional[str] = None,
+        verbose: bool = False,
+        json_output: bool = True,
+    ) -> str:
+        """
+        检查 HyperFrames 项目的语法和结构完整性
+
+        Args:
+            project_dir: 项目目录路径。默认为当前工作空间
+            verbose: 是否显示 info 级别的详细信息（默认只显示 errors 和 warnings）
+            json_output: 是否输出结构化 JSON 结果（默认 True）
+
+        Returns:
+            lint 检查结果
+        """
+        args = ["lint"]
+
+        if verbose:
+            args.append("--verbose")
+
+        if json_output:
+            args.append("--json")
+
+        workspace = find_workspace() if not project_dir else project_dir
+        result = await run_hyperframes(args, cwd=workspace)
+
+        if not result["success"] and not result["stdout"]:
+            return f"❌ lint 检查失败\n{result['stderr']}"
+
+        if json_output and result["stdout"]:
+            parsed = parse_lint_json(result["stdout"])
+            if "errorCount" in parsed:
+                ec = parsed.get("errorCount", 0)
+                wc = parsed.get("warningCount", 0)
+                ic = parsed.get("infoCount", 0)
+                findings = parsed.get("findings", [])
+                lines = [f"📋 Lint 结果：{ec} 个错误, {wc} 个警告, {ic} 个信息\n"]
+                for f in findings:
+                    severity = f.get("severity", "info")
+                    icon = {"error": "❌", "warning": "⚠️", "info": "ℹ️"}.get(severity, "•")
+                    msg = f.get("message", "")
+                    loc = f.get("location", "")
+                    lines.append(f"  {icon} [{severity}] {msg}")
+                    if loc:
+                        lines[-1] += f" ({loc})"
+                if ec > 0:
+                    lines.append("\n💡 存在错误，建议修复后再 preview/render")
+                return "\n".join(lines)
+
+        return result["stdout"] or result["stderr"]

timeverse_hyperframes_mcp/tools/media.py

@@ -0,0 +1,128 @@
+"""
+hyperframes_media — 媒体处理工具（TTS / 转录）
+
+功能简述:
+    封装 npx hyperframes tts 和 npx hyperframes transcribe 命令。
+    支持文本转语音、音频/视频转录字幕、字幕导入导出。
+
+主要方法清单:
+    - register_tools(mcp): 注册 hyperframes_tts / hyperframes_transcribe / hyperframes_list_voices
+"""
+
+from typing import Optional
+
+from ..cli_executor import run_hyperframes, find_workspace
+
+
+def register_tools(mcp) -> None:
+    """注册媒体处理相关的 MCP 工具"""
+
+    @mcp.tool(
+        name="hyperframes_tts",
+        description="文本转语音（Text-to-Speech）。生成配音音频文件。"
+    )
+    async def hyperframes_tts(
+        text: str,
+        voice: Optional[str] = None,
+        output: Optional[str] = None,
+        project_dir: Optional[str] = None,
+    ) -> str:
+        """
+        文本转语音
+
+        Args:
+            text: 需要朗读的文本内容，或包含文本的文件路径
+            voice: 语音角色（如 af_nova, bf_emma）。不指定则用默认角色
+            output: 输出音频文件路径，默认 narration.wav
+            project_dir: 项目目录路径
+
+        Returns:
+            TTS 执行结果
+        """
+        args = ["tts"]
+
+        # 判断 text 是文件路径还是纯文本
+        args.append(text)
+
+        if voice:
+            args.extend(["--voice", voice])
+
+        if output:
+            args.extend(["--output", output])
+
+        workspace = find_workspace() if not project_dir else project_dir
+        result = await run_hyperframes(args, cwd=workspace)
+
+        if result["success"]:
+            return f"✅ TTS 生成成功\n{result['stdout']}"
+        else:
+            return f"❌ TTS 生成失败\n{result['stderr']}"
+
+    @mcp.tool(
+        name="hyperframes_list_voices",
+        description="列出所有可用的 TTS 语音角色。"
+    )
+    async def hyperframes_list_voices(
+        project_dir: Optional[str] = None,
+    ) -> str:
+        """
+        列出所有可用的 TTS 语音角色
+
+        Args:
+            project_dir: 项目目录路径
+
+        Returns:
+            可用语音角色列表
+        """
+        result = await run_hyperframes(
+            ["tts", "--list"],
+            cwd=find_workspace() if not project_dir else project_dir,
+        )
+
+        if result["success"]:
+            return result["stdout"]
+        else:
+            return f"❌ 获取语音列表失败\n{result['stderr']}"
+
+    @mcp.tool(
+        name="hyperframes_transcribe",
+        description="音频/视频转录为文字字幕。支持多种输入格式。"
+    )
+    async def hyperframes_transcribe(
+        input_path: str,
+        model: Optional[str] = None,
+        language: Optional[str] = None,
+        output_format: Optional[str] = None,
+        project_dir: Optional[str] = None,
+    ) -> str:
+        """
+        音频/视频转录文字
+
+        Args:
+            input_path: 输入音频/视频文件路径，或现有字幕文件路径（.srt/.vtt/.json）
+            model: Whisper 模型大小（如 tiny, base, small, medium, large）。默认 medium.en
+            language: 语言代码（如 en, zh, ja）。不指定则自动检测
+            output_format: 输出字幕格式（当输入是媒体文件时）。不指定则自动推断
+            project_dir: 项目目录路径
+
+        Returns:
+            转录结果
+        """
+        args = ["transcribe", input_path]
+
+        if model:
+            args.extend(["--model", model])
+
+        if language:
+            args.extend(["--language", language])
+
+        if output_format:
+            args.extend(["--output-format", output_format])
+
+        workspace = find_workspace() if not project_dir else project_dir
+        result = await run_hyperframes(args, cwd=workspace, timeout=300)
+
+        if result["success"]:
+            return f"✅ 转录成功\n{result['stdout']}"
+        else:
+            return f"❌ 转录失败\n{result['stderr']}"

timeverse_hyperframes_mcp/tools/preview.py

@@ -0,0 +1,61 @@
+"""
+hyperframes_preview — 视频预览工具
+
+功能简述:
+    封装 npx hyperframes preview 命令，启动本地实时预览服务。
+    支持自定义端口，热重载。
+
+主要方法清单:
+    - register_tools(mcp): 注册 hyperframes_preview
+"""
+
+from typing import Optional
+
+from ..cli_executor import run_hyperframes, find_workspace
+
+
+def register_tools(mcp) -> None:
+    """注册预览相关的 MCP 工具"""
+
+    @mcp.tool(
+        name="hyperframes_preview",
+        description="启动 HyperFrames 项目的本地实时预览服务。热重载，编辑即更新。"
+    )
+    async def hyperframes_preview(
+        project_dir: Optional[str] = None,
+        port: Optional[int] = None,
+    ) -> str:
+        """
+        启动本地预览服务
+
+        Args:
+            project_dir: 项目目录路径。默认为当前工作空间
+            port: 端口号（默认 3002）
+
+        Returns:
+            预览服务信息，包含访问地址
+        """
+        args = ["preview"]
+
+        if port:
+            args.extend(["--port", str(port)])
+
+        workspace = find_workspace() if not project_dir else project_dir
+        # preview 是一个持续运行的服务，设置较短超时拿到初始输出即可
+        result = await run_hyperframes(args, cwd=workspace, timeout=15)
+
+        if result["success"]:
+            output = result["stdout"]
+            # 从 stdout 中提取 URL
+            url = ""
+            for line in output.split("\n"):
+                if "http" in line:
+                    url = line.strip()
+                    break
+            msg = f"✅ 预览服务已启动\n"
+            if url:
+                msg += f"   访问地址: {url}\n"
+            msg += output
+            return msg
+        else:
+            return f"❌ 预览启动失败\n{result['stderr']}"

timeverse_hyperframes_mcp/tools/render.py

@@ -0,0 +1,105 @@
+"""
+hyperframes_render — 视频渲染工具
+
+功能简述:
+    封装 npx hyperframes render 命令，支持多种质量/格式/帧率。
+    支持指定 composition、GPU 加速、Docker 可重现构建等高级选项。
+
+主要方法清单:
+    - register_tools(mcp): 注册 hyperframes_render
+"""
+
+from typing import Optional
+
+from ..cli_executor import run_hyperframes, find_workspace, RENDER_TIMEOUT
+
+
+def register_tools(mcp) -> None:
+    """注册渲染相关的 MCP 工具"""
+
+    @mcp.tool(
+        name="hyperframes_render",
+        description="将 HyperFrames 项目渲染为 MP4/WebM 视频。"
+    )
+    async def hyperframes_render(
+        project_dir: Optional[str] = None,
+        output: Optional[str] = None,
+        fps: Optional[int] = None,
+        quality: Optional[str] = None,
+        format: Optional[str] = None,
+        composition: Optional[str] = None,
+        workers: Optional[int] = None,
+        gpu: bool = False,
+        docker: bool = False,
+        strict: bool = False,
+        strict_all: bool = False,
+        timeout: int = RENDER_TIMEOUT,
+    ) -> str:
+        """
+        渲染 HyperFrames 视频项目
+
+        Args:
+            project_dir: 项目目录路径。默认为当前工作空间
+            output: 输出视频路径。默认保存在 renders/ 目录
+            fps: 帧率，可选 24/30/60。默认 30
+            quality: 渲染质量。可选 draft（快速迭代）/ standard（审阅）/ high（最终交付）
+            format: 输出格式。mp4 或 webm（webm 支持透明背景）
+            composition: 只渲染指定的 composition 文件（相对于项目目录的路径）
+            workers: 并行工作进程数，可选 1-8 或 auto。默认 auto
+            gpu: 启用 GPU 加速编码（默认关闭）
+            docker: 使用 Docker 可重现构建（默认关闭）
+            strict: lint 错误时中止渲染（默认关闭）
+            strict_all: lint 错误和警告时都中止（默认关闭）
+            timeout: 渲染超时秒数，默认 600
+
+        Returns:
+            渲染结果输出信息
+        """
+        args = ["render"]
+
+        if output:
+            args.extend(["--output", output])
+
+        if fps:
+            if fps not in (24, 30, 60):
+                return f"❌ 无效帧率: {fps}。可选值: 24, 30, 60"
+            args.extend(["--fps", str(fps)])
+
+        if quality:
+            if quality not in ("draft", "standard", "high"):
+                return "❌ 无效质量值。可选: draft, standard, high"
+            args.extend(["--quality", quality])
+
+        if format:
+            if format not in ("mp4", "webm"):
+                return "❌ 无效格式。可选: mp4, webm"
+            args.extend(["--format", format])
+
+        if composition:
+            args.extend(["--composition", composition])
+
+        if workers is not None:
+            w = str(workers)
+            if w not in ("auto", "1", "2", "3", "4", "5", "6", "7", "8"):
+                return "❌ 无效 workers 值。可选: auto, 1-8"
+            args.extend(["--workers", w])
+
+        if gpu:
+            args.append("--gpu")
+
+        if docker:
+            args.append("--docker")
+
+        if strict:
+            args.append("--strict")
+
+        if strict_all:
+            args.append("--strict-all")
+
+        workspace = find_workspace() if not project_dir else project_dir
+        result = await run_hyperframes(args, cwd=workspace, timeout=timeout)
+
+        if result["success"]:
+            return f"✅ 渲染成功\n{result['stdout']}"
+        else:
+            return f"❌ 渲染失败\n{result['stderr']}"

timeverse_hyperframes_mcp/tools/system.py

@@ -0,0 +1,168 @@
+"""
+hyperframes_system — 系统管理工具
+
+功能简述:
+    封装 doctor / info / upgrade / benchmark / compositions 等管理类命令。
+    用于检测环境、获取版本信息、列出 composition、跑基准测试等。
+
+主要方法清单:
+    - register_tools(mcp): 注册 hyperframes_doctor / hyperframes_info / 等
+"""
+
+from typing import Optional
+
+from ..cli_executor import run_hyperframes, find_workspace, check_environment
+
+
+def register_tools(mcp) -> None:
+    """注册系统管理相关的 MCP 工具"""
+
+    @mcp.tool(
+        name="hyperframes_doctor",
+        description="检测 HyperFrames 运行环境（Node.js, FFmpeg, Chrome 等）。渲染前建议先运行。"
+    )
+    async def hyperframes_doctor(
+        project_dir: Optional[str] = None,
+    ) -> str:
+        """
+        检测运行环境
+
+        Args:
+            project_dir: 项目目录。不指定则检查全局环境
+
+        Returns:
+            环境检测结果
+        """
+        env_check = await check_environment()
+        lines = ["🔍 HyperFrames 环境检测\n"]
+        lines.append(f"  Node.js: {'✅' if env_check['node_ok'] else '❌'} {env_check['node_version']}")
+        lines.append(f"  npx:     {'✅' if env_check['npx_ok'] else '❌'}")
+        lines.append(f"  FFmpeg:  {'✅' if env_check['ffmpeg_ok'] else '❌'} {env_check['ffmpeg_version']}")
+
+        if not env_check["all_ok"]:
+            lines.append("\n⚠️ 环境不完整，请安装缺失依赖：")
+            if not env_check["node_ok"]:
+                lines.append("  - Node.js >= 22: https://nodejs.org")
+            if not env_check["ffmpeg_ok"]:
+                lines.append("  - FFmpeg: brew install ffmpeg / apt install ffmpeg")
+            if not env_check["npx_ok"]:
+                lines.append("  - npx: npm install -g npx")
+
+        # 也跑一下 hyperframes doctor
+        workspace = find_workspace() if not project_dir else project_dir
+        hf_result = await run_hyperframes(["doctor"], cwd=workspace, timeout=30)
+        if hf_result["stdout"]:
+            lines.append(f"\n--- HyperFrames Doctor ---\n{hf_result['stdout']}")
+
+        return "\n".join(lines)
+
+    @mcp.tool(
+        name="hyperframes_info",
+        description="获取 HyperFrames 版本和环境详细信息。"
+    )
+    async def hyperframes_info(
+        project_dir: Optional[str] = None,
+    ) -> str:
+        """
+        获取版本和环境信息
+
+        Args:
+            project_dir: 项目目录路径
+
+        Returns:
+            版本和环境信息
+        """
+        result = await run_hyperframes(
+            ["info"],
+            cwd=find_workspace() if not project_dir else project_dir,
+        )
+        if result["success"]:
+            return result["stdout"]
+        else:
+            return f"❌ 获取信息失败\n{result['stderr']}"
+
+    @mcp.tool(
+        name="hyperframes_upgrade",
+        description="检查 HyperFrames 是否有更新版本。"
+    )
+    async def hyperframes_upgrade(
+        check_only: bool = True,
+        json_output: bool = True,
+    ) -> str:
+        """
+        检查 HyperFrames 版本更新
+
+        Args:
+            check_only: 仅检查不升级（默认 True）
+            json_output: JSON 格式输出（默认 True，适合 AI 解析）
+
+        Returns:
+            版本更新信息
+        """
+        args = ["upgrade"]
+        if check_only:
+            args.append("--check")
+        if json_output:
+            args.extend(["--check", "--json"])
+
+        result = await run_hyperframes(args)
+
+        if result["success"]:
+            return result["stdout"]
+        else:
+            return f"❌ 检查更新失败\n{result['stderr']}"
+
+    @mcp.tool(
+        name="hyperframes_compositions",
+        description="列出 HyperFrames 项目中的所有 composition 文件。"
+    )
+    async def hyperframes_compositions(
+        project_dir: Optional[str] = None,
+    ) -> str:
+        """
+        列出项目中的 composition 文件
+
+        Args:
+            project_dir: 项目目录路径
+
+        Returns:
+            composition 列表
+        """
+        result = await run_hyperframes(
+            ["compositions"],
+            cwd=find_workspace() if not project_dir else project_dir,
+        )
+        if result["success"]:
+            return f"📄 Composition 列表：\n{result['stdout']}"
+        else:
+            return f"❌ 获取 composition 列表失败\n{result['stderr']}"
+
+    @mcp.tool(
+        name="hyperframes_benchmark",
+        description="对 HyperFrames 项目运行渲染基准测试。"
+    )
+    async def hyperframes_benchmark(
+        composition: Optional[str] = None,
+        project_dir: Optional[str] = None,
+    ) -> str:
+        """
+        运行渲染性能基准测试
+
+        Args:
+            composition: 指定的 composition 文件路径（相对于项目目录）
+            project_dir: 项目目录路径
+
+        Returns:
+            基准测试结果
+        """
+        args = ["benchmark"]
+        if composition:
+            args.append(composition)
+
+        workspace = find_workspace() if not project_dir else project_dir
+        result = await run_hyperframes(args, cwd=workspace, timeout=300)
+
+        if result["success"]:
+            return f"📊 基准测试结果：\n{result['stdout']}"
+        else:
+            return f"❌ 基准测试失败\n{result['stderr']}"

timeverse_hyperframes_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: timeverse-hyperframes-mcp
+Version: 0.1.0
+Summary: MCP server wrapping HyperFrames CLI — turn HTML/CSS/JS into MP4 videos
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0

timeverse_hyperframes_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+timeverse_hyperframes_mcp/__init__.py,sha256=HTdlmbi6giBoz1QLbCt6SOJVT2stn7RXumBvc-kLjm0,816
+timeverse_hyperframes_mcp/__main__.py,sha256=hbWteOuauvjMZ41amSwr8ywOpFn1QX19DgPoBtIxa7w,56
+timeverse_hyperframes_mcp/cli_executor.py,sha256=wQfycCu_8lWdaJhvQHB-gy9DeFtyhtUhWm_zvktdpuQ,5615
+timeverse_hyperframes_mcp/server.py,sha256=zNcEW_0ml69Fe-eBYFt7Uu_mJxDYseuyB_UIEIHw6_o,1417
+timeverse_hyperframes_mcp/tools/__init__.py,sha256=jqugTRv9TIIJE1cGjZwgqODP62tEaB0kCrgo7ByF2T0,673
+timeverse_hyperframes_mcp/tools/init.py,sha256=UH0W2_vIzjGC46gMjhoQJ3tGITcQiqaeCQWLRdRZbvA,3965
+timeverse_hyperframes_mcp/tools/lint.py,sha256=iJJ-T-so9NH22Dthg2fnn2dQZMk7AcNaI6uUX3iM9xM,2687
+timeverse_hyperframes_mcp/tools/media.py,sha256=PTaTU_cX5kZbzPPIU05qhFuAMFCpwVRCHwqxX0_sbmA,4007
+timeverse_hyperframes_mcp/tools/preview.py,sha256=5AHyZveF0cxdGN7wq11imFhtJv2q9Cfq4_Lxuz9XC_o,1835
+timeverse_hyperframes_mcp/tools/render.py,sha256=tAD2GuhnhCl_46h1uTsD6q7DTsN4zTivaEUfbj9SkO4,3638
+timeverse_hyperframes_mcp/tools/system.py,sha256=xmCb66eJ47f1EhbcqRmLeDez-2F09nMzs7OnopPKETU,5406
+timeverse_hyperframes_mcp-0.1.0.dist-info/METADATA,sha256=b4iQVGxHI4hjT3HF_O-rRiz7gcs_w2J483zP8m1t7Kc,261
+timeverse_hyperframes_mcp-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+timeverse_hyperframes_mcp-0.1.0.dist-info/entry_points.txt,sha256=COzvHluM-CSDKzNSmVMKSqxwugV9KidJfIh5UUxNlD8,84
+timeverse_hyperframes_mcp-0.1.0.dist-info/top_level.txt,sha256=GsEq1qsZra0XtXR532rQWnoWekrDiu5YWATaPI4cdjk,26
+timeverse_hyperframes_mcp-0.1.0.dist-info/RECORD,,

timeverse_hyperframes_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

timeverse_hyperframes_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+timeverse-hyperframes-mcp = timeverse_hyperframes_mcp.server:main

timeverse_hyperframes_mcp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+timeverse_hyperframes_mcp