Playwright MCP Injector

一个基于 Playwright 的 MCP (Model Context Protocol) 服务器，能够在每次打开或导航到页面时自动注入指定的 JavaScript 代码。

功能特性

• 🚀 自动页面导航和脚本注入
• 🐛 内置调试模式支持
• 📸 页面截图功能
• 🔧 自定义脚本注入
• 📝 Console输出监听和获取 🆕
• 🎯 全面的页面操作功能（点击、输入、选择等）
• 🛡️ 完整的错误处理和资源清理
• 📦 符合 npm 包发布规范

安装

方式一：直接通过 npx 使用（推荐）

无需安装，直接使用：

npx playwright-mcp-injector

方式二：全局安装

npm install -g playwright-mcp-injector

安装后可以直接运行：

playwright-mcp-injector

方式三：作为项目依赖

npm install playwright-mcp-injector

方式四：从源码构建

git clone <repository-url>
cd playwright-mcp-injector
npm install
npm run build

使用方法

方式一：直接通过 npx 运行（推荐）

# 启动 MCP 服务器
npx playwright-mcp-injector

# 启用调试模式
DEBUG=true npx playwright-mcp-injector

方式二：全局安装后运行

# 启动 MCP 服务器
playwright-mcp-injector

# 启用调试模式
DEBUG=true playwright-mcp-injector

方式三：作为项目依赖使用

import { spawn } from 'child_process';

// 启动 MCP 服务器
const mcpServer = spawn('npx', ['playwright-mcp-injector'], {
  stdio: ['inherit', 'inherit', 'inherit'],
  env: { ...process.env, DEBUG: 'true' }
});

方式四：本地构建后运行

npm run build
npm start

可用工具

1. browser_navigate

导航到指定 URL 并自动注入默认脚本

{
  "name": "browser_navigate",
  "arguments": {
    "url": "https://example.com",
    "debug": true
  }
}

2. browser_inject

在当前页面注入自定义脚本

{
  "name": "browser_inject",
  "arguments": {
    "script": "console.log('自定义脚本');",
    "debug": true
  }
}

3. browser_screenshot

截取当前页面的截图

{
  "name": "browser_screenshot",
  "arguments": {
    "debug": true
  }
}

4. browser_action

在当前页面执行各种操作（点击、输入、选择等）

{
  "name": "browser_action",
  "arguments": {
    "selector": "button.submit",
    "html": "<button onclick=\"submit()\">提交</button>",
    "description": "点击提交按钮",
    "action": "click",
    "value": "",
    "options": {
      "timeout": 10000,
      "force": false,
      "waitForSelector": true
    },
    "debug": true
  }
}

支持的操作类型：

• click - 点击元素
• input - 输入文本
• select - 选择选项
• hover - 悬停元素
• scroll - 滚动到元素
• wait - 等待元素出现
• custom - 自定义JavaScript操作
• get_html - 获取元素的HTML内容 🆕

参数说明：

• selector - CSS选择器定位元素
• html - HTML内容用于辅助匹配元素（可选）
• description - 操作描述
• action - 操作类型，默认为"click"
• value - 操作值（用于input、select等操作）
• options - 操作选项
  • timeout - 超时时间（毫秒），默认10000
  • force - 是否强制操作，默认false
  • waitForSelector - 是否等待选择器找到元素，默认true

get_html 操作返回格式：

{
  "success": true,
  "message": "HTML获取成功",
  "selector": ".container",
  "tagName": "DIV",
  "innerHTML": "<h2>主要容器</h2><p>...</p>",
  "outerHTML": "<div class=\"container\" id=\"main-container\"><h2>...</h2></div>",
  "textContent": "主要容器 这是一个描述段落，包含一些重要的文本内容。",
  "className": "container",
  "id": "main-container",
  "attributes": [
    {
      "name": "class",
      "value": "container"
    },
    {
      "name": "id", 
      "value": "main-container"
    }
  ]
}

5. browser_console

获取页面的所有console输出

{
  "name": "browser_console",
  "arguments": {
    "clear": false,
    "debug": true
  }
}

参数说明：

• clear - 获取后是否清空console消息记录，默认false

返回格式：

{
  "messageCount": 10,
  "messages": [
    {
      "type": "log",
      "text": "这是一条日志消息",
      "location": "http://example.com:15:10",
      "timestamp": "2025-11-21T08:58:59.103Z"
    },
    {
      "type": "error",
      "text": "这是一条错误消息",
      "location": "http://example.com:20:5",
      "timestamp": "2025-11-21T08:58:59.105Z"
    }
  ],
  "cleared": false
}

支持的Console类型：

• log - 普通日志
• info - 信息消息
• warn - 警告消息
• error - 错误消息
• debug - 调试消息

6. browser_scan_elements 🆕

扫描页面中的所有交互元素（输入框、按钮、可点击元素等）

{
  "name": "browser_scan_elements",
  "arguments": {
    "elementType": "all",
    "includeHidden": false,
    "filterText": "",
    "includePosition": true,
    "debug": true
  }
}

参数说明：

• elementType - 要扫描的元素类型：
  • "all" - 所有交互元素（默认）
  • "inputs" - 仅输入框（input、textarea、select）
  • "buttons" - 仅按钮（button、input[type=button/submit/reset]等）
  • "clickables" - 仅可点击元素（带onclick、data-action等）
  • "dynamic" - 仅动态元素（使用现代框架生成的元素）
• includeHidden - 是否包含隐藏元素，默认false
• filterText - 按文本内容过滤元素（可选）
• includePosition - 是否包含元素位置信息，默认true

返回格式：

{
  "timestamp": "2025-12-02T01:45:00.000Z",
  "url": "https://example.com",
  "title": "页面标题",
  "scanOptions": {
    "elementType": "all",
    "includeHidden": false,
    "filterText": "",
    "includePosition": true
  },
  "elements": [
    {
      "index": 0,
      "elementType": "input",
      "tag": "input",
      "type": "text",
      "id": "username",
      "name": "username",
      "className": "form-input",
      "placeholder": "请输入用户名",
      "value": "",
      "required": true,
      "disabled": false,
      "readonly": false,
      "maxLength": 50,
      "selector": "#username",
      "visible": true,
      "title": "",
      "ariaLabel": "用户名输入框",
      "ariaPlaceholder": "",
      "checked": false,
      "selected": false,
      "position": {
        "x": 100,
        "y": 200,
        "width": 300,
        "height": 40
      }
    },
    {
      "index": 1,
      "elementType": "button",
      "tag": "button",
      "type": "submit",
      "id": "submit-btn",
      "name": "",
      "className": "btn btn-primary",
      "textContent": "提交",
      "href": "",
      "target": "",
      "selector": "#submit-btn",
      "visible": true,
      "disabled": false,
      "formAction": "",
      "formMethod": "",
      "onclick": "",
      "hasClickListener": false,
      "title": "",
      "ariaLabel": "提交表单",
      "role": "",
      "tabIndex": 0,
      "position": {
        "x": 100,
        "y": 250,
        "width": 100,
        "height": 40
      }
    }
  ],
  "summary": {
    "totalElements": 2,
    "elementType": "all",
    "filterApplied": false,
    "includeHidden": false
  }
}

使用示例：

# 扫描所有输入框
browser_scan_elements {"elementType": "inputs"}

# 扫描所有按钮
browser_scan_elements {"elementType": "buttons"}

# 扫描包含"提交"文本的所有元素
browser_scan_elements {"filterText": "提交"}

# 扫描包含隐藏元素的所有元素
browser_scan_elements {"includeHidden": true}

7. browser_close

关闭浏览器

{
  "name": "browser_close",
  "arguments": {
    "debug": true
  }
}

脚本注入

注意：此版本已移除默认脚本注入功能。现在系统不会自动注入任何脚本。

如果需要注入脚本，请使用 browser_inject 工具手动注入：

// 手动注入示例
browser_inject({
  script: "console.log('hello world');",
  debug: true
});

这样的设计提供了更大的灵活性，让用户完全控制何时注入何种脚本。

调试模式

要启用调试模式，可以：

1. 设置环境变量：DEBUG=true
2. 在工具调用时传递 "debug": true 参数

调试模式会输出详细的操作日志，包括：

• 浏览器初始化过程
• 页面导航状态
• 脚本注入详情
• 错误信息和堆栈跟踪

开发

项目结构

playwright-mcp-injector/
├── src/
│   └── index.ts          # 主服务器文件
├── dist/                 # 编译输出目录
├── package.json          # npm 包配置
├── tsconfig.json         # TypeScript 配置
└── README.md             # 项目文档

开发命令

# 安装依赖
npm install

# 开发模式（监听文件变化）
npm run dev

# 构建项目
npm run build

# 启动服务器
npm start

# 运行测试
npm test

# 代码检查
npm run lint

作为 MCP 客户端配置

将此服务器添加到您的 MCP 客户端配置中：

方式一：使用 npx（推荐）

{
  "mcpServers": {
    "playwright-injector": {
      "command": "npx",
      "args": ["playwright-mcp-injector"],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

方式二：使用全局安装的命令

{
  "mcpServers": {
    "playwright-injector": {
      "command": "playwright-mcp-injector",
      "args": [],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

方式三：使用本地 node_modules

{
  "mcpServers": {
    "playwright-injector": {
      "command": "node",
      "args": ["node_modules/playwright-mcp-injector/dist/index.js"],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

API 参考

调试日志函数

debugLog(message: string, data?: any, debug: boolean): void

• message: 日志消息
• data: 可选的额外数据对象
• debug: 是否强制输出调试信息

脚本注入函数

injectScript(page: Page, script: string, debug: boolean): Promise<void>

• page: Playwright 页面实例
• script: 要注入的 JavaScript 代码
• debug: 调试模式标志

环境要求

• Node.js >= 16.0.0
• Chromium 浏览器（由 Playwright 自动安装）

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！

更新日志

v1.5.0 🆕

• 🎯 新增 browser_scan_elements 工具 - 专业的页面元素扫描功能
• 📊 支持扫描所有交互元素：输入框、按钮、可点击元素、动态元素
• 🔍 高级过滤选项：按类型、文本内容、可见性筛选
• 📍 完整的元素位置信息（坐标、尺寸）
• 🎲 智能元素选择器生成
• ♿ 可访问性属性支持（aria-label、role等）
• 📱 现代框架元素识别（React、Vue、Angular等）
• ⚡ 高性能批量扫描和详细报告生成

v1.3.0

• 🆕 新增 get_html 操作类型到 browser_action 工具
• 📄 获取元素完整的HTML信息：innerHTML、outerHTML、textContent
• 🏷️ 返回详细元素属性：tagName、className、id、attributes
• 🎯 支持CSS选择器和HTML内容匹配定位
• 🔧 完整的错误处理和调试输出

v1.2.0

• 🆕 新增 browser_console 工具，获取页面所有console输出
• 📝 自动监听所有console事件：log、info、warn、error、debug
• 📍 记录详细的消息信息：类型、内容、位置、时间戳
• 🗑️ 支持获取后清空消息记录功能
• 🔧 完整的console输出调试和监控

v1.1.0

• 🆕 新增 browser_action 工具，支持全面的页面操作
• ✅ 支持多种操作类型：click、input、select、hover、scroll、wait、custom
• 🎯 智能元素定位：CSS选择器 + HTML内容匹配
• ⚙️ 丰富的操作选项：timeout、force、waitForSelector
• 🔧 完整的调试输出和错误处理
• 🛠️ 修复了页面加载时序问题，确保操作在页面完全加载后执行

v1.0.0

• 初始版本发布
• 支持 Playwright 页面自动化
• 自动脚本注入功能
• 完整的调试支持
• 符合 npm 包发布规范