dsapi-mcp-server

一个面向 Android 自动化的 MCP Server：通过 DirectScreenAPI 拉取屏幕帧，并提供点击、滑动、缩放、系统按键等能力。

特性

• 屏幕截图：返回 JPEG 图片和结构化元信息（分辨率、缩放比、frame_seq）。
• 手势控制：tap、long_press、swipe、drag_and_drop、zoom。
• 系统按键：system_nav、volume_up、volume_down。
• 坐标换算：自动把模型坐标映射回物理屏幕坐标，减少点位偏差。

项目结构

.
├── server.py          # MCP 工具注册与运行时编排
├── dsapi_client.py    # DirectScreenAPI 协议客户端（取帧/触控）
├── image_pipeline.py  # 图像处理（刻度绘制、缩放、JPEG 编码）
├── config.yaml        # 运行配置
└── requirements.txt   # Python 依赖

环境要求

• Python 3.10+
• Android 端已启动 DirectScreenAPI
• 本机可访问 UDS 文件（默认：DirectScreenAPI/artifacts/run/*.sock）

快速开始

1. 安装依赖：

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt

2. 检查 Socket 文件（按需修改 config.yaml）：

ls -l DirectScreenAPI/artifacts/run/dsapi*.sock

3. 启动服务：

python server.py

配置说明

默认读取同目录下 config.yaml，也可通过环境变量覆盖：

export DSAPI_MCP_CONFIG=/path/to/config.yaml

常用配置项：

• uds.data_socket：数据通道 socket 路径。
• timeouts.frame_wait_timeout_ms：单帧等待超时。
• image.max_long_edge：图片最长边，值越大越清晰（带宽/体积更高）。
• image.jpeg_quality：JPEG 质量（推荐 85~92）。
• image.jpeg_subsampling：色度子采样（0 清晰度最高）。
• image.enable_sharpen：是否启用锐化增强。
• image.axis_font_size：坐标字体大小（0 表示自动）。
• image.enable_axis：是否绘制边框刻度。
• system_control.use_su：是否通过 su -c input ... 发送系统按键。

路径解析规则：

• config.yaml 里的 uds.*socket 支持相对路径，服务会自动按 config.yaml 所在目录解析为绝对路径，避免受启动 cwd 影响。

客户端接入示例

Claude Desktop

在 Claude Desktop 的 MCP 配置文件中加入：

{
  "mcpServers": {
    "dsapi-mcp-server": {
      "command": "/path/to/dsapi-mcp-server/.venv/bin/python",
      "args": [
        "/path/to/dsapi-mcp-server/server.py"
      ],
      "env": {
        "DSAPI_MCP_CONFIG": "/path/to/dsapi-mcp-server/config.yaml"
      }
    }
  }
}

通用 stdio MCP 客户端

若客户端支持以命令启动 MCP Server，可使用：

/path/to/dsapi-mcp-server/.venv/bin/python /path/to/dsapi-mcp-server/server.py

并设置环境变量：

DSAPI_MCP_CONFIG=/path/to/dsapi-mcp-server/config.yaml

接入后验证

1. 在 MCP 客户端中刷新工具列表，确认出现 get_annotated_screen。
2. 调用 get_annotated_screen()，应返回一张图片和 status: ok 的结构化结果。
3. 再调用 tap(x, y) 做一次点击验证触控链路。

MCP 工具清单

• get_annotated_screen()：获取带坐标刻度的屏幕截图和元信息。
• tap(x, y)：单击。
• long_press(x, y, duration_ms=1000)：长按。
• swipe(start_x, start_y, end_x, end_y, duration_ms=300)：滑动。
• drag_and_drop(start_x, start_y, end_x, end_y, hold_ms=500, duration_ms=500)：拖拽。
• zoom(center_x, center_y, direction, distance=400, duration_ms=300)：双指缩放，direction 取 in/out。
• system_nav(action, repeat=1, interval_ms=80)：系统导航键，action 支持 back/home/recents。
• volume_up(steps=1, interval_ms=80)：音量增加。
• volume_down(steps=1, interval_ms=80)：音量减少。

常见问题

• touch_stream_handshake_*：通常是 uds.data_socket 路径不对，先确认 DirectScreenAPI 已启动。
• Permission denied（系统按键）：设备未授权 su 或不支持 root，改为 system_control.use_su: false 后重试。
• 截图超时：增大 timeouts.frame_wait_timeout_ms，并检查设备端是否持续产出帧。

许可证

本项目采用 MIT License。