cvm-vnc 0.1.9__tar.gz

cvm_vnc-0.1.9/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: cvm-vnc
+Version: 0.1.9
+Summary: Tencent Cloud CVM VNC browser control via agent-browser with MCP server support
+Author: Curu
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dotenv
+Requires-Dist: python-dotenv; extra == "dotenv"
+Provides-Extra: mcp
+Requires-Dist: mcp[cli]>=1.0.0; extra == "mcp"
+
+# cvm-vnc
+
+通过 `agent-browser` 对 Web VNC 页面进行程序化控制的 Python 工具，支持屏幕截图、文本输入和页面状态检测，并提供 MCP (Model Context Protocol) Server 供 AI Agent 集成。
+
+## 功能特性
+
+- **VNC 页面控制** — 打开并操作 Web VNC 界面
+- **屏幕截图** — 将 VNC Canvas 捕获为 PNG 图片
+- **智能文本输入** — 自动识别输入方式（远程命令对话框 / noVNC 键盘 / Canvas 直接输入等）
+- **MCP Server** — 以 stdio 模式运行，供 AI Agent 调用
+- **登录检测** — 自动识别 VNC 页面跳转至登录页的场景
+- **终端网格估算** — 根据 Canvas 尺寸启发式推算终端行列数
+
+## 安装
+
+### 从源码安装（开发模式）
+
+```bash
+git clone <repo-url>
+cd cvm-vnc
+pip install -e .
+```
+
+`-e`（editable）模式会将当前源码目录链接为已安装包，修改代码后无需重新安装即可生效。
+
+### 从 PyPI 安装
+
+```bash
+pip install cvm-vnc
+```
+
+### 可选依赖
+
+```bash
+# dotenv 支持（从 .env 文件加载环境变量）
+pip install -e '.[dotenv]'
+```
+
+### 前置依赖
+
+需要系统中安装 [agent-browser](https://www.npmjs.com/package/agent-browser)（Node.js CLI 工具）：
+
+```bash
+npm install -g agent-browser
+```
+
+## 使用方式
+
+### CLI 命令
+
+```bash
+# 打开 VNC 页面
+cvm-vnc open <url> [--wait-ms MS] [--session NAME] [--headed]
+
+# 截取 VNC 屏幕
+cvm-vnc capture [output] [--session NAME] [--headed]
+
+# 发送文本输入
+cvm-vnc type <text> [--enter] [--session NAME] [--headed]
+
+# 批量顺序输入（避免 AI 思考间隙导致登录超时）
+cvm-vnc type-sequence --steps-json '<JSON>' [--mode MODE] [--session NAME]
+
+# 关闭浏览器会话
+cvm-vnc close [--session NAME]
+
+# 启动 MCP Server
+cvm-vnc mcp [--session-default NAME] [--mode-default MODE] [--headed]
+```
+
+也可通过独立入口直接启动 MCP Server：
+
+```bash
+cvm-vnc-mcp
+```
+
+### MCP Server Tools
+
+MCP Server 对外暴露以下工具：
+
+| 工具 | 说明 |
+|------|------|
+| `vnc_open(url, wait_ms, session)` | 打开 VNC 页面 |
+| `vnc_status(session)` | 检查页面状态（Canvas 元数据、登录检测等） |
+| `vnc_capture(output_path, session)` | 截取 Canvas 为 PNG |
+| `vnc_type(text, press_enter, session, mode)` | 发送文本输入 |
+| `vnc_type_sequence(steps, session, mode)` | 批量顺序输入（适合系统登录等需要连续输入的场景） |
+| `vnc_close(session)` | 关闭浏览器会话，释放资源 |
+
+### 示例
+
+```bash
+# 打开 VNC 并等待页面加载
+cvm-vnc open https://vnc.example.com --wait-ms 3000
+
+# 截图保存到文件
+cvm-vnc capture /tmp/screen.png
+
+# 执行命令
+cvm-vnc type "ls -la" --enter
+
+# 一次性完成系统登录（用户名 + 密码）
+cvm-vnc type-sequence --steps-json '[{"text":"root","press_enter":true,"wait_ms":500},{"text":"password","press_enter":true}]'
+
+# 关闭浏览器会话
+cvm-vnc close
+```
+
+## 项目结构
+
+```
+src/cvm_vnc/
+├── __init__.py        # 版本信息
+├── __main__.py        # CLI 入口
+└── vnc_browser.py     # 核心实现（浏览器控制、MCP Server、JS 注入脚本）
+```
+
+## MCP Server 配置
+
+安装完成后，可将 cvm-vnc 作为 MCP Server 接入 AI 客户端。
+
+### Claude Code
+
+```bash
+claude mcp add cvm-vnc -- cvm-vnc-mcp
+```
+
+添加后可通过以下命令验证：
+
+```bash
+claude mcp list
+```
+
+### Codebuddy
+
+```bash
+codebuddy mcp add cvm-vnc -- cvm-vnc-mcp
+```
+
+或手动编辑 `~/.codebuddy/settings.json`：
+
+```json
+{
+  "mcpServers": {
+    "cvm-vnc": {
+      "command": "cvm-vnc-mcp"
+    }
+  }
+}
+```
+
+> **提示**：如果 `cvm-vnc-mcp` 不在 PATH 中，需使用完整路径，例如 `/path/to/venv/bin/cvm-vnc-mcp`。
+
+## 配置
+
+| 环境变量 | 说明 | 默认值 |
+|----------|------|--------|
+| `AGENT_BROWSER_BIN` | agent-browser 可执行文件路径 | 自动查找 |
+| `LOCK_TIMEOUT` | 会话锁超时时间（秒） | 120 |
+
+## License
+
+MIT

cvm_vnc-0.1.9/README.md

@@ -0,0 +1,163 @@
+# cvm-vnc
+
+通过 `agent-browser` 对 Web VNC 页面进行程序化控制的 Python 工具，支持屏幕截图、文本输入和页面状态检测，并提供 MCP (Model Context Protocol) Server 供 AI Agent 集成。
+
+## 功能特性
+
+- **VNC 页面控制** — 打开并操作 Web VNC 界面
+- **屏幕截图** — 将 VNC Canvas 捕获为 PNG 图片
+- **智能文本输入** — 自动识别输入方式（远程命令对话框 / noVNC 键盘 / Canvas 直接输入等）
+- **MCP Server** — 以 stdio 模式运行，供 AI Agent 调用
+- **登录检测** — 自动识别 VNC 页面跳转至登录页的场景
+- **终端网格估算** — 根据 Canvas 尺寸启发式推算终端行列数
+
+## 安装
+
+### 从源码安装（开发模式）
+
+```bash
+git clone <repo-url>
+cd cvm-vnc
+pip install -e .
+```
+
+`-e`（editable）模式会将当前源码目录链接为已安装包，修改代码后无需重新安装即可生效。
+
+### 从 PyPI 安装
+
+```bash
+pip install cvm-vnc
+```
+
+### 可选依赖
+
+```bash
+# dotenv 支持（从 .env 文件加载环境变量）
+pip install -e '.[dotenv]'
+```
+
+### 前置依赖
+
+需要系统中安装 [agent-browser](https://www.npmjs.com/package/agent-browser)（Node.js CLI 工具）：
+
+```bash
+npm install -g agent-browser
+```
+
+## 使用方式
+
+### CLI 命令
+
+```bash
+# 打开 VNC 页面
+cvm-vnc open <url> [--wait-ms MS] [--session NAME] [--headed]
+
+# 截取 VNC 屏幕
+cvm-vnc capture [output] [--session NAME] [--headed]
+
+# 发送文本输入
+cvm-vnc type <text> [--enter] [--session NAME] [--headed]
+
+# 批量顺序输入（避免 AI 思考间隙导致登录超时）
+cvm-vnc type-sequence --steps-json '<JSON>' [--mode MODE] [--session NAME]
+
+# 关闭浏览器会话
+cvm-vnc close [--session NAME]
+
+# 启动 MCP Server
+cvm-vnc mcp [--session-default NAME] [--mode-default MODE] [--headed]
+```
+
+也可通过独立入口直接启动 MCP Server：
+
+```bash
+cvm-vnc-mcp
+```
+
+### MCP Server Tools
+
+MCP Server 对外暴露以下工具：
+
+| 工具 | 说明 |
+|------|------|
+| `vnc_open(url, wait_ms, session)` | 打开 VNC 页面 |
+| `vnc_status(session)` | 检查页面状态（Canvas 元数据、登录检测等） |
+| `vnc_capture(output_path, session)` | 截取 Canvas 为 PNG |
+| `vnc_type(text, press_enter, session, mode)` | 发送文本输入 |
+| `vnc_type_sequence(steps, session, mode)` | 批量顺序输入（适合系统登录等需要连续输入的场景） |
+| `vnc_close(session)` | 关闭浏览器会话，释放资源 |
+
+### 示例
+
+```bash
+# 打开 VNC 并等待页面加载
+cvm-vnc open https://vnc.example.com --wait-ms 3000
+
+# 截图保存到文件
+cvm-vnc capture /tmp/screen.png
+
+# 执行命令
+cvm-vnc type "ls -la" --enter
+
+# 一次性完成系统登录（用户名 + 密码）
+cvm-vnc type-sequence --steps-json '[{"text":"root","press_enter":true,"wait_ms":500},{"text":"password","press_enter":true}]'
+
+# 关闭浏览器会话
+cvm-vnc close
+```
+
+## 项目结构
+
+```
+src/cvm_vnc/
+├── __init__.py        # 版本信息
+├── __main__.py        # CLI 入口
+└── vnc_browser.py     # 核心实现（浏览器控制、MCP Server、JS 注入脚本）
+```
+
+## MCP Server 配置
+
+安装完成后，可将 cvm-vnc 作为 MCP Server 接入 AI 客户端。
+
+### Claude Code
+
+```bash
+claude mcp add cvm-vnc -- cvm-vnc-mcp
+```
+
+添加后可通过以下命令验证：
+
+```bash
+claude mcp list
+```
+
+### Codebuddy
+
+```bash
+codebuddy mcp add cvm-vnc -- cvm-vnc-mcp
+```
+
+或手动编辑 `~/.codebuddy/settings.json`：
+
+```json
+{
+  "mcpServers": {
+    "cvm-vnc": {
+      "command": "cvm-vnc-mcp"
+    }
+  }
+}
+```
+
+> **提示**：如果 `cvm-vnc-mcp` 不在 PATH 中，需使用完整路径，例如 `/path/to/venv/bin/cvm-vnc-mcp`。
+
+## 配置
+
+| 环境变量 | 说明 | 默认值 |
+|----------|------|--------|
+| `AGENT_BROWSER_BIN` | agent-browser 可执行文件路径 | 自动查找 |
+| `LOCK_TIMEOUT` | 会话锁超时时间（秒） | 120 |
+
+## License
+
+MIT

cvm_vnc-0.1.9/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cvm-vnc"
+version = "0.1.9"
+description = "Tencent Cloud CVM VNC browser control via agent-browser with MCP server support"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "Curu"},
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dotenv = ["python-dotenv"]
+mcp = ["mcp[cli]>=1.0.0"]
+
+[project.scripts]
+cvm-vnc = "cvm_vnc.__main__:cli"
+cvm-vnc-mcp = "cvm_vnc.__main__:cli_mcp"
+
+[tool.setuptools.packages.find]
+where = ["src"]

cvm_vnc-0.1.9/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cvm_vnc-0.1.9/src/cvm_vnc/__init__.py

@@ -0,0 +1,7 @@
+"""CVM VNC package."""
+
+__version__ = "0.1.9"
+
+from cvm_vnc.vnc_browser import VncError
+
+__all__ = ["__version__", "VncError"]

cvm_vnc-0.1.9/src/cvm_vnc/__main__.py

@@ -0,0 +1,57 @@
+"""Allow running as `python -m cvm_vnc`."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from cvm_vnc.vnc_browser import MODE_PROFILES, load_dotenv_file, main, run_mcp_server
+
+
+def _parse_mcp_alias_args(argv: Sequence[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog=argv[0] if argv else "cvm-vnc-mcp",
+        description="Run a stdio MCP server for VNC browser control.",
+    )
+    parser.add_argument(
+        "--session",
+        help="agent-browser session name to reuse. Defaults to current agent-browser default session.",
+    )
+    parser.add_argument(
+        "--headed",
+        action="store_true",
+        help="run agent-browser in headed mode for commands that launch a browser",
+    )
+    parser.add_argument(
+        "--session-default",
+        default="vnc-mcp",
+        help="default agent-browser session name for MCP tools (default: vnc-mcp)",
+    )
+    parser.add_argument(
+        "--mode-default",
+        choices=tuple(MODE_PROFILES),
+        default="stable",
+        help="default timing profile for MCP tools (default: stable)",
+    )
+    return parser.parse_args(list(argv[1:]))
+
+
+def cli() -> None:
+    try:
+        main()
+    except KeyboardInterrupt:
+        sys.exit(130)
+
+
+def cli_mcp() -> None:
+    load_dotenv_file()
+    args = _parse_mcp_alias_args(sys.argv)
+    try:
+        run_mcp_server(args)
+    except KeyboardInterrupt:
+        sys.exit(130)
+
+
+if __name__ == "__main__":
+    cli()