marionette (Christopher J Miller)

木偶

用于Linux桌面窗口操作的模型上下文协议（MCP）服务器。Marionette允许AI助手与您的桌面窗口进行交互，非常适合游戏自动化、UI测试和交互式桌面应用程序。

特性

• 窗口发现：按标题或类别列出和筛选窗口
• 截图：捕获窗口内容以进行目视检查
• 输入模拟：通过ydotool键入文本并按键
• 窗口管理：聚焦、移动和调整窗口大小
• 稳定的引用：Windows被分配了稳定的引用（w0、w1、w2…），这些引用在调用之间持续存在
• X11和Wayland支持：适用于X11和XWayland应用程序

建筑

木偶用途：

• X11后端 （通过 x11rb)用于窗口枚举和管理
• X电容 用于跨平台截图
• Ydotool 适用于X11和Wayland的内核级输入模拟
• rmcp 用于在stdio上实现MCP协议

安装

使用镍片（推荐）

使用牵线木偶最简单的方法是直接从GitHub：

{
  "mcpServers": {
    "marionette": {
      "command": "nix",
      "args": ["--quiet", "run", "github:ChristopherJMiller/marionette"]
    }
  }
}

从源头构建

# Clone the repository
git clone https://github.com/ChristopherJMiller/marionette.git
cd marionette

# Build with Nix
nix build

# Or build with cargo in a nix shell
nix develop
cargo build --release

NixOS设置

木偶需要 ydotool 用于输入模拟。在NixOS上，将以下内容添加到您的配置中：

{
  # Enable ydotool system service
  programs.ydotool.enable = true;

  # Add your user to the ydotool group
  users.users.yourUsername = {
    extraGroups = [ "ydotool" ];
  };
}

添加以下内容后：

1. 跑 sudo nixos-rebuild switch
2. 注销并重新登录（或重新启动）
3. 通过以下方式进行验证： groups | grep ydotool

ydotool系统服务应自动运行。请检查： systemctl status ydotoold.service

用法

作为MCP服务器

将牵线木偶添加到MCP客户端配置中（例如，Claude Desktop的 .mcp.json):

{
  "mcpServers": {
    "marionette": {
      "command": "nix",
      "args": ["--quiet", "run", "github:ChristopherJMiller/marionette"]
    }
  }
}

或者使用本地构建：

{
  "mcpServers": {
    "marionette": {
      "command": "/path/to/marionette/target/release/marionette",
      "args": []
    }
  }
}

与MCP检查员一起进行测试

nix develop
npx @modelcontextprotocol/inspector target/debug/marionette

这将打开一个web界面，以交互方式测试所有工具。

使用Shell脚本进行测试

包含用于基本功能测试的测试脚本：

nix develop
./test_mcp.sh

可用工具

窗口列表

列出所有窗口及其引用和元数据。

参数：

• title_filter （可选）：按窗口标题筛选（子字符串匹配）
• class_filter （可选）：按窗口类/应用程序名称筛选

退货： 带有refs（w0、w1、w2…）、标题、类、几何图形和焦点状态的窗口数组。

windows_screenshot

捕获特定窗口的屏幕截图。

参数：

• ref （必填）：来自Window_list的窗口引用（例如“w0”）
• format （可选）：“base64”（默认）或“file”

退货： Base64编码的PNG图像或文件路径。

窗口快照

获取有关窗口当前状态的详细元数据。

参数：

• ref （必填）：窗口引用（例如“w0”）

退货： 窗口标题、类、几何图形、焦点状态、可见性和平台ID。

窗口类型

在当前聚焦的窗口中键入文本。

参数：

• text （必填）：要键入的文本
• delay_ms （可选）：按键之间的延迟（默认值：12ms）

窗口密钥

按一个键或组合键。

参数：

• key （必填）：键名（例如，“Return”、“Escape”、“a”、“F1”）
• modifiers （可选）：修饰符数组：“ctrl”、“alt”、“shift”、“super”

例子： 按Ctrl+C： {"key": "c", "modifiers": ["ctrl"]}

窗点击

在窗口内的坐标处单击。

参数：

• ref （必填）：窗口参考
• x, y （必填）：窗口内的坐标
• button （可选）：“左”（默认）、“右”或“中”
• description （可选）：点击内容的可读描述

窗口焦点

聚焦/激活窗口，将其置于前景。

参数：

• ref （必填）：窗口参考

窗口_移动

将窗口移动到新位置。

参数：

• ref （必填）：窗口参考
• x, y （必填）：屏幕坐标中的新位置

窗口大小

调整窗口大小。

参数：

• ref （必填）：窗口参考
• width, height （必填）：新的像素尺寸

工作流示例

1. List windows:
   → window_list()
   ← Returns: [{"ref": "w0", "title": "Terminal", ...}, ...]

2. Take a screenshot:
   → window_screenshot(ref: "w0")
   ← Returns: base64 PNG image

3. Type in the window:
   → window_type(text: "echo hello")

4. Press Enter:
   → window_key(key: "Return")

5. Take another screenshot to verify:
   → window_screenshot(ref: "w0")

技术细节

窗口注册表

Marionette维护着一个稳定的窗口注册表，该注册表根据窗口的平台ID为窗口分配引用（w0、w1、w2…）。这些引用在同一会话内的工具调用中持续存在。

输入定时

输入系统包括精心调整的延迟：

• 按键操作前延迟100ms（确保系统准备就绪）
• 按键向下和按键向上事件之间有50毫秒的延迟（防止错过按键）
• 鼠标移动和点击之间有10ms的延迟（确保位置精度）
• 可配置的打字延迟（默认每次按键12ms）

这些延迟防止了输入事件被丢弃或未正确注册的常见问题。

日志记录

所有日志记录都会进入stderr，以保持stdio MCP通道的干净。集 RUST_LOG=debug 用于详细的调试输出。

需求

• Linux X11或Wayland（XWayland用于游戏）
• Ydotool 系统服务正在运行（在NixOS上自动处理 programs.ydotool.enable = true)
• 用户必须在 ydotool 输入模拟组

用例

• 游戏自动化：使用AI助手控制游戏窗口
• 用户界面测试：桌面应用程序的自动化测试
• 桌面自动化：自动化重复的桌面任务
• 无障碍：在人工智能指导下构建自定义无障碍工具
• 屏幕录制机器人：创建可以查看应用程序并与之交互的机器人

许可证

麻省理工学院

贡献

欢迎投稿！该项目尚处于早期开发阶段，欢迎反馈。

故障排除

输入不起作用

• 验证ydotool服务是否正在运行： systemctl status ydotoold.service
• 检查您是否在ydotool组中： groups | grep ydotool
• 将自己添加到组后注销并重新登录

未找到窗口错误

• 跑 window_list 首先获取当前窗口引用
• 服务器重启后窗口引用发生变化
• 检查窗口是否为XWayland窗口（不是本地Wayland）

未捕获的屏幕截图

• 确保窗口可见且未最小化
• 检查xcap是否具有必要的权限
• 对于Wayland，一些合成师可能需要额外的权限