Caliberfs Playwright MCP Server

QA自动化堆栈-MCP服务器

🚀 用于多框架浏览器自动化的模型上下文协议服务器 -WebDriver自动化工具可通过MCP访问，支持Selenium、WebDriver IO和Cypress。

🎯 概述

通过统一接口提供浏览器自动化功能的MCP（模型上下文协议）服务器。服务器公开了WebDriver自动化工具，AI助手可以使用这些工具与web浏览器进行交互。

主要特点：

• MCP服务器：将浏览器自动化作为MCP工具公开
• 多框架支持：适用于Selenium、WebDriver IO和Cypress的适配器
• 统一API：用于浏览器自动化的框架无关接口
• 类型安全：具有正确类型定义的完整TypeScript实现
• 整洁架构：用于可扩展工具处理的处理程序注册表模式

🛠️ 技术栈

核心依赖关系

• @模型上下文协议/sdk （^1.22.0）-MCP服务器实现
• YAML （^2.8.1）-配置文件支持
• TypeScript （5.0+）-类型安全与现代发展

可选框架适配器（对等依赖）

• Selenium WebDriver （^4.27.0）-行业标准WebDriver API
• WebDriver IO （^9.20.0）-具有增强功能的现代包装
• 柏树 （^13.16.0）-快速的浏览器内测试框架

注： 框架依赖关系是可选的对等依赖关系。只安装你需要的东西： ``bash npm install selenium-webdriver webdriverio cypress ``

🚀 快速开始

1.安装依赖项

# Use --ignore-scripts to avoid binary download failures
npm install --ignore-scripts

或者使用安装脚本：

npm run setup

2.建设项目

npm run build

3.启动MCP服务器

# Development mode (TypeScript)
npm run dev

# Production mode (compiled)
npm start

# Or directly
npm run mcp:server

📋 可用脚本

npm run build          # Compile TypeScript to dist/
npm start              # Run compiled MCP server
npm run dev            # Run MCP server in development mode
npm run setup          # Install deps (--ignore-scripts) + build
npm run clean          # Remove dist/, reports/, test-results/
npm run lint           # Check code style with ESLint
npm run lint:fix       # Auto-fix linting issues
npm run format         # Format code with Prettier
npm run format:check   # Check formatting without changes
npm run mcp:server     # Run MCP server with tsx

🔌 MCP工具

MCP服务器公开了以下浏览器自动化工具：

导航工具

• navigate -导航到URL
• go_back -返回浏览器历史记录
• go_forward -在浏览器历史记录中前进
• refresh_page -刷新当前页面

交互工具

• click -单击元素
• type -在元素中键入文本
• hover -将鼠标悬停在元素上

检测工具

• get_text -获取元素的文本内容
• get_page_title -获取当前页面标题
• get_current_url -获取当前URL
• screenshot -截图

表单工具

• fill_form -填写多个表单字段
• select_option -从下拉列表中选择一个选项

等待工具

• wait_for_element -等待元素出现

滚动工具

• scroll_to -滚动到特定元素

🏗️ 建筑

项目结构

src/
├── mcp-server.ts              # MCP server entry point
├── framework/                 # Multi-framework adapter system
│   ├── types.ts              # Common interfaces
│   ├── base-adapter.ts       # Abstract base class
│   ├── factory.ts            # Creates appropriate adapter
│   ├── config.ts             # Default configurations
│   ├── test-helper.ts        # Simplified API
│   └── adapters/             # Framework implementations
│       ├── selenium-adapter.ts
│       ├── webdriverio-adapter.ts
│       └── cypress-adapter.ts
├── handlers/                  # MCP tool handlers
│   ├── base-handler.ts       # Handler interface
│   ├── navigation-handlers.ts
│   ├── interaction-handlers.ts
│   ├── inspection-handlers.ts
│   ├── form-handlers.ts
│   ├── wait-handlers.ts
│   ├── scroll-handlers.ts
│   └── index.ts              # Handler registry
├── tools/                     # MCP tool definitions
│   └── index.ts              # Tool schemas
└── webdriver/                 # WebDriver manager
    └── manager.ts            # Browser session management

处理程序注册表模式

MCP服务器使用干净的处理程序注册表模式：

1. 基本处理程序接口：所有处理程序都实现 Handler
2. 处理程序注册表：将工具名称映射到处理程序实例
3. 专业处理人员：每个工具都有自己的处理程序类
4. 益处：开放/封闭原则，单一责任，可测试

添加新工具

1. 在中创建处理程序类 src/handlers/*-handlers.ts
2. 注册 handlerRegistry 在中映射 src/handlers/index.ts
3. 在中添加工具定义 src/tools/index.ts

框架适配器模式

统一的浏览器自动化API可跨多个框架工作：

// All frameworks support the same interface
interface IBrowserAdapter {
  // Navigation
  navigate(url: string): Promise;
  back(): Promise;
  forward(): Promise;

  // Interaction
  click(locator: string | Locator): Promise;
  type(locator: string | Locator, text: string): Promise;

  // Inspection
  getText(locator: string | Locator): Promise;
  isVisible(locator: string | Locator): Promise;

  // ... and many more
}

🔧 配置

框架选择

配置要使用的浏览器自动化框架：

import { FrameworkFactory, FrameworkType } from './src/framework/index.js';

// Create adapter
const browser = FrameworkFactory.createAdapter({
  framework: FrameworkType.SELENIUM, // or WEBDRIVERIO, CYPRESS
  browser: 'chrome',
  headless: true,
  timeout: 10000,
  viewport: { width: 1440, height: 900 }
});

await browser.initialize();
await browser.navigate('https://example.com');
await browser.close();

环境变量

FRAMEWORK=selenium|webdriverio|cypress   # Framework selection
BROWSER=chrome|firefox|safari            # Browser selection
HEADLESS=1                               # Headless mode
TIMEOUT=15000                            # Custom timeout (ms)

📦 安装说明

为什么 --ignore-scripts?

我们使用 --ignore-scripts 避免：

• 二进制下载 -chromedriver，壁虎驱动器，柏树二进制
• 网络故障 -在CI/CD环境中下载403错误
• 弃用警告 -更清洁的安装输出

这 .npmrc 文件集 loglevel=error 以抑制来自深度依赖链的弃用警告。

安装框架依赖项

框架依赖关系是 可选的对等依赖关系。只安装您需要的东西：

# Install all frameworks
npm install selenium-webdriver webdriverio cypress --ignore-scripts

# Or install specific frameworks
npm install selenium-webdriver --save-dev
npm install webdriverio --save-dev
npm install cypress --save-dev --ignore-scripts

🔒 类型安全

全部 any 类型已被替换为正确的TypeScript类型：

• Cookie cookie操作界面
• unknown 用于通用驱动程序和脚本参数
• 框架功能的适当类型防护装置
• 整个代码库中的完整类型推理

🚀 益处

1. MCP集成

AI助手可以通过模型上下文协议访问浏览器自动化。

2. 框架独立性

不锁定在任何单一框架中。无需重写工具即可切换适配器。

3. 整洁架构

处理程序注册表模式使添加新工具变得简单。

4. 类型安全

具有正确类型定义的完全TypeScript支持。

5. 可扩展

易于添加新的自动化框架或MCP工具。

6. 生产就绪

干净安装，无弃用警告，正确的错误处理。

📊 添加新框架

要添加对新框架（例如Playwright）的支持：

1. 创建 src/framework/adapters/playwright-adapter.ts
2. 实施 IBrowserAdapter 接口
3. 扩展 BaseBrowserAdapter 基类
4. 增添 FrameworkFactory 在 factory.ts
5. 更新 FrameworkType 枚举在 types.ts
6. 在中添加为对等依赖关系 package.json

例子：

import { BaseBrowserAdapter } from '../base-adapter.js';
import type { IBrowserAdapter } from '../types.js';

export class PlaywrightAdapter extends BaseBrowserAdapter implements IBrowserAdapter {
  async initialize(): Promise {
    // Playwright-specific initialization
  }

  async navigate(url: string): Promise {
    // Playwright-specific navigation
  }

  // ... implement all interface methods
}

🧹 代码质量

# Linting
npm run lint           # Check code style
npm run lint:fix       # Auto-fix issues

# Formatting
npm run format         # Format all files
npm run format:check   # Check without changes

# Type Checking
npm run build          # TypeScript compilation check

🤝 贡献

欢迎投稿！请确保：

• ✅ 构建通行证(npm run build)
• ✅ 林廷传球(npm run lint)
• ✅ 正确的TypeScript类型（否 any)
• ✅ 新工具的处理程序注册表模式
• ✅ 文件已更新

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件

🔗 资源

• 模型上下文协议
• MCP SDK文档
• Selenium WebDriver文档
• WebDriver IO文档
• 赛普拉斯文档
• 框架.md -详细的架构指南

______________________________________________________________________

内置于❤️ 用于MCP驱动的浏览器自动化