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
