egui MCP

egui mcp

MCP（模型上下文协议）服务器，使AI代理能够与egui GUI应用程序交互。

概述

egui mcp为以下对象提供UI自动化功能 egui 通过模型上下文协议的应用程序。它利用Linux的AT-SPI（辅助技术服务提供商接口）访问UI树，并将其暴露给任何兼容MCP的客户端。

特性

工作工具

\*对于组合框，检查name属性以确定是否选择了某些内容（返回0或1）。 \*\*这些工具要求元素首先具有焦点。使用 focus_element 在打电话之前。如果没有焦点，则返回-1。 \*\*\*需要egui应用程序呼叫 record_frame_auto()。参见 性能指标. \*\*\*\*需要将egui应用程序配置为 McpLogLayer。参见 日志访问.

不工作（限制）

以下工具已实施，但 不要工作 由于各种限制：

不需要的

以下工具已实现，但对egui没有用：

备注：参见 docs/egui-accessibility-investigation.md 对每个限制进行详细分析。

建筑

┌───────────────────────────────────────────────────────────────┐
│                    MCP Client (AI Agent)                      │
└───────────────────────────────────────────────────────────────┘
                              │
                              │ MCP Protocol (stdio)
                              ▼
┌───────────────────────────────────────────────────────────────┐
│                      egui-mcp-server                          │
│                                                               │
│  ┌─────────────────────┐      ┌─────────────────────┐         │
│  │   AT-SPI Client     │      │    IPC Client       │         │
│  │ (UI tree & actions) │      │   (screenshots)     │         │
│  └──────────┬──────────┘      └───────────┬─────────┘         │
└─────────────┼─────────────────────────────┼───────────────────┘
              │ D-Bus                       │ Unix Socket
              ▼                             ▼
┌─────────────────────────┐     ┌───────────────────────────────┐
│      AT-SPI Bus         │     │     egui-mcp-client           │
│  (org.a11y.atspi.*)     │     │  (embedded in egui app)       │
└─────────────────────────┘     └───────────────────────────────┘
              ▲                             ▲
              │ auto-publish                │ embedded
              │                             │
┌───────────────────────────────────────────────────────────────┐
│                      egui Application                         │
│           enable_accesskit() → AccessKit → AT-SPI             │
└───────────────────────────────────────────────────────────────┘

需求

• Linux （需要AT-SPI）
• 锈 1.85+（2024年版）

安装

来自crates.io（推荐）

cargo install egui-mcp-server

使用货仓（更快）

如果你有 货仓 安装后，您可以下载预构建的二进制文件：

cargo binstall egui-mcp-server

从源代码构建

git clone https://github.com/dijdzv/egui-mcp.git
cd egui-mcp
cargo build --release

服务器二进制文件将位于 target/release/egui-mcp-server.

用法

1.准备您的egui申请

添加 egui-mcp-client 要启用屏幕截图支持，请执行以下操作：

# Cargo.toml
[dependencies]
egui-mcp-client = { git = "https://github.com/dijdzv/egui-mcp.git" }

use egui_mcp_client::McpClient;

fn main() {
    let mcp_client = McpClient::new();

    // Start IPC server
    let runtime = tokio::runtime::Runtime::new().unwrap();
    let client_clone = mcp_client.clone();
    runtime.spawn(async move {
        egui_mcp_client::IpcServer::run(client_clone).await.ok();
    });

    // Run eframe app
    eframe::run_native("My App", options, Box::new(|cc| {
        // Enable AccessKit (publishes UI tree to AT-SPI)
        cc.egui_ctx.enable_accesskit();
        // ...
    }));
}

备注：呼叫 enable_accesskit() 通过AT-SPI自动发布UI树。无需手动导出。

2.配置MCP客户端

跑 egui-mcp-server guide 有关详细的设置说明，包括：

• MCP客户端配置(.mcp.json)
• 所需的环境变量
• 可用的MCP工具

# Show setup guide
egui-mcp-server guide

3.可用工具

连接后，以下MCP工具可用：

连接信息（&I）：

• ping -检查服务器是否正在运行
• check_connection -验证与egui应用程序的连接

UI树（AT-SPI）：

• get_ui_tree -以JSON格式获取完整的UI结构
• find_by_label -查找包含标签子字符串的元素
• find_by_label_exact -查找标签完全匹配的元素
• find_by_role -按角色查找元素（按钮、文本输入、复选框等）
• get_element -按ID获取元素详细信息

元素交互（AT-SPI）：

• click_element -按ID单击元素（AT-SPI操作）
• set_text -按ID设置文本输入的文本内容（AT-SPI可编辑文本）

基于坐标的输入（IPC）：

• click_at -点击特定坐标
• double_click -在特定坐标处双击
• hover -将鼠标移动到特定坐标
• drag -从点A拖动到点B
• keyboard_input -发送键盘输入
• scroll -在特定坐标处滚动

屏幕截图（IPC）：

• take_screenshot -捕获屏幕截图（返回ImageContent或保存到文件）

看 特性 适用于由于egui限制而无法工作的工具。

性能指标

启用性能指标(get_frame_stats, start_perf_recording, get_perf_report)，呼叫 record_frame_auto() 在egui应用程序的更新循环中：

impl eframe::App for MyApp {
    fn update(&mut self, ctx: &egui::Context, _frame: &mut eframe::Frame) {
        // ... your UI code ...

        // Record frame for performance metrics (1 line only!)
        self.runtime.block_on(self.mcp_client.record_frame_auto());
    }
}

日志访问

启用日志访问(get_logs, clear_logs)，配置 McpLogLayer 追踪：

use egui_mcp_client::{McpClient, McpLogLayer};
use tracing_subscriber::prelude::*;

fn main() {
    // Set up MCP log layer (captures logs for MCP access)
    let (mcp_layer, log_buffer) = McpLogLayer::new(1000); // Keep last 1000 entries

    tracing_subscriber::registry()
        .with(mcp_layer)                           // Capture logs for MCP
        .with(tracing_subscriber::fmt::layer())    // Also log to stdout
        .init();

    // Pass log buffer to MCP client
    let mcp_client = McpClient::new().with_log_buffer_sync(log_buffer);
    // ... run egui app
}

元素高亮显示

启用元素突出显示(highlight_element, clear_highlights)，呼叫 draw_highlights() 在更新循环结束时：

impl eframe::App for MyApp {
    fn update(&mut self, ctx: &egui::Context, _frame: &mut eframe::Frame) {
        // ... your UI code ...

        // Draw highlights at the end
        let highlights = self.runtime.block_on(self.mcp_client.get_highlights());
        egui_mcp_client::draw_highlights(ctx, &highlights);
    }
}

发展

设置

此项目使用 devenv:

cd egui-mcp
# direnv auto-loads the environment, or:
devenv shell

构建演示应用程序

演示应用程序需要额外的frame/egui（Wayland后端）系统依赖关系：

# Ubuntu/Debian
sudo apt-get install -y libwayland-dev libxkbcommon-dev

备注：这些是构建支持Wayland的egui/frame应用程序所必需的，而不是egui-mcp服务器本身。

命令

just check    # Run clippy and fmt check
just fmt      # Format code
just build    # Build all targets
just test     # Run tests
just demo     # Run demo egui app
just server   # Run MCP server

测试

1. 1号航站楼： just demo （启动演示应用程序）
2. 2号航站楼： just server （启动MCP服务器）
3. 连接任何MCP客户端

项目结构

egui-mcp/
├── crates/
│   ├── egui-mcp-server/    # MCP server binary
│   ├── egui-mcp-client/    # Library for egui apps
│   └── egui-mcp-protocol/  # Shared protocol definitions
├── examples/
│   └── demo-app/           # Demo egui application
├── devenv.nix              # Development environment
└── justfile                # Build commands

贡献

提交消息

此项目使用 约定式提交 用于自动版本控制。

# New feature (bumps minor version)
git commit -m "feat: add new tool"

# Bug fix (bumps patch version)
git commit -m "fix: correct calculation"

# Breaking change (bumps major version)
git commit -m "feat!: change API format"

发布过程

通过以下方式自动发布 释放plz:

1. 推至 main 触发自动发布PR创建
2. 合并发布PR以发布到crates.io

许可证

麻省理工学院或阿帕奇-2.0

相关

• egui -Rust的即时模式GUI库
• AccessKit -跨平台可访问性抽象
• 主控程序 -模型上下文协议
• AT-SPI -Linux可访问性接口