### Install MaaMCP using uv

Source: https://github.com/maa-ai/maamcp/blob/main/README.md

Recommended installation method using uv. Ensure uv is installed first.

```bash
uvx maa-mcp
```

--------------------------------

### Install MaaMCP from source

Source: https://context7.com/maa-ai/maamcp/llms.txt

Installs MaaMCP by cloning the repository and installing from source using pip.

```bash
git clone https://github.com/MistEO/MaaMCP.git
cd MaaMCP
pip install -e .
```

--------------------------------

### Install MaaMCP using pip

Source: https://github.com/maa-ai/maamcp/blob/main/README.md

Standard installation method using pip.

```bash
pip install maa-mcp
```

--------------------------------

### Install Dependencies

Source: https://github.com/maa-ai/maamcp/blob/main/CLAUDE_CN.md

Install project dependencies in development mode. This command is used to set up the project for local development.

```bash
pip install -e .
```

--------------------------------

### start_pipeline

Source: https://context7.com/maa-ai/maamcp/llms.txt

Starts a background pipeline thread for continuous device screenshotting and OCR processing, caching results in a message queue. Only one pipeline instance can run at a time. Requires the `maa-mcp-server` to be started in pipeline mode.

```APIDOC
## start_pipeline

### Description
Starts a background thread to continuously capture screenshots of the device and perform OCR, caching the results in a message queue. Only one pipeline instance can run at a time. **Requires the pipeline mode server** (`maa-mcp-server`) to be started.

### Parameters
- **controller_id** (string) - Required - The identifier of the controller.
- **fps** (float) - Optional - The frames per second for screenshotting. Defaults to 2.0.

### Request Example
```python
# Start with default 2 FPS
result = start_pipeline(controller_id=controller_id)
# Success returns "✅ Pipeline started (Thread: PipelineThread-xxx)"
# Failure returns "❌ Failed to start pipeline: ..."
# Already running returns "⚠️ Pipeline is already running"

# Customize frame rate (screenshots per second)
result = start_pipeline(controller_id=controller_id, fps=5.0)
```
```

--------------------------------

### Start Pipeline Monitoring

Source: https://github.com/maa-ai/maamcp/blob/main/README.md

Initiates background monitoring using the pipeline mode, continuously capturing screenshots and caching their paths.

```text
start_pipeline(controller_id)
```

--------------------------------

### Clone MaaMCP Repository

Source: https://github.com/maa-ai/maamcp/blob/main/README.md

Clone the MaaMCP repository from GitHub to install from source.

```bash
git clone https://github.com/MistEO/MaaMCP.git
cd MaaMCP
```

--------------------------------

### run_pipeline

Source: https://context7.com/maa-ai/maamcp/llms.txt

Loads and executes a Pipeline JSON file, returning a dictionary with execution status and node details. Ensure the device is on the starting screen for the Pipeline entry point before running.

```APIDOC
## `run_pipeline` — 运行 Pipeline

Loads and executes a Pipeline JSON file, returning a dictionary with execution status and node details. **Ensure the device is on the starting screen for the Pipeline entry point before running.**

### Parameters
#### Path Parameters
- **controller_id** (str) - Required - The ID of the controller.
- **pipeline_path** (str) - Required - The path to the Pipeline JSON file.

#### Optional Parameters
- **entry** (str) - Optional - The entry node name. If not specified, the first node in the Pipeline is used.
- **resource_path** (str) - Optional - Specifies a custom resource directory.

### Request Example
```python
result = run_pipeline(
    controller_id=controller_id,
    pipeline_path="/home/user/.local/share/MaaMCP/pipelines/adjust_brightness_20250615_143025.json",
    # entry="Start Task",       # Optional, defaults to the first node
    # resource_path="/path/to/custom/resource",  # Optional, specify external resource directory
)

if isinstance(result, str):
    print(f"Failed to run: {result}")
else:
    print(f"Task ID: {result['task_id']}")
    print(f"Entry node: {result['entry']}")
    print(f"Execution status: {result['status']}")      # "succeeded" | "failed" | "running" | "pending" | "done"
    print(f"Number of executed nodes: {result['node_count']}")

    # Check recognition results
    for node in result.get("nodes", []):
        rec = node.get("recognition", {})
        all_results = rec.get("all_results", [])
        if all_results:
            print(f"Node [{node['name']}] recognized successfully: {all_results[0]}")
            # all_results[0] example: {"box": [100, 200, 50, 30], "score": 0.998}
        else:
            print(f"Node [{node['name']}] recognition failed")

# Example of iterative optimization on recognition failure
if result.get("status") == "failed":
    # Analyze the failed node, adjust ROI or relax OCR matching conditions, re-save, and run again
    pass
```

### Response
#### Success Response (dict)
- Returns a dictionary containing:
  - **task_id** (str): The ID of the executed task.
  - **entry** (str): The entry node of the pipeline.
  - **status** (str): The execution status ("succeeded", "failed", "running", "pending", "done").
  - **node_count** (int): The number of nodes executed.
  - **nodes** (list): A list of dictionaries, each representing a node with its details, including recognition results if available.

#### Error Response (str)
- Returns an error message string if the pipeline fails to run.
```

--------------------------------

### Run MaaMCP Pipeline Server

Source: https://github.com/maa-ai/maamcp/blob/main/README.md

Run the MaaMCP pipeline server for multi-threaded background monitoring. This can be done after installing the package or from source.

```bash
# Already installed package
maa-mcp-server

# Development run from source
python -m maa_mcp.pipeline_server
```

--------------------------------

### Run MaaMCP Standard Server

Source: https://github.com/maa-ai/maamcp/blob/main/README.md

Run the standard MaaMCP server in serial mode. This can be done after installing the package or from source.

```bash
# Already installed package
maa-mcp

# Development run from source
python -m maa_mcp
```

--------------------------------

### Start Background Pipeline

Source: https://context7.com/maa-ai/maamcp/llms.txt

Initiates a background thread for continuous screen capture and OCR processing, storing results in a message queue. Only one pipeline instance can run at a time. Requires the `maa-mcp-server` to be running.

```python
# 以默认 2 FPS 启动
result = start_pipeline(controller_id=controller_id)
# 成功返回 "✅ 流水线已启动 (Thread: PipelineThread-xxx)"
# 失败返回 "❌ 启动流水线失败: ..."
# 已在运行 "⚠️ 流水线已经在运行中"

# 自定义帧率（每秒截图次数）
result = start_pipeline(controller_id=controller_id, fps=5.0)
```

--------------------------------

### Example MaaFramework Pipeline JSON Output

Source: https://github.com/maa-ai/maamcp/blob/main/README.md

This JSON structure represents a generated pipeline. Each key is a step name, defining recognition methods, actions, and the next steps in the sequence.

```json
{
  "开始任务": {
    "recognition": "DirectHit",
    "action": "DoNothing",
    "next": ["点击设置"]
  },
  "点击设置": {
    "recognition": "OCR",
    "expected": "设置",
    "action": "Click",
    "next": ["进入显示"]
  },
  "进入显示": {
    "recognition": "OCR",
    "expected": "显示",
    "action": "Click",
    "next": ["调整亮度"]
  },
  "调整亮度": {
    "recognition": "OCR",
    "expected": "亮度",
    "action": "Swipe",
    "begin": [200, 500],
    "end": [400, 500],
    "duration": 200
  }
}
```

--------------------------------

### Run Pipeline JSON

Source: https://context7.com/maa-ai/maamcp/llms.txt

Executes a Pipeline JSON file, returning execution status and node details. Ensure the device is on the starting interface for the pipeline before running.

```python
result = run_pipeline(
    controller_id=controller_id,
    pipeline_path="/home/user/.local/share/MaaMCP/pipelines/调整亮度_20250615_143025.json",
    # entry="开始任务",       # 可选，不指定则使用 Pipeline 第一个节点
    # resource_path="/path/to/custom/resource",  # 可选，指定外部资源目录
)

if isinstance(result, str):
    print(f"运行失败: {result}")
else:
    print(f"任务 ID: {result['task_id']}")
    print(f"入口节点: {result['entry']}")
    print(f"执行状态: {result['status']}")      # "succeeded" | "failed" | "running" | "pending" | "done"
    print(f"执行节点数: {result['node_count']}")

    # 检查识别结果
    for node in result.get("nodes", []):
        rec = node.get("recognition", {})
        all_results = rec.get("all_results", [])
        if all_results:
            print(f"节点 [{node['name']}] 识别成功：{all_results[0]}")
            # all_results[0] 示例：{"box": [100, 200, 50, 30], "score": 0.998}
        else:
            print(f"节点 [{node['name']}] 识别失败")

# 识别失败时的迭代优化示例
if result.get("status") == "failed":
    # 分析失败节点，调整 ROI 或放宽 OCR 匹配条件，重新保存后再次运行
    pass
```

--------------------------------

### Get Pipeline Protocol Documentation

Source: https://context7.com/maa-ai/maamcp/llms.txt

Fetches the complete specification document for the MaaFramework Pipeline protocol. This includes details on recognition algorithms, action types, parameters, and best practices. It is recommended to call this tool before generating Pipeline JSON.

```python
doc = get_pipeline_protocol()
# 返回完整的 Markdown 格式协议文档，内容包括：
# - 识别算法：DirectHit、OCR、TemplateMatch、ColorMatch
# - 动作类型：Click、Swipe、Scroll、InputText、ClickKey、LongPress、StartApp/StopApp
# - 通用属性：next、post_delay
# - 完整示例和最佳实践
print(doc)
```

--------------------------------

### Get New Pipeline Messages

Source: https://github.com/maa-ai/maamcp/blob/main/README.md

Retrieves newly cached screenshot paths from the pipeline's background monitoring.

```text
get_new_messages()
```

--------------------------------

### swipe

Source: https://context7.com/maa-ai/maamcp/llms.txt

Simulates a swipe gesture from a starting point to an ending point. This method is preferred for scrolling or page turning on Android devices. For Windows, use the `scroll` method.

```APIDOC
## swipe

### Description
Simulates a swipe gesture from a starting point to an ending point. This method is preferred for scrolling or page turning on Android devices. For Windows, use the `scroll` method.

### Method
Python Function

### Endpoint
N/A

### Parameters
#### Path Parameters
- **controller_id** (str) - Required - The ID of the controller for the target device or window.
- **start_x** (int) - Required - The starting X-coordinate of the swipe.
- **start_y** (int) - Required - The starting Y-coordinate of the swipe.
- **end_x** (int) - Required - The ending X-coordinate of the swipe.
- **end_y** (int) - Required - The ending Y-coordinate of the swipe.
- **duration** (int) - Optional - The duration of the swipe in milliseconds. A longer duration results in a slower swipe, recommended for page turns (e.g., 3000ms). A shorter duration is suitable for quick swipes (e.g., 1500ms).

### Request Example
```python
# Android page up swipe (slow, duration=3000 recommended)
success = swipe(
    controller_id,
    start_x=360, start_y=800,
    end_x=360,   end_y=200,
    duration=3000,  # Slow swipe, suitable for page turns
)

# Quick swipe (duration=1500 recommended)
success = swipe(
    controller_id,
    start_x=360, start_y=500,
    end_x=100,   end_y=500,
    duration=1500,
)

print("Operation successful" if success else "Operation failed")
```

### Response
#### Success Response
- `success` (bool) - True if the swipe operation was successful, False otherwise.

#### Response Example
```json
true
```
```

--------------------------------

### Get Current Date and Time

Source: https://context7.com/maa-ai/maamcp/llms.txt

Retrieves the current system date and time as a formatted string (YYYY-MM-DD HH:MM:SS). This function helps ensure accurate time references in automated tasks.

```python
now = get_current_datetime()
# 返回示例："2025-06-15 14:30:25"
```

--------------------------------

### Perform Swipe Gesture

Source: https://context7.com/maa-ai/maamcp/llms.txt

Simulates a swipe gesture from a start point to an end point. Primarily used for scrolling or page turning on Android devices. Duration controls the speed of the swipe.

```python
# Android 向上滑动翻页（慢速，duration=3000 推荐）
success = swipe(
    controller_id,
    start_x=360, start_y=800,
    end_x=360,   end_y=200,
    duration=3000,  # 慢速滑动，适合翻页
)

# 快速滑动（duration=1500 推荐）
success = swipe(
    controller_id,
    start_x=360, start_y=500,
    end_x=100,   end_y=500,
    duration=1500,
)
```

--------------------------------

### connect_window

Source: https://context7.com/maa-ai/maamcp/llms.txt

Establishes a connection with the specified Windows window, returning a `controller_id`. Supports configuring screenshot, mouse, and keyboard methods. Defaults to background mode (`FramePool` + `PostMessage`) which does not interfere with mouse and keyboard input. Screenshot resolution defaults to 1080p on the shorter side.

```APIDOC
## connect_window

### Description
Establishes a connection with the specified Windows window, returning a `controller_id`. Supports configuring screenshot, mouse, and keyboard methods. Defaults to background mode (`FramePool` + `PostMessage`) which does not interfere with mouse and keyboard input. Screenshot resolution defaults to 1080p on the shorter side.

### Method
Python Function

### Endpoint
N/A

### Parameters
#### Path Parameters
- **window_name** (str) - Required - The name of the Windows window to connect to.
- **screencap_method** (str) - Optional - The method for taking screenshots. Options: `FramePool`, `PrintWindow`, `GDI`, `DXGI_DesktopDup_Window`, `ScreenDC`, `DXGI_DesktopDup`. Defaults to `FramePool`.
- **mouse_method** (str) - Optional - The method for mouse input. Options: `PostMessage`, `PostMessageWithCursorPos`, `Seize`. Defaults to `PostMessage`.
- **keyboard_method** (str) - Optional - The method for keyboard input. Options: `PostMessage`, `Seize`. Defaults to `PostMessage`.

### Request Example
```python
# Default background mode connection (recommended)
controller_id = connect_window(window_name="Notepad")

# Attempting other methods if default fails
controller_id = connect_window(
    window_name="Notepad",
    screencap_method="PrintWindow",
    mouse_method="PostMessage",
    keyboard_method="PostMessage",
)

# Using 'Seize' mode for keyboard shortcuts
ctrl_seize = connect_window(
    window_name="Notepad",
    keyboard_method="Seize",
)

# Returns a string like "ctrl_xyz789" on success, or None on failure.
```

### Response
#### Success Response
- `controller_id` (str) - A unique identifier for the established connection.

#### Response Example
```json
"ctrl_xyz789"
```
```

--------------------------------

### connect_adb_device

Source: https://context7.com/maa-ai/maamcp/llms.txt

Establishes a connection with the specified ADB device, creates a controller instance, and registers it. Returns a `controller_id` string for subsequent operations. The screenshot resolution defaults to 720p on the shorter side.

```APIDOC
## connect_adb_device

### Description
Establishes a connection with the specified ADB device, creates a controller instance, and registers it. Returns a `controller_id` string for subsequent operations. The screenshot resolution defaults to 720p on the shorter side.

### Method
Python Function

### Endpoint
N/A

### Parameters
#### Path Parameters
- **device_name** (str) - Required - The name of the ADB device to connect to.

### Request Example
```python
controller_id = connect_adb_device(device_name="emulator-5554")
# Returns a string like "ctrl_abc123" on success, or None on failure.
```

### Response
#### Success Response
- `controller_id` (str) - A unique identifier for the established connection.

#### Response Example
```json
"ctrl_abc123"
```
```

--------------------------------

### Connect to Windows Window (Custom Methods)

Source: https://context7.com/maa-ai/maamcp/llms.txt

Connects to a specified Windows window, allowing customization of screenshot, mouse, and keyboard methods. Use 'Seize' for keyboard methods if keyboard shortcuts are needed.

```python
# 若默认截图方式不可用，可尝试其他方式
controller_id = connect_window(
    window_name="记事本",
    screencap_method="PrintWindow",   # 可选: FramePool, PrintWindow, GDI, DXGI_DesktopDup_Window, ScreenDC, DXGI_DesktopDup
    mouse_method="PostMessage",        # 可选: PostMessage, PostMessageWithCursorPos, Seize
    keyboard_method="PostMessage",     # 可选: PostMessage, Seize
)

# 需要键盘快捷键时必须使用 Seize 模式
ctrl_seize = connect_window(
    window_name="记事本",
    keyboard_method="Seize",
)

if controller_id is None:
    print("连接失败，请检查窗口是否存在且未最小化")
```

--------------------------------

### Connect to Windows Window (Default)

Source: https://context7.com/maa-ai/maamcp/llms.txt

Connects to a specified Windows window using default background methods (FramePool + PostMessage) for screenshots and input, which do not steal focus. Default screenshot resolution has a short side of 1080p.

```python
# 默认后台模式连接（推荐）
controller_id = connect_window(window_name="记事本")

if controller_id is None:
    print("连接失败，请检查窗口是否存在且未最小化")
```

--------------------------------

### Connect to ADB Device

Source: https://context7.com/maa-ai/maamcp/llms.txt

Establishes a connection to a specified ADB device and returns a controller ID. The default screenshot resolution has a short side of 720p.

```python
# 需先通过 find_adb_device_list() 获得设备名
controller_id = connect_adb_device(device_name="emulator-5554")

# 成功返回类似 "ctrl_abc123" 的字符串，失败返回 None

if controller_id is None:
    print("连接失败，请检查 ADB 是否正常")
else:
    print(f"连接成功，控制器 ID: {controller_id}")
```

--------------------------------

### Run MCP Server (Standard Serial Mode)

Source: https://github.com/maa-ai/maamcp/blob/main/CLAUDE_CN.md

Execute the standard MCP server. This can be run directly as a command or through the Python module.

```bash
maa-mcp
# or
python -m maa_mcp
```

--------------------------------

### Simulate Text Input

Source: https://context7.com/maa-ai/maamcp/llms.txt

Send text to the device. Ensure the controller is connected before use.

```python
success = input_text(controller_id, text="你好，世界！")
success = input_text(controller_id, text="Hello MaaMCP")
```

--------------------------------

### Get Pipeline Status

Source: https://context7.com/maa-ai/maamcp/llms.txt

Retrieves the current status of the pipeline, including whether it is running, the bound controller ID, uptime, and the number of messages pending in the queue. This helps in monitoring pipeline health and performance.

```python
status = get_pipeline_status()
# 返回示例：
# {
#   "is_running": True,
#   "controller_id": "ctrl_abc123",
#   "uptime": 15.3,       # 已运行 15.3 秒
#   "pending": 4          # 队列中待处理消息数
# }

if status["pending"] > 50:
    print("消息积压过多，AI 处理速度可能跟不上截图速度")
```

--------------------------------

### Configure MCP Server in Cursor

Source: https://github.com/maa-ai/maamcp/blob/main/README.md

Configuration snippet for adding MaaMCP as an MCP server in Cursor.

```json
{
  "mcpServers": {
    "MaaMCP": {
      "command": "maa-mcp"
    }
  }
}
```

--------------------------------

### Get New OCR Messages

Source: https://context7.com/maa-ai/maamcp/llms.txt

Retrieves the latest OCR recognition results from the message queue in a non-blocking manner. Messages are removed from the queue upon retrieval and are not returned again. Useful for real-time analysis and decision-making based on screen content.

```python
# 获取最多 10 条消息（默认）
messages = get_new_messages()

# 获取最多 5 条
messages = get_new_messages(max_count=5)

for msg in messages:
    print(f"帧 #{msg['frame_id']} @ {msg['timestamp']}")
    for item in msg['ocr_results']:
        print(f"  文字: {item.text}, 坐标: {item.box}")

    # 根据 OCR 结果做决策，例如检测到弹窗并点击确认
    for item in msg['ocr_results']:
        if "确认" in item.text:
            cx = item.box[0] + item.box[2] // 2
            cy = item.box[1] + item.box[3] // 2
            click(controller_id, cx, cy)
```

--------------------------------

### Run MCP Server (Pipeline Mode)

Source: https://github.com/maa-ai/maamcp/blob/main/CLAUDE_CN.md

Launch the MCP server in pipeline mode, which includes a background screenshot thread for continuous monitoring. This can be run directly as a command or through the Python module.

```bash
maa-mcp-server
# or
python -m maa_mcp.pipeline_server
```

--------------------------------

### keyboard_shortcut

Source: https://context7.com/maa-ai/maamcp/llms.txt

Executes keyboard shortcut combinations. This function is only supported on Windows controllers and requires the `Seize` connection method.

```APIDOC
## keyboard_shortcut

### Description
Executes key combination shortcut operations. **Only supported on Windows controllers**, and **requires connection using `keyboard_method="Seize"`**.

### Parameters
- **controller_id** (object) - Required - The controller object obtained from `connect_window` with `keyboard_method="Seize"`.
- **modifiers** (list of integers) - Required - A list of modifier key VK codes (e.g., Ctrl, Alt, Shift).
- **primary_key** (integer) - Required - The VK code of the primary key in the shortcut.

### Request Example
```python
# Must first reconnect the window in Seize mode
ctrl_seize = connect_window(window_name="记事本", keyboard_method="Seize")

# Ctrl+C Copy
success = keyboard_shortcut(ctrl_seize, modifiers=[162], primary_key=67)  # 162=Left Ctrl, 67=C

# Ctrl+V Paste
success = keyboard_shortcut(ctrl_seize, modifiers=[162], primary_key=86)

# Ctrl+Z Undo
success = keyboard_shortcut(ctrl_seize, modifiers=[162], primary_key=90)

# Alt+F4 Close window
success = keyboard_shortcut(ctrl_seize, modifiers=[164], primary_key=115)  # 164=Left Alt, 115=F4

# Common modifier VK codes: Left Shift=160, Left Ctrl=162, Left Alt=164, Left Win=91
```
```

--------------------------------

### Take Screenshot

Source: https://context7.com/maa-ai/maamcp/llms.txt

Captures a screenshot of the device screen and saves it as a PNG file, returning the absolute path. Use this sparingly as it consumes significant tokens; prefer OCR for element location.

```python
path = screencap(controller_id=controller_id)
# 返回类似 "/home/user/.local/share/MaaMCP/screenshots/screenshot_20250101_120000_000000.png"

if path:
    print(f"截图保存至: {path}")
    # 可通过 read_file 工具读取图片内容进行视觉分析
else:
    print("截图失败")
```

--------------------------------

### find_window_list

Source: https://context7.com/maa-ai/maamcp/llms.txt

Scans and enumerates all visible Windows desktop windows on the current system, returning a list of window names. If multiple windows are found, it waits for user selection.

```APIDOC
## find_window_list

### Description
Scans and enumerates all visible Windows desktop windows on the current system, returning a list of window names. If multiple windows are found, it waits for user selection.

### Method
Python Function

### Endpoint
N/A

### Parameters
None

### Request Example
```python
windows = find_window_list()
# Returns: ["Notepad", "Google Chrome", "WeChat"]
```

### Response
#### Success Response
- `windows` (list[str]) - A list of strings, where each string is a window name.

#### Response Example
```json
["Notepad", "Google Chrome", "WeChat"]
```
```

--------------------------------

### Execute Keyboard Shortcuts (Windows Only)

Source: https://context7.com/maa-ai/maamcp/llms.txt

Executes keyboard shortcut combinations. This function is exclusively for Windows controllers and requires a 'Seize' connection method. Ensure the window is connected using `keyboard_method="Seize"` before executing shortcuts.

```python
# 必须先以 Seize 模式重新连接窗口
ctrl_seize = connect_window(window_name="记事本", keyboard_method="Seize")

# Ctrl+C 复制
success = keyboard_shortcut(ctrl_seize, modifiers=[162], primary_key=67)  # 162=Left Ctrl, 67=C

# Ctrl+V 粘贴
success = keyboard_shortcut(ctrl_seize, modifiers=[162], primary_key=86)

# Ctrl+Z 撤销
success = keyboard_shortcut(ctrl_seize, modifiers=[162], primary_key=90)

# Alt+F4 关闭窗口
success = keyboard_shortcut(ctrl_seize, modifiers=[164], primary_key=115)  # 164=Left Alt, 115=F4

# 常用修饰键 VK 码: Left Shift=160, Left Ctrl=162, Left Alt=164, Left Win=91
```

--------------------------------

### screencap

Source: https://context7.com/maa-ai/maamcp/llms.txt

Captures a screenshot of the current device screen and saves it as a PNG file, returning the absolute path for reading. This operation has a high token cost and should be used on demand, preferably using `ocr` instead.

```APIDOC
## screencap

### Description
Captures a screenshot of the current device screen and saves it as a PNG file, returning the absolute path for reading. This operation has a high token cost and should be used on demand, preferably using `ocr` instead.

### Method
Python Function

### Endpoint
N/A

### Parameters
#### Path Parameters
- **controller_id** (str) - Required - The ID of the controller for the target device or window.

### Request Example
```python
path = screencap(controller_id=controller_id)
# Returns a path like "/home/user/.local/share/MaaMCP/screenshots/screenshot_20250101_120000_000000.png"

if path:
    print(f"Screenshot saved to: {path}")
    # The image content can be read using a file reading tool for visual analysis.
else:
    print("Screenshot failed")
```

### Response
#### Success Response
- `path` (str) - The absolute path to the saved screenshot file.

#### Response Example
```json
"/home/user/.local/share/MaaMCP/screenshots/screenshot_20250101_120000_000000.png"
```
```

--------------------------------

### Device Discovery and Connection

Source: https://github.com/maa-ai/maamcp/blob/main/README.md

Functions to discover and connect to Android devices and Windows windows.

```APIDOC
## find_adb_device_list

### Description
Scans for available ADB devices.

### Method
find_adb_device_list

### Parameters
None

### Response
List of available ADB devices.
```

```APIDOC
## find_window_list

### Description
Scans for available Windows windows.

### Method
find_window_list

### Parameters
None

### Response
List of available Windows windows.
```

```APIDOC
## connect_adb_device

### Description
Connects to an Android device.

### Method
connect_adb_device

### Parameters
- **device_id** (string) - Required - The ID of the ADB device to connect to.

### Response
Controller ID for the connected Android device.
```

```APIDOC
## connect_window

### Description
Connects to a Windows window.

### Method
connect_window

### Parameters
- **window_id** (string) - Required - The ID of the Windows window to connect to.

### Response
Controller ID for the connected Windows window.
```

--------------------------------

### Open Pipeline in Browser

Source: https://context7.com/maa-ai/maamcp/llms.txt

Opens a local Pipeline JSON file in the system's default browser for visualization. This function is intended for viewing the flowchart and will throw a ValueError if the pipeline exceeds 60KB.

```python
# 在浏览器中打开 Pipeline 可视化（无返回值）
open_pipeline_in_browser(
    pipeline_file_path="/home/user/.local/share/MaaMCP/pipelines/调整亮度_20250615_143025.json"
)
# 自动打开浏览器，显示 Pipeline 节点流程图

# 若 Pipeline 过大（> 60KB），会抛出 ValueError 提示手动导入
```

--------------------------------

### open_pipeline_in_browser

Source: https://context7.com/maa-ai/maamcp/llms.txt

Reads a local Pipeline JSON file, generates a shareable link after compression and encoding, and automatically opens the visualization interface in the system's default browser. This function is intended for users who want to view the visualization and generates URLs not exceeding 60KB.

```APIDOC
## `open_pipeline_in_browser` — 在浏览器中可视化 Pipeline

Reads a local Pipeline JSON file, compresses and encodes it to generate a shareable link, and automatically opens the visualization interface in the system's default browser. This function is intended for users who want to view the visualization and generates URLs not exceeding 60KB.

### Parameters
#### Path Parameters
- **pipeline_file_path** (str) - Required - The path to the Pipeline JSON file.

### Request Example
```python
# Open Pipeline visualization in the browser (no return value)
open_pipeline_in_browser(
    pipeline_file_path="/home/user/.local/share/MaaMCP/pipelines/adjust_brightness_20250615_143025.json"
)
# Automatically opens the browser displaying the Pipeline node flowchart

# If the Pipeline is too large (> 60KB), a ValueError will be raised, prompting manual import
```

### Response
#### Success Response
- Opens the default system browser with the Pipeline visualization. No return value.

#### Error Response
- **ValueError**: Raised if the Pipeline file size exceeds 60KB, indicating it's too large for direct URL sharing.
```

--------------------------------

### Run Tests

Source: https://github.com/maa-ai/maamcp/blob/main/CLAUDE_CN.md

Execute project tests using pytest. You can run all tests or specify a particular test file.

```bash
pytest tests/ -v
pytest tests/test_basic.py -v  # Run a specific file
```

--------------------------------

### Manual OCR Model Download Attempt

Source: https://github.com/maa-ai/maamcp/blob/main/README.md

Use this Python command to manually attempt downloading and extracting OCR model files if automatic downloads fail. Ensure you are in the correct environment.

```python
from maa_mcp.download import download_and_extract_ocr
download_and_extract_ocr()
```

--------------------------------

### get_pipeline_protocol

Source: https://context7.com/maa-ai/maamcp/llms.txt

Fetches the complete specification document for the MaaFramework Pipeline protocol, including all recognition algorithm types, action types, parameter descriptions, and best practices. AI should call this tool before generating Pipeline JSON.

```APIDOC
## get_pipeline_protocol

### Description
Gets the complete specification document for the MaaFramework Pipeline protocol, including all recognition algorithm types, action types, parameter descriptions, and best practices. AI should call this tool before generating Pipeline JSON.

### Response
#### Success Response
- **doc** (string) - The complete protocol specification in Markdown format.

### Response Example
```python
doc = get_pipeline_protocol()
# Returns the complete Markdown formatted protocol document, including:
# - Recognition algorithms: DirectHit, OCR, TemplateMatch, ColorMatch
# - Action types: Click, Swipe, Scroll, InputText, ClickKey, LongPress, StartApp/StopApp
# - Common properties: next, post_delay
# - Complete examples and best practices
print(doc)
```
```

--------------------------------

### load_pipeline

Source: https://context7.com/maa-ai/maamcp/llms.txt

Reads an existing Pipeline JSON file and returns its content as a dictionary, which can be viewed or modified before saving.

```APIDOC
## `load_pipeline` — 读取 Pipeline 文件

Reads an existing Pipeline JSON file and returns its content as a dictionary, which can be viewed or modified before saving.

### Parameters
#### Path Parameters
- **pipeline_path** (str) - Required - The path to the Pipeline JSON file.

### Request Example
```python
pipeline = load_pipeline(pipeline_path="/home/user/.local/share/MaaMCP/pipelines/adjust_brightness_20250615_143025.json")

if isinstance(pipeline, str):
    print(f"Failed to load: {pipeline}")
else:
    print(f"Pipeline contains {len(pipeline)} nodes: {list(pipeline.keys())}")
    # Modify a node
    pipeline["adjust_brightness"]["duration"] = 300
    # Re-save
    save_pipeline(pipeline_json=str(pipeline), output_path="...", overwrite=True)
```

### Response
#### Success Response (dict)
- Returns a dictionary representing the pipeline structure.

#### Error Response (str)
- Returns an error message string if loading fails.
```

--------------------------------

### Find ADB Devices

Source: https://context7.com/maa-ai/maamcp/llms.txt

Scans for and lists all available ADB devices connected to the system. If multiple devices are found, user interaction is required to select one.

```python
# 返回示例：["emulator-5554", "192.168.1.10:5555"]
devices = find_adb_device_list()
# 输出：["emulator-5554", "192.168.1.10:5555"]
```

--------------------------------

### Find Windows Windows

Source: https://context7.com/maa-ai/maamcp/llms.txt

Scans for and lists all visible Windows desktop windows. User selection is required if multiple windows are found.

```python
# 返回示例：["记事本", "Google Chrome", "微信"]
windows = find_window_list()
# 过滤出目标窗口
target = [w for w in windows if "记事本" in w]
```

--------------------------------

### find_adb_device_list

Source: https://context7.com/maa-ai/maamcp/llms.txt

Scans and enumerates all available ADB devices (Android phones or emulators) on the current system. Returns a list of device names. If multiple devices exist, it pauses and prompts the user to select one.

```APIDOC
## find_adb_device_list

### Description
Scans and enumerates all available ADB devices (Android phones or emulators) on the current system. Returns a list of device names. If multiple devices exist, it pauses and prompts the user to select one.

### Method
Python Function

### Endpoint
N/A

### Parameters
None

### Request Example
```python
devices = find_adb_device_list()
# Returns: ["emulator-5554", "192.168.1.10:5555"]
```

### Response
#### Success Response
- `devices` (list[str]) - A list of strings, where each string is a device name.

#### Response Example
```json
["emulator-5554", "192.168.1.10:5555"]
```
```

--------------------------------

### ocr

Source: https://context7.com/maa-ai/maamcp/llms.txt

Takes a screenshot of the current device screen and performs OCR recognition, returning a structured list of text, coordinates, and confidence scores. If OCR models are not downloaded on first use, it returns a prompt string requiring manual download initiation. OCR is the primary method for locating UI element coordinates, preferred over `screencap`.

```APIDOC
## ocr

### Description
Takes a screenshot of the current device screen and performs OCR recognition, returning a structured list of text, coordinates, and confidence scores. If OCR models are not downloaded on first use, it returns a prompt string requiring manual download initiation. OCR is the primary method for locating UI element coordinates, preferred over `screencap`.

### Method
Python Function

### Endpoint
N/A

### Parameters
#### Path Parameters
- **controller_id** (str) - Required - The ID of the controller for the target device or window.

### Request Example
```python
result = ocr(controller_id=controller_id)

# Possible results:
# 1. List (successful recognition)
# 2. String (OCR resources not downloaded, prompts to call check_and_download_ocr())
# 3. None (screenshot or OCR failed)

if isinstance(result, str):
    print(f"Prompt: {result}")  # OCR resources not found, download required
elif result is None:
    print("OCR recognition failed")
else:
    for item in result:
        # Each item contains text content, bounding box coordinates [x, y, w, h], and confidence score
        print(f"Text: {item.text}, Coordinates: {item.box}, Confidence: {item.score:.3f}")

    # Example: Find and click the "Confirm" button
    for item in result:
        if "Confirm" in item.text:
            cx = item.box[0] + item.box[2] // 2
            cy = item.box[1] + item.box[3] // 2
            click(controller_id, cx, cy)
            break
```

### Response
#### Success Response
- `result` (list[dict] or str or None) - A list of dictionaries, where each dictionary contains:
  - `text` (str) - The recognized text.
  - `box` (list[int]) - The bounding box coordinates [x, y, width, height].
  - `score` (float) - The confidence score of the recognition.
Returns a string with download instructions if resources are missing, or None if an error occurred.
```

--------------------------------

### Pipeline Management

Source: https://github.com/maa-ai/maamcp/blob/main/README.md

Functions for managing and executing pipeline configurations.

```APIDOC
## get_pipeline_protocol

### Description
Retrieves the documentation for the Pipeline protocol.

### Method
get_pipeline_protocol

### Parameters
None

### Response
Pipeline protocol documentation.
```

```APIDOC
## save_pipeline

### Description
Saves a Pipeline JSON to a file.

### Method
save_pipeline

### Parameters
- **pipeline_data** (object) - Required - The Pipeline JSON data to save.
- **file_path** (string) - Required - The path to save the file to.

### Response
Success status of saving the pipeline.
```

```APIDOC
## load_pipeline

### Description
Loads an existing Pipeline file.

### Method
load_pipeline

### Parameters
- **file_path** (string) - Required - The path to the Pipeline file to load.

### Response
Pipeline data loaded from the file.
```

```APIDOC
## run_pipeline

### Description
Executes a Pipeline and returns the result.

### Method
run_pipeline

### Parameters
- **pipeline_data** (object) - Required - The Pipeline JSON data to execute.

### Response
Execution result of the pipeline.
```

```APIDOC
## open_pipeline_in_browser

### Description
Opens the Pipeline visualization interface in a web browser.

### Method
open_pipeline_in_browser

### Parameters
None

### Response
URL to the Pipeline visualization interface.
```

--------------------------------

### Simulate Key Presses (Android/Windows)

Source: https://context7.com/maa-ai/maamcp/llms.txt

Simulates key presses, supporting long presses. Use Android KeyEvent codes for Android and Virtual Key (VK) codes for Windows. Ensure the correct key codes are used for the target platform.

```python
# Android 常用按键
click_key(controller_id, key=4)   # 返回键
click_key(controller_id, key=3)   # Home 键
click_key(controller_id, key=66)  # 回车/确认键
click_key(controller_id, key=67)  # 删除/退格键
```

```python
# Windows 常用按键
click_key(controller_id, key=13)  # 回车 (Enter)
click_key(controller_id, key=27)  # ESC
click_key(controller_id, key=8)   # 退格 (Backspace)
click_key(controller_id, key=9)   # Tab
```

```python
# 长按（500毫秒）
click_key(controller_id, key=4, duration=500)
```

--------------------------------

### get_current_datetime

Source: https://context7.com/maa-ai/maamcp/llms.txt

Retrieves the current system date and time as a formatted string (YYYY-MM-DD HH:MM:SS). This helps prevent AI from guessing the time.

```APIDOC
## get_current_datetime

### Description
Gets the current system date and time string (Format: `YYYY-MM-DD HH:MM:SS`), preventing AI from guessing the time.

### Response
#### Success Response
- **datetime_string** (string) - The current date and time.

### Response Example
```python
now = get_current_datetime()
# Returns example: "2025-06-15 14:30:25"
```
```

--------------------------------

### Perform OCR on Screen

Source: https://context7.com/maa-ai/maamcp/llms.txt

Captures the screen and performs Optical Character Recognition (OCR) to return structured data including text, coordinates, and confidence scores. If OCR models are not downloaded, it returns a prompt string.

```python
result = ocr(controller_id=controller_id)

# result 可能是：
# 1. 列表（识别成功）
# 2. 字符串（OCR 资源未下载，提示调用 check_and_download_ocr()）
# 3. None（截图或 OCR 失败）

if isinstance(result, str):
    print(f"提示: {result}")  # OCR 资源不存在，需先下载
elif result is None:
    print("OCR 识别失败")
else:
    for item in result:
        # 每项包含文字内容、边界框坐标 [x, y, w, h]、置信度 score
        print(f"文字: {item.text}, 坐标: {item.box}, 置信度: {item.score:.3f}")

    # 查找并点击"确认"按钮
    for item in result:
        if "确认" in item.text:
            cx = item.box[0] + item.box[2] // 2
            cy = item.box[1] + item.box[3] // 2
            click(controller_id, cx, cy)
            break
```

--------------------------------

### Load and Modify Pipeline JSON

Source: https://context7.com/maa-ai/maamcp/llms.txt

Loads an existing Pipeline JSON file into a dictionary for viewing or modification. Ensure the pipeline is saved after modifications.

```python
pipeline = load_pipeline(pipeline_path="/home/user/.local/share/MaaMCP/pipelines/调整亮度_20250615_143025.json")

if isinstance(pipeline, str):
    print(f"读取失败: {pipeline}")
else:
    print(f"Pipeline 包含 {len(pipeline)} 个节点：{list(pipeline.keys())}")
    # 修改某个节点
    pipeline["调整亮度"]["duration"] = 300
    # 重新保存
    save_pipeline(pipeline_json=str(pipeline), output_path="...", overwrite=True)
```