glovebox-mcp

# glovebox-mcp 一款**隔离的计算机使用MCP服务器** — 让AI代理驱动真实的浏览器和桌面应用程序（鼠标、键盘、截图、视觉基础），限定在**嵌套的X11窗口**中，因此它永远不会触及您的真实屏幕、文件或其他应用程序。 就像实验室中的**手套箱**：代理伸手并操纵真实的应用程序，与其他所有内容隔离。在该窗口内启动沙盒，登录您想要自动化的任意网站或应用程序，代理仅在那里操作 — 您可以实时观看并立即关闭它。 > 支持 [模型上下文协议](https://modelcontextprotocol.io)，因此它与MCP客户端（如Claude Code）一起工作。您的主机可以运行Wayland；沙盒为代理提供一个真实的X服务器来驱动。  _{代理在沙盒中驱动真实的浏览器 — 移动光标、插入unicode名称（`Nadja Kovačič`）、输入和提交。所有操作都限定在嵌套的X11窗口中。} ## 为什么使用嵌套的X11沙盒？ - 大多数桌面自动化（xdotool、PyAutoGUI）**仅限于X11**，但许多现代桌面运行 **Wayland**。 - **Xephyr** 在单个窗口内提供一个真实的X服务器（`DISPLAY :1`）。代理执行的所有操作 — 点击、输入、截图 — **都限定在该窗口中**，而不是您的真实桌面。 - 您保持控制：实时观看，`pkill Xephyr` 关闭所有内容。 ## 要求 - **Linux** — 沙盒嵌套一个真实的X服务器（Xephyr），因此它甚至可以在 **Wayland** 主机上运行（通过Xwayland）。不支持macOS/Windows。在Ubuntu上开发；任何具有以下软件包的现代Linux都可以使用。 - **Python 3.10+** 和 [`uv`](https://docs.astral.sh/uv/) （用于虚拟环境）。 - **系统软件包** — `xserver-xephyr`（Xephyr）、`openbox`、`scrot`、`x11-utils`、`xdotool`、`wmctrl`、`xclip`（+ `tesseract-ocr` 用于 `basic`）。在Debian/Ubuntu上，安装程序通过`apt`（sudo）**自动安装**它们；在Fedora/Arch上，它打印匹配的`dnf`/`pacman`命令。MCP服务器本身是与发行版无关的 — 任何具有这些工具的Linux都可以使用。 - 沙盒中的一个 **浏览器** （Chromium或Chrome）。 - **NVIDIA GPU（≥6 GB VRAM）** — 仅用于 `local` 视觉模式。 ## 安装 选择一个视觉后端并运行其一键安装程序（克隆 → 安装）。每个安装程序都安装系统软件包（在Debian/Ubuntu上通过`apt`自动安装）和该模式的Python依赖项，并编写一个准备好的`mcp-config.json`，包含您的路径。 **`none`** — 无本地模型；您的代理读取截图（最轻量级，立即）: ```bash git clone https://github.com/segentic-lab/glovebox-mcp && cd glovebox-mcp && ./install.sh none ``` **`basic`** — Tesseract OCR基础（`parse_screen` → 文本 + 坐标，仅限CPU）: ```bash git clone https://github.com/segentic-lab/glovebox-mcp && cd glovebox-mcp && ./install.sh basic ``` **`local`** — NVIDIA GPU上的OmniParser（`parse_screen` → 文本 **+ 图标**，精确到像素；约4 GB权重，≥6 GB VRAM）: ```bash git clone https://github.com/segentic-lab/glovebox-mcp && cd glovebox-mcp && ./install.sh local ``` 您的选择写入 `.vision-mode` （通过 `GLOVEBOX_VISION` 环境变量覆盖每次运行）。 ### 与任何MCP客户端/框架兼容 Claude Code、Cursor、Codex 或您自己的代理 — 它是一个标准的MCP服务器，不绑定到任何主机。两个兼容性注意事项： **`basic`/`local`** 返回元素 **坐标为文本**，因此它们甚至可以与仅限文本的代理一起工作； **`none`** 依赖客户端将工具的 **截图** 传递给多模态模型（适用于Claude Code、Cursor和其他具有图像能力的MCP客户端）。 ## 快速入门 1. **启动沙盒** （保持运行）： ```bash ./start-display.sh # 1440×900 Xephyr 窗口，带有一个浏览器 ./start-display.sh 1920x1080 # … 或传递屏幕大小（或设置 $RES） ``` 在 **该窗口中** 登录您想要自动化的任意网站或应用程序。 2. **将服务器注册** 到您的MCP客户端。`install.sh` 已经编写了 **`mcp-config.json`**，包含您的实际安装路径 — 将其 `glovebox` 块复制到客户端的MCP配置中： ```jsonc { "mcpServers": { "glovebox": { "command": "/abs/path/to/glovebox-mcp/.venv/bin/python", // 由 install.sh 填充 "args": ["/abs/path/to/glovebox-mcp/server.py"], "env": { "DISPLAY": ":1" } } } } ``` 重启客户端使其加载服务器。 3. 请求代理截图 / 点击 / 输入 — 它 **仅在** `:1` 窗口上操作。 > **用AI代理驱动它？** 将 [`AGENTS.md`](AGENTS.md) 粘贴到代理的系统提示中 — 它教会观察 → 动作 → 验证循环、基础、上传/ unicode陷阱和何时停止。 ## 工具 | 工具 | 功能 | |---|---| | `parse_screen()` | 视觉基础 → 每个元素的JSON（id、type、label、interactive、像素中心）+ 在`/tmp/glovebox_annotated.png`处的带编号的标记图像集。（`local`模式：GPU上的OmniParser，约2秒。） | | `click_element(id)` | 点击上一次`parse_screen`中的元素（无需坐标猜测）。 | | `screenshot()` | 实例的截图。 | | `click(x,y)` · `move_mouse` · `scroll` · `drag` · `double_click` | 指针操作。 | | `type_text(text)` | **Unicode安全** 输入（ASCII通过xdotool；带有č/š/ž…的任何内容通过剪贴板插入，因为xdotool的合成unicode被某些GTK应用程序静默丢弃）。 | | `press_keys("ctrl+a"/"Return"/…)` | 键/组合键（xdotool语法）。 | | `upload_file(filepath, selector?)` | 通过 **Chrome DevTools协议** 将本地文件附加到页面的`<input type=file>`。嵌套的X11文件选择器对自动化 **不可见** 并且会挂起渲染器，因此请为所有上传使用此功能 — 永远不要点击上传按钮期望对话框。对于通过`launch_app`/`start-display.sh`启动的Chromium（它们打开一个实例特定的 `--remote-debugging-port`，`9222+N`）。 **仅限浏览器文件输入** — 对于本地应用程序，请参见 `open_file`。 | | `open_file(filepath, app?)` | 在实例的显示上，在 **本地** 应用程序中打开本地文件（例如 `app="gimp"`）或通过 `xdg-open`。GTK应用程序获得与 `launch_app` 相同的X11/D-Bus处理。 | | `list_files()` | 实例的暂存文件夹 `files/<N>/` （在安装目录下）+ 其内容。 | | `launch_app(command, name?, size?)` · `list_instances()` · `close_instance(n)` | 多实例控制（见下文）。 | | `wait_ms(ms)` · `get_screen_size()` | 计时 / 沙盒大小。 | 每个控制工具都接受 **`instance=N`** 和可选的 **`observe`** / **`settle_ms`** （见下文）。在 `local` 模式下，OmniParser在第一次 `parse_screen` 时 **延迟加载** （约6秒，然后约2秒/解析）。 ### 视觉后端（可选） `GLOVEBOX_VISION` 环境变量，或 `.vision-mode` 文件，或默认 `local`: | 模式 | `parse_screen` | 需要 | 何时 | |---|---|---|---| | `none` | 禁用（返回备注） — 使用 `screenshot()` + 原因 | 无（mcp、mss、xdotool） | 最轻量级；让代理的自身视觉进行基础 | | `basic` | Tesseract OCR → 文本元素 + 坐标 | `tesseract-ocr` + `pytesseract` | 无GPU；仅限文本基础 | | `local` | OmniParser → 文本 **+ 图标** + 坐标 | torch + CUDA + OmniParser权重 | 最佳基础 | 随时使用 `./install.sh <mode>` 切换（仅安装该模式所需的内容）。 ### 多实例（多个应用程序窗口） 每个控制工具都接受 **`instance=N`** （默认为1，即 `start-display.sh` 沙盒）。启动更多 — 每个都有自己的Xephyr显示/窗口在主机桌面上： - `launch_app(command, name?, size?)` → 启动下一个可用的 `:N` 运行 **任意** GUI应用程序（`chromium`、`gimp`、`inkscape`、`xterm`，...）。Chromium自动获取X11标志、实例特定的配置文件、远程调试端口和D-Bus隔离。返回实例ID。 - `list_instances()` · `close_instance(n)`。 因为每个显示都有其 **自己的光标**，所以多个代理可以 **并行** 驱动不同的实例 — 每个窗口一个。只有 `local` 模式下的 `parse_screen` 的GPU是共享的（它只是排队）。新窗口的主机显示为 `GLOVEBOX_HOST_DISPLAY` （默认为 `:0`）；`XAUTHORITY` 自动发现。 ### 一键操作 + 观察 `click` · `click_element` · `type_text` · `press_keys` · `scroll` · `drag` · `double_click` 接受 **观察**（默认为 `none` · `screenshot` · `parse`）和 **`settle_ms`**。使用 `observe="screenshot"`，操作返回其结果 **和** 生成的屏幕，单次调用（带有 `settle_ms` 以便页面更新首先）— 无需单独的截图往返。默认 `none` 保持例行步骤廉价；选择 `screenshot`/`parse` 在更改页面的步骤（导航、提交）。 ### 文件和上传 每个实例都获得一个暂存文件夹 **`files/<N>/`**，位于安装目录下 — 一个稳定的位置，用于为该实例放置文件（可被本地应用程序和snap Chromium读取）。`list_files(instance)` 显示文件夹及其内容。 - **浏览器** `<input type=file>` → **`upload_file(path, instance)`** （通过CDP）。嵌套的文件选择器对自动化 **不可见** 并且会挂起snap Chromium，因此永远不要点击上传按钮期望对话框。 - **本地应用程序** （GIMP、Inkscape、编辑器）→ **`open_file(path, instance, app="gimp")`**，或仅驱动应用程序自己的 **打开对话框** — 与浏览器的不同，它是一个真实的可视窗口，您可以在其中输入路径（GTK文件选择器中的`Ctrl+L`）。 - **保存/下载** → 应用程序以您的用户身份运行，因此它们可以保存到您可以写入的任何地方。启动的Chromium实例预配置为 **下载并“保存为”到 `files/<N>/`**；将本地应用程序的保存对话框指向那里，然后 `list_files(instance)` 查看结果。 ## 维护（`local` 模式） `install.sh` 克隆 [OmniParser](https://github.com/microsoft/OmniParser)，下载v2权重，并自动应用两个补丁： - **可选PaddleOCR** （使用easyocr）：`OmniParser/util/utils.py`中的 `from paddleocr import PaddleOCR` 被包装在try/except中，模块级别的 `paddle_ocr = PaddleOCR(...)` 被保护为 `… if PaddleOCR is not None else None`。 - **`transformers` 固定为4.49.0** — 较新的版本会破坏Florence-2的远程配置。 如果您手动升级OmniParser，请重新应用PaddleOCR补丁。权重存储在 `OmniParser/weights/` 中。 ## 停止 ```bash pkill Xephyr # 关闭沙盒（浏览器 + 窗口管理器 + 显示） ``` ## 安全 - 代理的输入和视觉 **仅限于沙盒显示** — 它看不到或控制您的真实桌面。 - 服务器进程以您的用户身份运行（shell/文件访问权限，如任何MCP服务器）；只有其 **GUI控制** 被沙盒化到Xephyr窗口。对于文件的安全隔离，请在VM或容器中运行它。 - 您可以实时观看所有内容，并在 `pkill Xephyr` 时立即关闭它。 - 自动化操作需谨慎 — 仅限您有权使用的网站和服务。 ## 文件 - `server.py` — MCP服务器（所有工具）。 - `install.sh` — 模式感知安装程序（`none` / `basic` / `local`）。 - `start-display.sh` — 启动Xephyr沙盒（显示 + 窗口管理器 + 浏览器）。 - `AGENTS.md` — AI代理的插入式工具使用说明（粘贴到其系统提示中）。 - `mcp-config.json` — 一个可以直接粘贴的MCP客户端配置片段。 ## 致谢 `local` 视觉模式使用微软的 [OmniParser](https://github.com/microsoft/OmniParser) （由 `install.sh` 克隆和下载权重，在其自己的许可下）。屏幕捕获使用 [mss](https://github.com/BoboTiG/python-mss)；输入由 [xdotool](https://github.com/jordansissel/xdotool) 驱动。与微软无关。 ## 贡献 在 **MIT** 许可下发布 **原样**。欢迎提出问题和拉取请求，但由一人维护 — **不保证支持或响应时间**。如果它对您有用，⭐ 帮助。 ## 许可 MIT — 见 [LICENSE](LICENSE)。