项目定位与核心价值

BrowserStack MCP Server 的核心价值在于降低测试自动化的门槛。传统方式下，开发者需要手动编写复杂的配置文件、理解 BrowserStack API 并编写集成代码。通过 MCP 协议，用户可以直接用自然语言描述测试需求，系统自动识别项目技术栈并生成相应的配置和测试代码。

当前版本为 v1.2.20，该版本主要修复了 CI 工作流安全加固以及 TLS 证书验证相关问题。

技术架构

整体架构

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]

核心组件结构

核心功能模块

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

安装与配置

环境要求

安装步骤

1. 克隆仓库：

git clone https://github.com/browserstack/mcp-server
cd mcp-server

1. 安装依赖：

npm install

1. 构建项目：

npm run build

1. 配置环境变量：

export BROWSERSTACK_USERNAME="your_username"
export BROWSERSTACK_ACCESS_KEY="your_access_key"

MCP 客户端配置

支持两种配置方式：

远程 MCP 服务器配置示例：

{
  "mcpServers": {
    "browserstack": {
      "command": "npx",
      "args": ["-y", "@browserstack/mcp-server"]
    }
  }
}

工具清单

MCP Server 提供的核心工具按照功能可分为以下类别：

可访问性测试

Web 自动化

App 自动化

测试管理

视觉测试

AI 代理

典型使用场景

场景一：配置 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. 更新测试结果

版本历史与社区反馈

近期版本亮点

社区关注点

根据社区讨论，以下问题值得关注：

1. 发布说明不够详细：用户反馈当前发布说明仅显示"See CHANGELOG.md for details"，但 CHANGELOG.md 在仓库中难以找到。

1. 日志与截图获取：用户希望能直接通过 MCP 获取 Automate 的执行日志和截图，减少在浏览器中手动查看的步骤。

安全性注意事项

最新版本中包含以下安全改进：

• 文件上传路径验证：防止路径遍历攻击
• 环境变量清理：确保敏感信息正确清理
• TLS 验证：启用严格的 TLS 证书验证

贡献与支持

欢迎社区贡献！请参阅 CONTRIBUTING.md 了解贡献指南。

如遇到问题，可通过以下方式获取支持：

• 在 GitHub Issues 提交问题
• 联系 BrowserStack 支持团队

延伸阅读

• MCP 协议规范
• BrowserStack 开发者文档
• Percy 视觉测试文档

系统要求

BrowserStack MCP Server 基于 Node.js 构建，主要依赖环境如下：

环境变量配置

MCP Server 通过环境变量进行身份认证和功能配置。环境变量文件采用标准格式，支持多行 YAML 配置。

必需的环境变量

可选环境变量

环境配置文件示例

# .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

本地安装

方式一：从源码安装

# 克隆仓库
git clone https://github.com/browserstack/mcp-server.git
cd mcp-server

# 安装依赖
npm install

# 构建项目
npm run build

# 复制并编辑环境变量文件
cp .env.example .env
vim .env  # 编辑配置

方式二：使用 Docker

# 构建镜像
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 等直接通过标准输入输出通信的客户端集成：

npm run build
node ./dist/index.js

HTTP 模式

适用于远程连接场景，需要配置 HTTP 端点：

npm run build
node ./dist/index.js http

服务器将启动在配置的 HOST:PORT 上，默认监听 http://0.0.0.0:3000。

远程 MCP 服务器

BrowserStack 提供托管的远程 MCP 服务器，可直接使用：

SDK 集成配置

MCP Server 支持多种测试框架和语言的 SDK 集成配置，通过分析项目代码自动生成相应的配置指令。

支持的编程语言

支持的自动化框架

平台配置

SDK 支持桌面和移动设备测试配置：

graph TD
    A[平台配置] --> B[桌面平台]
    A --> C[移动平台]
    B --> B1[Windows]
    B --> B2[macOS]
    C --> C1[Android]
    C --> C2[iOS]

#### 桌面平台配置结构

platform: windows | macos
osVersion: "10" | "11" | "latest" | "oldest"
browser: Chrome | Firefox | Safari | Edge
browserVersion: "latest" | "oldest" | "130"

#### 移动平台配置结构

deviceName: "Samsung Galaxy S24" | "iPhone 15"
osVersion: "14" | "16" | "latest" | "oldest"
browser: Chrome | Safari

资料来源：src/tools/sdk-utils/bstack/configUtils.ts

BrowserStack SDK 安装命令

根据检测到的语言和框架，生成对应的 SDK 安装命令：

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[返回配置步骤]

# 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

browserstack.yml 配置文件

对于非 Cypress/WebDriverIO 框架，配置通过 browserstack.yml 文件管理：

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

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 支持的配置

App Automate Maven 配置（Java）

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

Percy 集成配置

MCP Server 支持两种 Percy 集成类型：

Percy 集成类型

Percy Token 配置

# 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

Percy Web 配置参数

资料来源：src/tools/sdk-utils/common/schema.ts

身份认证机制

MCP Server 使用 API Token 方式进行身份认证。

认证流程

sequenceDiagram
    participant User
    participant MCP as MCP Server
    participant BS as BrowserStack API
    User->>MCP: 配置环境变量
    MCP->>BS: 发送认证请求
    BS-->>MCP: 验证成功/失败
    MCP-->>User: 返回认证状态

认证方式

// 方式一：环境变量
BROWSERSTACK_USERNAME=xxx
BROWSERSTACK_ACCESS_KEY=xxx

// 方式二：API Token（内部使用）
headers: {
  "API-TOKEN": getBrowserStackAuth(config)
}

资料来源：src/lib/get-auth.ts

TLS/SSL 配置

对于需要严格 TLS 验证的企业用户，MCP Server 支持自定义 CA 证书配置：

启用严格 TLS 验证：

# 设置 CA 证书路径
CA_CERT_PATH=/path/to/enterprise-ca-cert.pem

# 服务器将启用严格 TLS 验证

资料来源：v1.2.20 安全修复

验证配置

启动 MCP Server 后，可通过以下方式验证配置是否正确：

1. 检查服务器状态

# STDIO 模式启动后，观察日志输出
npm run build && node ./dist/index.js

2. 测试可用工具

配置完成后，以下工具应可正常使用：

常见配置问题

问题：认证失败

解决方案：

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 导出方式配置

进阶配置

自定义日志级别

LOG_LEVEL=debug npm run build && node ./dist/index.js

支持级别：error, warn, info, debug, trace

代理配置

如需通过代理访问 BrowserStack API，在环境变量中配置：

HTTP_PROXY=http://proxy.example.com:8080
HTTPS_PROXY=http://proxy.example.com:8080

概述

测试管理工具（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、v1.2.18 Release Notes

架构设计

模块结构

测试管理工具采用分层架构设计，核心模块位于 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              # 文件夹列表

数据流架构

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. 项目与文件夹管理

项目和文件夹是测试管理的基础组织单元。用户可以通过自然语言描述创建项目结构。

主要工具：

创建项目示例：

# 创建新项目和子文件夹
"create new Test management project named My Demo Project with two sub folders - Login & Checkout"

资料来源：create-project-folder.ts

2. 测试用例管理

测试用例管理模块提供了完整的 CRUD 操作能力，支持从文档文件批量导入测试用例。

主要工具：

数据类型映射：

interface DefaultFieldMaps {
  priority: Record<string, number>;
  status: Record<string, number>;
  caseType: Record<string, number>;
}

资料来源：types.ts:18-22

创建测试用例示例：

# 添加登录失败测试用例
"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. 测试运行管理

测试运行用于组织和执行一组测试用例，并记录测试结果。

主要工具：

创建测试运行示例：

# 创建测试运行
"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. 测试计划管理

测试计划用于组织和管理相关测试用例的集合，支持层级结构（父计划与子计划）。

主要工具：

功能演进：

graph LR
    A[v1.2.16] -->|新增| B[listTestPlans]
    A -->|新增| C[getTestPlan]
    D[v1.2.18] -->|扩展| E[listSubTestPlans]
    D -->|扩展| F[getSubTestPlan]

资料来源：#283 PR、#301 PR

5. 文件夹管理

文件夹提供了在项目内部组织测试用例的额外层级结构。

主要工具：

资料来源：#280 PR

API 接口层

底层 API 封装位于 src/tools/testmanagement-utils/TCG-utils/api.ts，提供了与 BrowserStack Test Management API 的通信能力。

API 封装结构

// API 层主要职责
- HTTP 请求封装
- 认证头处理
- 错误处理和重试
- 响应数据转换
- API 端点管理

资料来源：api.ts

请求处理流程

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 定义：

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

Scenario 接口

场景数据模型定义：

interface Scenario {
  id: string;
  name: string;
  testcases: any[];
  traceId?: string;
}

资料来源：types.ts:24-29

使用场景与示例

典型工作流程

graph TD
    A[创建项目] --> B[创建文件夹结构]
    B --> C[添加测试用例]
    C --> D[创建测试计划]
    D --> E[组织子测试计划]
    E --> F[创建测试运行]
    F --> G[执行测试]
    G --> H[更新测试结果]

完整使用示例

场景：管理登录功能测试

# 步骤 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

配置与依赖

环境要求

• Node.js 运行环境
• BrowserStack 账户（需配置 username 和 access_key）
• BrowserStack Test Management 功能订阅

认证配置

测试管理工具通过 MCP Server 的全局配置获取 BrowserStack 认证凭证：

// 认证信息通过 config 参数传递
addTestManagementTools(server, config) {
  // config.username - BrowserStack 用户名
  // config.accessKey - BrowserStack 访问密钥
}

版本历史

相关资源

• BrowserStack Test Management 官方文档
• MCP Server 官方仓库
• 测试管理工具源码

概述

实时测试与自动化工具是 BrowserStack MCP Server 的核心功能模块，为开发者提供通过自然语言与 BrowserStack 测试平台交互的能力。该模块包含四大主要工具集：

这些工具通过 MCP（Model Context Protocol）协议与 AI 助手集成，使用户能够通过自然语言描述来启动测试会话、获取截图、日志和失败详情。

架构概览

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 测试会话。

参数说明：

源码位置： src/tools/applive-utils/start-session.ts

#### 2. deviceSearch

搜索可用的移动设备。

参数说明：

源码位置： src/tools/applive-utils/device-search.ts

工作流程

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

支持的测试框架：

源码位置： 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 文件

配置示例：

platforms:
  - deviceName: "Samsung Galaxy S24"
    osVersion: "14"
    browserName: "android"

Live 工具

功能说明

Live 工具提供实时浏览器测试能力，支持在多种操作系统和浏览器上进行交互式测试。

核心工具

#### startLiveSession

启动 Live 浏览器测试会话。

参数说明：

源码位置： src/tools/live-utils/start-session.ts

Automate 工具

功能说明

Automate 工具支持在 BrowserStack 托管的浏览器上运行 Selenium/WebDriver 自动化测试。

核心工具

#### fetchScreenshots

获取自动化测试的屏幕截图。

参数说明：

源码位置： src/tools/automate-utils/fetch-screenshots.ts

WDIO 集成

MCP Server 与 WebDriverIO (WDIO) 深度集成，支持使用自然语言配置和运行 WDIO 测试套件。

⚠️ 已知问题：早期版本（v1.2.11/v1.2.12）中存在 WDIO 集成在 Windows 机器上无法正确重定向的问题，已在后续版本中修复。

失败日志工具

功能说明

失败日志工具用于从自动化测试运行中检索失败测试的详细日志，帮助开发者快速定位问题根因。

核心工具

#### getFailureLogs

获取失败测试的日志信息。

参数说明：

返回数据：

源码位置： src/tools/get-failure-logs.ts

日志处理模块

失败日志工具根据目标平台使用不同的处理模块：

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

数据模型

设备配置模型

interface DeviceConfig {
  deviceName?: string;      // 移动设备名称
  os?: string;              // 操作系统 (Windows/OS X/Android/iOS)
  osVersion: string;        // 系统版本
  browserName?: string;     // 浏览器名称
  browserVersion?: string;  // 浏览器版本
}

会话响应模型

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"
}

版本历史

社区反馈

高优先级需求

Issue #25：获取自动化日志和截图工具（4 条评论）

用户反馈：在使用 Automate 和 App Automate 时，测试失败后会打印 BrowserStack 会话 URL，用户需要手动打开 URL 来查看视频录制和日志。社区强烈请求通过 MCP 工具直接获取这些信息。

当前解决方案： 已通过 fetchScreenshots 和 getFailureLogs 工具满足此需求。

安全改进

近期版本（v1.2.17+）增强了安全措施：

• 添加文件上传路径验证，防止路径遍历攻击
• 修复环境变量清理机制
• 强化 CI 工作流安全性

相关文档

• SDK 工具配置 - SDK 集成详细指南
• Percy 可视化测试 - 视觉回归测试集成
• 测试管理工具 - 测试用例和计划管理

概述

无障碍扫描工具是 BrowserStack MCP Server 的核心功能之一，通过自然语言交互帮助开发者扫描并修复网站的无障碍（Accessibility）问题。该工具集成于 BrowserStack 平台，支持对本地的开发环境（localhost）和生产环境网站进行自动化无障碍审计。

根据社区发布记录，该功能在 v1.2.12 版本中首次引入超时机制支持（#239），并在 v1.2.13 和 v1.2.14 版本中持续增强，新增了高级规则选项配置（#252）。

核心功能

工具架构

无障碍扫描工具采用模块化架构设计，包含以下核心组件：

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

组件说明

使用方式

基本语法

无障碍扫描工具支持两种主要使用场景：

#### 1. 本地开发环境扫描

"帮我扫描 localhost:3000 上运行网站的 accessibility 问题"

#### 2. 生产环境扫描

"运行 accessibility scan & 识别我的网站 www.bstackdemo.com 上的问题"

高级规则配置

在 v1.2.14 版本中新增的高级规则选项，允许用户指定特定的 WCAG 标准进行扫描：

工具参数定义

根据源码中的 Zod schema 定义，无障碍扫描工具支持以下参数：

// 参数结构定义示例
{
  url: z.string().describe("待扫描的目标 URL"),
  standard: z.enum(["A", "AA", "AAA", "latest"]).optional(),
  timeout: z.number().optional(),
  waitUntil: z.enum(["load", "domcontentloaded", "networkidle"]).optional()
}

扫描流程

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 返回的原始扫描报告转换为结构化数据：

// 报告数据结构
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 实现基于检索增强生成的修复建议系统：

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 工具配合使用，形成完整的测试工作流：

版本历史

常见问题

扫描超时

如果网站加载时间过长，可通过 timeout 参数增加超时时间：

"扫描 www.example.com 的 accessibility 问题，超时时间设置为 60 秒"

本地环境访问

对于 localhost 环境，确保服务已启动并可从 MCP Server 所在网络访问。

高级规则选择

建议生产环境使用 "AA" 标准进行扫描，兼顾覆盖面与严格程度。

参考资料

• BrowserStack 官方文档：BrowserStack Accessibility Testing
• WCAG 2.1 规范：W3C WCAG 2.1
• 工具源码：src/tools/accessibility.ts

系统架构概述

SDK 集成模块采用分层架构设计，将通用功能与特定框架实现解耦。系统主要由以下几个核心模块组成：

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 集成语言：

资料来源：src/tools/sdk-utils/common/types.ts:4-9

Appium SDK 语言支持

Appium SDK 集成模块在 src/tools/appautomate-utils/appium-sdk/types.ts 中定义了独立的语言枚举：

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 测试场景：

资料来源：src/tools/sdk-utils/common/types.ts:15-21

测试运行框架

每种语言都支持多种测试运行框架，具体支持情况如下：

#### Java 测试框架

资料来源：src/tools/appautomate-utils/appium-sdk/languages/java.ts:8-25

#### Python 测试框架

资料来源：src/tools/appautomate-utils/appium-sdk/languages/python.ts:6-37

#### Appium 测试框架

移动端 Appium 测试支持更广泛的框架：

资料来源：src/tools/appautomate-utils/appium-sdk/types.ts:13-46

SDK 集成类型

Percy 可视化测试集成

Percy 集成支持三种模式，每种模式针对不同的测试场景：

资料来源：src/tools/sdk-utils/common/types.ts:1-3

类型定义详解

Percy Web 配置映射结构：

export type ConfigMapping = {
  [language: string]: {
    [automationFramework: string]: {
      instructions: string;
      snapshotInstruction: string;
    };
  };
};

资料来源：src/tools/sdk-utils/percy-web/types.ts:1-10

Percy Automate 配置映射结构：

export type ConfigMapping = {
  [language: string]: {
    [driver: string]: {
      [framework: string]: {
        instructions: string;
      };
    };
  };
};

资料来源：src/tools/sdk-utils/percy-automate/types.ts:1-13

Percy + BrowserStack SDK 配置映射结构：

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

输入参数架构

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

处理流程

graph LR
    A[输入参数验证] --> B[生成 BrowserStack YML 配置]
    B --> C[生成 App 上传指令]
    C --> D[生成项目配置和运行指令]
    D --> E[格式化输出]

Appium SDK 处理流程在 src/tools/appautomate-utils/appium-sdk/handler.ts 中实现：

// 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 工具：

资料来源：src/tools/appautomate-utils/native-execution/constants.ts:8-30

设备配置

移动设备通过以下 Schema 定义：

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：

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

框架指令生成

系统根据测试框架类型生成对应的运行指令：

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 配置文件：

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 输出示例

生成的配置文件格式如下：

# 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 查看

1. 版本兼容性：WDIO 集成的修复（v1.2.11, v1.2.12）

• 针对 Windows 机器的 Live 工具重定向问题进行了修复

1. 安全增强：路径验证和环境变量清理（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
• 最新版本：v1.2.20
• Appium SDK 集成工具：setupBrowserStackAppAutomateTests
• 原生测试执行工具：runAppTestsOnBrowserStack

概述

Percy 视觉测试集成是 BrowserStack MCP Server 提供的核心功能之一，允许用户在 AI 助手的指导下快速配置和集成 Percy 视觉测试服务。该模块支持三种集成类型：Percy Web、Percy Automate 和 Percy + BrowserStack SDK，每种类型针对不同的测试场景和工作流程进行了优化。

架构设计

集成类型体系

MCP Server 中的 Percy 集成采用分层架构，根据测试框架和自动化工具的不同组合提供定制化的配置指令：

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 配置映射

// src/tools/sdk-utils/percy-web/types.ts:1-10
export type ConfigMapping = {
  [language: string]: {
    [automationFramework: string]: {
      instructions: string;
      snapshotInstruction: string;
    };
  };
};

#### Percy Automate 配置映射

// src/tools/sdk-utils/percy-automate/types.ts:1-12
export type ConfigMapping = {
  [language: string]: {
    [driver: string]: {
      [framework: string]: {
        instructions: string;
      };
    };
  };
};

#### Percy + BrowserStack SDK 配置映射

// 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。处理器根据检测到的编程语言和自动化框架生成相应的配置指令。

// 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: [],
  };
}

支持的编程语言和框架：

2. Percy Automate 处理器

Percy Automate 允许在 BrowserStack Automate 基础设施上执行视觉测试，同时获取 Selenium/Playwright 的原生能力。

// src/tools/sdk-utils/percy-automate/handler.ts
// 支持 Playwright, Selenium, Cypress, WebdriverIO

3. Percy + BrowserStack SDK 处理器

这是最完整的集成方案，结合 BrowserStack SDK 的所有功能，包括测试执行、可视化报告和自我修复能力。

// src/tools/sdk-utils/percy-bstack/handler.ts:30-80
export async function runPercyWithBrowserstackSDK(
  input: SetupPercyParams,
  config: BrowserStackConfig
): Promise<SetupResult> {
  // 检测到的设备列表
  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: [] };
}

指令生成系统

指令检索机制

// 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}
`;
}

支持的语言枚举

// src/tools/sdk-utils/common/types.ts:6-12
export enum SDKSupportedLanguageEnum {
  nodejs = "nodejs",
  python = "python",
  java = "java",
  csharp = "csharp",
  ruby = "ruby",
}

支持的自动化框架枚举

// src/tools/sdk-utils/common/types.ts:14-21
export enum SDKSupportedBrowserAutomationFrameworkEnum {
  playwright = "playwright",
  selenium = "selenium",
  cypress = "cypress",
  webdriverio = "webdriverio",
}

支持的测试框架枚举

// 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 测试文件：

// 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\]/,
];

快照指令常量

// 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');
\`\`\`
`;

集成类型枚举

// src/tools/sdk-utils/common/types.ts:1-4
export enum PercyIntegrationTypeEnum {
  WEB = "web",
  AUTOMATE = "automate",
}

安全配置

PERCY_TOKEN 管理

系统通过环境变量安全地处理 Percy 令牌：

// 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=<your Percy project token>) 
or export it in your shell:

  - macOS/Linux:    export PERCY_TOKEN="<your Percy project token>"
  - Windows (PS):   $env:PERCY_TOKEN="<your Percy project token>"
  - Windows (CMD):  set PERCY_TOKEN=<your Percy project token>

Do not paste the token into chat or commit it.`;
}

工作流程

设置流程图

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[完成配置]

参数定义

// 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 测试文件目录路径数组"),
};

版本历史

相关工具

MCP Server 还提供了以下与 Percy 相关的工具：

• setupPercy - 设置 Percy 视觉测试环境
• runPercyScan - 执行 Percy 扫描并生成报告
• addPercySnapshots - 为现有测试添加快照
• reviewPercySnapshots - 审查快照差异
• managePercyBuildApproval - 管理构建审批状态

BrowserStack MCP Server 提供了强大的 AI 智能体功能，帮助开发者自动化测试工作流程。这些 AI 智能体包括自我修复智能体（Self-Heal Agent）、根因分析智能体（RCA Agent）和低代码自动化智能体（Low-Code Automation Agent）。通过这些功能，开发者可以利用 AI 技术自动修复不稳定的测试脚本、生成测试用例，以及将手动测试转换为自动化脚本。

功能概述

AI 智能体功能主要解决以下测试挑战：

架构设计

整体架构

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[返回自动化脚本]

自我修复流程

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

#### 状态流转

stateDiagram-v2
    [*] --> Pending: 创建修复任务
    Pending --> InProgress: 开始处理
    InProgress --> InProgress: 继续处理
    InProgress --> Success: 修复完成
    InProgress --> Failed: 处理失败
    Failed --> [*]
    Success --> [*]

使用示例

// 触发自我修复
const result = await selfHealCore({
  buildId: "build-12345",
  projectId: "project-abc",
  framework: "playwright",
  language: "typescript"
});

配置参数

资料来源：src/tools/selfheal.ts:50-80

根因分析智能体（RCA Agent）

功能描述

根因分析智能体（RCA Agent）用于深入分析测试失败的原因，提供结构化的失败分析和修复建议。该智能体通过收集测试执行数据、日志和错误信息，帮助开发者快速定位问题根源。

资料来源：src/tools/rca-agent.ts:1-60

数据收集流程

graph LR
    A[获取构建数据] --> B[获取失败测试ID]
    B --> C[收集测试日志]
    C --> D[格式化RCA报告]
    D --> E[返回分析结果]

核心功能

#### 1. 获取失败测试 ID

getFailedTestId() 函数从构建数据中提取失败的测试用例标识符。

返回值结构：

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 报告格式。

处理逻辑：

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 数据结构

资料来源：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

工作流程

graph TD
    A[用户提供测试用例] --> B[创建LCA任务]
    B --> C[上传相关文件]
    C --> D[轮询任务状态]
    D -->|处理中| D
    D -->|完成| E[获取生成的代码]
    E --> F[下载自动化脚本]

核心 API

#### 1. 创建低代码自动化任务

createLCASteps() 函数向 BrowserStack Test Management API 发起自动化转换请求。

API 调用：

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() 函数持续检查低代码自动化任务的处理状态。

轮询策略：

async function pollLCAStatus(
  traceRequestId: string,
  maxAttempts: number = 10,
  intervalMs: number = 5000
): Promise<LCAResult> {
  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 分析和生成自动化脚本。

上传流程：

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

支持的文件类型：

资料来源：src/tools/testmanagement-utils/upload-file.ts:1-100

使用示例

// 将手动测试转换为自动化脚本
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:测试管理部分

支持的测试类型识别

智能体能够自动识别测试文件中的不同测试类型：

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: 当自我修复无法自动解决问题时，系统会提供详细的失败原因分析和替代建议，帮助开发者手动修复。

相关链接

• 自我修复功能文档
• 根因分析功能文档
• 低代码自动化功能文档

概述

构建洞察与 Review 智能体是 BrowserStack MCP Server 中的核心功能模块，专注于为测试构建提供深度分析、质量门评估和可视化审查能力。该模块通过集成 BrowserStack 的可观测性服务，帮助开发团队快速获取构建状态、识别失败模式、追踪错误趋势，并通过 Percy 集成实现自动化视觉回归审查。

构建洞察功能（Build Insights）通过组合构建详情（Build Details）与质量门结果（Quality Gate Results），为测试执行提供全面的质量可见性。Review 智能体则专注于管理视觉回归测试的审批流程，支持对 Percy 构建进行批准、拒绝和取消批准等操作。

核心组件架构

组件关系图

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

模块职责划分

构建洞察功能详解

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）

返回数据结构

{
  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 提供的质量保障机制，用于评估构建是否满足预定义的质量标准。模块会映射每个质量配置文件的名称和结果状态：

const qualityProfiles = qualityData.quality_profiles?.map(
  (profile: any) => ({
    name: profile.name,
    result: profile.result,
  }),
);

当存在质量门配置时，返回格式化的文本描述；否则返回"No Quality Gate Profiles available."提示信息。

洞察数据字段映射

Review 智能体功能

功能概述

Review 智能体专注于视觉回归测试的审查与审批流程，与 Percy 平台深度集成。它允许 AI 代理通过自然语言指令管理视觉构建的审批状态，实现测试工作流的自动化。

Percy 构建审批管理

Percy 审批功能通过 ManagePercyBuildApprovalParamsShape 定义操作参数：

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

#### 支持的操作类型

构建计数统计

构建计数模块提供构建通过/失败的统计能力，帮助团队监控测试趋势：

export default function addBuildCountsTools(
  server: McpServer,
  config: BrowserStackConfig,
) {
  const tools: Record<string, any> = {};
  // 工具注册逻辑
}

工作流程设计

构建洞察获取流程

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 智能体操作流程

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 参数

ManagePercyBuildApproval 参数

错误处理机制

构建洞察与 Review 智能体均实现了健壮的错误处理：

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)

使用示例

获取构建洞察

# 通过 MCP 协议调用
{
  "tool": "fetchBuildInsights",
  "arguments": {
    "build_id": "build-12345",
    "project_id": "project-abc"
  }
}

批准 Percy 构建

# 批准视觉回归测试通过
{
  "tool": "managePercyBuildApproval",
  "arguments": {
    "buildId": "percy-build-67890",
    "action": "approve"
  }
}

安全考虑

根据 v1.2.17 版本的安全修复，项目实现了以下安全措施：

• 上传路径验证，防止文件外泄攻击
• 环境变量清理机制

资料来源：v1.2.17 Release Notes

最佳实践

1. 定期审查质量门配置：确保质量标准与团队目标保持一致
2. 利用智能标签：使用 AI 生成的 smart_tags 快速识别问题模式
3. 集成 CI/CD 流程：通过 ci_build_url 关联外部构建系统
4. 视觉回归审批规范化：建立明确的审批流程和责任划分

版本演进

相关资源

• BrowserStack Observability 文档
• Percy 视觉回归测试
• 质量门配置指南

概述

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：网站无障碍扫描功能

整体架构

graph TD
    subgraph "MCP Server Core"
        A[src/index.ts<br/>入口文件] --> B[src/server-factory.ts<br/>服务器工厂]
        B --> C[src/oninitialized.ts<br/>初始化处理]
        C --> D[src/lib/types.ts<br/>类型定义]
        D --> E[src/lib/utils.ts<br/>工具函数]
    end
    
    subgraph "API Layer"
        F[src/lib/apiClient.ts<br/>API客户端] --> G[src/lib/api.ts<br/>API函数]
        G --> H[src/lib/error.ts<br/>错误处理]
    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 请求处理机制：

资料来源：src/lib/apiClient.ts:1-50

#### src/lib/api.ts

包含所有与 BrowserStack API 交互的具体函数，如获取测试用例详情、触发构建分析等。该模块依赖于 apiClient 发起实际请求。

#### src/lib/error.ts

统一的错误处理模块，定义了以下错误类型：

// 错误类型定义（示意）
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 等

示例代码结构：

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 作为日志库，提供结构化日志输出：

// 日志级别配置
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 工具使用类型化的配置映射来支持多语言和多框架：

// ConfigMapping 类型定义（percy-automate/types.ts）
export type ConfigMapping = {
  [language: string]: {
    [driver: string]: {
      [framework: string]: {
        instructions: string;
      };
    };
  };
};

这种嵌套结构允许根据项目技术栈动态生成相应的配置说明。

Appium SDK 处理流程

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

特殊处理逻辑：

// 对于 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 配置文件内容，支持移动端和桌面端平台配置：

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 封装：

使用追踪请求模式（traceRequestId）实现异步操作：

export async function fetchTestCaseDetails(
  documentId: number,
  folderId: string,
  projectId: string,
  testCaseIds: string[],
  source: string,
  config: BrowserStackConfig,
): Promise<string> {
  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 配置结构

interface BrowserStackConfig {
  username: string;      // BrowserStack 用户名
  accessKey: string;     // BrowserStack 访问密钥
  // ... 其他配置项
}

认证信息通过环境变量或配置文件获取：

export BROWSERSTACK_USERNAME="your_username"
export BROWSERSTACK_ACCESS_KEY="your_access_key"

环境基础 URL 动态获取

v1.2.8 版本重构了 TM API URLs 使用动态基础 URL 检索：

const tmBaseUrl = await getTMBaseURL(config);

这允许在不同环境（生产、预发、测试）中使用不同的 API 端点。

技术栈总结

相关社区问题

根据社区反馈，以下问题可能与架构相关：

1. 发布说明不够详细（Issue #49）：用户反映 release notes 只显示 "See CHANGELOG.md for details"，但找不到 CHANGELOG.md 文件

1. 工具请求：获取自动化日志和截图（Issue #25）：用户希望在测试失败时能通过 MCP 工具直接获取 BrowserStack 会话 URL、视频录制和日志

版本演进要点

Pitfall Log / 踩坑日志

项目：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