使用说明

Laravel Herd的Puppeter MCP服务器

一个专门为Laravel Herd本地开发测试设计的模型上下文协议（MCP）服务器，使Claude能够使用Puppeteer自动化Laravel应用程序的浏览器测试。

概述

这个MCP服务器通过与Laravel Herd的原生性能环境深度集成，弥合了人工智能驱动的自动化和现代Laravel开发之间的差距。它使Claude能够通过可视化调试、自动化交互和全面的测试自动化来执行复杂的浏览器测试。

主要特点

核心浏览器自动化

可视化调试：直接在网页上输出调试信息以供Claude分析
交互式测试：执行点击、滚动和JavaScript执行以进行全面测试
屏幕截图分析：捕获和分析页面状态以进行迭代调试
元素交互：使用CSS选择器和可访问性属性进行高级元素选择

Laravel羊群集成

本地.test域支持：通过Herd的dnsmasq自动解析域
SSL证书管理：使用自动生成的证书进行无缝HTTPS测试
PHP版本管理：通过Herd代理命令支持特定于站点的PHP版本
数据库状态管理：用于并行执行的隔离测试数据库

高性能

浏览器池管理：5-10个浏览器实例的高效连接池
上下文隔离：通过单独的浏览器上下文独立执行测试
性能监控：Chrome DevTools协议集成用于指标收集
网络侦听：API模拟和请求/响应分析

建筑

输运模型

混合式结构：stdio用于本地开发，HTTP+SSE用于远程访问
JSON-RPC 2.0：使用OAuth 2.1身份验证的标准MCP协议实现
连接池：优化浏览器实例管理（每个实例100-200MB）

安全功能

OAuth 2.1合规性PKCE支持HTTP传输
基于环境的身份验证：确保当地发展准入
输入验证：具有测试灵活性的注射攻击预防
精细权限：团队环境的范围访问控制

绩效目标

响应时间：p95<200ms，实现最佳克劳德相互作用
内存效率：每个浏览器实例100-200MB，自动清理
并行执行：支持多个并发的Laravel项目
可扩展性：通过分布式浏览器池进行横向扩展

Laravel测试集成

框架兼容性

拉雅韦尔黄昏API：无缝迁移的兼容模式
PHPUnit&害虫：与现有测试框架集成
ChromeDriver管理：由Herd自动处理
身份验证助手：Laravel特有的登录和会话管理

开发环境特征

自动配置：零配置的测试环境设置
数据库种子：支持测试数据管理和回滚
中间件测试：会话、身份验证和授权测试
API验证：全面的后端API测试功能

开发方法

此项目针对使用Claude Code进行迭代调试进行了优化：

可视化调试策略

直接在网页上输出调试信息，而不是控制台日志记录
使用Puppeteer捕捉屏幕截图以进行Claude分析
实现基于页面的调试信息显示
为测试迭代启用实时视觉反馈

交互式测试方法

直接在页面上执行JavaScript函数
执行自动点击、滚动和表单交互
捕获和分析用户交互流
支持复杂的多步骤测试场景

错误处理和恢复

智能分类：基于网络、超时和元素的错误分类
重试机制：可恢复故障的指数级回退
综合录井：屏幕截图、控制台日志和网络活动捕获
性能指标：与Chrome DevTools集成的详细故障分析

用例

前端开发

响应式设计测试：多设备和视口测试
组件交互：React/Vue组件行为验证
CSS回归测试：UI更改的视觉差异分析
性能优化：核心网络生命监测和分析

后端开发

API端点验证：使用网络拦截进行请求/响应测试
身份验证流程：完成登录/注销和会话管理测试
数据库集成：模型关系和数据一致性验证
中间件测试：安全和授权层验证

质量保证

端到端测试：完成用户旅程自动化
跨浏览器兼容性：多浏览器测试支持
负载测试：各种用户场景下的性能
可访问性测试：WCAG合规性验证

技术规格

浏览器管理

实例池：5-10个可配置的浏览器实例
内存管理：自动清理和重启机制
超时策略：分层超时配置
上下文隔离：独立测试环境

Laravel群体优化

目录集成：原生~/Herd目录支持
域名解析：自动.test域处理
SSL支持：使用Herd证书进行无缝HTTPS测试
PHP版本意识：特定于站点的PHP环境检测

未来路线图

第一阶段：核心实施

具有Laravel Dusk兼容性的基本浏览器自动化
屏幕截图和可视化调试
Laravel身份验证助手
数据库状态管理

第二阶段：群体优化

本地域解析集成
SSL证书自动化
PHP版本特定测试
性能优化

第三阶段：高级功能

使用jest图像快照进行视觉回归测试
并行测试编排
AI驱动的测试生成
团队协作功能

竞争优势

Laravel特定：与Laravel生态系统和Herd环境深度集成
AI优化：专为Claude Code迭代调试工作流程设计
性能优先：与容器化解决方案相比，测试执行速度提高了35%
可视化调试：基于屏幕截图的调试针对AI分析进行了优化
零配置：通过Laravel Herd集成自动设置

安装

使用npx（推荐）

为了快速设置和测试：

# Install and run directly
npx -y @truefrontier/puppeteer-laravel-mcp-server

Claude桌面应用程序配置

要将此MCP服务器与Claude Desktop一起使用：

启用开发人员模式:
- 打开克劳德桌面应用程序
- 转到“设置”→ 开发人员选项卡
- 启用开发人员模式，然后单击“编辑配置”
添加到claude_desktop_config json:

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

重新启动克劳德桌面 使更改生效

MCP检验员测试

使用官方MCP检查器测试您的服务器设置：

# Test the server directly
npx @modelcontextprotocol/inspector npx -y @truefrontier/puppeteer-laravel-mcp-server

# Or test with environment variables
npx @modelcontextprotocol/inspector -e BROWSER_POOL_SIZE=3 npx -y @truefrontier/puppeteer-laravel-mcp-server

# CLI mode for automation
npx @modelcontextprotocol/inspector --cli npx -y @truefrontier/puppeteer-laravel-mcp-server

检查器将打开一个web界面（默认：http://localhost:6274)您可以在哪里：

查看所有可用工具
测试工具执行
监控服务器响应
调试连接问题

先决条件

Node.js 18+与npm
Laravel Herd（用于本地开发）
Chrome/Chromium浏览器

开发设置

# Clone the repository
git clone <repository-url>
cd puppeteer-laravel-mcp-server

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env to match your Laravel Herd setup

# Build the project
npm run build

# Start the MCP server
npm start

验证

使用附带的测试脚本测试服务器：

node test-mcp.js

这将验证：

MCP服务器正确初始化
所有工具均已正确注册
浏览器池管理工作
会话管理功能
基本的导航和屏幕截图功能正常工作

Laravel羊群配置

# Ensure Herd is running
herd start

# Secure your sites for HTTPS testing (optional)
herd secure your-site.test

# Verify PHP version for specific sites
herd php -v --site=your-site.test

用法

基本浏览器自动化

// Navigate to a Laravel application
await page.goto('https://your-app.test');

// Interact with forms
await page.fill('#email', 'user@example.com');
await page.click('button[type="submit"]');

// Capture screenshots for debugging
await page.screenshot({ path: 'debug.png' });

Laravel特定功能

// Authentication testing
await laravelAuth.loginAs('user@example.com');
await laravelAuth.actingAs(userId);

// Database state management
await laravelDb.seed('UserSeeder');
await laravelDb.rollback();

使用Claude进行可视化调试

// Output debug information on page
await page.evaluate(() => {
  document.body.innerHTML += `
    <div style="position:fixed;top:0;right:0;background:red;color:white;padding:10px;z-index:9999">
      Debug: Current user ID = ${window.currentUserId}
    </div>
  `;
});

// Capture for Claude analysis
const screenshot = await page.screenshot();
// Screenshot is automatically sent to Claude for analysis

配置

环境变量

# Browser settings
BROWSER_POOL_SIZE=5
BROWSER_TIMEOUT=30000
HEADLESS=true

# Laravel Herd integration
HERD_DIRECTORY=~/Herd
DEFAULT_DOMAIN_SUFFIX=.test
SSL_ENABLED=true

# MCP server settings
MCP_TRANSPORT=stdio
MCP_PORT=3000
MCP_AUTH_ENABLED=false

浏览器池配置

{
  "browserPool": {
    "min": 0,
    "max": 10,
    "acquireTimeoutMillis": 30000,
    "createTimeoutMillis": 30000,
    "destroyTimeoutMillis": 5000,
    "idleTimeoutMillis": 300000,
    "reapIntervalMillis": 1000,
    "createRetryIntervalMillis": 200,
    "autostart": false
  }
}

备注：浏览器池配置为 min: 0 和 autostart: false 确保浏览器仅在需要时通过工具调用启动，而不是在服务器启动时启动。这可以防止MCP健康检查或状态查询启动浏览器实例，优化资源使用并防止不必要的浏览器进程。

api参考

核心工具

`navigate(url, options)`

导航到具有Laravel Herd域解析的URL。

`screenshot(options)`

捕获页面截图，针对克劳德分析进行了优化。

`interact(selector, action, value)`

执行用户交互（单击、键入、滚动）。

`execute(script)`

在浏览器上下文中执行JavaScript。

`waitFor(selector, options)`

等待具有智能超时处理的元素。

Laravel集成工具

`laravelAuth.loginAs(email)`

以特定用户身份进行身份验证。

`laravelDb.seed(seeder)`

运行数据库种子程序以获取测试数据。

`laravelRoute.visit(routeName, params)`

使用Laravel路由名称导航。

贡献

开发设置

# Install development dependencies
npm install --dev

# Run tests
npm test

# Run linting
npm run lint

# Start development server with hot reload
npm run dev

代码规范

遵循Laravel编码规范
使用TypeScript实现类型安全
实施全面的错误处理
包括可视化调试功能
维护基于屏幕截图的测试模式

测试

# Run unit tests
npm run test:unit

# Run integration tests with Laravel Herd
npm run test:integration

# Run visual regression tests
npm run test:visual

实施状态

✅ 完整且功能齐全

MCP服务器完全通过以下方式实现：

已实现核心功能

MCP协议合规性：通过正确的工具注册实现完整的JSON-RPC 2.0
浏览器池管理：5-10个浏览器实例的高效连接池
会话管理：用于并行测试的独立浏览器上下文
可视化调试：Claude分析的页面调试信息显示
电脑屏幕截图工具：自动生成用于AI反馈的屏幕截图

可用工具集

浏览器导航: navigate 使用Laravel Herd域解析
用户交互: interact 用于单击、键入、滚动和选择
JavaScript执行: execute 用于自定义浏览器脚本
元素等待: wait_for 具有智能超时处理功能
视觉捕捉: screenshot 具有多种格式选项

Laravel羊群集成

认证: laravel_auth_login, laravel_auth_acting_as 用于用户模拟
数据库管理: laravel_db_seed 用于测试数据设置
路线导航: laravel_route_visit 用于Laravel基于路线的导航
Artisan命令: laravel_artisan 用于Laravel CLI集成

测试已验证

JSON-RPC协议通信
工具注册和发现
会话创建和管理
浏览器池统计信息
错误处理和优雅关机

生产就绪功能

TypeScript类型安全贯穿始终
具有重试机制的全面错误处理
基于环境的配置
自动清理和资源管理
性能监控和调试功能

这个MCP服务器代表了人工智能驱动的自动化和现代Laravel开发环境的融合，实现了更智能、高效和可靠的测试工作流程，以适应不断变化的web开发需求。

使用说明

Laravel Herd的Puppeter MCP服务器

概述

主要特点

核心浏览器自动化

Laravel羊群集成

高性能

建筑

输运模型

安全功能

绩效目标

Laravel测试集成

框架兼容性

开发环境特征

开发方法

可视化调试策略

交互式测试方法

错误处理和恢复

用例

前端开发

后端开发

质量保证

技术规格

浏览器管理

Laravel群体优化

未来路线图

第一阶段：核心实施

第二阶段：群体优化

第三阶段：高级功能

竞争优势

安装

使用npx（推荐）

Claude桌面应用程序配置

MCP检验员测试

先决条件

开发设置

验证

Laravel羊群配置

用法

基本浏览器自动化

Laravel特定功能

使用Claude进行可视化调试

配置

环境变量

浏览器池配置

api参考

核心工具

navigate(url, options)

screenshot(options)

interact(selector, action, value)

execute(script)

waitFor(selector, options)

Laravel集成工具

laravelAuth.loginAs(email)

laravelDb.seed(seeder)

laravelRoute.visit(routeName, params)

贡献

开发设置

代码规范

测试

实施状态

已实现核心功能

可用工具集

Laravel羊群集成

测试已验证

生产就绪功能

相关 MCP

浏览器自动化MCP服务

浏览器自动化MCP服务器

网页内容抓取服务

Playwright浏览器自动化服务器

iOS模拟器交互服务器

搜索引擎集成服务器

`navigate(url, options)`

`screenshot(options)`

`interact(selector, action, value)`

`execute(script)`

`waitFor(selector, options)`

`laravelAuth.loginAs(email)`

`laravelDb.seed(seeder)`

`laravelRoute.visit(routeName, params)`