内容
# vterm-mcp
允许 Claude 驱动和测试 TUI 应用程序的 MCP 服务器。在伪终端上创建一个子进程，将其输出通过 [libghostty-vt](https://crates.io/crates/libghostty-vt)（Ghostty 的无头终端引擎）处理，并提供工具来读取渲染的屏幕和发送按键。
## 工具
| 工具 | 用途 |
|---|---|
| `start_session` | 在 PTY 上创建一个子进程。返回 `{ session_id }`。 |
| `stop_session` | 杀死并回收子进程。 |
| `list_sessions` | 列出活跃的会话。 |
| `get_screen` | 获取当前视口的快照（文本行 + 光标，可选的每个单元格样式）。 |
| `send_keys` | 发送命名按键（`Enter`、`C-c`、`M-x`、`Up`、`F1`等）和/或原始文本。 |
| `wait_for_text` | 等待直到屏幕上出现子字符串或正则表达式。 |
## 构建
需要在 `PATH` 中安装 Zig 0.15.x（用于 `libghostty-vt-sys` 构建本地 VT 引擎）和 Rust ≥ 1.93。
```sh
cargo build --release
```
二进制文件位于 `target/release/vterm-mcp`。
## 在 Claude 代码中注册
在 `~/.claude.json` 中的 `mcpServers` 下添加：
```json
"vterm": { "command": "/绝对路径/to/target/release/vterm-mcp" }
```
## 按键表示法
`Enter Tab Esc Backspace Delete Up Down Left Right Home End PageUp PageDown Insert Space F1..F12`。前缀为 `C-`（ctrl）、`M-`（alt）、`S-`（shift）、`D-`/`Super-` — 可堆叠：`C-S-Home`。单个字符（`a`、`7`、`;`）也接受。
## 测试
```sh
cargo test --release
```
## 未来的工作
- **kitty 图形 / sixel 的图像检索。** libghostty-vt 0.1.x 解析这些序列并报告每行的“kitty 虚拟占位符”标志，但不通过其 C API 公开图像像素数据。Ghostty 1.4.0 跟踪添加缺少的图像 API — 参见 <https://github.com/ghostty-org/ghostty/milestone/12>。一旦可用，扩展 `get_screen` 以返回图像有效载荷而不是仅占位符标志。
