timeverse-hyperframes-mcp 0.1.0__tar.gz → 0.1.2__tar.gz

{timeverse_hyperframes_mcp-0.1.0 → timeverse_hyperframes_mcp-0.1.2}/PKG-INFO

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

{timeverse_hyperframes_mcp-0.1.0 → timeverse_hyperframes_mcp-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "timeverse-hyperframes-mcp"
-version = "0.1.0"
+version = "0.1.2"
 description = "MCP server wrapping HyperFrames CLI — turn HTML/CSS/JS into MP4 videos"
 requires-python = ">=3.11"
 dependencies = [

{timeverse_hyperframes_mcp-0.1.0 → timeverse_hyperframes_mcp-0.1.2}/src/timeverse_hyperframes_mcp/cli_executor.py

@@ -27,20 +27,35 @@ logger = logging.getLogger(__name__)
 
 # ==================== 常量定义 ====================
 
-DEFAULT_TIMEOUT = 120  # 默认超时（秒）
+DEFAULT_TIMEOUT = 300  # 默认超时（秒，首次 npx 下载约 30-60 秒）
 RENDER_TIMEOUT = 600  # 渲染超时（秒）
 WORKSPACE_ENV_VAR = "HYPERFRAMES_WORKSPACE_DIR"
 
 
 # ==================== 核心方法 ====================
 
+def _resolve_hyperframes_command() -> tuple[list[str], str]:
+    """
+    解析 hyperframes 可执行路径。
+    优先使用全局安装的 hyperframes，否则回退到 npx hyperframes。
+
+    Returns:
+        (cmd_parts, display_name)
+        如 (["hyperframes"], "hyperframes") 或 (["npx", "hyperframes"], "npx hyperframes")
+    """
+    global_cmd = shutil.which("hyperframes")
+    if global_cmd:
+        return [global_cmd], "hyperframes"
+    return ["npx", "hyperframes"], "npx hyperframes"
+
+
 async def run_hyperframes(
     args: list[str],
     cwd: Optional[str] = None,
     timeout: int = DEFAULT_TIMEOUT,
 ) -> dict:
     """
-    执行 npx hyperframes <args> 命令
+    执行 hyperframes <args> 命令（优先全局命令，回退 npx）
 
     Args:
         args: 子命令及参数列表，如 ["init", "my-video", "--non-interactive"]
@@ -59,8 +74,9 @@ async def run_hyperframes(
     Raises:
         TimeoutError: 命令执行超时
     """
-    cmd = ["npx", "hyperframes", *args]
-    cmd_str = " ".join(cmd)
+    base_cmd, display_name = _resolve_hyperframes_command()
+    cmd = [*base_cmd, *args]
+    cmd_str = f"{display_name} {' '.join(args)}"
 
     if cwd is None:
         cwd = os.environ.get(WORKSPACE_ENV_VAR, os.getcwd())
@@ -90,10 +106,11 @@ async def run_hyperframes(
     except asyncio.TimeoutError:
         raise TimeoutError(f"命令超时（{timeout}s）: {cmd_str}")
     except FileNotFoundError:
+        hints = "请安装 Node.js >= 22，或执行 npm install -g hyperframes 全局安装"
         return {
             "success": False,
             "stdout": "",
-            "stderr": "未找到 npx，请确认 Node.js >= 22 已安装",
+            "stderr": f"未找到 hyperframes / npx 命令。{hints}",
             "exit_code": -1,
             "command": cmd_str,
         }

timeverse_hyperframes_mcp-0.1.2/src/timeverse_hyperframes_mcp/server.py

@@ -0,0 +1,103 @@
+#!/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
+import threading
+
+from mcp.server import FastMCP
+
+from . import __version__
+from .cli_executor import _resolve_hyperframes_command, run_hyperframes
+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 等命令。",
+)
+
+# ==================== 后台预热 ====================
+
+_WARMED_UP = False
+
+
+async def _warmup_npx_cache() -> None:
+    """
+    后台预热 npx 缓存。
+    提前下载 hyperframes npm 包，让后续工具调用更快。
+    """
+    global _WARMED_UP
+    try:
+        logger.info("后台预热：检测 hyperframes CLI...")
+        base_cmd, display_name = _resolve_hyperframes_command()
+        if "npx" in base_cmd:
+            logger.info("后台预热：通过 %s 下载 hyperframes 包（首次需联网，约 30-60 秒）...", display_name)
+            result = await run_hyperframes(["--help"], timeout=180)
+            if result["success"]:
+                logger.info("后台预热：完成")
+            else:
+                logger.warning("后台预热：%s", result["stderr"][:200])
+        else:
+            logger.info("后台预热：全局 hyperframes 命令已可用，跳过")
+        _WARMED_UP = True
+    except Exception as exc:
+        logger.warning("后台预热失败（不影响后续使用）: %s", exc)
+        _WARMED_UP = True  # 标记为已尝试
+
+
+def _start_background_warmup() -> None:
+    """在后台线程中启动预热"""
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    try:
+        loop.run_until_complete(_warmup_npx_cache())
+    except Exception:
+        pass
+    finally:
+        loop.close()
+
+
+# ==================== 注册工具 ====================
+
+register_all(mcp)
+
+
+# ==================== 启动 ====================
+
+def main() -> None:
+    """启动 MCP 服务器（stdio 模式），同时后台预热 npx 缓存"""
+    logger.info(
+        "启动 timeverse-hyperframes-mcp v%s（stdio 模式），后台预热 hyperframes CLI...",
+        __version__,
+    )
+    threading.Thread(target=_start_background_warmup, daemon=True).start()
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

{timeverse_hyperframes_mcp-0.1.0 → timeverse_hyperframes_mcp-0.1.2}/src/timeverse_hyperframes_mcp.egg-info/PKG-INFO

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

timeverse_hyperframes_mcp-0.1.0/src/timeverse_hyperframes_mcp/server.py

@@ -1,57 +0,0 @@
-#!/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()