can-see

can-see

一个 MCP 服务，可让 AI Agent 通过虚拟终端和 PNG 截图来查看并交互终端/命令行应用。

专为 Claude Code 及任何兼容 MCP 的 Agent 打造。

为什么？

有些事情展示出来比描述起来更容易。在调试 TUI 应用、交互式命令行向导或任何具有可视化终端输出的内容时，can-see 可以让 Agent 看到你所看到的一切——颜色、布局、光标位置等。

工作原理

1. 启动在虚拟终端中运行命令行应用（node-pty + @xterm/headless）
2. 截取截图，将终端保存为 PNG 图像（通过 node-canvas 渲染）
3. 发送按键/文本与应用交互
4. 再次截取截图以查看结果
5. 完成后关闭会话

安装

npm install -g can-see

前置条件

can-see 依赖 node-canvas（Cairo）和 node-pty，需要进行原生编译。大多数系统需要：

• **Windows：**Visual Studio Build Tools（C++ 工作负载）——npm install --global windows-build-tools，或通过 Visual Studio Installer 安装
• **macOS：**Xcode 命令行工具——xcode-select --install
• Linux：sudo apt install build-essential libcairo2-dev libjpeg-dev libpango1.0-dev libgif-dev librsvg2-dev

配置

Claude Code

将以下内容添加到项目的 .mcp.json：

{
  "mcpServers": {
    "can-see": {
      "command": "npx",
      "args": ["-y", "can-see"]
    }
  }
}

或者，如果是全局安装：

{
  "mcpServers": {
    "can-see": {
      "command": "can-see"
    }
  }
}

其他 MCP 客户端

can-see 使用 stdio 传输。将 MCP 客户端指向 can-see 二进制文件或 npx -y can-see。

工具

工具	描述
launch	在虚拟终端中启动 CLI 应用。返回 sessionId。可选接受 env，用于设置环境变量。
screenshot	将终端截取为 PNG 图像。
screenshot_region	截取终端的特定矩形区域。
screenshot_text_region	在视口中查找文本，并将其周围区域截取为 PNG。
capture_baseline	保存终端状态快照，以便之后进行差异比较。
diff_screenshot	将当前状态与基准进行比较，并突出显示变更。
get_cell_info	查询指定单元格中的字符、颜色和属性。支持 compact 模式以减少输出。
read_text	将终端缓冲区作为纯文本读取。
read_scrollback	读取已滚动到可见视口上方的文本。
wait_for_text	等待指定文本出现在终端缓冲区中。
wait_for_idle	等待终端输出在指定时长内保持稳定。支持 stableMs，用于内容比较模式（适用于带计时器或旋转指示器的应用）；支持 excludeRows 忽略指定行；支持 excludePattern（正则表达式）排除动态行。
wait_for_color	等待指定颜色出现在某个位置。
wait_for_exit	等待进程退出，并返回其退出代码和信号。
start_recording	开始捕获帧，以制作动画 GIF。
stop_recording	停止录制，并返回带有元数据（frameCount、durationMs）的动画 GIF。如果 GIF 超过内联大小限制，则自动修剪帧数或保存到文件。
send_keys	发送按键（例如 Enter、Ctrl+C、['Down', 'Down', 'Enter']）。
send_text	在应用中输入一串文本。
get_process_status	获取进程状态，以区分“应用处于空闲状态”和“应用已退出”。返回 PID、运行状态和退出代码。
list_sessions	列出所有活动的终端会话。
close	终止应用并清理资源。完成后务必关闭。
close_all	一次性终止所有活动会话。适用于测试运行之间的清理。

支持的按键

Enter、Tab、Escape、Backspace、Space、Up、Down、Left、Right、Home、End、Delete、PageUp、PageDown、Ctrl+A 至 Ctrl+Z。

环境变量

变量	默认值	描述
DEFAULT_COLS	120	终端宽度（列数）
DEFAULT_ROWS	30	终端高度（行数）
IDLE_TIMEOUT_MS	300000	空闲会话在此毫秒数后自动关闭（5 分钟）

使用示例

通过 MCP 连接的 Agent：

Agent: I'll launch your app to see what's happening.
→ launch("node", ["app.js"])  → sessionId: "abc-123"

Agent: Let me wait for the app to start.
→ wait_for_text("abc-123", "Ready")  → Found "Ready" after 1200ms

Agent: Let me read the current output.
→ read_text("abc-123")  → "Welcome to MyApp\nReady\n> "

Agent: I can see the prompt. Let me select option 2.
→ send_keys("abc-123", ["Down", "Enter"])

Agent: Waiting for the screen to settle.
→ wait_for_idle("abc-123")  → Terminal idle for 520ms

Agent: Let me check the result.
→ screenshot("abc-123")  → [PNG image showing result]

Agent: Done, closing the session.
→ close("abc-123")

更新日志

0.5.0

新增工具：

• wait_for_exit — 等待进程退出，获取退出代码和信号
• close_all — 一次性终止所有活动会话
• get_process_status — 区分“应用处于空闲状态”和“应用已退出”
• screenshot_text_region — 在视口中查找文本，并截取其周围区域为 PNG

增强功能：

• launch 接受 env 参数，用于设置自定义环境变量
• wait_for_idle 在 stableMs 模式下支持使用 excludePattern（正则表达式）排除动态行
• stop_recording 返回 GIF 及其 frameCount 和 durationMs 元数据
• get_cell_info 支持 compact 选项以减少输出（仅包含 {char, fg, bold}）

错误修复：

• 修复了 wait_for_text 和 wait_for_color 的竞态条件：进程同时退出时，会遗漏最终缓冲区中存在的文本或颜色
• 为 wait_for_idle 添加了互斥验证，避免同时传入 stableMs 和 idleMs

许可证

MIT