MCP工具文档

概述

DrissionPage MCP Server 提供了丰富的浏览器自动化工具，基于 DrissionPage 和 FastMCP 框架构建。本文档详细介绍了所有可用的 MCP 工具及其使用方法。

工具分类

🌐 浏览器管理工具

connect_browser

连接到现有浏览器实例或启动新的浏览器。

参数：

port (int, 可选): 浏览器调试端口，默认 9222
headless (bool, 可选): 是否无头模式，默认 False
user_data_dir (str, 可选): 用户数据目录路径

返回： 浏览器连接状态信息

示例：

python

# 连接到默认端口的浏览器
connect_browser()

# 连接到指定端口的无头浏览器
connect_browser(port=9223, headless=True)

# 使用自定义用户数据目录
connect_browser(user_data_dir="/path/to/userdata")

new_tab

创建新的浏览器标签页。

参数：

url (str, 可选): 新标签页要打开的URL

返回： 新标签页创建结果

示例：

python

# 创建空白标签页
new_tab()

# 创建并导航到指定URL
new_tab(url="https://example.com")

navigate

导航到指定URL。

参数：

url (str, 必需): 目标URL

返回： 导航结果信息

示例：

python

navigate(url="https://www.google.com")

🎯 元素操作工具

click_element

点击页面元素（智能优化版）。

重要提示： 使用前请遵循标准化工作流程：

📸 先使用 take_screenshot() 确认目标元素存在
🔍 使用 get_dom_tree() 或 find_elements() 分析页面结构
🎯 基于准确信息构建选择器，禁止猜测元素名称

参数：

selector (str, 必需): 元素选择器
selector_type (str, 可选): 选择器类型 (css, xpath, text)，默认 "css"
index (int, 可选): 元素索引（多个匹配时），默认 0
smart_feedback (bool, 可选): 是否启用智能反馈，默认 True

选择器优先级：

ID选择器：#element-id （最优先）
CSS类选择器：.class-name
属性选择器：[data-testid="value"]
XPath选择器：//div[@class="example"]
文本匹配：仅作为辅助手段

示例：

python

# 点击ID为submit的按钮
click_element(selector="#submit", selector_type="css")

# 点击包含特定文本的元素
click_element(selector="提交", selector_type="text")

# 使用XPath选择器
click_element(selector="//button[@class='btn-primary']", selector_type="xpath")

input_text

在输入框中输入文本（智能优化版）。

参数：

selector (str, 必需): 输入框选择器
text (str, 必需): 要输入的文本内容
clear_first (bool, 可选): 是否先清空输入框，默认 True

示例：

python

# 在用户名输入框中输入文本
input_text(selector="#username", text="myusername")

# 在输入框中追加文本（不清空原内容）
input_text(selector="[name='message']", text="Hello World", clear_first=False)

get_element_text

获取元素文本内容（精确定位版）。

参数：

selector (str, 必需): 元素选择器

返回： 元素的文本内容

示例：

python

# 获取标题文本
get_element_text(selector="h1")

# 获取状态信息
get_element_text(selector=".status-message")

get_page_text

获取页面完整文本内容（预处理必备工具）。

用途：

🔍 在操作元素前，获取页面的完整文本信息
📋 为非多模态LLM提供详细的页面内容描述
🎯 帮助构建精确的元素选择器
✅ 确认页面加载完成和内容可用性

返回： 页面的完整可见文本内容（去除HTML标签）

示例：

python

# 获取当前页面的所有文本内容
page_content = get_page_text()

📸 截图工具

take_screenshot

截取页面截图（标准化工作流程第1步）。

参数：

filename (str, 可选): 截图文件名，自动生成时间戳命名
full_page (bool, 可选): 是否截取完整页面，默认 False（可视区域）
element_selector (str, 可选): 仅截取特定元素

返回： 截图保存路径和操作结果

示例：

python

# 截取可视区域
take_screenshot()

# 截取完整页面
take_screenshot(full_page=True)

# 截取特定元素
take_screenshot(element_selector="#main-content")

# 指定文件名
take_screenshot(filename="login_page.png")

get_screenshot_data

获取截图二进制数据。

参数：

format (str, 可选): 图片格式，默认 "png"

返回： 截图的二进制数据

示例：

python

# 获取PNG格式的截图数据
screenshot_data = get_screenshot_data(format="png")

🌳 DOM操作工具

get_dom_tree

获取DOM树结构（结构化分析工具）。

参数：

selector (str, 可选): 起始选择器，默认 "body"
max_depth (int, 可选): 最大遍历深度，默认 10

返回： 结构化的DOM树信息

示例：

python

# 获取整个页面的DOM结构
get_dom_tree()

# 获取特定区域的DOM结构
get_dom_tree(selector="#main-content", max_depth=5)

find_elements

查找页面元素（智能定位工具）。

参数：

selector (str, 必需): 元素选择器
selector_type (str, 可选): 选择器类型 (css, xpath, text)，默认 "css"
limit (int, 可选): 返回元素数量限制，默认 10
include_similar (bool, 可选): 是否包含相似元素，默认 True

返回： 匹配元素的详细信息列表

示例：

python

# 查找所有按钮元素
find_elements(selector="button", selector_type="css")

# 查找包含特定文本的元素
find_elements(selector="登录", selector_type="text", limit=5)

# 使用XPath查找元素
find_elements(selector="//input[@type='text']", selector_type="xpath")

🌐 网络监控工具

enable_network_monitoring

启用网络监控。

参数：

filter_types (List[str], 可选): 需要监听的mimeType类型列表

返回： 启用结果

示例：

python

# 启用所有网络监控
enable_network_monitoring()

# 只监控JSON和图片请求
enable_network_monitoring(filter_types=["application/json", "image/png"])

get_network_logs

获取网络请求日志。

参数：

limit (int, 可选): 返回日志的最大数量，默认 50

返回： 网络日志数据

示例：

python

# 获取最近50条网络日志
get_network_logs()

# 获取最近100条网络日志
get_network_logs(limit=100)

📁 文件操作工具

save_page_source

保存页面源码到文件。

参数：

filename (str, 可选): 保存文件名，自动生成时间戳命名

返回： 保存结果信息

示例：

python

# 保存当前页面源码
save_page_source()

# 指定文件名保存
save_page_source(filename="homepage.html")

get_cookies

获取当前页面的Cookies。

返回： 当前页面的所有Cookie信息

示例：

python

# 获取当前页面的所有Cookie
cookies = get_cookies()

⚡ JavaScript执行工具

execute_javascript

执行JavaScript代码。

参数：

code (str, 必需): 要执行的JavaScript代码
return_result (bool, 可选): 是否返回执行结果，默认 True

返回： JavaScript执行结果

示例：

python

# 执行简单的JavaScript代码
execute_javascript(code="document.title")

# 执行复杂的JavaScript操作
execute_javascript(code="""
    const elements = document.querySelectorAll('.item');
    return elements.length;
""")

# 修改页面元素
execute_javascript(code="document.getElementById('myButton').click()")

🔧 CDP命令工具

run_cdp_command

执行Chrome DevTools Protocol命令。

参数：

command (str, 必需): CDP命令名称
**params: CDP命令参数

返回： CDP命令执行结果

示例：

python

# 停止页面加载
run_cdp_command(command="Page.stopLoading")

# 导航到指定URL
run_cdp_command(command="Page.navigate", url="https://example.com")

# 获取页面性能指标
run_cdp_command(command="Performance.getMetrics")

最佳实践工作流程

标准化操作流程

📸 视觉确认 - 使用 take_screenshot() 获取页面截图
📄 文本分析 - 使用 get_page_text() 获取页面文本内容
🌳 结构分析 - 使用 get_dom_tree() 分析页面DOM结构
🔍 元素定位 - 使用 find_elements() 精确定位目标元素
🎯 执行操作 - 使用 click_element() 或 input_text() 执行具体操作

选择器构建原则

优先级顺序：
- ID选择器：#element-id
- CSS类选择器：.class-name
- 属性选择器：[data-testid="value"]
- XPath选择器：//div[@class="example"]
- 文本匹配：仅作为辅助手段
禁止行为：
- 禁止猜测元素名称或选择器
- 禁止使用未经验证的选择器
- 禁止跳过预处理步骤直接操作

错误处理和调试

操作失败时：
- 重新截图确认页面状态
- 检查DOM结构是否发生变化
- 验证选择器是否仍然有效
- 查看网络日志排查异步加载问题
性能优化：
- 利用浏览器内置缓存机制提升页面加载速度
- 合理设置元素查找限制 (limit)
- 适当控制DOM树深度 (max_depth)

配置和环境

环境变量

DRISSIONPAGE_MCP_LOG_LEVEL: 日志级别，默认 "INFO"
DRISSIONPAGE_MCP_BROWSER_PATH: 浏览器可执行文件路径
DRISSIONPAGE_MCP_DOWNLOAD_PATH: 下载文件保存路径
DRISSIONPAGE_MCP_SCREENSHOT_PATH: 截图保存路径
DRISSIONPAGE_MCP_HEADLESS: 是否启用无头模式，默认 "false"
DRISSIONPAGE_MCP_TIMEOUT: 操作超时时间，默认 "30"

默认配置

json

{
  "browser": {
    "debug_port": 9222,
    "headless": false,
    "window_size": [1920, 1080],
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
  },
  "screenshot": {
    "format": "png",
    "quality": 90,
    "full_page": false
  },
  "performance": {
    "element_wait_timeout": 10,
    "page_load_timeout": 30,
    "script_timeout": 30
  }
}

常见问题

Q: 如何处理动态加载的内容？

A: 使用网络监控工具监听AJAX请求，结合适当的等待策略和重试机制。

Q: 选择器失效怎么办？

A: 重新分析DOM结构，使用更稳定的选择器（如ID或data属性），避免依赖易变的class名称。

Q: 如何提高操作成功率？

A: 严格遵循标准化工作流程，充分利用预处理工具，避免盲目猜测元素选择器。

Q: 无头模式下截图异常？

A: 确保设置了合适的窗口大小，某些页面在无头模式下渲染可能有差异。

MCP工具文档 ​

概述 ​

工具分类 ​

🌐 浏览器管理工具 ​

connect_browser ​

new_tab ​

navigate ​

🎯 元素操作工具 ​

click_element ​

input_text ​

get_element_text ​

get_page_text ​

📸 截图工具 ​

take_screenshot ​

get_screenshot_data ​

🌳 DOM操作工具 ​

get_dom_tree ​

find_elements ​

🌐 网络监控工具 ​

enable_network_monitoring ​

get_network_logs ​

📁 文件操作工具 ​

save_page_source ​

get_cookies ​

⚡ JavaScript执行工具 ​

execute_javascript ​

🔧 CDP命令工具 ​

run_cdp_command ​

最佳实践工作流程 ​

标准化操作流程 ​

选择器构建原则 ​

错误处理和调试 ​

配置和环境 ​

环境变量 ​

默认配置 ​

常见问题 ​

Q: 如何处理动态加载的内容？ ​

Q: 选择器失效怎么办？ ​

Q: 如何提高操作成功率？ ​

Q: 无头模式下截图异常？ ​

MCP工具文档

概述

工具分类

🌐 浏览器管理工具

connect_browser

new_tab

navigate

🎯 元素操作工具

click_element

input_text

get_element_text

get_page_text

📸 截图工具

take_screenshot

get_screenshot_data

🌳 DOM操作工具

get_dom_tree

find_elements

🌐 网络监控工具

enable_network_monitoring

get_network_logs

📁 文件操作工具

save_page_source

get_cookies

⚡ JavaScript执行工具

execute_javascript

🔧 CDP命令工具

run_cdp_command

最佳实践工作流程

标准化操作流程

选择器构建原则

错误处理和调试

配置和环境

环境变量

默认配置

常见问题

Q: 如何处理动态加载的内容？

Q: 选择器失效怎么办？

Q: 如何提高操作成功率？

Q: 无头模式下截图异常？