使用说明

MCP调试器-专业剧作家浏览器自动化服务器

Railway-ready HTTP API，用于全面的浏览器自动化和测试

带有SMCHS创新中心生产级功能的PlayMCP增强版

🚀 最新动态

这是一个 专业等级提升 PlayMCP，专门为以下目的重建：

✅ HTTP API 代替stdio MCP协议
✅ 铁路部署 使用优化的Dockerfile
✅ 实时监控 -控制台日志和网络请求
✅ 网络模拟 -拦截和模拟API响应
✅ Cookie和存储管理 -完全浏览器状态控制
✅ 生产稳定性 -TypeScript、错误处理、健康检查

📊 增强功能

第一阶段：控制台和网络监控✅

问题已解决： 原始PlayMCP在自动化过程中无法监视控制台日志或网络请求。

实时控制台捕获 -所有浏览器控制台消息（日志、警告、错误、信息）
网络请求跟踪 -完整的HTTP请求/响应详细信息
请求/响应检查 -标题、状态代码、正文内容
清除历史记录端点 -测试之间重置

第二阶段：网络拦截与模拟✅

问题已解决： 无法测试前端测试的错误状态或模拟API。

请求拦截 -中止、继续或模拟任何网络请求
API响应嘲讽 -用测试数据替换API响应
资源阻塞 -阻止图像/CSS/字体以加快测试速度
基于模式的路由 -正则表达式或字符串匹配

第三阶段：Cookie和存储管理✅

问题已解决： 无法管理浏览器状态以进行身份验证测试。

Cookie CRUD -获取、设置、清除浏览器Cookie
本地存储管理 -读/写浏览器存储
会话持续 -在各个导航中保持状态

第四阶段：HTTP服务器支持✅

问题已解决： 截图方法只保存到文件中，不能直接返回数据。

截图作为缓冲区 -HTTP的Base64响应
图元可见性 -检查元素是否可见
填表 -输入
灵活的等待 -基于时间或选择器
直接页面访问 -通过Playwright API进行高级操作

📡 HTTP API参考

基础配置

Base URL: https://your-app.up.railway.app
Health Check: GET /health
Main Endpoint: POST /mcp
Content-Type: application/json

快速示例

健康检查：

curl https://your-app.up.railway.app/health

导航和屏幕截图：

curl -X POST https://your-app.up.railway.app/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "method": "screenshot",
    "params": {
      "url": "https://example.com",
      "fullPage": true
    }
  }'

多步测试：

curl -X POST https://your-app.up.railway.app/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "method": "multi_step_test",
    "params": {
      "url": "https://myapp.com/login",
      "steps": [
        {"action": "type", "selector": "#email", "text": "user@example.com"},
        {"action": "type", "selector": "#password", "text": "pass123"},
        {"action": "click", "selector": "#login-btn"},
        {"action": "wait", "duration": 2000},
        {"action": "is_visible", "selector": "#dashboard"}
      ]
    }
  }'

完整的API方法

Navigation & Content (6 methods)

// Navigate
{"method": "navigate", "params": {"url": "https://example.com"}}

// Get page content
{"method": "get_content", "params": {
  "url": "https://example.com",
  "includeHtml": true,
  "includeText": true
}}

// Screenshot
{"method": "screenshot", "params": {
  "url": "https://example.com",
  "fullPage": true,
  "type": "png"
}}

// Evaluate JavaScript
{"method": "evaluate", "params": {
  "url": "https://example.com",
  "script": "document.title"
}}

// Wait for selector
{"method": "wait_for_selector", "params": {
  "url": "https://example.com",
  "selector": "#my-element",
  "timeout": 30000
}}

// Multi-step test
{"method": "multi_step_test", "params": {
  "url": "https://example.com",
  "steps": [
    {"action": "wait", "duration": 1000},
    {"action": "click", "selector": "#button"},
    {"action": "type", "selector": "#input", "text": "Hello"},
    {"action": "is_visible", "selector": "#result"},
    {"action": "dom_state"},
    {"action": "evaluate", "script": "document.title"}
  ]
}}

Console & Network Monitoring (4 methods)

// Get console messages
{"method": "get_console_messages", "params": {}}

// Get network requests
{"method": "get_network_requests", "params": {}}

// Clear console messages
{"method": "clear_console_messages", "params": {}}

// Clear network requests
{"method": "clear_network_requests", "params": {}}

Network Interception (3 methods)

// Intercept requests
{"method": "intercept_request", "params": {
  "urlPattern": "**/api/users",
  "action": "mock",
  "mockResponse": {
    "status": 200,
    "contentType": "application/json",
    "body": {"users": []}
  }
}}

// Mock API response
{"method": "mock_api_response", "params": {
  "url": "https://api.example.com/data",
  "mockData": {"result": "success"},
  "status": 200
}}

// Block resources
{"method": "block_resources", "params": {
  "resourceTypes": ["image", "stylesheet", "font"]
}}

Cookie Management (3 methods)

// Get cookies
{"method": "get_cookies", "params": {"name": "session_id"}}

// Set cookie
{"method": "set_cookie", "params": {
  "cookie": {
    "name": "session_id",
    "value": "abc123",
    "domain": "example.com",
    "path": "/",
    "expires": 1234567890
  }
}}

// Clear cookies
{"method": "clear_cookies", "params": {}}

Storage Management (3 methods)

// Get localStorage
{"method": "get_local_storage", "params": {"key": "user_data"}}

// Set localStorage
{"method": "set_local_storage", "params": {
  "key": "user_data",
  "value": "{\"name\": \"John\"}"
}}

// Clear localStorage
{"method": "clear_local_storage", "params": {}}

Gemini Vision Analysis (2 methods) ⭐ NEW!

// Analyze screenshot (navigate + screenshot + analyze)
{"method": "analyze_screenshot", "params": {
  "url": "https://example.com",       // Required: URL to screenshot
  "prompt": "What UI elements are visible?",  // Optional: analysis prompt
  "apiKey": "your-gemini-api-key",    // Required: or set GEMINI_API_KEY env var
  "fullPage": true,                   // Optional: full page screenshot
  "screenshotType": "png"             // Optional: png|jpeg
}}
// Returns: {
//   "success": true,
//   "analysis": "The page shows...",
//   "screenshot": "base64...",
//   "url": "https://example.com",
//   "title": "Page Title"
// }

// Analyze existing image
{"method": "analyze_image", "params": {
  "imageBase64": "iVBORw0KGgoAAAA...",  // Required: base64 image
  "prompt": "Describe this image",     // Optional: analysis prompt
  "apiKey": "your-gemini-api-key"      // Required: or set GEMINI_API_KEY env var
}}
// Returns: {
//   "success": true,
//   "analysis": "The image shows..."
// }

双子座视觉特征：

💰 便宜40倍 与GPT-4 Vision相比（约0.00025美元/张，0.01美元/张）
🎯 双子座2.5闪光灯 -最新快速、经济高效的视觉模型
📊 详细的分析 -UI元素、文本、布局、功能
🔧 自定义提示 -询问有关屏幕截图的具体问题
🖼️ 灵活的输入 -分析新的屏幕截图或现有图像

总计：21个HTTP端点 （19个自动化+2个AI视觉）

🏗️ 建筑

核心组件

playmcp/
├── src/
│   ├── controllers/
│   │   └── playwright.ts         # Enhanced PlaywrightController
│   │       ├── Phase 1: Console & Network Monitoring
│   │       ├── Phase 2: Network Interception
│   │       ├── Phase 3: Cookie & Storage
│   │       ├── Phase 4: HTTP Support Methods
│   │       └── Phase 5: Gemini Vision Analysis ⭐
│   └── types/
│       └── index.ts              # TypeScript definitions
├── http-server.ts                # Express HTTP server
├── Dockerfile                    # Railway-optimized
├── railway.toml                  # Deployment config
├── package.json
└── tsconfig.json

设计模式

Singleton控制器 -每个容器一个浏览器实例
延迟初始化 -浏览器在第一次请求时启动
事件驱动监控 -实时控制台/网络捕获
安全型API -完整的TypeScript实现

🔧 地方发展

先决条件

Node.js 16+
npm或纱线

设置

git clone https://github.com/maizoro87/MCP-Debugger.git
cd MCP-Debugger
npm install
npm run build
npm start

服务器在上运行 PORT （默认值：3000）

测试

# Health check
curl http://localhost:3000/health

# Screenshot test
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"method":"screenshot","params":{"url":"https://example.com"}}'

🚂 铁路部署

快速部署

分叉此回购 转到您的GitHub帐户

创建铁路项目：

railway login
railway init
railway link

部署：
```
git push railway main
```
获取URL: 铁路将分配： https://[your-app].up.railway.app

配置

railway.toml （已包含）：

[build]
builder = "DOCKERFILE"

[deploy]
healthcheckPath = "/health"
healthcheckTimeout = 300
restartPolicyType = "ON_FAILURE"
restartPolicyMaxRetries = 3

Dockerfile （已优化）：

基地： mcr.microsoft.com/playwright:v1.55.0-jammy
铬预安装
构建时间：2-3分钟
内存：约200-500MB

环境变量

NODE_ENV=production
PORT=3000  # Railway sets automatically

🎯 用例

1.E2E测试

// Test login flow with console monitoring
POST /mcp
{
  "method": "multi_step_test",
  "params": {
    "url": "https://myapp.com/login",
    "steps": [
      {"action": "type", "selector": "#email", "text": "test@example.com"},
      {"action": "type", "selector": "#password", "text": "password123"},
      {"action": "click", "selector": "#login-button"},
      {"action": "wait", "duration": 2000},
      {"action": "is_visible", "selector": "#dashboard"}
    ]
  }
}

// Response includes:
// - consoleLogs: ["info: Login successful", ...]
// - networkRequests: [{url: "/api/login", status: 200}, ...]
// - steps: [{step: 1, success: true}, ...]

2.API前端测试模拟

// Mock API before testing
POST /mcp
{"method": "mock_api_response", "params": {
  "url": "https://api.myapp.com/users",
  "mockData": {"users": [{"id": 1, "name": "Test"}]}
}}

// Navigate and test
POST /mcp
{"method": "navigate", "params": {"url": "https://myapp.com/users"}}

// Verify mock was used
POST /mcp
{"method": "get_network_requests", "params": {}}

3.视觉回归测试

// Take baseline screenshot
POST /mcp
{"method": "screenshot", "params": {
  "url": "https://myapp.com/dashboard",
  "fullPage": true
}}

// Returns: {"screenshot": "base64-encoded-image"}

4.控制台错误监控

// Navigate and collect errors
POST /mcp
{"method": "navigate", "params": {"url": "https://myapp.com"}}

POST /mcp
{"method": "get_console_messages", "params": {}}

// Returns: {
//   "messages": [
//     {"type": "error", "text": "Uncaught TypeError: ...", "timestamp": "..."}
//   ]
// }

🔐 安全

✅ 当前实施：

API密钥验证 -使用以下方式保护MCP端点 MCP_API_KEY 环境变量
- 集 MCP_API_KEY 在铁路上启用身份验证
- 通过传递密钥 X-API-Key 标题或 Authorization: Bearer <key>
- 健康端点保持公开（用于铁路健康检查）
- 如果未设置，则API处于打开状态（日志警告）
铁路实施HTTPS

⚠️ 仍然缺失：

速率限制
输入净化
CORS配置

🛡️ 使用身份验证：

在铁路上设置环境变量：

MCP_API_KEY=your-secret-key-here

在请求中使用：

# Option 1: X-API-Key header
curl -X POST https://your-app.up.railway.app/mcp \
  -H "X-API-Key: your-secret-key-here" \
  -H "Content-Type: application/json" \
  -d '{"method":"screenshot","params":{"url":"https://example.com"}}'

# Option 2: Authorization Bearer token
curl -X POST https://your-app.up.railway.app/mcp \
  -H "Authorization: Bearer your-secret-key-here" \
  -H "Content-Type: application/json" \
  -d '{"method":"screenshot","params":{"url":"https://example.com"}}'

注：生成一个强大的API密钥（例如，使用 openssl rand -hex 32)

📈 演出

资源使用情况

空闲： ~200MB RAM
活动： ~500MB闸板
CPU： 空闲时最小，页面加载时峰值

构建时间

铁路： 2-3分钟（剧作家底图）
当地： <10秒（仅限TypeScript）

优化提示

使用 block_resources 跳过图像/字体
清除测试之间的控制台/网络日志
重用浏览器实例（自动）

🛠️ 开发指南

添加新方法

1.添加到PlaywrightController：

// src/controllers/playwright.ts
async myNewMethod(param: string): Promise<void> {
  if (!this.isInitialized() || !this.state.page) {
    throw new Error('Browser not initialized');
  }
  this.log('My new method', { param });
  // Implementation
}

2.在HTTP服务器中公开：

// http-server.ts
case 'my_new_method': {
  const controller = await initBrowser();
  await controller.myNewMethod(params.param);
  res.json({
    success: true,
    message: 'Method executed'
  });
  break;
}

3.README文件： 更新API参考部分。

测试更改

npm run build
npm start

# In another terminal
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"method":"my_new_method","params":{"param":"test"}}'

🚧 路线图

✅ 已完成（第1-5阶段）

控制台和网络监控
网络拦截和模拟
Cookie和存储管理
HTTP服务器支持方法
Gemini视觉分析 ⭐ - AI驱动的截图分析
铁路部署配置
TypeScript编译
生产建设

⏳ 下一步（第6+阶段）

设备仿真 -手机、平板电脑、台式机测试
性能指标 -加载时间、资源分析
视频录制 -捕获测试执行
多页支持 -弹出窗口、新窗口
身份验证场景 -OAuth、SSO测试
高级AI功能 -多图像分析、OCR、表单检测

🤝 贡献

这是为SMCHS创新中心项目构建的增强型MCP调试器。

原始项目： PlayMCP by@jomon003 增强方式： 创新中心团队

目标：

✅ 生产级浏览器自动化
✅ 铁路准备部署
✅ 实时监控与调试
⏳ 人工智能测试（即将推出）

📝 许可证

MIT许可证（继承自PlayMCP）

🔗 链接

github： https://github.com/maizoro87/MCP-Debugger
原始PlayMCP： https://github.com/jomon003/PlayMCP
铁路： 一键部署
剧作家文档： https://playwright.dev/
创新中心： https://sm-innovation-hub.replit.app

🎓 比较：原始与增强

功能	原始PlayMCP	MCP调试器
协议	stdio/JSON-RPC	HTTP REST API
部署	仅限本地	铁路准备就绪
控制台监控	❌	✅ 实时
网络监控	❌	✅ 详细信息
API模拟	❌	✅ 拦截和模拟
Cookie管理	❌	✅ 获取、设置、清除
截图	仅限文件	✅ Base64响应
建造时间	慢速	2-3分钟（优化）
生产就绪	否	✅ 是的
健康检查	❌	✅ /健康终点
TypeScript	✅	✅ 增强型

内置于❤️ 用于全面的浏览器测试