# https://github.com/browserstack/mcp-server 项目说明书
生成时间：2026-05-31 05:48:18 UTC
## 目录
- [项目概述](#page-1)
- [安装与配置](#page-2)
- [测试管理工具](#page-3)
- [实时测试与自动化工具](#page-4)
- [无障碍扫描工具](#page-5)
- [SDK 集成与框架支持](#page-6)
- [Percy 视觉测试集成](#page-7)
- [AI 智能体功能](#page-8)
- [构建洞察与 Review 智能体](#page-9)
- [架构与代码结构](#page-10)
## 项目概述
### 相关页面
相关主题：[安装与配置](#page-2), [测试管理工具](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/browserstack/mcp-server/blob/main/README.md)
- [package.json](https://github.com/browserstack/mcp-server/blob/main/package.json)
- [src/index.ts](https://github.com/browserstack/mcp-server/blob/main/src/index.ts)
- [src/server-factory.ts](https://github.com/browserstack/mcp-server/blob/main/src/server-factory.ts)
- [src/tools/sdk-utils/common/constants.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/sdk-utils/common/constants.ts)
- [src/tools/sdk-utils/bstack/sdkHandler.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/sdk-utils/bstack/sdkHandler.ts)
- [src/tools/appautomate-utils/appium-sdk/constants.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/appautomate-utils/appium-sdk/constants.ts)
- [src/tools/build-insights.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/build-insights.ts)
# 项目概述
BrowserStack MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器实现，旨在将 BrowserStack 的测试服务与 AI 助手（如 Claude）进行深度集成。通过这个 MCP 服务器，用户可以使用自然语言与 BrowserStack 平台进行交互，完成从测试配置、执行到结果分析的完整测试工作流程。
## 项目定位与核心价值
BrowserStack MCP Server 的核心价值在于**降低测试自动化的门槛**。传统方式下，开发者需要手动编写复杂的配置文件、理解 BrowserStack API 并编写集成代码。通过 MCP 协议，用户可以直接用自然语言描述测试需求，系统自动识别项目技术栈并生成相应的配置和测试代码。
当前版本为 **v1.2.20**，该版本主要修复了 CI 工作流安全加固以及 TLS 证书验证相关问题。
## 技术架构
### 整体架构
```mermaid
graph TD
A[用户自然语言请求] --> B[MCP Server]
B --> C{请求类型识别}
C -->|SDK 配置| D[sdkHandler]
C -->|App 测试| E[appium-sdk]
C -->|视觉测试| F[percy-*]
C -->|测试管理| G[testmanagement-utils]
C -->|构建洞察| H[build-insights]
C -->|可访问性| I[accessibility tools]
D --> J[BrowserStack API]
E --> J
F --> J
G --> J
H --> J
I --> J
J --> K[BrowserStack Cloud]
```
### 核心组件结构
| 组件路径 | 功能描述 | 依赖技术 |
|---------|---------|---------|
| `src/tools/sdk-utils/bstack/` | BrowserStack SDK 集成配置 | TypeScript, YAML |
| `src/tools/sdk-utils/percy-*/` | Percy 视觉测试集成 | Selenium, Playwright |
| `src/tools/appautomate-utils/` | App Automate SDK 集成 | Appium |
| `src/tools/testmanagement-utils/` | 测试用例与计划管理 | BrowserStack TM API |
| `src/tools/build-insights.ts` | 构建洞察与质量门禁 | SonarQube |
## 核心功能模块
### 1. SDK 自动化配置
SDK 配置模块能够根据检测到的项目技术栈自动生成 BrowserStack 配置文件。该模块支持多种编程语言和测试框架的组合，通过分析项目结构自动识别：
- **编程语言**：JavaScript/TypeScript、Python、Java、C#、Ruby
- **自动化框架**：Selenium、Playwright、Cypress、WebDriverIO、Appium
- **测试框架**：JUnit、TestNG、Pytest、Mocha、NUnit
资料来源：[src/tools/sdk-utils/bstack/sdkHandler.ts:1-50]()
### 2. Percy 视觉测试
Percy 集成模块提供完整的视觉回归测试支持，包括三个子模块：
- **percy-web**：Web 应用的快照拍摄
- **percy-automate**：结合 BrowserStack Automate 的视觉测试
- **percy-bstack**：BrowserStack SDK 与 Percy 的联合配置
支持的语言包括 Ruby (Capybara)、C# (.NET)、Java (Playwright)、Python (Selenium) 和 Node.js。
### 3. App Automate 移动测试
App Automate 模块专注于移动应用测试配置，支持：
- Android 和 iOS 真机测试
- Appium 框架集成
- Java 和 C# 语言支持
资料来源：[src/tools/appautomate-utils/appium-sdk/constants.ts:1-30]()
### 4. 测试管理集成
测试管理功能允许用户直接通过 MCP 创建和管理测试用例：
- 创建项目与文件夹结构
- 添加、更新测试用例
- 创建测试计划与测试运行
- 列出子测试计划
### 5. 构建洞察与质量分析
构建洞察模块 (`fetchBuildInsights`) 能够获取构建的详细信息并与 SonarQube 质量门禁结果结合分析，返回内容包括：
- 构建状态统计
- 失败类别分析
- 智能标签
- 唯一错误列表
- CI 构建链接
资料来源：[src/tools/build-insights.ts:50-80]()
## 安装与配置
### 环境要求
| 要求 | 最低版本 |
|-----|---------|
| Node.js | 18.x |
| npm | 8.x |
### 安装步骤
1. 克隆仓库：
```bash
git clone https://github.com/browserstack/mcp-server
cd mcp-server
```
2. 安装依赖：
```bash
npm install
```
3. 构建项目：
```bash
npm run build
```
4. 配置环境变量：
```bash
export BROWSERSTACK_USERNAME="your_username"
export BROWSERSTACK_ACCESS_KEY="your_access_key"
```
### MCP 客户端配置
支持两种配置方式：
| 配置方式 | 适用场景 | 配置内容 |
|---------|---------|---------|
| 本地 MCP | 本地开发调试 | 本地服务器 URL + 认证信息 |
| 远程 MCP | 生产环境使用 | https://mcp.browserstack.com/mcp |
远程 MCP 服务器配置示例：
```json
{
"mcpServers": {
"browserstack": {
"command": "npx",
"args": ["-y", "@browserstack/mcp-server"]
}
}
}
```
## 工具清单
MCP Server 提供的核心工具按照功能可分为以下类别：
### 可访问性测试
| 工具名称 | 功能描述 |
|---------|---------|
| `runAccessibilityScan` | 对本地或生产网站运行可访问性扫描 |
| 高级规则选项 | 支持自定义 WCAG 规则配置 |
### Web 自动化
| 工具名称 | 功能描述 |
|---------|---------|
| `setupBrowserStackTests` | 配置 BrowserStack SDK 进行 Web 自动化测试 |
| `getSessionDetails` | 获取测试会话详细信息 |
### App 自动化
| 工具名称 | 功能描述 |
|---------|---------|
| `setupBrowserStackAppAutomateTests` | 配置 App Automate SDK（仅支持 Appium） |
| `runAppTestsOnBrowserStack` | 运行预构建的 Espresso/XCUITest 测试套件 |
### 测试管理
| 工具名称 | 功能描述 |
|---------|---------|
| `createProject` | 创建测试管理项目 |
| `createFolder` | 在项目中创建文件夹 |
| `createTestCase` | 添加测试用例 |
| `updateTestCase` | 更新测试用例 |
| `listTestCases` | 列出测试用例 |
| `createTestPlan` | 创建测试计划 |
| `listTestPlans` | 列出测试计划 |
| `createTestRun` | 创建测试运行 |
| `updateTestRun` | 更新测试运行结果 |
### 视觉测试
| 工具名称 | 功能描述 |
|---------|---------|
| `setupPercyVisualTests` | 配置 Percy 视觉测试 |
| `percySnapshot` | 拍摄快照 |
| `percySimulate` | 模拟视觉变更 |
### AI 代理
| 工具名称 | 功能描述 |
|---------|---------|
| Self-Heal Agent | 自动修复不稳定的测试脚本 |
| Test Case Generator | 从 PRD 生成测试用例 |
| Low-Code Authoring | 将手动测试转换为低代码自动化 |
## 典型使用场景
### 场景一：配置 Web 自动化测试
用户请求：
> "帮我配置 BrowserStack SDK 用于我的 Cypress 项目"
系统响应流程：
1. 检测到 Cypress 框架
2. 识别项目语言
3. 生成 `browserstack.yml` 配置文件
4. 提供 SDK 安装命令
5. 生成运行测试的命令
### 场景二：移动端视觉测试
用户请求：
> "为我的 Android 应用添加视觉回归测试"
系统响应流程：
1. 检测 Appium 项目结构
2. 生成 App Automate 配置
3. 集成 Percy 快照指令
4. 提供完整的测试运行指南
### 场景三：测试管理与执行
用户请求：
> "在 Test Management 项目 My Demo Project 中添加登录测试用例并创建测试运行"
系统响应流程：
1. 创建/定位指定项目
2. 创建测试用例
3. 创建测试计划
4. 创建测试运行
5. 更新测试结果
## 版本历史与社区反馈
### 近期版本亮点
| 版本 | 主要更新 |
|-----|---------|
| v1.2.20 | CI 工作流安全加固、TLS 验证修复 |
| v1.2.19 | Percy 设置处理器回归防护、环境清理安全修复 |
| v1.2.18 | 新增 listSubTestPlans 和 getSubTestPlan 工具 |
| v1.2.17 | 安全修复：防止文件泄露的路径验证 |
| v1.2.16 | 新增 listTestPlans 和 getTestPlan 工具 |
### 社区关注点
根据社区讨论，以下问题值得关注：
1. **发布说明不够详细**：用户反馈当前发布说明仅显示"See CHANGELOG.md for details"，但 CHANGELOG.md 在仓库中难以找到。
2. **日志与截图获取**：用户希望能直接通过 MCP 获取 Automate 的执行日志和截图，减少在浏览器中手动查看的步骤。
## 安全性注意事项
最新版本中包含以下安全改进：
- **文件上传路径验证**：防止路径遍历攻击
- **环境变量清理**：确保敏感信息正确清理
- **TLS 验证**：启用严格的 TLS 证书验证
## 贡献与支持
欢迎社区贡献！请参阅 [CONTRIBUTING.md](https://github.com/browserstack/mcp-server/blob/main/CONTRIBUTING.md) 了解贡献指南。
如遇到问题，可通过以下方式获取支持：
- 在 [GitHub Issues](https://github.com/browserstack/mcp-server/issues) 提交问题
- 联系 BrowserStack [支持团队](https://www.browserstack.com/contact)
## 延伸阅读
- [MCP 协议规范](https://modelcontextprotocol.io/)
- [BrowserStack 开发者文档](https://www.browserstack.com/docs)
- [Percy 视觉测试文档](https://docs.percy.io/)
---
## 安装与配置
### 相关页面
相关主题：[项目概述](#page-1), [架构与代码结构](#page-10)
相关源码文件
以下源码文件用于生成本页说明：
- [.env.example](https://github.com/browserstack/mcp-server/blob/main/.env.example)
- [src/config.ts](https://github.com/browserstack/mcp-server/blob/main/src/config.ts)
- [src/lib/get-auth.ts](https://github.com/browserstack/mcp-server/blob/main/src/lib/get-auth.ts)
- [src/lib/constants.ts](https://github.com/browserstack/mcp-server/blob/main/src/lib/constants.ts)
- [src/tools/sdk-utils/bstack/sdkHandler.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/sdk-utils/bstack/sdkHandler.ts)
- [src/tools/sdk-utils/bstack/configUtils.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/sdk-utils/bstack/configUtils.ts)
- [src/tools/appautomate-utils/appium-sdk/constants.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/appautomate-utils/appium-sdk/constants.ts)
- [src/tools/sdk-utils/common/schema.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/sdk-utils/common/schema.ts)
# 安装与配置
本文档详细介绍 BrowserStack MCP Server 的安装与配置流程，涵盖环境变量配置、本地部署、远程 MCP 服务器连接以及 SDK 集成配置等内容。
## 系统要求
BrowserStack MCP Server 基于 Node.js 构建，主要依赖环境如下：
| 组件 | 要求 | 说明 |
|------|------|------|
| Node.js | ≥ 18.0.0 | 推荐使用 LTS 版本 |
| npm/yarn | 最新稳定版 | 用于包管理 |
| 操作系统 | Windows/macOS/Linux | 支持主流操作系统 |
| 网络 | 可访问 BrowserStack API | 确保网络畅通 |
## 环境变量配置
MCP Server 通过环境变量进行身份认证和功能配置。环境变量文件采用标准格式，支持多行 YAML 配置。
### 必需的环境变量
| 变量名 | 描述 | 示例值 |
|--------|------|--------|
| `BROWSERSTACK_USERNAME` | BrowserStack 账户用户名 | `john_doe` |
| `BROWSERSTACK_ACCESS_KEY` | BrowserStack 访问密钥 | `xKmXXXXXXXXX` |
| `PERCY_TOKEN` | Percy 项目 Token | `percy_xxxxx` |
### 可选环境变量
| 变量名 | 描述 | 默认值 |
|--------|------|--------|
| `PORT` | MCP 服务器监听端口 | `3000` |
| `HOST` | MCP 服务器绑定地址 | `0.0.0.0` |
| `LOG_LEVEL` | 日志级别 | `info` |
| `CA_CERT_PATH` | CA 证书路径（企业用户） | 空 |
### 环境配置文件示例
```bash
# .env 文件内容
BROWSERSTACK_USERNAME=your_username
BROWSERSTACK_ACCESS_KEY=your_access_key
PERCY_TOKEN=your_percy_token
# MCP 服务器配置（可选）
PORT=3000
HOST=0.0.0.0
# 企业用户 TLS 配置（可选）
CA_CERT_PATH=/path/to/ca-certificate.pem
```
> 资料来源：[.env.example](https://github.com/browserstack/mcp-server/blob/main/.env.example)
## 本地安装
### 方式一：从源码安装
```bash
# 克隆仓库
git clone https://github.com/browserstack/mcp-server.git
cd mcp-server
# 安装依赖
npm install
# 构建项目
npm run build
# 复制并编辑环境变量文件
cp .env.example .env
vim .env # 编辑配置
```
### 方式二：使用 Docker
```bash
# 构建镜像
docker build -t browserstack-mcp-server .
# 运行容器
docker run -d \
--name mcp-server \
-p 3000:3000 \
--env-file .env \
browserstack-mcp-server
```
## MCP 服务器启动方式
### STDIO 模式
适用于与 Claude Desktop 等直接通过标准输入输出通信的客户端集成：
```bash
npm run build
node ./dist/index.js
```
### HTTP 模式
适用于远程连接场景，需要配置 HTTP 端点：
```bash
npm run build
node ./dist/index.js http
```
服务器将启动在配置的 `HOST:PORT` 上，默认监听 `http://0.0.0.0:3000`。
### 远程 MCP 服务器
BrowserStack 提供托管的远程 MCP 服务器，可直接使用：
| 配置项 | 值 |
|--------|-----|
| 服务器 URL | `https://mcp.browserstack.com/mcp` |
| 服务器 ID | `browserstack` |
## SDK 集成配置
MCP Server 支持多种测试框架和语言的 SDK 集成配置，通过分析项目代码自动生成相应的配置指令。
### 支持的编程语言
| 语言 | 标识符 | 框架支持 |
|------|--------|----------|
| Java | `java` | JUnit4, JUnit5, TestNG, Selenide, Cucumber, Behave, Serenity |
| Python | `python` | Pytest, Behave, Robot, Unittest |
| JavaScript | `javascript` | Cypress, Playwright, WebDriverIO, Nightwatch |
| TypeScript | `typescript` | Cypress, Playwright, WebDriverIO, Nightwatch |
| C# | `csharp` | NUnit, xUnit, SpecFlow, MSTest |
| Ruby | `ruby` | Capybara, RSpec |
### 支持的自动化框架
| 框架 | 语言支持 |
|------|----------|
| Selenium | Java, Python, C#, JavaScript, Ruby |
| Playwright | Java, Python, JavaScript, TypeScript, C# |
| WebDriverIO | JavaScript, TypeScript |
| Cypress | JavaScript, TypeScript |
| Appium | Java, Python, JavaScript, C# |
### 平台配置
SDK 支持桌面和移动设备测试配置：
```mermaid
graph TD
A[平台配置] --> B[桌面平台]
A --> C[移动平台]
B --> B1[Windows]
B --> B2[macOS]
C --> C1[Android]
C --> C2[iOS]
```
#### 桌面平台配置结构
```yaml
platform: windows | macos
osVersion: "10" | "11" | "latest" | "oldest"
browser: Chrome | Firefox | Safari | Edge
browserVersion: "latest" | "oldest" | "130"
```
#### 移动平台配置结构
```yaml
deviceName: "Samsung Galaxy S24" | "iPhone 15"
osVersion: "14" | "16" | "latest" | "oldest"
browser: Chrome | Safari
```
> 资料来源：[src/tools/sdk-utils/bstack/configUtils.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/sdk-utils/bstack/configUtils.ts)
### BrowserStack SDK 安装命令
根据检测到的语言和框架，生成对应的 SDK 安装命令：
```mermaid
graph TD
A[检测项目配置] --> B{框架类型}
B -->|Cypress/WebDriverIO| C[框架特定配置]
B -->|其他框架| D[browserstack.yml 配置]
C --> E[生成 setup 指令]
D --> F[生成 SDK 安装命令]
E --> G[生成 run 指令]
F --> G
G --> H[返回配置步骤]
```
```bash
# Java + TestNG
mvn archetype:generate \
-DarchetypeGroupId=com.browserstack \
-DarchetypeArtifactId=junit-archetype-integrate \
-DarchetypeVersion=1.4 \
-DgroupId=com.browserstack \
-DartifactId=testng-test
# Python + Pytest
pip install browserstack-sdk
# Node.js + Playwright
npm install @browserstack/sdk
```
> 资料来源：[src/tools/sdk-utils/bstack/sdkHandler.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/sdk-utils/bstack/sdkHandler.ts)
### browserstack.yml 配置文件
对于非 Cypress/WebDriverIO 框架，配置通过 `browserstack.yml` 文件管理：
```yaml
browserstack:
javascript:
access_key: ${BROWSERSTACK_ACCESS_KEY}
username: ${BROWSERSTACK_USERNAME}
platforms:
- os: Windows
osVersion: "10"
browserName: Chrome
browserVersion: latest
- deviceName: Samsung Galaxy S24
osVersion: "14"
browserName: Chrome
```
> 资料来源：[src/tools/sdk-utils/bstack/configUtils.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/sdk-utils/bstack/configUtils.ts)
## App Automate 配置
针对移动应用测试，BrowserStack MCP Server 提供专用的 App Automate SDK 配置工具。
### App SDK 工具描述
```
Set up BrowserStack App Automate SDK integration for Appium-based mobile app testing.
ONLY for Appium based framework. This tool configures SDK for various languages with appium.
```
### App Automate 支持的配置
| 参数 | 类型 | 描述 |
|------|------|------|
| `detectedFramework` | string | 移动自动化框架（仅支持 `appium`） |
| `detectedTestingFramework` | string | 测试框架（testng, behave, pytest, robot 等） |
| `detectedLanguage` | string | 编程语言（java, csharp） |
| `devices` | array | 目标移动设备元组，最多 3 个 |
### App Automate Maven 配置（Java）
```bash
mvn archetype:generate \
-DarchetypeGroupId=com.browserstack \
-DarchetypeArtifactId=junit-archetype-integrate \
-DarchetypeVersion=1.0 \
-DgroupId=com.browserstack \
-DartifactId=appium-test
```
> 资料来源：[src/tools/appautomate-utils/appium-sdk/constants.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/appautomate-utils/appium-sdk/constants.ts)
## Percy 集成配置
MCP Server 支持两种 Percy 集成类型：
### Percy 集成类型
| 类型 | 标识符 | 描述 |
|------|--------|------|
| Web | `web` | 适用于 Web 应用截图对比 |
| Automate | `automate` | 适用于与 Selenium/Playwright 集成 |
### Percy Token 配置
```bash
# macOS/Linux
export PERCY_TOKEN="your_percy_token"
# Windows PowerShell
$env:PERCY_TOKEN="your_percy_token"
# Windows CMD
set PERCY_TOKEN=your_percy_token
```
> 资料来源：[src/tools/run-percy-scan.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/run-percy-scan.ts)
### Percy Web 配置参数
| 参数 | 类型 | 描述 |
|------|------|------|
| `projectName` | string | Percy 项目唯一名称 |
| `detectedLanguage` | enum | 编程语言枚举 |
| `detectedBrowserAutomationFramework` | enum | 自动化框架枚举 |
| `detectedTestingFramework` | enum | 测试框架枚举 |
| `integrationType` | enum | Percy 集成类型（web/automate） |
| `folderPaths` | array | UI 测试文件夹路径 |
> 资料来源：[src/tools/sdk-utils/common/schema.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/sdk-utils/common/schema.ts)
## 身份认证机制
MCP Server 使用 API Token 方式进行身份认证。
### 认证流程
```mermaid
sequenceDiagram
participant User
participant MCP as MCP Server
participant BS as BrowserStack API
User->>MCP: 配置环境变量
MCP->>BS: 发送认证请求
BS-->>MCP: 验证成功/失败
MCP-->>User: 返回认证状态
```
### 认证方式
```typescript
// 方式一：环境变量
BROWSERSTACK_USERNAME=xxx
BROWSERSTACK_ACCESS_KEY=xxx
// 方式二：API Token（内部使用）
headers: {
"API-TOKEN": getBrowserStackAuth(config)
}
```
> 资料来源：[src/lib/get-auth.ts](https://github.com/browserstack/mcp-server/blob/main/src/lib/get-auth.ts)
## TLS/SSL 配置
对于需要严格 TLS 验证的企业用户，MCP Server 支持自定义 CA 证书配置：
| 配置项 | 描述 |
|--------|------|
| `CA_CERT_PATH` | CA 证书文件路径 |
| 证书格式 | PEM 格式 |
启用严格 TLS 验证：
```bash
# 设置 CA 证书路径
CA_CERT_PATH=/path/to/enterprise-ca-cert.pem
# 服务器将启用严格 TLS 验证
```
> 资料来源：[v1.2.20 安全修复](https://github.com/browserstack/mcp-server/pull/309)
## 验证配置
启动 MCP Server 后，可通过以下方式验证配置是否正确：
### 1. 检查服务器状态
```bash
# STDIO 模式启动后，观察日志输出
npm run build && node ./dist/index.js
```
### 2. 测试可用工具
配置完成后，以下工具应可正常使用：
| 功能模块 | 工具示例 |
|----------|----------|
| 自动化测试 | `setupBrowserStackTests`, `runBrowserStackTests` |
| 移动应用测试 | `setupBrowserStackAppAutomateTests`, `runAppTestsOnBrowserStack` |
| Percy 集成 | `setupPercy`, `runPercySnapshot` |
| 测试管理 | `createTestCase`, `listTestCases`, `updateTestCase` |
| 实时测试 | `createLiveTest`, `getLiveTestDetails` |
| 构建洞察 | `fetchBuildInsights` |
## 常见配置问题
### 问题：认证失败
**解决方案**：
1. 确认 `BROWSERSTACK_USERNAME` 和 `BROWSERSTACK_ACCESS_KEY` 正确
2. 检查环境变量是否正确加载
3. 验证 BrowserStack 账户状态是否正常
### 问题：平台配置无效
**解决方案**：
1. 检查 `osVersion` 是否为支持的版本
2. 确认 `browserVersion` 参数格式正确
3. 对于移动设备，确保 `deviceName` 存在于 BrowserStack 设备列表中
### 问题：Percy Token 未识别
**解决方案**：
1. 确保 `PERCY_TOKEN` 环境变量已设置
2. Token 不应直接粘贴到对话中或提交到代码库
3. 使用 `.env` 文件或 shell 导出方式配置
## 进阶配置
### 自定义日志级别
```bash
LOG_LEVEL=debug npm run build && node ./dist/index.js
```
支持级别：`error`, `warn`, `info`, `debug`, `trace`
### 代理配置
如需通过代理访问 BrowserStack API，在环境变量中配置：
```bash
HTTP_PROXY=http://proxy.example.com:8080
HTTPS_PROXY=http://proxy.example.com:8080
---
## 测试管理工具
### 相关页面
相关主题：[实时测试与自动化工具](#page-4), [AI 智能体功能](#page-8)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/testmanagement.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/testmanagement.ts)
- [src/tools/testmanagement-utils/create-project-folder.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/testmanagement-utils/create-project-folder.ts)
- [src/tools/testmanagement-utils/create-testcase.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/testmanagement-utils/create-testcase.ts)
- [src/tools/testmanagement-utils/list-testcases.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/testmanagement-utils/list-testcases.ts)
- [src/tools/testmanagement-utils/create-testrun.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/testmanagement-utils/create-testrun.ts)
- [src/tools/testmanagement-utils/list-testplans.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/testmanagement-utils/list-testplans.ts)
- [src/tools/testmanagement-utils/get-testplan.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/testmanagement-utils/get-testplan.ts)
- [src/tools/testmanagement-utils/list-sub-testplans.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/testmanagement-utils/list-sub-testplans.ts)
- [src/tools/testmanagement-utils/get-sub-testplan.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/testmanagement-utils/get-sub-testplan.ts)
- [src/tools/testmanagement-utils/list-folders.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/testmanagement-utils/list-folders.ts)
- [src/tools/testmanagement-utils/TCG-utils/api.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/testmanagement-utils/TCG-utils/api.ts)
- [src/tools/testmanagement-utils/TCG-utils/types.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/testmanagement-utils/TCG-utils/types.ts)
# 测试管理工具
## 概述
测试管理工具（Test Management Tools）是 BrowserStack MCP Server 的核心功能模块之一，专门用于与 BrowserStack Test Management 平台进行集成。该模块提供了一套完整的 MCP 工具集，允许用户通过自然语言指令创建、管理和组织测试用例、测试计划和测试运行。
测试管理工具支持以下主要功能：
- 创建和管理项目及文件夹结构
- 创建、读取、更新测试用例
- 创建测试运行并更新测试结果
- 管理测试计划（包括子测试计划）
- 从文档文件批量导入测试用例
该模块在 v1.2.16 版本中新增了 `listTestPlans` 和 `getTestPlan` 工具，在 v1.2.18 版本中进一步扩展了子测试计划的管理能力，添加了 `listSubTestPlans` 和 `getSubTestPlan` 工具。资料来源：[v1.2.16 Release Notes](https://github.com/browserstack/mcp-server/releases/tag/v1.2.16)、[v1.2.18 Release Notes](https://github.com/browserstack/mcp-server/releases/tag/v1.2.18)
## 架构设计
### 模块结构
测试管理工具采用分层架构设计，核心模块位于 `src/tools/testmanagement-utils/` 目录下：
```
src/tools/testmanagement-utils/
├── TCG-utils/
│ ├── api.ts # 底层 API 调用封装
│ └── types.ts # TypeScript 类型定义
├── create-project-folder.ts # 项目/文件夹创建
├── create-testcase.ts # 测试用例创建
├── list-testcases.ts # 测试用例列表
├── create-testrun.ts # 测试运行创建
├── list-testplans.ts # 测试计划列表
├── get-testplan.ts # 获取测试计划详情
├── list-sub-testplans.ts # 子测试计划列表
├── get-sub-testplan.ts # 获取子测试计划详情
└── list-folders.ts # 文件夹列表
```
### 数据流架构
```mermaid
graph TD
A[MCP 客户端请求] --> B[testmanagement.ts]
B --> C{功能路由分发}
C -->|创建项目| D[create-project-folder.ts]
C -->|创建用例| E[create-testcase.ts]
C -->|查询用例| F[list-testcases.ts]
C -->|测试计划| G[list-testplans.ts / get-testplan.ts]
C -->|子测试计划| H[list-sub-testplans.ts / get-sub-testplan.ts]
C -->|文件夹| I[list-folders.ts]
D --> J[TCG-utils/api.ts]
E --> J
F --> J
G --> J
H --> J
I --> J
J --> K[BrowserStack Test Management API]
```
## 核心功能
### 1. 项目与文件夹管理
项目和文件夹是测试管理的基础组织单元。用户可以通过自然语言描述创建项目结构。
**主要工具**：
| 工具名称 | 功能描述 |
|---------|---------|
| `createProjectFolder` | 创建新的测试管理项目或文件夹 |
**创建项目示例**：
```bash
# 创建新项目和子文件夹
"create new Test management project named My Demo Project with two sub folders - Login & Checkout"
```
资料来源：[create-project-folder.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/testmanagement-utils/create-project-folder.ts)
### 2. 测试用例管理
测试用例管理模块提供了完整的 CRUD 操作能力，支持从文档文件批量导入测试用例。
**主要工具**：
| 工具名称 | 功能描述 |
|---------|---------|
| `createTestCase` | 创建单个测试用例 |
| `createTestCasesFromFile` | 从文档批量创建测试用例 |
| `listTestCases` | 列出并过滤测试用例 |
| `updateTestCase` | 更新现有测试用例 |
**数据类型映射**：
```typescript
interface DefaultFieldMaps {
priority: Record;
status: Record;
caseType: Record;
}
```
资料来源：[types.ts:18-22](https://github.com/browserstack/mcp-server/blob/main/src/tools/testmanagement-utils/TCG-utils/types.ts)
**创建测试用例示例**：
```bash
# 添加登录失败测试用例
"add invalid login test case in Test Management project named My Demo Project"
# 列出高优先级用例
"list high priority Login test cases from Test Management project - My Demo Project"
```
### 3. 测试运行管理
测试运行用于组织和执行一组测试用例，并记录测试结果。
**主要工具**：
| 工具名称 | 功能描述 |
|---------|---------|
| `createTestRun` | 创建新的测试运行 |
| `updateTestRun` | 更新测试运行状态和结果 |
**创建测试运行示例**：
```bash
# 创建测试运行
"create a test run for Login tests from Test Management project - My Demo Project"
# 更新测试结果
"update test results as passed for Login tests test run from My Demo Project"
```
### 4. 测试计划管理
测试计划用于组织和管理相关测试用例的集合，支持层级结构（父计划与子计划）。
**主要工具**：
| 工具名称 | 功能描述 | 引入版本 |
|---------|---------|---------|
| `listTestPlans` | 列出项目中的测试计划 | v1.2.16 |
| `getTestPlan` | 获取测试计划详情 | v1.2.16 |
| `listSubTestPlans` | 列出子测试计划 | v1.2.18 |
| `getSubTestPlan` | 获取子测试计划详情 | v1.2.18 |
**功能演进**：
```mermaid
graph LR
A[v1.2.16] -->|新增| B[listTestPlans]
A -->|新增| C[getTestPlan]
D[v1.2.18] -->|扩展| E[listSubTestPlans]
D -->|扩展| F[getSubTestPlan]
```
资料来源：[#283 PR](https://github.com/browserstack/mcp-server/pull/283)、[#301 PR](https://github.com/browserstack/mcp-server/pull/301)
### 5. 文件夹管理
文件夹提供了在项目内部组织测试用例的额外层级结构。
**主要工具**：
| 工具名称 | 功能描述 | 引入版本 |
|---------|---------|---------|
| `listFolders` | 列出项目中的文件夹 | v1.2.16 |
资料来源：[#280 PR](https://github.com/browserstack/mcp-server/pull/280)
## API 接口层
底层 API 封装位于 `src/tools/testmanagement-utils/TCG-utils/api.ts`，提供了与 BrowserStack Test Management API 的通信能力。
### API 封装结构
```typescript
// API 层主要职责
- HTTP 请求封装
- 认证头处理
- 错误处理和重试
- 响应数据转换
- API 端点管理
```
资料来源：[api.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/testmanagement-utils/TCG-utils/api.ts)
### 请求处理流程
```mermaid
sequenceDiagram
participant MCP as MCP 客户端
participant TM as testmanagement.ts
participant Utils as 工具函数
participant API as TCG-utils/api.ts
participant BS as BrowserStack API
MCP->>TM: 请求测试操作
TM->>Utils: 调用具体工具
Utils->>API: 构建 API 请求
API->>BS: 发送 HTTP 请求
BS-->>API: 返回响应数据
API-->>Utils: 处理响应
Utils-->>TM: 返回格式化结果
TM-->>MCP: 返回 MCP 响应
```
## 数据模型
### CreateTestCasesFromFileSchema
从文档创建测试用例时使用的 Zod schema 定义：
```typescript
const CreateTestCasesFromFileSchema = z.object({
documentId: z.string().describe("内部文档标识符"),
folderId: z.string().describe("BrowserStack 文件夹 ID"),
projectReferenceId: z.string().describe(
"BrowserStack 项目引用 ID，是 Test Management 平台项目 URL 中的唯一标识符，也在 Upload Document 工具的返回值中提供"
),
});
```
资料来源：[types.ts:1-15](https://github.com/browserstack/mcp-server/blob/main/src/tools/testmanagement-utils/TCG-utils/types.ts)
### Scenario 接口
场景数据模型定义：
```typescript
interface Scenario {
id: string;
name: string;
testcases: any[];
traceId?: string;
}
```
资料来源：[types.ts:24-29](https://github.com/browserstack/mcp-server/blob/main/src/tools/testmanagement-utils/TCG-utils/types.ts)
## 使用场景与示例
### 典型工作流程
```mermaid
graph TD
A[创建项目] --> B[创建文件夹结构]
B --> C[添加测试用例]
C --> D[创建测试计划]
D --> E[组织子测试计划]
E --> F[创建测试运行]
F --> G[执行测试]
G --> H[更新测试结果]
```
### 完整使用示例
**场景：管理登录功能测试**
```bash
# 步骤 1: 创建项目
"create new Test management project named My Demo Project with two sub folders - Login & Checkout"
# 步骤 2: 添加测试用例
"add invalid login test case in Test Management project named My Demo Project"
# 步骤 3: 列出高优先级用例
"list high priority Login test cases from Test Management project - My Demo Project"
# 步骤 4: 创建测试运行
"create a test run for Login tests from Test Management project - My Demo Project"
# 步骤 5: 更新测试结果
"update test results as passed for Login tests test run from My Demo Project"
```
资料来源：[README.md - Test Management](https://github.com/browserstack/mcp-server/blob/main/README.md)
## 配置与依赖
### 环境要求
- Node.js 运行环境
- BrowserStack 账户（需配置 username 和 access_key）
- BrowserStack Test Management 功能订阅
### 认证配置
测试管理工具通过 MCP Server 的全局配置获取 BrowserStack 认证凭证：
```typescript
// 认证信息通过 config 参数传递
addTestManagementTools(server, config) {
// config.username - BrowserStack 用户名
// config.accessKey - BrowserStack 访问密钥
}
```
## 版本历史
| 版本 | 更新内容 | 相关 PR |
|-----|---------|---------|
| v1.2.18 | 新增 listSubTestPlans 和 getSubTestPlan 工具 | [#301](https://github.com/browserstack/mcp-server/pull/301) |
| v1.2.16 | 新增 listTestPlans、getTestPlan、listFolders 工具 | [#283](https://github.com/browserstack/mcp-server/pull/283)、[#280](https://github.com/browserstack/mcp-server/pull/280) |
| v1.2.8 | 重构 TM API URL 使用动态基础 URL 获取 | [#181](https://github.com/browserstack/mcp-server/pull/181) |
## 相关资源
- [BrowserStack Test Management 官方文档](https://www.browserstack.com/test-management)
- [MCP Server 官方仓库](https://github.com/browserstack/mcp-server)
- [测试管理工具源码](https://github.com/browserstack/mcp-server/tree/main/src/tools/testmanagement-utils)
---
## 实时测试与自动化工具
### 相关页面
相关主题：[测试管理工具](#page-3), [SDK 集成与框架支持](#page-6)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/applive.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/applive.ts)
- [src/tools/live.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/live.ts)
- [src/tools/automate.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/automate.ts)
- [src/tools/appautomate.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/appautomate.ts)
- [src/tools/applive-utils/start-session.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/applive-utils/start-session.ts)
- [src/tools/applive-utils/device-search.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/applive-utils/device-search.ts)
- [src/tools/live-utils/start-session.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/live-utils/start-session.ts)
- [src/tools/automate-utils/fetch-screenshots.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/automate-utils/fetch-screenshots.ts)
- [src/tools/get-failure-logs.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/get-failure-logs.ts)
- [src/tools/failurelogs-utils/automate.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/failurelogs-utils/automate.ts)
- [src/tools/failurelogs-utils/app-automate.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/failurelogs-utils/app-automate.ts)
# 实时测试与自动化工具
## 概述
实时测试与自动化工具是 BrowserStack MCP Server 的核心功能模块，为开发者提供通过自然语言与 BrowserStack 测试平台交互的能力。该模块包含四大主要工具集：
| 工具集 | 用途 | 目标平台 |
|--------|------|----------|
| **App Live** | 实时交互式移动设备测试 | Android、iOS |
| **App Automate** | 自动化移动应用测试 | Android、iOS |
| **Live** | 实时交互式浏览器测试 | 桌面浏览器 |
| **Automate** | 自动化浏览器测试 | 跨浏览器 |
这些工具通过 MCP（Model Context Protocol）协议与 AI 助手集成，使用户能够通过自然语言描述来启动测试会话、获取截图、日志和失败详情。
## 架构概览
```mermaid
graph TD
A[用户请求 - 自然语言] --> B[MCP Server]
B --> C{工具路由}
C -->|移动端| D[App Live / App Automate]
C -->|Web端| E[Live / Automate]
D --> F[BrowserStack API]
E --> F
F --> G[设备/浏览器集群]
G --> H[测试会话/结果]
H --> I[用户]
D --> J[失败日志模块]
E --> J
J --> K[日志分析工具]
```
## App Live 工具
### 功能说明
App Live 工具支持用户通过自然语言在真实移动设备上进行交互式测试，无需编写测试脚本。开发者可以实时操作设备、截取屏幕截图并记录测试会话。
### 核心工具
#### 1. startAppLiveSession
启动 App Live 测试会话。
**参数说明：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| device | string | 是 | 设备名称，如 "Samsung Galaxy S24" |
| osVersion | string | 是 | 操作系统版本，如 "14", "17" |
| appFile | string | 是 | 应用文件路径（.apk 或 .ipa） |
| duration | number | 否 | 会话持续时间（秒），默认 300 |
**源码位置：** `src/tools/applive-utils/start-session.ts`
#### 2. deviceSearch
搜索可用的移动设备。
**参数说明：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| query | string | 是 | 设备搜索关键词 |
| deviceFilter | string | 否 | 设备过滤条件 |
**源码位置：** `src/tools/applive-utils/device-search.ts`
### 工作流程
```mermaid
sequenceDiagram
用户->>MCP: "在 Samsung Galaxy S24 上测试我的应用"
MCP->>App Live: 解析设备参数
App Live->>BrowserStack: 验证应用文件
BrowserStack->>设备集群: 分配设备
设备集群-->>用户: 返回会话URL
用户->>设备: 实时交互操作
用户->>MCP: "获取截图"
MCP->>BrowserStack: 请求截图
BrowserStack-->>用户: 返回截图数据
```
## App Automate 工具
### 功能说明
App Automate 工具用于在真实移动设备上运行自动化测试脚本，支持多种测试框架和 Appium SDK 集成。
### 核心工具
#### setupAppAutomateTests
配置 App Automate SDK 集成。
**支持的框架：** `appium`
**支持的测试框架：**
| 语言 | 支持的测试框架 |
|------|----------------|
| Java | testng, junit4, junit5, selenide, cucumber, serenity, behave |
| Python | pytest, behave, lettuce, robot |
| Node.js | webdriverio, nightwatch, jest, mocha, cucumber |
| Ruby | rspec, cucumber |
| C# | nunit, mstest, xunit, specflow, reqnroll |
**源码位置：** `src/tools/appautomate-utils/appium-sdk/handler.ts`
#### runAppTestsOnBrowserStack
在 BrowserStack 上运行预构建的 Espresso 或 XCUITest 测试套件。
**源码位置：** `src/tools/appautomate.ts`
### App SDK 配置生成
App Automate 工具会根据检测到的项目配置自动生成相应的 SDK 集成指令，包括：
1. **browserstack.yml 配置** - 定义测试环境和设备平台
2. **项目依赖配置** - Maven/Gradle/Podfile 依赖
3. **应用上传指令** - 如何上传 .apk 或 .ipa 文件
**配置示例：**
```yaml
platforms:
- deviceName: "Samsung Galaxy S24"
osVersion: "14"
browserName: "android"
```
## Live 工具
### 功能说明
Live 工具提供实时浏览器测试能力，支持在多种操作系统和浏览器上进行交互式测试。
### 核心工具
#### startLiveSession
启动 Live 浏览器测试会话。
**参数说明：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| os | string | 是 | 操作系统，如 "Windows", "OS X" |
| osVersion | string | 是 | 系统版本，如 "10", "14" |
| browser | string | 是 | 浏览器名称，如 "Chrome", "Firefox" |
| browserVersion | string | 否 | 浏览器版本，默认 "latest" |
| url | string | 否 | 初始测试 URL |
**源码位置：** `src/tools/live-utils/start-session.ts`
## Automate 工具
### 功能说明
Automate 工具支持在 BrowserStack 托管的浏览器上运行 Selenium/WebDriver 自动化测试。
### 核心工具
#### fetchScreenshots
获取自动化测试的屏幕截图。
**参数说明：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| buildId | string | 是 | 构建 ID |
| sessionId | string | 否 | 会话 ID |
**源码位置：** `src/tools/automate-utils/fetch-screenshots.ts`
### WDIO 集成
MCP Server 与 WebDriverIO (WDIO) 深度集成，支持使用自然语言配置和运行 WDIO 测试套件。
> ⚠️ **已知问题**：早期版本（v1.2.11/v1.2.12）中存在 WDIO 集成在 Windows 机器上无法正确重定向的问题，已在后续版本中修复。
## 失败日志工具
### 功能说明
失败日志工具用于从自动化测试运行中检索失败测试的详细日志，帮助开发者快速定位问题根因。
### 核心工具
#### getFailureLogs
获取失败测试的日志信息。
**参数说明：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| buildId | string | 是 | 构建 ID |
| testStatus | string | 否 | 测试状态过滤，默认 "failed" |
**返回数据：**
| 字段 | 说明 |
|------|------|
| sessionUrl | BrowserStack 会话链接 |
| logs | 失败日志内容 |
| screenshotUrl | 失败时的截图链接 |
| videoUrl | 测试执行视频链接 |
**源码位置：** `src/tools/get-failure-logs.ts`
### 日志处理模块
失败日志工具根据目标平台使用不同的处理模块：
| 平台 | 处理模块 | 源码位置 |
|------|----------|----------|
| Automate | `failurelogs-utils/automate.ts` | 处理 Web 自动化日志 |
| App Automate | `failurelogs-utils/app-automate.ts` | 处理移动端自动化日志 |
```mermaid
graph LR
A[getFailureLogs] --> B{判断平台类型}
B -->|Web| C[automate.ts]
B -->|移动端| D[app-automate.ts]
C --> E[获取 Selenium Logs]
D --> F[获取 Appium Logs]
E --> G[返回日志数据]
F --> G
```
## 数据模型
### 设备配置模型
```typescript
interface DeviceConfig {
deviceName?: string; // 移动设备名称
os?: string; // 操作系统 (Windows/OS X/Android/iOS)
osVersion: string; // 系统版本
browserName?: string; // 浏览器名称
browserVersion?: string; // 浏览器版本
}
```
### 会话响应模型
```typescript
interface SessionResponse {
sessionId: string; // 会话唯一标识
sessionUrl: string; // BrowserStack 会话链接
device?: string; // 分配的设备信息
status: 'SUCCESS' | 'ERROR';
}
```
## 使用示例
### 示例 1：启动 App Live 会话
```
用户：启动一个 App Live 会话，在 Samsung Galaxy S24（Android 14）上测试我的应用
MCP 工具：startAppLiveSession
参数：
{
"device": "Samsung Galaxy S24",
"osVersion": "14",
"appFile": "./app-debug.apk",
"duration": 600
}
```
### 示例 2：获取失败日志
```
用户：获取构建 build_abc123 的失败测试日志
MCP 工具：getFailureLogs
参数：
{
"buildId": "build_abc123",
"testStatus": "failed"
}
```
## 版本历史
| 版本 | 变更内容 |
|------|----------|
| v1.2.20 | 修复 CI 工作流安全问题，启用严格 TLS 验证 |
| v1.2.19 | 修复环境清理安全问题 |
| v1.2.18 | 扩展 self-heal 工具支持构建 |
| v1.2.17 | 修复测试用例更新步骤，添加路径验证防止文件泄露 |
| v1.2.12 | 添加 Accessibility Scan 超时配置 |
| v1.2.11 | 修复 Windows 机器上 Live 工具重定向问题 |
| v1.2.7 | 修复 Live 工具在 Windows 上的会话重定向 |
| v1.2.5 | 添加 Appium Java 支持，添加 Percy 模拟工具 |
## 社区反馈
### 高优先级需求
**Issue #25：获取自动化日志和截图工具**（4 条评论）
用户反馈：在使用 Automate 和 App Automate 时，测试失败后会打印 BrowserStack 会话 URL，用户需要手动打开 URL 来查看视频录制和日志。社区强烈请求通过 MCP 工具直接获取这些信息。
**当前解决方案：** 已通过 `fetchScreenshots` 和 `getFailureLogs` 工具满足此需求。
### 安全改进
近期版本（v1.2.17+）增强了安全措施：
- 添加文件上传路径验证，防止路径遍历攻击
- 修复环境变量清理机制
- 强化 CI 工作流安全性
## 相关文档
- [SDK 工具配置](./sdk-tools.md) - SDK 集成详细指南
- [Percy 可视化测试](./percy-tools.md) - 视觉回归测试集成
- [测试管理工具](./test-management.md) - 测试用例和计划管理
---
## 无障碍扫描工具
### 相关页面
相关主题：[项目概述](#page-1), [实时测试与自动化工具](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/accessibility.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/accessibility.ts)
- [src/tools/accessiblity-utils/scanner.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/accessiblity-utils/scanner.ts)
- [src/tools/accessiblity-utils/report-parser.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/accessiblity-utils/report-parser.ts)
- [src/tools/accessiblity-utils/accessibility-rag.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/accessiblity-utils/accessibility-rag.ts)
- [src/tools/accessiblity-utils/report-fetcher.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/accessiblity-utils/report-fetcher.ts)
# 无障碍扫描工具
## 概述
无障碍扫描工具是 BrowserStack MCP Server 的核心功能之一，通过自然语言交互帮助开发者扫描并修复网站的无障碍（Accessibility）问题。该工具集成于 BrowserStack 平台，支持对本地的开发环境（localhost）和生产环境网站进行自动化无障碍审计。
根据社区发布记录，该功能在 **v1.2.12** 版本中首次引入超时机制支持（#239），并在 **v1.2.13** 和 **v1.2.14** 版本中持续增强，新增了高级规则选项配置（#252）。
## 核心功能
| 功能类别 | 描述 | 支持版本 |
|---------|------|---------|
| 本地站点扫描 | 扫描 localhost 开发环境 | v1.2.12+ |
| 生产环境扫描 | 扫描线上生产网站 | v1.2.12+ |
| 超时配置 | 自定义扫描超时时间 | v1.2.12+ |
| 高级规则 | 自定义无障碍规则集 | v1.2.13+ |
| 问题修复建议 | 提供可操作的无障碍问题修复方案 | v1.2.12+ |
## 工具架构
无障碍扫描工具采用模块化架构设计，包含以下核心组件：
```mermaid
graph TD
A[用户请求] --> B[accessibility.ts 工具入口]
B --> C[scanner.ts 扫描引擎]
C --> D[report-fetcher.ts 报告获取]
D --> E[report-parser.ts 报告解析]
E --> F[accessibility-rag.ts RAG修复建议]
F --> G[返回扫描结果与修复建议]
H[BrowserStack API] --> D
```
### 组件说明
| 组件文件 | 功能职责 |
|---------|---------|
| `accessibility.ts` | MCP 工具定义、参数验证、工具入口 |
| `scanner.ts` | 执行无障碍扫描的核心扫描引擎 |
| `report-parser.ts` | 解析扫描报告，提取问题列表 |
| `accessibility-rag.ts` | 基于 RAG 技术生成问题修复建议 |
| `report-fetcher.ts` | 与 BrowserStack API 交互获取扫描结果 |
## 使用方式
### 基本语法
无障碍扫描工具支持两种主要使用场景：
#### 1. 本地开发环境扫描
```
"帮我扫描 localhost:3000 上运行网站的 accessibility 问题"
```
#### 2. 生产环境扫描
```
"运行 accessibility scan & 识别我的网站 www.bstackdemo.com 上的问题"
```
### 高级规则配置
在 v1.2.14 版本中新增的高级规则选项，允许用户指定特定的 WCAG 标准进行扫描：
| 规则级别 | WCAG 标准 | 说明 |
|---------|----------|------|
| A | WCAG 2.0 Level A | 基础无障碍要求 |
| AA | WCAG 2.0/2.1 Level AA | 标准无障碍要求（默认） |
| AAA | WCAG 2.0/2.1 Level AAA | 最高无障碍标准 |
| 最新 | WCAG 3.0 | 最新无障碍标准 |
## 工具参数定义
根据源码中的 Zod schema 定义，无障碍扫描工具支持以下参数：
```typescript
// 参数结构定义示例
{
url: z.string().describe("待扫描的目标 URL"),
standard: z.enum(["A", "AA", "AAA", "latest"]).optional(),
timeout: z.number().optional(),
waitUntil: z.enum(["load", "domcontentloaded", "networkidle"]).optional()
}
```
| 参数名称 | 类型 | 必填 | 默认值 | 描述 |
|---------|------|------|-------|------|
| `url` | string | 是 | - | 目标网站 URL |
| `standard` | enum | 否 | "AA" | WCAG 合规标准级别 |
| `timeout` | number | 否 | 30000 | 扫描超时时间（毫秒） |
| `waitUntil` | enum | 否 | "load" | 页面加载策略 |
## 扫描流程
```mermaid
sequenceDiagram
participant U as 用户
participant M as MCP Server
participant S as Scanner
participant API as BrowserStack API
participant RAG as RAG Engine
U->>M: 发送扫描请求
M->>S: 初始化扫描任务
S->>API: 调用无障碍扫描 API
API-->>S: 返回扫描任务 ID
loop 轮询状态
S->>API: 查询扫描状态
API-->>S: 返回进度/结果
end
S->>API: 获取扫描报告
API-->>S: 返回原始报告
S->>RAG: 提交报告获取修复建议
RAG-->>S: 返回结构化修复建议
M->>U: 返回完整扫描结果
```
## 报告解析机制
`report-parser.ts` 组件负责将 BrowserStack API 返回的原始扫描报告转换为结构化数据：
```typescript
// 报告数据结构
interface AccessibilityReport {
url: string;
timestamp: string;
issues: AccessibilityIssue[];
summary: {
passed: number;
warnings: number;
failures: number;
};
}
interface AccessibilityIssue {
id: string;
severity: "critical" | "major" | "minor" | "recommendation";
wcagCriterion: string;
description: string;
element: string;
suggestion: string;
}
```
## RAG 修复建议系统
`accessibility-rag.ts` 实现基于检索增强生成的修复建议系统：
```mermaid
graph LR
A[扫描报告] --> B[问题提取]
B --> C[知识库检索]
C --> D[上下文组装]
D --> E[LLM 生成]
E --> F[结构化修复建议]
C -.-> G[WCAG 2.1 规则库]
C -.-> H[最佳实践库]
C -.-> I[代码示例库]
```
该系统利用预先构建的 WCAG 合规知识库，为每个识别出的无障碍问题提供：
- 问题根因分析
- WCAG 标准引用
- 具体修复代码示例
- 修复前后对比
## 与其他 MCP 工具的集成
无障碍扫描工具可与其他 BrowserStack MCP Server 工具配合使用，形成完整的测试工作流：
| 集成工具 | 集成场景 |
|---------|---------|
| SDK 集成工具 | 扫描 SDK 测试页面 |
| Live 工具 | 实时调试无障碍问题 |
| Percy 工具 | 视觉无障碍对比 |
| 测试管理工具 | 将问题导入测试用例 |
## 版本历史
| 版本 | 更新内容 | PR |
|-----|---------|-----|
| v1.2.14 | 新增高级规则选项配置 | #252 |
| v1.2.13 | 新增高级规则选项 | #252, #240 |
| v1.2.12 | 添加扫描超时配置 | #239 |
## 常见问题
### 扫描超时
如果网站加载时间过长，可通过 `timeout` 参数增加超时时间：
```
"扫描 www.example.com 的 accessibility 问题，超时时间设置为 60 秒"
```
### 本地环境访问
对于 localhost 环境，确保服务已启动并可从 MCP Server 所在网络访问。
### 高级规则选择
建议生产环境使用 "AA" 标准进行扫描，兼顾覆盖面与严格程度。
## 参考资料
- BrowserStack 官方文档：[BrowserStack Accessibility Testing](https://www.browserstack.com/docs/accessibility-testing)
- WCAG 2.1 规范：[W3C WCAG 2.1](https://www.w3.org/TR/WCAG21/)
- 工具源码：[src/tools/accessibility.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/accessibility.ts)
---
## SDK 集成与框架支持
### 相关页面
相关主题：[Percy 视觉测试集成](#page-7), [实时测试与自动化工具](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/sdk-utils/common/types.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/sdk-utils/common/types.ts)
- [src/tools/sdk-utils/common/index.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/sdk-utils/common/index.ts)
- [src/tools/sdk-utils/percy-web/types.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/sdk-utils/percy-web/types.ts)
- [src/tools/sdk-utils/percy-bstack/types.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/sdk-utils/percy-bstack/types.ts)
- [src/tools/sdk-utils/percy-automate/types.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/sdk-utils/percy-automate/types.ts)
- [src/tools/appautomate-utils/appium-sdk/types.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/appautomate-utils/appium-sdk/types.ts)
- [src/tools/appautomate-utils/appium-sdk/languages/java.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/appautomate-utils/appium-sdk/languages/java.ts)
- [src/tools/appautomate-utils/appium-sdk/languages/python.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/appautomate-utils/appium-sdk/languages/python.ts)
- [src/tools/appautomate-utils/appium-sdk/languages/ruby.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/appautomate-utils/appium-sdk/languages/ruby.ts)
- [src/tools/appautomate-utils/appium-sdk/constants.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/appautomate-utils/appium-sdk/constants.ts)
- [src/tools/appautomate-utils/appium-sdk/instructions.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/appautomate-utils/appium-sdk/instructions.ts)
- [src/tools/appautomate-utils/appium-sdk/handler.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/appautomate-utils/appium-sdk/handler.ts)
- [src/tools/appautomate-utils/native-execution/constants.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/appautomate-utils/native-execution/constants.ts)
# SDK 集成与框架支持
BrowserStack MCP Server 提供了强大的 SDK 集成功能，支持多种编程语言和测试框架，帮助开发者在 BrowserStack 平台上快速配置和运行自动化测试。本页面详细介绍 SDK 集成的架构设计、支持的语言和框架，以及具体的使用方式。
## 系统架构概述
SDK 集成模块采用分层架构设计，将通用功能与特定框架实现解耦。系统主要由以下几个核心模块组成：
| 模块 | 位置 | 职责 |
|------|------|------|
| SDK 工具处理器 | `src/tools/sdk-utils/` | SDK 工具的核心业务逻辑处理 |
| Appium SDK 集成 | `src/tools/appautomate-utils/appium-sdk/` | Appium 移动端测试 SDK 配置 |
| Percy 可视化测试 | `src/tools/sdk-utils/percy-*` | Percy 截图对比测试集成 |
| 通用类型定义 | `src/tools/sdk-utils/common/types.ts` | 跨模块共享的类型定义 |
| 语言特定实现 | `src/tools/appautomate-utils/appium-sdk/languages/` | 各语言的指令生成和命令 |
```mermaid
graph TD
A[SDK 工具请求] --> B[SDK Utils Handler]
B --> C{集成类型判断}
C -->|Appium| D[Appium SDK Handler]
C -->|Percy Web| E[Percy Web Handler]
C -->|Percy Automate| F[Percy Automate Handler]
C -->|Percy BStack| G[Percy BrowserStack Handler]
D --> H[语言特定处理器]
H --> I1[Java]
H --> I2[Python]
H --> I3[Ruby]
H --> I4[C#]
H --> I5[Node.js]
I1 --> J[生成配置和指令]
I2 --> J
I3 --> J
I4 --> J
I5 --> J
J --> K[返回格式化指令]
```
## 支持的编程语言
BrowserStack MCP Server 的 SDK 集成功能支持多种主流编程语言，每种语言都有对应的指令生成器和配置模板。
### SDK 通用语言支持
根据 `src/tools/sdk-utils/common/types.ts` 中的定义，系统支持以下 SDK 集成语言：
| 语言枚举 | 说明 | 支持状态 |
|----------|------|----------|
| `nodejs` | Node.js / JavaScript | 完整支持 |
| `python` | Python | 完整支持 |
| `java` | Java | 完整支持 |
| `csharp` | C# / .NET | 完整支持 |
| `ruby` | Ruby | 完整支持 |
资料来源：[src/tools/sdk-utils/common/types.ts:4-9]()
### Appium SDK 语言支持
Appium SDK 集成模块在 `src/tools/appautomate-utils/appium-sdk/types.ts` 中定义了独立的语言枚举：
```typescript
export enum AppSDKSupportedLanguageEnum {
java = "java",
nodejs = "nodejs",
python = "python",
ruby = "ruby",
csharp = "csharp",
}
export type AppSDKSupportedLanguage = keyof typeof AppSDKSupportedLanguageEnum;
```
资料来源：[src/tools/appautomate-utils/appium-sdk/types.ts:1-8]()
## 支持的测试框架
### 浏览器自动化框架
系统支持多种浏览器自动化测试框架，用于 BrowserStack Automate 和 App Automate 的 Web 测试场景：
| 框架枚举 | 说明 | 典型使用场景 |
|----------|------|-------------|
| `playwright` | Microsoft Playwright | 现代 Web 应用测试 |
| `selenium` | Selenium WebDriver | 跨浏览器兼容性测试 |
| `cypress` | Cypress | 端到端测试 |
| `webdriverio` | WebDriverIO | Node.js 自动化测试 |
资料来源：[src/tools/sdk-utils/common/types.ts:15-21]()
### 测试运行框架
每种语言都支持多种测试运行框架，具体支持情况如下：
#### Java 测试框架
| 测试框架 | SDK 版本映射 | Maven 原型 |
|----------|-------------|------------|
| `testng` | 1.4 | testng-archetype-integrate |
| `junit5` | 1.0 | browserstack-sdk-archetype-integrate |
| `junit4` | 1.0 | browserstack-sdk-archetype-integrate |
| `selenide` | 1.4 | selenide-archetype-integrate |
| `jbehave` | 1.0 | browserstack-sdk-archetype-integrate |
| `cucumberTestng` | 1.0 | browserstack-sdk-archetype-integrate |
| `cucumberJunit4` | 1.0 | browserstack-sdk-archetype-integrate |
| `cucumberJunit5` | 1.0 | browserstack-sdk-archetype-integrate |
| `serenity` | 1.0 | browserstack-sdk-archetype-integrate |
资料来源：[src/tools/appautomate-utils/appium-sdk/languages/java.ts:8-25]()
#### Python 测试框架
| 测试框架 | 执行命令 |
|----------|----------|
| `pytest` | `browserstack-sdk pytest -s ` |
| `robot` | `browserstack-sdk robot ` |
| `behave` | `browserstack-sdk behave ` |
| `lettuce` | 通过 paver 执行 |
资料来源：[src/tools/appautomate-utils/appium-sdk/languages/python.ts:6-37]()
#### Appium 测试框架
移动端 Appium 测试支持更广泛的框架：
| 框架类别 | 支持的框架 |
|----------|-----------|
| Java 框架 | testng, junit5, junit4, selenide, jbehave, serenity, cucumberTestng, cucumberJunit4, cucumberJunit5 |
| Node.js 框架 | webdriverio, nightwatch, jest, mocha, cucumberJs |
| Python 框架 | pytest, robot, behave, lettuce |
| Ruby 框架 | rspec, cucumberRuby |
| .NET 框架 | nunit, mstest, xunit, specflow, reqnroll |
资料来源：[src/tools/appautomate-utils/appium-sdk/types.ts:13-46]()
## SDK 集成类型
### Percy 可视化测试集成
Percy 集成支持三种模式，每种模式针对不同的测试场景：
| 集成类型 | 说明 | 配置结构 |
|----------|------|----------|
| `WEB` | 纯 Web 应用截图对比 | 语言 → 自动化框架 → 快照指令 |
| `AUTOMATE` | 浏览器自动化集成 | 语言 → 驱动 → 测试框架 → 指令 |
| `BStack` | BrowserStack SDK 集成 | 语言 → 自动化框架 → 测试框架 → 指令 |
资料来源：[src/tools/sdk-utils/common/types.ts:1-3]()
### 类型定义详解
**Percy Web 配置映射结构：**
```typescript
export type ConfigMapping = {
[language: string]: {
[automationFramework: string]: {
instructions: string;
snapshotInstruction: string;
};
};
};
```
资料来源：[src/tools/sdk-utils/percy-web/types.ts:1-10]()
**Percy Automate 配置映射结构：**
```typescript
export type ConfigMapping = {
[language: string]: {
[driver: string]: {
[framework: string]: {
instructions: string;
};
};
};
};
```
资料来源：[src/tools/sdk-utils/percy-automate/types.ts:1-13]()
**Percy + BrowserStack SDK 配置映射结构：**
```typescript
export type ConfigMapping = {
[language: string]: {
[automationFramework: string]: {
[testingFramework: string]: {
instructions: string;
};
};
};
};
```
资料来源：[src/tools/sdk-utils/percy-bstack/types.ts:1-15]()
## Appium SDK 集成详解
### 工具概述
Appium SDK 集成工具 `setupBrowserStackAppAutomateTests` 专门用于配置 Appium 移动端测试环境。根据 `src/tools/appautomate-utils/appium-sdk/constants.ts` 的定义：
> Set up BrowserStack App Automate SDK integration for Appium-based mobile app testing. ONLY for Appium based framework . This tool configures SDK for various languages with appium. For pre-built Espresso or XCUITest test suites, use 'runAppTestsOnBrowserStack' instead.
资料来源：[src/tools/appautomate-utils/appium-sdk/constants.ts:14-16]()
### 输入参数架构
```typescript
export const SETUP_APP_AUTOMATE_SCHEMA = {
detectedFramework: z
.nativeEnum(AppSDKSupportedFrameworkEnum)
.describe("The mobile automation framework configured in the project. Example: 'appium'"),
detectedTestingFramework: z
.nativeEnum(AppSDKSupportedTestingFrameworkEnum)
.describe("The testing framework used in the project. Be precise with framework selection Example: 'testng', 'behave', 'pytest', 'robot'"),
detectedLanguage: z
.nativeEnum(AppSDKSupportedLanguageEnum)
.describe("The programming language used in the project. Supports Java and C#. Example: 'java', 'csharp'"),
devices: z
.array(MobileDeviceSchema)
.max(3)
.default([])
.describe("Tuples describing target mobile devices. Add device only when user asks explicitly for it."),
};
```
资料来源：[src/tools/appautomate-utils/appium-sdk/constants.ts:17-41]()
### 处理流程
```mermaid
graph LR
A[输入参数验证] --> B[生成 BrowserStack YML 配置]
B --> C[生成 App 上传指令]
C --> D[生成项目配置和运行指令]
D --> E[格式化输出]
```
Appium SDK 处理流程在 `src/tools/appautomate-utils/appium-sdk/handler.ts` 中实现：
```typescript
// Step 1: Generate environment configuration
const validatedEnvironments = await validateAndParseEnvironments(input);
// Step 2: Generate browserstack.yml configuration
const configInstructions = generateAppBrowserStackYMLInstructions({
validatedEnvironments,
platforms,
testingFramework,
projectName: input.project as string,
}, username, accessKey, appPath);
// Step 3: Generate app upload instruction
const appUploadInstruction = await getAppUploadInstruction(
appPath, username, accessKey, testingFramework
);
// Step 4: Generate project configuration and run instructions
const projectInstructions = getAppInstructionsForProjectConfiguration(
framework, testingFramework, language
);
```
资料来源：[src/tools/appautomate-utils/appium-sdk/handler.ts:1-25]()
## 原生测试执行
### 预编译测试套件执行
对于已编译的 Espresso (Android) 和 XCUITest (iOS) 测试套件，系统提供 `runAppTestsOnBrowserStack` 工具：
| 平台 | 测试类型 | 构建命令 |
|------|----------|----------|
| Android | Espresso | `gradle assembleAndroidTest` |
| Android | APK | `gradle assembleDebug` |
| iOS | XCUITest | `xcodebuild test-without-building -scheme YOUR_SCHEME` |
| iOS | IPA | `xcodebuild archive -scheme YOUR_SCHEME` |
资料来源：[src/tools/appautomate-utils/native-execution/constants.ts:8-30]()
### 设备配置
移动设备通过以下 Schema 定义：
```typescript
export const MobileDeviceSchema = z.object({
platform: z
.enum(["android", "ios"])
.describe("Platform name: 'android' or 'ios'"),
deviceName: z
.string()
.describe("Device name, e.g. 'Samsung Galaxy S24', 'Google Pixel 8', 'iPhone 15', 'iPhone 14 Pro'"),
osVersion: z
.string()
.describe("OS version, e.g. '14', '16', '17', 'latest'"),
});
```
资料来源：[src/tools/appautomate-utils/native-execution/constants.ts:5-18]()
## SDK 命令生成
### 语言特定命令
每种语言都有专门的 SDK 命令生成逻辑，位于 `src/tools/appautomate-utils/appium-sdk/instructions.ts`：
```typescript
export function getAppSDKPrefixCommand(
language: AppSDKSupportedLanguage,
testingFramework: string,
username: string,
accessKey: string,
appPath?: string,
): string {
switch (language) {
case "csharp":
return getCSharpSDKCommand(username, accessKey);
case "java":
return getJavaSDKCommand(testingFramework, username, accessKey, appPath);
case "nodejs":
return getNodejsSDKCommand(testingFramework, username, accessKey);
case "python":
return getPythonSDKCommand(testingFramework, username, accessKey);
case "ruby":
return getRubySDKCommand(testingFramework, username, accessKey);
default:
return "";
}
}
```
资料来源：[src/tools/appautomate-utils/appium-sdk/instructions.ts:1-22]()
### 框架指令生成
系统根据测试框架类型生成对应的运行指令：
```typescript
export function getAppInstructionsForLanguage(
language: AppSDKSupportedLanguage,
testingFramework: AppSDKSupportedTestingFramework,
): string {
switch (language) {
case "java":
return getJavaAppInstructions(testingFramework);
case "python":
return getPythonAppInstructions(testingFramework);
case "ruby":
return getRubyAppInstructions();
case "csharp":
return getCSharpAppInstructions();
default:
return "";
}
}
```
资料来源：[src/tools/appautomate-utils/appium-sdk/instructions.ts:24-38]()
## 配置生成
### BrowserStack YML 配置
系统支持根据验证后的环境自动生成 `browserstack.yml` 配置文件：
```typescript
function generatePlatformConfigs(config: {
validatedEnvironments?: ValidatedEnvironment[];
platforms?: string[];
}): string {
if (config.validatedEnvironments && config.validatedEnvironments.length > 0) {
const platforms = config.validatedEnvironments.map((env) => {
if (env.platform === "windows" || env.platform === "macos") {
// Desktop configuration
return {
os: env.platform === "windows" ? "Windows" : "OS X",
osVersion: env.osVersion,
browserName: env.browser,
browserVersion: env.browserVersion || "latest",
};
} else {
// Mobile configuration (android/ios)
return {
deviceName: env.deviceName,
osVersion: env.osVersion,
browserName: env.browser,
};
}
});
// Convert to YAML format...
}
}
```
资料来源：[src/tools/sdk-utils/bstack/configUtils.ts:1-30]()
### YAML 输出示例
生成的配置文件格式如下：
```yaml
# Mobile configuration
- deviceName: "Samsung Galaxy S24"
osVersion: "14"
browserName: android
# Desktop configuration
- os: Windows
osVersion: "11"
browserName: Chrome
browserVersion: latest
```
## 常见问题与社区反馈
### 用户关注的问题
根据社区反馈，用户对以下方面较为关注：
1. **工具请求**：获取自动化日志和截图功能（Issue #25）
- 用户期望能在测试失败后直接获取会话日志和视频录制
- 当前工作流程需要手动打开 BrowserStack 会话 URL 查看
2. **版本兼容性**：WDIO 集成的修复（v1.2.11, v1.2.12）
- 针对 Windows 机器的 Live 工具重定向问题进行了修复
3. **安全增强**：路径验证和环境变量清理（v1.2.17, v1.2.19）
- 增加了上传路径验证以防止文件泄露
- 增强了环境变量清理机制
## 扩展与定制
### 添加新语言支持
要添加新的语言支持，需要完成以下步骤：
1. 在 `AppSDKSupportedLanguageEnum` 中添加新的语言枚举值
2. 创建新的语言文件（如 `languages/go.ts`）
3. 实现语言特定的指令生成函数
4. 在 `getAppSDKPrefixCommand` 中添加 switch case
5. 更新相关类型定义
### 添加新框架支持
新框架的添加遵循类似流程：
1. 在 `AppSDKSupportedTestingFrameworkEnum` 中添加框架枚举
2. 在对应的语言文件中添加框架特定的配置和命令
3. 更新 SDK 版本映射（如果需要）
## 相关资源
- 源码仓库：[browserstack/mcp-server](https://github.com/browserstack/mcp-server)
- 最新版本：v1.2.20
- Appium SDK 集成工具：`setupBrowserStackAppAutomateTests`
- 原生测试执行工具：`runAppTestsOnBrowserStack`
---
## Percy 视觉测试集成
### 相关页面
相关主题：[SDK 集成与框架支持](#page-6), [AI 智能体功能](#page-8)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/sdk-utils/percy-web/handler.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/sdk-utils/percy-web/handler.ts)
- [src/tools/sdk-utils/percy-web/types.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/sdk-utils/percy-web/types.ts)
- [src/tools/sdk-utils/percy-web/constants.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/sdk-utils/percy-web/constants.ts)
- [src/tools/sdk-utils/percy-bstack/handler.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/sdk-utils/percy-bstack/handler.ts)
- [src/tools/sdk-utils/percy-bstack/instructions.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/sdk-utils/percy-bstack/instructions.ts)
- [src/tools/sdk-utils/percy-bstack/types.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/sdk-utils/percy-bstack/types.ts)
- [src/tools/sdk-utils/percy-automate/handler.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/sdk-utils/percy-automate/handler.ts)
- [src/tools/sdk-utils/percy-automate/types.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/sdk-utils/percy-automate/types.ts)
- [src/tools/percy-snapshot-utils/constants.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/percy-snapshot-utils/constants.ts)
- [src/tools/run-percy-scan.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/run-percy-scan.ts)
# Percy 视觉测试集成
## 概述
Percy 视觉测试集成是 BrowserStack MCP Server 提供的核心功能之一，允许用户在 AI 助手的指导下快速配置和集成 Percy 视觉测试服务。该模块支持三种集成类型：Percy Web、Percy Automate 和 Percy + BrowserStack SDK，每种类型针对不同的测试场景和工作流程进行了优化。
## 架构设计
### 集成类型体系
MCP Server 中的 Percy 集成采用分层架构，根据测试框架和自动化工具的不同组合提供定制化的配置指令：
```mermaid
graph TD
A[Percy 视觉测试集成] --> B[Percy Web]
A --> C[Percy Automate]
A --> D[Percy + BrowserStack SDK]
B --> B1[nodejs/Selenium]
B --> B2[Python/Selenium]
B --> B3[Java/Playwright]
B --> B4[Ruby/Capybara]
B --> B5[C#/Selenium]
C --> C1[Playwright]
C --> C2[Selenium]
C --> C3[Cypress]
C --> C4[WebdriverIO]
D --> D1[Jest/Playwright]
D --> D2[Pytest/Playwright]
D --> D3[TestNG/Selenium]
D --> D4[Mocha/Selenium]
```
### 类型定义结构
#### Percy Web 配置映射
```typescript
// src/tools/sdk-utils/percy-web/types.ts:1-10
export type ConfigMapping = {
[language: string]: {
[automationFramework: string]: {
instructions: string;
snapshotInstruction: string;
};
};
};
```
#### Percy Automate 配置映射
```typescript
// src/tools/sdk-utils/percy-automate/types.ts:1-12
export type ConfigMapping = {
[language: string]: {
[driver: string]: {
[framework: string]: {
instructions: string;
};
};
};
};
```
#### Percy + BrowserStack SDK 配置映射
```typescript
// src/tools/sdk-utils/percy-bstack/types.ts:1-13
export type ConfigMapping = {
[language: string]: {
[automationFramework: string]: {
[testingFramework: string]: {
instructions: string;
};
};
};
};
```
## 核心组件
### 1. Percy Web 处理器
Percy Web 集成提供独立的视觉测试能力，不依赖 BrowserStack SDK。处理器根据检测到的编程语言和自动化框架生成相应的配置指令。
```typescript
// src/tools/sdk-utils/percy-web/handler.ts:45-62
export function setupPercyWeb(
input: SetupPercyParams & { folderPaths?: string[] }
): SetupResult {
// ...
steps.push({
type: "instruction",
title: `Percy Web Setup Instructions`,
content: instructions,
});
return {
steps,
requiresPercy: true,
missingDependencies: [],
};
}
```
**支持的编程语言和框架：**
| 语言 | 自动化框架 | 快照方法 |
|------|-----------|---------|
| Node.js | Selenium | `percySnapshot(driver, "name")` |
| Python | Selenium | `percy_snapshot(driver, 'name')` |
| Java | Selenium | `Percy.Snapshot(driver, "name")` |
| Java | Playwright | `percy.snapshot("name")` |
| Ruby | Capybara | `page.percy_snapshot('name')` |
| C# | Selenium | `Percy.Snapshot(driver, "name")` |
### 2. Percy Automate 处理器
Percy Automate 允许在 BrowserStack Automate 基础设施上执行视觉测试，同时获取 Selenium/Playwright 的原生能力。
```typescript
// src/tools/sdk-utils/percy-automate/handler.ts
// 支持 Playwright, Selenium, Cypress, WebdriverIO
```
### 3. Percy + BrowserStack SDK 处理器
这是最完整的集成方案，结合 BrowserStack SDK 的所有功能，包括测试执行、可视化报告和自我修复能力。
```typescript
// src/tools/sdk-utils/percy-bstack/handler.ts:30-80
export async function runPercyWithBrowserstackSDK(
input: SetupPercyParams,
config: BrowserStackConfig
): Promise {
// 检测到的设备列表
const devices = (input as any).devices as string[][] | undefined;
// 生成 SDK 安装命令
const sdkSetupCommand = getSDKPrefixCommand(
input.detectedLanguage as SDKSupportedLanguage,
input.detectedTestingFramework as SDKSupportedTestingFramework,
username,
accessKey,
);
// 生成 browserstack.yml 配置
const ymlInstructions = generateBrowserStackYMLInstructions({
platforms: devices?.map(t => t.join(" ")) || [],
enablePercy: true,
projectName: input.projectName,
}, config);
return { steps, requiresPercy: true, missingDependencies: [] };
}
```
## 指令生成系统
### 指令检索机制
```typescript
// src/tools/sdk-utils/percy-bstack/instructions.ts:10-32
export function getPercyInstructions(
language: SDKSupportedLanguage,
automationFramework: SDKSupportedBrowserAutomationFramework,
testingFramework: SDKSupportedTestingFramework,
): { instructions: string } | null {
const langConfig = PERCY_INSTRUCTIONS[language];
if (!langConfig) return null;
const frameworkConfig = langConfig[automationFramework];
if (!frameworkConfig) return null;
const percyInstructions = frameworkConfig[testingFramework];
if (!percyInstructions) return null;
return percyInstructions;
}
export function formatPercyInstructions(instructions: { instructions: string }): string {
return `---STEP--- Percy Visual Testing Setup
To enable visual testing with Percy, you need to make the following changes to your project configuration and test scripts.
${instructions.instructions}
`;
}
```
### 支持的语言枚举
```typescript
// src/tools/sdk-utils/common/types.ts:6-12
export enum SDKSupportedLanguageEnum {
nodejs = "nodejs",
python = "python",
java = "java",
csharp = "csharp",
ruby = "ruby",
}
```
### 支持的自动化框架枚举
```typescript
// src/tools/sdk-utils/common/types.ts:14-21
export enum SDKSupportedBrowserAutomationFrameworkEnum {
playwright = "playwright",
selenium = "selenium",
cypress = "cypress",
webdriverio = "webdriverio",
}
```
### 支持的测试框架枚举
```typescript
// src/tools/sdk-utils/common/types.ts:23-46
export enum SDKSupportedTestingFrameworkEnum {
jest = "jest",
codeceptjs = "codeceptjs",
playwright = "playwright",
pytest = "pytest",
robot = "robot",
behave = "behave",
cucumber = "cucumber",
nightwatch = "nightwatch",
mocha = "mocha",
junit4 = "junit4",
junit5 = "junit5",
testng = "testng",
cypress = "cypress",
nunit = "nunit",
mstest = "mstest",
xunit = "xunit",
specflow = "specflow",
reqnroll = "reqnroll",
rspec = "rspec",
serenity = "serenity",
}
```
## UI 测试文件检测
### 正则表达式模式
系统使用多层次的正则表达式来识别 UI 测试文件：
```typescript
// src/tools/percy-snapshot-utils/constants.ts:1-60
const fileNamePatterns = [
/.*Test\.py$/, // Python
/.*Spec\.js$/, // Mocha
/.*Test\.js$/, // Jest
/.*\.feature$/, // Cucumber
/.*Test\.java$/, // Java JUnit
/.*Tests?\.java$/,
/.*Web.*Test\.cs$/, // C# .NET
/.*E2E.*Test\.cs$/,
];
const contentRegex = [
/\[Test\]/, // NUnit
/\[TestCase\]/,
/\[Fact\]/, // xUnit
/\[Theory\]/,
/using\s+NUnit\.Framework/,
/using\s+Xunit/,
];
const uiDriverRegex = [
/using\s+OpenQA\.Selenium/,
/using\s+Appium/,
/using\s+Microsoft\.Playwright/,
/using\s+Selenide/,
/IWebDriver/,
/WebDriver/,
];
const uiIndicatorRegex = [
/\.SendKeys\s*\(/,
/\.Click\s*\(/,
/By\.Id/,
/By\.XPath/,
/TakeScreenshot/,
/\[UITest\]/,
/\[WebTest\]/,
/\[E2ETest\]/,
];
```
### 快照指令常量
```typescript
// src/tools/sdk-utils/percy-web/constants.ts:25-90
export const pythonInstructionsSnapshot = `
Example:
\`\`\`python
from selenium import webdriver
from percy import percy_snapshot
driver = webdriver.Chrome()
driver.get('http://localhost:8000')
percy_snapshot(driver, 'Home page')
\`\`\`
`;
export const nodejsInstructionsSnapshot = `
- Import the Percy snapshot helper:
const { percySnapshot } = require('@percy/selenium-js');
- In your test, take snapshots like this:
await percySnapshot(driver, "Your snapshot name");
Example:
\`\`\`javascript
const { percySnapshot } = require('@percy/selenium-webdriver');
await percySnapshot(driver, 'Home page');
\`\`\`
`;
```
## 集成类型枚举
```typescript
// src/tools/sdk-utils/common/types.ts:1-4
export enum PercyIntegrationTypeEnum {
WEB = "web",
AUTOMATE = "automate",
}
```
## 安全配置
### PERCY_TOKEN 管理
系统通过环境变量安全地处理 Percy 令牌：
```typescript
// src/tools/run-percy-scan.ts:65-78
function generatePercyTokenInstructions(): string {
return `Set the PERCY_TOKEN environment variable for your project.
Retrieve your project's token from the Percy dashboard
(https://percy.io → Project Settings → Project Token) and add it to
your project's .env file (PERCY_TOKEN=)
or export it in your shell:
- macOS/Linux: export PERCY_TOKEN=""
- Windows (PS): $env:PERCY_TOKEN=""
- Windows (CMD): set PERCY_TOKEN=
Do not paste the token into chat or commit it.`;
}
```
## 工作流程
### 设置流程图
```mermaid
graph TD
A[开始 Percy 设置] --> B{选择集成类型}
B -->|web| C[setupPercyWeb]
B -->|automate| D[setupPercyAutomate]
B -->|browserstack| E[runPercyWithBrowserstackSDK]
C --> F[检测语言/框架]
D --> G[生成浏览器驱动配置]
E --> H[检测设备和平台]
F --> I[获取快照指令]
G --> J[配置 browserstack.yml]
H --> K[生成 SDK 安装命令]
I --> L[返回设置步骤]
J --> L
K --> L
L --> M[完成配置]
```
### 参数定义
```typescript
// src/tools/sdk-utils/common/schema.ts:20-35
export const SetUpPercyParamsShape = {
projectName: z.string().describe("项目唯一名称"),
detectedLanguage: z.nativeEnum(SDKSupportedLanguageEnum),
detectedBrowserAutomationFramework: z.nativeEnum(
SDKSupportedBrowserAutomationFrameworkEnum,
),
detectedTestingFramework: z.nativeEnum(SDKSupportedTestingFrameworkEnum),
integrationType: z.nativeEnum(PercyIntegrationTypeEnum).describe(
"Specify the Percy integration type: web or automate",
),
folderPaths: z
.array(z.string())
.optional()
.describe("UI 测试文件目录路径数组"),
};
```
## 版本历史
| 版本 | 更新内容 |
|------|---------|
| v1.2.19 | 新增 Percy 设置处理器的无泄漏回归防护测试 |
| v1.2.6 | 支持指定文件路径的 Percy 测试文件处理 |
| v1.2.5 | 添加 Percy 模拟工具（percy simulate） |
## 相关工具
MCP Server 还提供了以下与 Percy 相关的工具：
- **setupPercy** - 设置 Percy 视觉测试环境
- **runPercyScan** - 执行 Percy 扫描并生成报告
- **addPercySnapshots** - 为现有测试添加快照
- **reviewPercySnapshots** - 审查快照差异
- **managePercyBuildApproval** - 管理构建审批状态
---
## AI 智能体功能
### 相关页面
相关主题：[测试管理工具](#page-3), [构建洞察与 Review 智能体](#page-9)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/selfheal.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/selfheal.ts)
- [src/tools/selfheal-utils/selfheal.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/selfheal-utils/selfheal.ts)
- [src/tools/selfheal-utils/fetch-test-code.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/selfheal-utils/fetch-test-code.ts)
- [src/tools/rca-agent.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/rca-agent.ts)
- [src/tools/rca-agent-utils/format-rca.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/rca-agent-utils/format-rca.ts)
- [src/tools/rca-agent-utils/get-failed-test-id.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/rca-agent-utils/get-failed-test-id.ts)
- [src/tools/testmanagement-utils/create-lca-steps.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/testmanagement-utils/create-lca-steps.ts)
- [src/tools/testmanagement-utils/poll-lca-status.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/testmanagement-utils/poll-lca-status.ts)
- [src/tools/testmanagement-utils/upload-file.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/testmanagement-utils/upload-file.ts)
# AI 智能体功能
BrowserStack MCP Server 提供了强大的 AI 智能体功能，帮助开发者自动化测试工作流程。这些 AI 智能体包括**自我修复智能体（Self-Heal Agent）**、**根因分析智能体（RCA Agent）**和**低代码自动化智能体（Low-Code Automation Agent）**。通过这些功能，开发者可以利用 AI 技术自动修复不稳定的测试脚本、生成测试用例，以及将手动测试转换为自动化脚本。
## 功能概述
AI 智能体功能主要解决以下测试挑战：
| 功能模块 | 用途 | 关键能力 |
|---------|------|---------|
| 自我修复 | 自动修复 flaky 测试脚本 | 检测失败原因、生成修复方案、应用代码修复 |
| 根因分析 | 分析测试失败原因 | 收集失败信息、格式化 RCA 数据、提供修复建议 |
| 低代码自动化 | 将手动测试转换为自动化脚本 | 分析测试用例、生成自动化代码、上传测试文件 |
## 架构设计
### 整体架构
```mermaid
graph TD
A[用户请求] --> B{智能体类型判断}
B -->|Self-Heal| C[SelfHeal 工具]
B -->|RCA| D[RCA Agent 工具]
B -->|Low-Code| E[Low-Code 自动化工具]
C --> C1[fetchTestCode 获取测试代码]
C1 --> C2[selfHealCore 核心修复逻辑]
C2 --> C3[返回修复建议]
D --> D1[getFailedTestId 获取失败测试ID]
D1 --> D2[formatRCA 格式化RCA数据]
D2 --> D3[返回RCA分析结果]
E --> E1[createLCA 创建自动化任务]
E1 --> E2[pollLCAStatus 轮询任务状态]
E2 --> E3[uploadFile 上传生成的代码]
E3 --> E4[返回自动化脚本]
```
### 自我修复流程
```mermaid
sequenceDiagram
participant U as 用户
participant MCP as MCP Server
participant SH as SelfHeal Utils
participant BS as BrowserStack API
U->>MCP: 请求修复 flaky 测试
MCP->>SH: 调用 selfHealCore
SH->>SH: validateBuildId 验证构建ID
SH->>SH: getFailedTestCases 获取失败用例
SH->>SH: fetchTestCode 获取测试代码
SH->>SH: triggerSelfHeal 触发自我修复
SH->>BS: 发送修复请求
BS-->>SH: 返回修复任务ID
SH->>SH: pollSelfHealStatus 轮询状态
loop 轮询直到完成
SH->>BS: 查询状态
BS-->>SH: 当前状态
end
SH-->>MCP: 返回修复结果
MCP-->>U: 展示修复建议
```
## 自我修复智能体（Self-Heal Agent）
### 功能描述
自我修复智能体是 BrowserStack AI 功能的核心组件，专门用于自动修复不稳定的测试脚本（flaky tests）。当测试用例出现间歇性失败时，该智能体能够分析失败原因并自动生成修复方案。
资料来源：[src/tools/selfheal.ts:1-50]()
### 核心模块
#### SelfHealUtils 模块
该模块负责与 BrowserStack API 交互，获取构建信息和失败测试用例数据。
**主要功能：**
- `validateBuildId()` - 验证构建 ID 的有效性
- `getFailedTestCases()` - 获取构建中失败的测试用例列表
- `fetchTestCode()` - 获取指定测试用例的源代码
- `triggerSelfHeal()` - 触发自我修复流程
- `pollSelfHealStatus()` - 轮询修复任务状态
资料来源：[src/tools/selfheal-utils/selfheal.ts:1-100]()
#### 状态流转
```mermaid
stateDiagram-v2
[*] --> Pending: 创建修复任务
Pending --> InProgress: 开始处理
InProgress --> InProgress: 继续处理
InProgress --> Success: 修复完成
InProgress --> Failed: 处理失败
Failed --> [*]
Success --> [*]
```
### 使用示例
```typescript
// 触发自我修复
const result = await selfHealCore({
buildId: "build-12345",
projectId: "project-abc",
framework: "playwright",
language: "typescript"
});
```
### 配置参数
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| buildId | string | 是 | BrowserStack 构建 ID |
| projectId | string | 是 | 项目标识符 |
| framework | string | 是 | 自动化框架类型 |
| language | string | 是 | 编程语言类型 |
资料来源：[src/tools/selfheal.ts:50-80]()
## 根因分析智能体（RCA Agent）
### 功能描述
根因分析智能体（RCA Agent）用于深入分析测试失败的原因，提供结构化的失败分析和修复建议。该智能体通过收集测试执行数据、日志和错误信息，帮助开发者快速定位问题根源。
资料来源：[src/tools/rca-agent.ts:1-60]()
### 数据收集流程
```mermaid
graph LR
A[获取构建数据] --> B[获取失败测试ID]
B --> C[收集测试日志]
C --> D[格式化RCA报告]
D --> E[返回分析结果]
```
### 核心功能
#### 1. 获取失败测试 ID
`getFailedTestId()` 函数从构建数据中提取失败的测试用例标识符。
**返回值结构：**
```typescript
interface FailedTestInfo {
testId: string | number;
testCase: string;
failureReason: string;
}
```
资料来源：[src/tools/rca-agent-utils/get-failed-test-id.ts:1-50]()
#### 2. 格式化 RCA 数据
`formatRCA()` 函数将原始测试数据转换为可读的 RCA 报告格式。
**处理逻辑：**
```typescript
function formatRCA(testCases: TestCaseData[]): string {
let output = "";
testCases.forEach(testCase => {
if (testCase.rcaData) {
output += `**测试用例:** ${testCase.testName}\n\n`;
output += `**根本原因:** ${testCase.rcaData.rootCause}\n\n`;
output += `**建议修复:** ${testCase.rcaData.possible_fix}\n\n`;
}
output += "---\n\n";
});
return output;
}
```
资料来源：[src/tools/rca-agent-utils/format-rca.ts:1-80]()
### RCA 数据结构
| 字段名 | 类型 | 描述 |
|-------|------|------|
| testName | string | 测试用例名称 |
| state | string | 测试状态（passed/failed） |
| rcaData.rootCause | string | 根本原因分析 |
| rcaData.possible_fix | string | 建议的修复方案 |
| rcaData.error | string | 错误信息 |
资料来源：[src/tools/rca-agent-utils/format-rca.ts:30-60]()
## 低代码自动化智能体（Low-Code Automation Agent）
### 功能描述
低代码自动化智能体（LCA Agent）能够将手动测试用例自动转换为自动化脚本。用户只需提供测试用例描述，系统即可生成对应的自动化代码。
资料来源：[src/tools/testmanagement-utils/create-lca-steps.ts:1-100]()
### 工作流程
```mermaid
graph TD
A[用户提供测试用例] --> B[创建LCA任务]
B --> C[上传相关文件]
C --> D[轮询任务状态]
D -->|处理中| D
D -->|完成| E[获取生成的代码]
E --> F[下载自动化脚本]
```
### 核心 API
#### 1. 创建低代码自动化任务
`createLCASteps()` 函数向 BrowserStack Test Management API 发起自动化转换请求。
**API 调用：**
```typescript
const traceRequestId = await createLCASteps({
documentId: number,
folderId: string,
projectId: string,
testCaseIds: string[],
source: string,
webhookUrl: string,
config: BrowserStackConfig
});
```
资料来源：[src/tools/testmanagement-utils/create-lca-steps.ts:100-150]()
#### 2. 轮询任务状态
`pollLCAStatus()` 函数持续检查低代码自动化任务的处理状态。
**轮询策略：**
```typescript
async function pollLCAStatus(
traceRequestId: string,
maxAttempts: number = 10,
intervalMs: number = 5000
): Promise {
for (let i = 0; i < maxAttempts; i++) {
const status = await checkLCAStatus(traceRequestId);
if (status === "completed") {
return getLCAResult();
}
await sleep(intervalMs);
}
throw new Error("LCA processing timeout");
}
```
资料来源：[src/tools/testmanagement-utils/poll-lca-status.ts:1-80]()
#### 3. 上传文件
`uploadFile()` 函数用于上传测试相关文件，以便 AI 分析和生成自动化脚本。
**上传流程：**
```mermaid
sequenceDiagram
participant C as 客户端
participant API as BrowserStack API
participant TCG as TCG Service
C->>API: 获取上传预签名 URL
API-->>C: 返回预签名 URL
C->>API: 使用预签名 URL 上传文件
API-->>C: 上传成功确认
C->>TCG: 触发 TCG 处理
TCG-->>C: 返回 traceRequestId
```
**支持的文件类型：**
| 文件类型 | 用途 | 最大大小 |
|---------|------|---------|
| .feature | Gherkin 格式测试 | 10MB |
| .java | Java 测试文件 | 10MB |
| .py | Python 测试文件 | 10MB |
| .js | JavaScript 测试文件 | 10MB |
| .ts | TypeScript 测试文件 | 10MB |
资料来源：[src/tools/testmanagement-utils/upload-file.ts:1-100]()
### 使用示例
```typescript
// 将手动测试转换为自动化脚本
const taskId = await createLCASteps({
documentId: 12345,
folderId: "folder-abc",
projectId: "project-xyz",
testCaseIds: ["TC001", "TC002", "TC003"],
source: "mcp-server",
webhookUrl: "https://api.browserstack.com/tcg/webhook",
config: browserStackConfig
});
// 等待处理完成
const result = await pollLCAStatus(taskId, 15, 3000);
```
## 测试用例生成智能体
### 功能描述
AI 智能体还可以根据产品需求文档（PRD）自动生成测试用例。这是 BrowserStack Test Management 功能的扩展，通过分析 PRD 内容提取关键需求并生成相应的测试用例。
资料来源：[README.md:测试管理部分]()
### 支持的测试类型识别
智能体能够自动识别测试文件中的不同测试类型：
```typescript
const testTypeRegex = {
unit: [/\.test\./, /spec\./, /\[Test\]/, /\[Fact\]/],
integration: [/Integration/, /E2E/, /\[E2ETest\]/],
e2e: [/\[WebTest\]/, /\[UITest\]/],
api: [/\[ApiTest\]/, /\[DatabaseTest\]/]
};
```
## 安全与权限
### 文件上传安全
所有文件上传都经过严格的安全验证：
- **路径验证** - 防止路径遍历攻击
- **文件类型限制** - 仅允许特定扩展名的文件
- **大小限制** - 防止大文件攻击
- **签名验证** - 使用预签名 URL 确保安全访问
资料来源：[src/tools/testmanagement-utils/upload-file.ts:50-80]()
### 环境变量清理
AI 智能体在处理过程中会注意敏感信息的处理：
- 不在日志中暴露认证凭据
- 清理处理过程中的临时文件
- 使用安全的环境变量传递机制
资料来源：[v1.2.19 Release Notes - fix: security fix(env cleanup)]()
## 常见问题
### Q: 自我修复智能体支持哪些框架？
A: 当前版本支持 Cypress、Playwright、Selenium、WebDriverIO 等主流自动化框架。
### Q: RCA 分析需要多长时间？
A: RCA 分析时间取决于构建规模和失败用例数量，通常在几秒到几分钟之间。
### Q: 低代码自动化生成的代码质量如何？
A: AI 生成的代码会尽可能贴近用户的手动测试流程，但可能需要人工审核和微调以适应特定项目结构。
### Q: 如何处理自我修复失败的情况？
A: 当自我修复无法自动解决问题时，系统会提供详细的失败原因分析和替代建议，帮助开发者手动修复。
## 相关链接
- [自我修复功能文档](https://github.com/browserstack/mcp-server/blob/main/src/tools/selfheal.ts)
- [根因分析功能文档](https://github.com/browserstack/mcp-server/blob/main/src/tools/rca-agent.ts)
- [低代码自动化功能文档](https://github.com/browserstack/mcp-server/blob/main/src/tools/testmanagement-utils/create-lca-steps.ts)
---
## 构建洞察与 Review 智能体
### 相关页面
相关主题：[AI 智能体功能](#page-8), [架构与代码结构](#page-10)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/build-insights.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/build-insights.ts)
- [src/tools/review-agent.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/review-agent.ts)
- [src/tools/review-agent-utils/build-counts.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/review-agent-utils/build-counts.ts)
- [src/tools/review-agent-utils/percy-approve-reject.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/review-agent-utils/percy-approve-reject.ts)
- [src/tools/rca-agent-utils/rca-data.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/rca-agent-utils/rca-data.ts)
- [src/tools/rca-agent-utils/get-build-id.ts](https://github.com/browserstack/mcp-server/blob/main/src/tools/rca-agent-utils/get-build-id.ts)
# 构建洞察与 Review 智能体
## 概述
构建洞察与 Review 智能体是 BrowserStack MCP Server 中的核心功能模块，专注于为测试构建提供深度分析、质量门评估和可视化审查能力。该模块通过集成 BrowserStack 的可观测性服务，帮助开发团队快速获取构建状态、识别失败模式、追踪错误趋势，并通过 Percy 集成实现自动化视觉回归审查。
构建洞察功能（Build Insights）通过组合构建详情（Build Details）与质量门结果（Quality Gate Results），为测试执行提供全面的质量可见性。Review 智能体则专注于管理视觉回归测试的审批流程，支持对 Percy 构建进行批准、拒绝和取消批准等操作。
## 核心组件架构
### 组件关系图
```mermaid
graph TD
A[用户请求] --> B[MCP Server]
B --> C[构建洞察模块]
B --> D[Review 智能体]
C --> C1[fetchBuildInsights 工具]
C --> C2[质量门评估]
C --> E[BrowserStack Observability API]
D --> D1[Percy 审批管理]
D --> D2[构建计数统计]
D --> F[Percy API]
E --> G[Build Data]
E --> H[Quality Gate Data]
F --> I[Build 审批状态]
F --> J[视觉差异对比]
G --> K[洞察分析结果]
H --> K
```
### 模块职责划分
| 模块 | 文件路径 | 主要职责 |
|------|----------|----------|
| 构建洞察工具 | `src/tools/build-insights.ts` | 获取构建详情与质量门结果，提供综合洞察 |
| Review 智能体 | `src/tools/review-agent.ts` | 管理视觉回归测试的审批流程 |
| 构建计数 | `src/tools/review-agent-utils/build-counts.ts` | 统计构建通过/失败数量 |
| Percy 审批 | `src/tools/review-agent-utils/percy-approve-reject.ts` | 处理 Percy 构建的 approve/reject 操作 |
| RCA 数据 | `src/tools/rca-agent-utils/rca-data.ts` | 提供根本原因分析数据支持 |
| 构建 ID 获取 | `src/tools/rca-agent-utils/get-build-id.ts` | 解析和获取构建标识符 |
## 构建洞察功能详解
### fetchBuildInsights 工具
`fetchBuildInsights` 是构建洞察模块的核心工具，通过 MCP 协议暴露给 AI 代理使用。该工具通过组合 BrowserStack 的多个数据源，生成包含构建状态、失败分类、错误概述和可观测性链接的综合报告。
资料来源：[src/tools/build-insights.ts:1-100]()
### 数据获取与整合
构建洞察工具通过调用 BrowserStack Observability API 获取两类核心数据：
**构建详情数据（Build Data）**：
- 用户信息与标签
- 构建告警与状态统计
- 失败分类与唯一错误概述
- 智能标签（Smart Tags）
- 可观测性 URL
- CI 构建链接
**质量门数据（Quality Gate Data）**：
- 质量门结果（通过/失败状态）
- 质量配置（Quality Profiles）
### 返回数据结构
```typescript
{
content: [
{
type: "text",
text: "Build insights:\n" + JSON.stringify(insights, null, 2)
},
{
type: "text",
text: qualityProfilesText
}
]
}
```
资料来源：[src/tools/build-insights.ts:60-75]()
### 质量门评估
质量门（Quality Gate）是 BrowserStack 提供的质量保障机制，用于评估构建是否满足预定义的质量标准。模块会映射每个质量配置文件的名称和结果状态：
```typescript
const qualityProfiles = qualityData.quality_profiles?.map(
(profile: any) => ({
name: profile.name,
result: profile.result,
}),
);
```
当存在质量门配置时，返回格式化的文本描述；否则返回"No Quality Gate Profiles available."提示信息。
### 洞察数据字段映射
| 源数据字段 | 目标洞察字段 | 说明 |
|------------|--------------|------|
| `user` | `user` | 构建执行用户 |
| `tags` | `tags` | 构建关联标签 |
| `alerts` | `alerts` | 构建期间产生的告警 |
| `status_stats` | `status_stats` | 测试状态统计 |
| `failure_categories` | `failure_categories` | 失败原因分类 |
| `smart_tags` | `smart_tags` | AI 生成的智能标签 |
| `unique_errors.overview` | `unique_errors` | 唯一错误概述 |
| `observability_url` | `observability_url` | 可观测性仪表板链接 |
| `ci_info.build_url` | `ci_build_url` | CI 系统构建链接 |
| `quality_gate_result` | `quality_gate_result` | 质量门最终结果 |
## Review 智能体功能
### 功能概述
Review 智能体专注于视觉回归测试的审查与审批流程，与 Percy 平台深度集成。它允许 AI 代理通过自然语言指令管理视觉构建的审批状态，实现测试工作流的自动化。
### Percy 构建审批管理
Percy 审批功能通过 `ManagePercyBuildApprovalParamsShape` 定义操作参数：
```typescript
export const ManagePercyBuildApprovalParamsShape = {
buildId: z.string().describe("The ID of the Percy build to approve or reject."),
action: z.enum(["approve", "unapprove", "reject"]).describe("The action to perform on the Percy build."),
};
```
资料来源：[src/tools/sdk-utils/common/schema.ts:1-50]()
#### 支持的操作类型
| 操作 | 说明 | 使用场景 |
|------|------|----------|
| `approve` | 批准构建 | 视觉差异已审查并确认可接受 |
| `unapprove` | 取消批准 | 需要重新审查已批准的构建 |
| `reject` | 拒绝构建 | 视觉差异不符合质量标准 |
### 构建计数统计
构建计数模块提供构建通过/失败的统计能力，帮助团队监控测试趋势：
```typescript
export default function addBuildCountsTools(
server: McpServer,
config: BrowserStackConfig,
) {
const tools: Record = {};
// 工具注册逻辑
}
```
## 工作流程设计
### 构建洞察获取流程
```mermaid
sequenceDiagram
participant U as 用户/AI代理
participant M as MCP Server
participant BSO as BrowserStack Observability API
U->>M: 请求 fetchBuildInsights
M->>M: 验证配置参数
M->>BSO: 获取构建详情
M->>BSO: 获取质量门数据
BSO-->>M: 构建数据响应
BSO-->>M: 质量门数据响应
M->>M: 数据整合与格式化
M-->>U: 返回洞察报告
```
### Review 智能体操作流程
```mermaid
graph LR
A[发起审批请求] --> B{验证 buildId}
B -->|有效| C[检查权限]
C -->|有权限| D[调用 Percy API]
D --> E{执行操作}
E -->|approve| F[更新构建状态为已批准]
E -->|reject| G[更新构建状态为已拒绝]
E -->|unapprove| H[清除批准状态]
F --> I[返回操作结果]
G --> I
H --> I
B -->|无效| J[返回错误]
C -->|无权限| J
```
## API 参数定义
### fetchBuildInsights 参数
| 参数名 | 类型 | 必需 | 说明 |
|--------|------|------|------|
| `build_id` | string | 是 | BrowserStack 构建的唯一标识符 |
| `project_id` | string | 是 | 项目标识符，用于关联构建数据 |
### ManagePercyBuildApproval 参数
| 参数名 | 类型 | 必需 | 说明 |
|--------|------|------|------|
| `buildId` | string | 是 | Percy 构建 ID |
| `action` | enum | 是 | 执行的操作：approve、unapprove、reject |
## 错误处理机制
构建洞察与 Review 智能体均实现了健壮的错误处理：
```typescript
try {
// 数据获取与处理逻辑
} catch (error) {
logger.error("Error fetching build insights", error);
throw error;
}
```
错误处理特点：
- 统一的日志记录机制
- 错误堆栈追踪
- 异常信息向上传递，供调用方处理
## 与其他模块的集成
### 可观测性集成
构建洞察模块与 BrowserStack 的可观测性服务紧密集成，提供：
- 实时构建状态监控
- 历史趋势分析
- 跨 CI/CD 平台的数据关联
### 测试管理集成
通过构建 ID 的共享机制，与测试管理（Test Management）模块协同工作：
- 构建结果自动同步到测试运行记录
- 质量门状态影响测试执行决策
### RCA 集成
根本原因分析（RCA）模块依赖构建洞察提供的数据：
- 构建 ID 解析服务 (`get-build-id.ts`)
- RCA 数据支持 (`rca-data.ts`)
## 使用示例
### 获取构建洞察
```bash
# 通过 MCP 协议调用
{
"tool": "fetchBuildInsights",
"arguments": {
"build_id": "build-12345",
"project_id": "project-abc"
}
}
```
### 批准 Percy 构建
```bash
# 批准视觉回归测试通过
{
"tool": "managePercyBuildApproval",
"arguments": {
"buildId": "percy-build-67890",
"action": "approve"
}
}
```
## 安全考虑
根据 v1.2.17 版本的安全修复，项目实现了以下安全措施：
- 上传路径验证，防止文件外泄攻击
- 环境变量清理机制
资料来源：[v1.2.17 Release Notes](https://github.com/browserstack/mcp-server/releases/tag/v1.2.17)
## 最佳实践
1. **定期审查质量门配置**：确保质量标准与团队目标保持一致
2. **利用智能标签**：使用 AI 生成的 smart_tags 快速识别问题模式
3. **集成 CI/CD 流程**：通过 `ci_build_url` 关联外部构建系统
4. **视觉回归审批规范化**：建立明确的审批流程和责任划分
## 版本演进
| 版本 | 更新内容 |
|------|----------|
| v1.2.18 | 扩展自愈工具以支持构建相关功能 |
| v1.2.8 | 重构测试管理 API URL 使用动态基础 URL 获取 |
| v1.2.6 | testId 类型从字符串改为数字 |
## 相关资源
- [BrowserStack Observability 文档](https://www.browserstack.com/docs/observability)
- [Percy 视觉回归测试](https://www.browserstack.com/docs/visual-testing)
- [质量门配置指南](https://www.browserstack.com/docs/quality-gates)
---
## 架构与代码结构
### 相关页面
相关主题：[项目概述](#page-1)
相关源码文件
以下源码文件用于生成本页说明：
- [src/index.ts](https://github.com/browserstack/mcp-server/blob/main/src/index.ts)
- [src/server-factory.ts](https://github.com/browserstack/mcp-server/blob/main/src/server-factory.ts)
- [src/lib/apiClient.ts](https://github.com/browserstack/mcp-server/blob/main/src/lib/apiClient.ts)
- [src/lib/api.ts](https://github.com/browserstack/mcp-server/blob/main/src/lib/api.ts)
- [src/lib/error.ts](https://github.com/browserstack/mcp-server/blob/main/src/lib/error.ts)
- [src/logger.ts](https://github.com/browserstack/mcp-server/blob/main/src/logger.ts)
- [src/lib/types.ts](https://github.com/browserstack/mcp-server/blob/main/src/lib/types.ts)
- [src/lib/utils.ts](https://github.com/browserstack/mcp-server/blob/main/src/lib/utils.ts)
- [src/oninitialized.ts](https://github.com/browserstack/mcp-server/blob/main/src/oninitialized.ts)
# 架构与代码结构
## 概述
BrowserStack MCP Server 是一个基于 Model Context Protocol (MCP) 协议构建的 TypeScript/Node.js 应用，它作为 BrowserStack 平台与 AI 助手（如 Claude）之间的桥梁，使 AI 能够通过自然语言指令与 BrowserStack 的各种服务进行交互。
核心功能包括：
- **自动化测试集成**：支持 Selenium、WebdriverIO、Cypress、Playwright 等主流自动化框架
- **App Automate**：提供 Appium SDK 集成，用于移动应用测试
- **Percy 视觉回归测试**：支持视觉快照和自动化截图对比
- **Test Management**：测试用例、测试计划和测试运行的管理
- **Build Insights**：构建分析和质量门禁数据获取
- **Accessibility Scan**：网站无障碍扫描功能
## 整体架构
```mermaid
graph TD
subgraph "MCP Server Core"
A[src/index.ts
入口文件] --> B[src/server-factory.ts
服务器工厂]
B --> C[src/oninitialized.ts
初始化处理]
C --> D[src/lib/types.ts
类型定义]
D --> E[src/lib/utils.ts
工具函数]
end
subgraph "API Layer"
F[src/lib/apiClient.ts
API客户端] --> G[src/lib/api.ts
API函数]
G --> H[src/lib/error.ts
错误处理]
end
subgraph "Tools Layer"
I[src/tools/build-insights.ts] --> J[工具集合]
K[src/tools/appautomate-utils] --> J
L[src/tools/sdk-utils] --> J
M[src/tools/testmanagement-utils] --> J
end
B --> C
F --> G
J --> F
```
## 核心模块详解
### 入口与服务器初始化
#### src/index.ts
主入口文件，负责整个 MCP 服务器的生命周期管理。服务器通过 `@modelcontextprotocol/sdk` 提供的 `Server` 类构建，并使用 Hono 框架处理 HTTP 请求。
#### src/server-factory.ts
服务器工厂模块，负责创建和配置 MCP 服务器实例。主要职责包括：
- 注册所有可用的 MCP 工具
- 配置中间件和错误处理
- 设置 CORS 和认证相关的 HTTP 端点
#### src/oninitialized.ts
处理 MCP 协议初始化阶段的逻辑，当客户端连接时执行特定的初始化任务。
### API 层
#### src/lib/apiClient.ts
基于 Axios 的 HTTP 客户端封装，提供了统一的 API 请求处理机制：
| 功能 | 说明 |
|------|------|
| `post()` | POST 请求封装 |
| `get()` | GET 请求封装 |
| 认证头处理 | 自动添加 `API-TOKEN` 和 `request-source` 头 |
| 错误转换 | 将 HTTP 错误转换为统一格式 |
资料来源：[src/lib/apiClient.ts:1-50]()
#### src/lib/api.ts
包含所有与 BrowserStack API 交互的具体函数，如获取测试用例详情、触发构建分析等。该模块依赖于 `apiClient` 发起实际请求。
#### src/lib/error.ts
统一的错误处理模块，定义了以下错误类型：
```typescript
// 错误类型定义（示意）
export enum ErrorType {
AUTH_ERROR = "AUTH_ERROR",
API_ERROR = "API_ERROR",
VALIDATION_ERROR = "VALIDATION_ERROR",
NETWORK_ERROR = "NETWORK_ERROR",
}
```
### 工具函数层
#### src/lib/types.ts
使用 Zod 定义了所有类型安全的数据模型和验证模式。主要包括：
- **工具参数模式**：使用 Zod schema 定义每个 MCP 工具的输入参数
- **响应类型**：定义工具返回数据的结构
- **枚举类型**：如 `AppSDKSupportedFrameworkEnum`、`SDKSupportedLanguageEnum` 等
示例代码结构：
```typescript
export const ManagePercyBuildApprovalParamsShape = {
buildId: z.string().describe("The ID of the Percy build"),
action: z.enum(["approve", "unapprove", "reject"]),
};
```
资料来源：[src/lib/types.ts:1-30]()
#### src/lib/utils.ts
通用的工具函数集合，包括：
- 配置解析
- 字符串处理
- 日期格式化
- 验证辅助函数
### 日志系统
#### src/logger.ts
使用 Pino 作为日志库，提供结构化日志输出：
```typescript
// 日志级别配置
const logger = pino({
level: process.env.LOG_LEVEL || "info",
transport: {
target: "pino-pretty",
},
});
```
## 工具模块架构
### 工具目录结构
```
src/tools/
├── build-insights.ts # 构建洞察工具
├── appautomate-utils/
│ └── appium-sdk/
│ ├── handler.ts # Appium SDK 处理逻辑
│ ├── constants.ts # 常量定义
│ └── languages/
│ └── java.ts # Java 特定配置
├── sdk-utils/
│ ├── bstack/
│ │ ├── sdkHandler.ts # BrowserStack SDK 处理器
│ │ └── configUtils.ts # YML 配置生成工具
│ ├── percy-web/ # Percy Web 配置
│ ├── percy-automate/ # Percy Automate 配置
│ └── percy-bstack/ # Percy + BrowserStack 集成
└── testmanagement-utils/
└── TCG-utils/
├── api.ts # TCG API 封装
└── types.ts # 测试管理类型定义
```
### SDK 配置映射结构
SDK 工具使用类型化的配置映射来支持多语言和多框架：
```typescript
// ConfigMapping 类型定义（percy-automate/types.ts）
export type ConfigMapping = {
[language: string]: {
[driver: string]: {
[framework: string]: {
instructions: string;
};
};
};
};
```
这种嵌套结构允许根据项目技术栈动态生成相应的配置说明。
### Appium SDK 处理流程
```mermaid
graph LR
A[用户请求] --> B[setupBrowserStackAppAutomateTests]
B --> C[验证设备环境]
C --> D[generateAppBrowserStackYMLInstructions]
D --> E[getAppUploadInstruction]
E --> F[getAppInstructionsForProjectConfiguration]
F --> G[返回组合指令]
```
关键处理步骤：
1. **设备验证**：验证用户指定的移动设备配置
2. **YML 配置生成**：创建 `browserstack.yml` 文件内容
3. **应用上传指令**：生成应用上传到 BrowserStack 的命令
4. **项目配置指令**：根据框架和语言生成特定的 SDK 配置
资料来源：[src/tools/appautomate-utils/appium-sdk/handler.ts:1-80]()
### BrowserStack SDK 处理器
`sdkHandler.ts` 负责处理 Web 自动化测试的 SDK 集成，支持以下框架：
- Cypress
- WebdriverIO
- Playwright
- Selenium
特殊处理逻辑：
```typescript
// 对于 Cypress 和 WebdriverIO，使用独立的设置指令
if (
input.detectedBrowserAutomationFramework === "cypress" ||
input.detectedBrowserAutomationFramework === "webdriverio"
) {
const frameworkInstructions = getInstructionsForProjectConfiguration(
input.detectedBrowserAutomationFramework,
input.detectedTestingFramework,
input.detectedLanguage,
username,
accessKey,
);
}
```
资料来源：[src/tools/sdk-utils/bstack/sdkHandler.ts:1-50]()
### YML 配置生成
`configUtils.ts` 模块负责生成 `browserstack.yml` 配置文件内容，支持移动端和桌面端平台配置：
```typescript
function generatePlatformConfigs(config: {
validatedEnvironments?: ValidatedEnvironment[];
platforms?: string[];
}): string {
if (config.validatedEnvironments && config.validatedEnvironments.length > 0) {
const platforms = config.validatedEnvironments.map((env) => {
if (env.platform === "windows" || env.platform === "macos") {
// 桌面配置
return {
os: env.platform === "windows" ? "Windows" : "OS X",
osVersion: env.osVersion,
browserName: env.browser,
browserVersion: env.browserVersion || "latest",
};
} else {
// 移动端配置
return {
deviceName: env.deviceName,
osVersion: env.osVersion,
browserName: env.browser,
};
}
});
}
}
```
资料来源：[src/tools/sdk-utils/bstack/configUtils.ts:1-50]()
## 测试管理模块
### TCG API 封装
`TCG-utils/api.ts` 提供了测试案例生成（Test Case Generation）相关的 API 封装：
| 函数 | 功能 |
|------|------|
| `fetchTestCaseDetails()` | 获取测试用例详情 |
| `pollTestCaseDetails()` | 轮询获取测试用例详情结果 |
| `triggerTcg()` | 触发测试案例生成任务 |
使用追踪请求模式（traceRequestId）实现异步操作：
```typescript
export async function fetchTestCaseDetails(
documentId: number,
folderId: string,
projectId: string,
testCaseIds: string[],
source: string,
config: BrowserStackConfig,
): Promise {
const tmBaseUrl = await getTMBaseURL(config);
const res = await apiClient.post({
url: FETCH_DETAILS_URL(tmBaseUrl),
headers: {
"API-TOKEN": getBrowserStackAuth(config),
"request-source": source,
},
body: {
document_id: documentId,
folder_id: folderId,
project_id: projectId,
test_case_ids: testCaseIds,
},
});
return res.data.request_trace_id;
}
```
资料来源：[src/tools/testmanagement-utils/TCG-utils/api.ts:1-50]()
## 配置与认证
### BrowserStackConfig 配置结构
```typescript
interface BrowserStackConfig {
username: string; // BrowserStack 用户名
accessKey: string; // BrowserStack 访问密钥
// ... 其他配置项
}
```
认证信息通过环境变量或配置文件获取：
```bash
export BROWSERSTACK_USERNAME="your_username"
export BROWSERSTACK_ACCESS_KEY="your_access_key"
```
### 环境基础 URL 动态获取
v1.2.8 版本重构了 TM API URLs 使用动态基础 URL 检索：
```typescript
const tmBaseUrl = await getTMBaseURL(config);
```
这允许在不同环境（生产、预发、测试）中使用不同的 API 端点。
## 技术栈总结
| 层级 | 技术/框架 | 用途 |
|------|----------|------|
| 协议层 | MCP SDK | Model Context Protocol 实现 |
| HTTP 框架 | Hono | 轻量级 Web 框架，处理 HTTP 端点 |
| HTTP 客户端 | Axios | API 请求封装 |
| 类型验证 | Zod | 运行时类型验证 |
| 日志 | Pino | 结构化日志 |
| 语言 | TypeScript | 类型安全的 JavaScript |
## 相关社区问题
根据社区反馈，以下问题可能与架构相关：
1. **发布说明不够详细**（Issue #49）：用户反映 release notes 只显示 "See CHANGELOG.md for details"，但找不到 CHANGELOG.md 文件
2. **工具请求：获取自动化日志和截图**（Issue #25）：用户希望在测试失败时能通过 MCP 工具直接获取 BrowserStack 会话 URL、视频录制和日志
## 版本演进要点
| 版本 | 架构变更 |
|------|----------|
| v1.2.20 | 强化 CI 工作流，严格 TLS 验证 |
| v1.2.18 | 扩展 self-heal 工具支持构建相关功能 |
| v1.2.17 | 安全修复：验证上传路径防止文件泄露 |
| v1.2.8 | 重构 TM API URLs 使用动态基础 URL 检索 |
| v1.2.7 | 修复 Windows 机器上 live 工具重定向问题 |
---
---
## Doramagic 踩坑日志
项目：agenttrust/mcp-server
摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 社区讨论暴露的待验证问题：darkzodchi en X: "Top MCP Servers That Turn Claude Into a Productivity Machine" / X。
## 1. 安装坑 · 社区讨论暴露的待验证问题：darkzodchi en X: "Top MCP Servers That Turn Claude Into a Productivity Machine" / X
- 严重度：medium
- 证据强度：source_linked
- 发现：darkzodchi en X: "Top MCP Servers That Turn Claude Into a Productivity Machine" / X Each session returns a live browser URL your agent controls. Free: 100 sessions/mo · https://github.com/browserbase/mcp-server-browserbase · 12 — GitHub — PRs, issues, code search, CI/CD workflows. The first MCP server every developer…
- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
- 证据：social_signal:x | ssig_9df635b2db4e49dc88b24ae5e8230ed4 | https://x.com/zodchiii/status/2041804097628582294 | darkzodchi en X: "Top MCP Servers That Turn Claude Into a Productivity Machine" / X
## 2. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | mcp_registry:ai.agenttrust/mcp-server:1.1.1 | https://registry.modelcontextprotocol.io/v0.1/servers/ai.agenttrust%2Fmcp-server/versions/1.1.1 | README/documentation is current enough for a first validation pass.
## 3. 运行坑 · 社区讨论暴露的待验证问题：Adding Github MCP to Claude Code Error : r/ClaudeAI - Reddit
- 严重度：medium
- 证据强度：source_linked
- 发现：Adding Github MCP to Claude Code Error : r/ClaudeAI - Reddit 22 Jun 2025 · Source of solution: https://github.com/github/github-mcp-server ... New in Claude Code: agent view. r/ClaudeAI - New in Claude Code ...
- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
- 证据：social_signal:reddit | ssig_928f35e76c1442709ae4143bf1ef6218 | https://www.reddit.com/r/ClaudeAI/comments/1li0v90/adding_github_mcp_to_claude_code_error/ | Adding Github MCP to Claude Code Error : r/ClaudeAI - Reddit
## 4. 运行坑 · 社区讨论暴露的待验证问题：you need somewhere between 1-10 Claude skills depending on what ...
- 严重度：medium
- 证据强度：source_linked
- 发现：you need somewhere between 1-10 Claude skills depending on what ... 20 Mar 2026 · https://github.com/haris-musa/excel-mcp-server ... Claude Inspector — See hidden Claude Code prompt mechanics https://github.com/kangraemin/claude ...
- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
- 证据：social_signal:x | ssig_504e57203f64433a83bf7ec96631f94c | https://x.com/Hesamation/status/2035136966719582695 | you need somewhere between 1-10 Claude skills depending on what ...
## 5. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | mcp_registry:ai.agenttrust/mcp-server:1.1.1 | https://registry.modelcontextprotocol.io/v0.1/servers/ai.agenttrust%2Fmcp-server/versions/1.1.1 | last_activity_observed missing
## 6. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | mcp_registry:ai.agenttrust/mcp-server:1.1.1 | https://registry.modelcontextprotocol.io/v0.1/servers/ai.agenttrust%2Fmcp-server/versions/1.1.1 | no_demo; severity=medium
## 7. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | mcp_registry:ai.agenttrust/mcp-server:1.1.1 | https://registry.modelcontextprotocol.io/v0.1/servers/ai.agenttrust%2Fmcp-server/versions/1.1.1 | no_demo; severity=medium
## 8. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | mcp_registry:ai.agenttrust/mcp-server:1.1.1 | https://registry.modelcontextprotocol.io/v0.1/servers/ai.agenttrust%2Fmcp-server/versions/1.1.1 | issue_or_pr_quality=unknown
## 9. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | mcp_registry:ai.agenttrust/mcp-server:1.1.1 | https://registry.modelcontextprotocol.io/v0.1/servers/ai.agenttrust%2Fmcp-server/versions/1.1.1 | release_recency=unknown