Metadata-Version: 2.4
Name: deepin-mcp
Version: 0.2.2
Summary: MCP server for Deepin desktop application automated testing via AT-SPI
Project-URL: Homepage, https://github.com/owncoral/deepin-mcp
Project-URL: Repository, https://github.com/owncoral/deepin-mcp
Project-URL: Issues, https://github.com/owncoral/deepin-mcp/issues
License: MIT
Keywords: at-spi,automation,deepin,mcp,testing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: fastmcp>=2.0
Requires-Dist: pillow>=10.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pygobject<3.51,>=3.42
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: ocr
Requires-Dist: paddleocr>=2.7; extra == 'ocr'
Requires-Dist: paddlepaddle>=2.5; extra == 'ocr'
Description-Content-Type: text/markdown

# 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 数据才能编译：

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

### 安装 uv（推荐）

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

# 或使用 pip
pip install uv
```

## Installation

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

# 或使用 pip
pip install deepin-mcp
```

## Usage

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

```bash
deepin-mcp
```

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

```bash
DEEPIN_MCP_TRANSPORT=http deepin-mcp
```

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

```bash
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 模式监听端口 |

### 运行测试用例

```yaml
# 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

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

# 运行测试
uv run pytest
```
