deepin-mcp 0.3.0

MCP server for Deepin desktop application automated testing via AT-SPI

Deepin MCP

MCP (Model Context Protocol) 服务器，用于通过 AT-SPI 对 Deepin 桌面应用进行自动化测试。

Features

• AT-SPI 应用检测 — 自动发现运行中的桌面应用及其控件树
• UI 控件操作 — 通过 AT-SPI 对按钮、输入框、菜单等控件执行点击、输入等操作
• 菜单 Comb 操作 — 支持 DTK 主菜单和右键菜单的 hover-crawl 操作
• D-Bus 调用 — 直接通过 D-Bus 接口与应用交互
• 编排式测试 — 支持 YAML/JSON 格式的测试用例定义和执行
• 截图诊断 — 操作过程中自动截图辅助调试

Architecture

三层隔离架构：

层级	组件	职责
检测层	TreeWalker, MenuScanner, Monitor, Snapshot	只读的控件发现与状态监控
执行层	ElementActor, InputController, MenuOperator, DBusExecutor	精准的控件操作执行
编排层	Parser, Runner, Assertions	测试用例解析与执行编排

Prerequisites

• Python >= 3.10
• 桌面 Linux 环境（Deepin / UOS），依赖 AT-SPI 和 xdotool

系统依赖（必须先安装）

PyGObject 需要系统级头文件和 GIR 数据才能编译：

sudo apt install libgirepository1.0-dev gcc libcairo2-dev pkg-config python3-dev gir1.2-atspi-2.0

安装 uv（推荐）

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或使用 pip
pip install uv

Installation

# 使用 uv 安装（推荐）
uv tool install deepin-mcp

# 或使用 pip
pip install deepin-mcp

Usage

作为 MCP 服务器运行（stdio 模式，默认）

deepin-mcp

作为 MCP 服务器运行（HTTP 模式）

DEEPIN_MCP_TRANSPORT=http deepin-mcp

远程访问时可指定监听地址和端口：

DEEPIN_MCP_TRANSPORT=http DEEPIN_MCP_HOST=0.0.0.0 DEEPIN_MCP_PORT=8000 deepin-mcp

环境变量	默认值	说明
DEEPIN_MCP_TRANSPORT	stdio	传输模式，可选 stdio 或 http
DEEPIN_MCP_HOST	127.0.0.1	HTTP 模式监听地址，远程访问设为 0.0.0.0
DEEPIN_MCP_PORT	8000	HTTP 模式监听端口

运行测试用例

# test_case.yaml
name: "Calculator addition"
app: "deepin-calculator"
steps:
  - name: "Click 5"
    action: element_action
    selector: {name: "5"}
  - name: "Click +"
    action: element_action
    selector: {name: "+"}
  - name: "Click 3"
    action: element_action
    selector: {name: "3"}
  - name: "Click ="
    action: element_action
    selector: {name: "="}
  - name: "Verify result"
    assert:
      - type: element_text
        selector: {role: "text"}
        contains: "8"

Development

# 安装开发依赖
uv sync --group dev

# 运行测试
uv run pytest