QA Automation MCP Plugin (Claude Code / Desktop 插件)

企业级 Web 系统（SCM / MOM / WMS / ERP）自动化测试 Claude Code & Claude Desktop 插件。

通过 Playwright CDP 接管本地物理 Chrome 浏览器，提供 DOM/iframe 语义分析、高韧性点击输入、批量动作链、VTable 场景图渲染层交互、动态浮层探查、测试用例实时录制以及 Shadcn 极简风格 Excel 报表与证据 JSON 一键落盘导出（内置 24 个 MCP 工具 + 测试设计 SOP 技能指南）。

---

目录

• 核心架构设计与原理总结
• 项目目录结构
• 前置条件与环境准备
• 插件安装与使用 SOP
  • 方式一：Claude Desktop 导入 ZIP 插件包（推荐生产使用）
  • 方式二：Claude Code 插件加载与市场安装
  • 方式三：常规 MCP 客户端直接接入（Cursor / VS Code / Claude Desktop 手动配置）
• MCP 工具与 SOP 技能清单
• 开发验证与单元测试

---

核心架构设计与原理总结

在项目设计与优化过程中，针对 MCP 插件的生命周期、环境打包、变量注入与启动性能得出了以下核心架构原理与结论：

1. 无需打包 .venv 的“现场自动建环”机制

• 零体积发布：分发 Zip 插件包时绝对不需要包含庞大的 .venv 虚拟环境，打出的插件 Zip 包体积仅 ~200 KB。
• 外层 uv run 负责环境感知与现场构建：当 MCP 客户端启动插件时，命令最外层的 uv run 会首先检查插件目录下是否存在 .venv。若不存在，uv 会读取 fastmcp.json / pyproject.toml 依赖声明，在目标机器上自动下载 Python 环境并瞬间构建虚拟环境、安装依赖。
• 内层 --skip-env 防止二次建环死循环：子命令 fastmcp run --skip-env fastmcp.json 中的 --skip-env 标志用于告知 FastMCP 内部 CLI 引擎：“外层 uv 已经完成了虚拟环境的创建与激活，FastMCP 无需在内部重复拉起 uv 嵌套构建”。此举杜绝了死循环，并将服务启动耗时缩短至毫秒级。

2. 插件全局挂载与 ${CLAUDE_PLUGIN_ROOT} 路径寻址

• 解决 not loaded 的关键：在 Claude Code / Claude Desktop 插件体系中，用户安装插件后，插件文件解压挂载在插件系统的全局路径下（如 ~/.claude/plugins/qa-automation/）。当用户在任意其他工作区目录使用该插件时，如果没有指定 --directory "${CLAUDE_PLUGIN_ROOT}"，uv 会在用户当前工作区寻找 fastmcp.json，从而导致找不到配置文件并引发 qa-automation-mcp: not loaded 加载失败。
• ${CLAUDE_PLUGIN_ROOT} 自动注入与挂载：在 .claude-plugin/plugin.json 与 .mcp.json 中配置 --directory "${CLAUDE_PLUGIN_ROOT}"，确保了无论用户在电脑上的哪个项目路径下触发插件，uv 都能准确跳至插件的实际安装根目录去加载 fastmcp.json 并激活环境，实现跨目录、跨项目的全局无缝调用。

3. 全面支持 Python 3.14 稳定版与向下兼容

• 项目依赖规范配置为 requires-python = ">=3.11"（pyproject.toml）与 "python": ">=3.11"（fastmcp.json）。
• 完全支持已正式发布的 Python 3.14 稳定版，同时对 Python 3.11 / 3.12 / 3.13 保持向下兼容。

---

项目目录结构

qa-automation-mcp-plugin/
├── .claude-plugin/
│   ├── plugin.json           # 插件主清单 (定义名称、版本、mcpServers 与 skills 显式映射)
│   └── marketplace.json      # 插件市场注册清单 (定义 Marketplace 索引与 GitHub 源码源)
├── .mcp.json                 # 工作区 MCP 配置 (用于开发者在本项目根目录下直接调试)
├── fastmcp.json              # FastMCP 声明式服务、入口与依赖配置
├── pyproject.toml            # Hatchling 构建与项目依赖声明 (包含 pytest 开发依赖组)
├── .env.example              # 环境变量配置模板
├── skills/
│   └── qa-automation-guide/
│       └── SKILL.md          # SCM/MOM/WMS/ERP Web 自动化测试 SOP 技能指南
├── src/qa_mcp/               # FastMCP 3.x 服务源码
│   ├── server.py             # 服务装配入口 (Lifespan, Middleware, Provider 与导出工具)
│   ├── config.py             # 统一超时、轮询与环境变量配置
│   ├── providers/            # FastMCP Provider 扩展 (BrowserProvider, VTableProvider)
│   ├── tools/                # 24 个 MCP 核心工具实现 (browser, vtable, recorder, vision 等)
│   └── utils/                # UI 组件适配器、场景图 JS 注入脚本与 Shadcn Excel 渲染器
└── tests/                    # 单元测试套件 (76 个自动化测试用例)

---

前置条件与环境准备

1. 安装必要工具：

   • 已安装 Claude Code 或 Claude Desktop。
   • 已安装 uv（Python 包与环境管理工具）。
   • 环境支持 Python 3.11、3.12、3.13 或 3.14+。

2. 启动本地物理 Chrome 远程调试端口： Playwright CDP 需连接至开启调试端口的 Chrome 实例，在终端运行：

   • Windows:

     chrome.exe --remote-debugging-port=9222 --user-data-dir="C:\Temp\ChromeDebugProfile"
     

   • macOS:

     /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir="/tmp/ChromeDebugProfile"
     

3. 配置环境变量（可选）： 复制项目模板并根据需要调整配置：

   cp .env.example .env
   

   • CDP_URL: Chrome CDP 调试地址（默认 http://127.0.0.1:9222）。
   • VISUAL_EFFECTS: 是否开启鼠标点击与定位框可视化高亮（默认 true）。
   • MIMO_API_KEY: 小米 MiMo-V2.5 视觉 API Key（仅当主模型为纯文本模型需要图像理解降级时配置）。

---

插件安装与使用 SOP

方式一：Claude Desktop 导入 ZIP 插件包（推荐生产使用）

1. 打包插件（开发者）： 直接将项目根目录下除 .venv、__pycache__ 外的文件打包为 qa-automation-mcp-plugin.zip（体积约 200KB）。
2. 导入 Claude Desktop：
   • 打开 Claude Desktop $\rightarrow$ 设置 $\rightarrow$ Plugins / MCP Servers $\rightarrow$ 选择导入 qa-automation-mcp-plugin.zip。
3. 自动运行：
   • Claude Desktop 会解压插件到本地插件目录。
   • 首次触发时外层 uv run 自动建环并安装依赖，内层 --skip-env 快速调起 MCP 服务。

方式二：Claude Code 插件加载与市场安装

• 本地开发调试： 在 Claude Code 中直接指定插件目录运行：

  claude --plugin-dir ./qa-automation-mcp-plugin
  

• 通过 Marketplace 安装： 在 Claude Code 中添加市场并安装：

  /plugin marketplace add hooplus1ce/qa-automation-mcp-plugin
  /plugin install qa-automation
  

方式三：常规 MCP 客户端直接接入（Cursor / VS Code / Claude Desktop 手动配置）

若不使用插件包装机制，可以直接在客户端配置（如 ~/.claude/claude_desktop_config.json 或 .cursor/mcp.json）中添加 mcpServers：

{
  "mcpServers": {
    "qa-automation-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/绝对路径/到/qa-automation-mcp-plugin",
        "fastmcp",
        "run",
        "--skip-env",
        "fastmcp.json"
      ],
      "env": {
        "CDP_URL": "http://127.0.0.1:9222",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

---

MCP 工具与 SOP 技能清单

项目共装配 24 个 MCP 核心工具 及 1 个企业级 Web 测试设计 SOP 技能：

1. 基础页面分析与交互工具 (11 个)

• analyze_current_page: 递归分析 DOM 及嵌套 iframe，生成可见交互元素定位器。
• click_interact: 统一点击工具（支持 CSS/XPath、get_by_role 语义定位、视口坐标点击，附带弹窗浮层与跳转观察）。
• fill_input: 文本框填充（支持清空、逐字模拟键盘输入、回车触发）。
• execute_action_chain: 批量动作链顺序执行（含 fallback 变体容错与降级机制）。
• probe_dynamic_layers: 探查页面/iframe 出现的可见弹窗、下拉悬浮层及消息气泡。
• wait_for_condition: 页面条件轮询等待（文本出现/元素可见/URL跳转）。
• capture_screenshot: CDP 原生无卡顿截屏（支持整页或视口，生成 PNG 及文件凭证）。
• switch_target_page: 显式重绑/锁定 MCP 操作的目标标签页。
• mimo_describe_image: 纯文本主模型环境下的视觉理解降级工具。
• start_recording: 初始化测试用例录制会话。
• execute_and_record: 执行动作并自动记录最优高韧性语义定位步骤。

2. VTable 场景图表格交互工具 (12 个)

• vtable_refresh_instance: 挂载并刷新 Canvas 渲染表格的 window._vtable 实例。
• vtable_analyze_headers: 【场景图驱动】分析列头图标与单元格交互组件。
• vtable_scan_columns: 【推荐】扫描全部列头及视口坐标（直接传给坐标点击）。
• vtable_get_row_count: 获取表格纯数据总行数。
• vtable_get_all_records: 一次性读取整表后台行记录 JSON。
• vtable_get_cell_text: 读取指定单元格展示文本（可读取场景图渲染层）。
• vtable_get_column_values: 按中文列标题批量提取列数据。
• vtable_get_cell_render_info: 读取单元格场景图渲染详情（颜色/背景色/字体/节点）。
• vtable_get_cell_center: 计算单元格中心顶层视口坐标。
• vtable_scroll_to: 精确滚动 VTable 表格到指定行/列/坐标。
• vtable_select_rows: 勾选/取消勾选 Canvas 表格多行复选框。
• vtable_drag_column: 复刻真实鼠标拖拽移动 VTable 列位置。

3. 会话导出工具 (1 个)

• export_session: 结束录制，生成证据 JSON 资产并落盘 Shadcn 极简风格 Excel 报表。

4. Agent SOP 技能

• qa-automation-guide: 提供 SCM/MOM/WMS/ERP 测试矩阵设计模式（Pattern A~E）及 UI 框架穿透路由标准。

---

开发验证与单元测试

在项目修改或扩展后，请执行以下命令进行完整验证：

# 1. 验证 Claude Plugin 清单格式与 Marketplace 架构
claude plugin validate .
claude plugin validate .claude-plugin/plugin.json

# 2. 检查 FastMCP 服务工具装配与状态
uv run fastmcp list src/qa_mcp/server.py

# 3. 运行自动化单元测试套件 (包含 76 个测试用例)
uv run pytest