内容
**中文** | [فارسی](./README.fa.md)
# 可视化检查工具 - MCP 服务器
一个 [MCP](https://modelcontextprotocol.io)（模型上下文协议）服务器，允许 Claude Code 或任何兼容 MCP 的客户端 **可视化检查渲染的网页**，通过由 [Playwright](https://playwright.dev) 驱动的持久无头 Chromium 浏览器。
与仅凭源代码猜测 UI 状态不同，您的 AI 助手可以导航到 URL、截图、点击元素、调整视口大小，并读取浏览器控制台日志 —— 所有操作都在单个持久页面会话中进行。
## 目录
- [为什么存在](#为什么存在)
- [工具](#工具)
- [导航](#导航)
- [截图](#截图)
- [点击](#点击)
- [调整大小](#调整大小)
- [控制台日志](#控制台日志)
- [安装](#安装)
- [先决条件](#先决条件)
- [克隆并安装依赖](#克隆并安装依赖)
- [使用](#使用)
- [直接运行](#直接运行)
- [与 Claude Code 注册](#与-Claude-Code-注册)
- [与 Claude Desktop 注册](#与-Claude-Desktop-注册)（或任何兼容 MCP 的客户端）
- [示例工作流程](#示例工作流程)
- [运行烟雾测试](#运行烟雾测试)
- [安全注意事项](#安全注意事项)
- [许可证](#许可证)
## 为什么存在
大多数 AI 编程助手仅读取您的源文件。`visual-inspector-mcp` 为您的助手提供了一个真正的浏览器窗口，以便它可以：
- **看到** 页面实际的样子（不仅仅是 HTML 所说的）
- **交互** UI - 打开菜单、导航选项卡、触发模态窗口 - 然后截图
- **可视化调试**，通过将损坏的布局与同一会话中的控制台错误关联起来
- **检查响应式断点**，通过动态调整视口大小
所有操作都通过单个、轻量级的 MCP 服务器 - 无需 Docker，无需其他服务。
## 工具
| 工具 | 描述 | 副作用？ |
| --- | --- | --- |
| `navigate` | 在持久的无头页面中加载 URL | 打开网络连接 |
| `screenshot` | 捕获视口、整个页面或 CSS 选择器 | 只读 |
| `click` | 通过 CSS 选择器或 Playwright 定位器点击元素 | 修改页面状态 |
| `resize` | 调整浏览器视口大小 | 修改页面状态 |
| `console_logs` | 返回最近的浏览器控制台消息和页面错误 | 只读 |
每个工具都带有 `readOnlyHint`、`destructiveHint` 和 `openWorldHint` 元数据，以便 MCP 客户端可以显示适当的确认提示。
### 导航
在持久的浏览器页面中加载 URL。页面保持打开状态，以便后续的 `click`、`screenshot` 或 `console_logs` 调用。
| 参数 | 类型 | 必需 | 备注 |
| --- | --- | --- | --- |
| `url` | 字符串 | 是 | 要加载的 URL（支持 `http://`、`https://`、`file://` 和 `data:` URI） |
| `waitForSelector` | 字符串 | 否 | 在返回之前等待此 CSS/Playwright 选择器 - 适用于 SPA |
返回解析的 URL 和页面标题在一行：`https://example.com — "Example Domain"`。
### 截图
截图当前页面并以 base64 编码的图像块返回。
| 参数 | 类型 | 必需 | 备注 |
| --- | --- | --- | --- |
| `selector` | 字符串 | 否 | 仅捕获此元素（最便宜）；CSS 选择器或 Playwright 定位器 |
| `fullPage` | 布尔值 | 否 | 捕获整个可滚动页面（最昂贵）；默认为视口 |
| `format` | `"png"` \| `"jpeg"` | 否 | `png`（默认，无损）或 `jpeg`（较小；适合布局检查） |
| `quality` | 数字 1-100 | 否 | JPEG 质量（默认 80）；忽略 PNG |
需要先调用 `navigate`。
### 点击
点击元素以达到 UI 状态（打开菜单、模态窗口或选项卡），然后截图。
| 参数 | 类型 | 必需 | 备注 |
| --- | --- | --- | --- |
| `selector` | 字符串 | 是 | 要点击的元素的 CSS 选择器或 Playwright 定位器 |
### 调整大小
调整浏览器视口大小以检查响应式断点。
| 参数 | 类型 | 必需 | 备注 |
| --- | --- | --- | --- |
| `width` | 数字 | 是 | 像素中的视口宽度 |
| `height` | 数字 | 是 | 像素中的视口高度 |
### 控制台日志
返回最近的浏览器控制台消息和页面错误 - 有助于将视觉故障与 JavaScript 错误关联起来。
| 参数 | 类型 | 必需 | 备注 |
| --- | --- | --- | --- |
| `limit` | 数字 | 否 | 要返回的最大条目，最近的优先（默认为 30） |
| `level` | `"all"` \| `"error"` | 否 | `"all"`（默认）或仅错误/警告 |
| `clear` | 布尔值 | 否 | 读取后清除日志缓冲区 |
| `withTimestamps` | 布尔值 | 否 | 在每个条目前添加 ISO 时间戳（默认为 false） |
## 安装
### 先决条件
- [Node.js](https://nodejs.org/) 18+（用于原生 `fetch` 和 ESM 支持）
- 终端/ shell
### 克隆并安装依赖
```bash
git clone https://github.com/MatinMHF/visual-inspector-mcp.git
cd visual-inspector-mcp
npm install # also runs `playwright install chromium` via postinstall
```
如果 Chromium 未自动安装，请运行：
```bash
npx playwright install chromium
```
## 使用
### 直接运行
```bash
node index.js
```
服务器通过 **stdio** 通信，因此它旨在由 MCP 客户端启动，而不是单独交互运行。
### 与 Claude Code 注册
```bash
claude mcp add visual-inspector -s user -- node /path/to/visual-inspector-mcp/index.js
```
在 Windows PowerShell 上，引用 `--` 分隔符以防止 PowerShell 静默删除它：
```powershell
claude mcp add visual-inspector -s user "--" node "C:/path/to/visual-inspector-mcp/index.js"
```
### 与 Claude Desktop（或任何 MCP 兼容客户端）注册
在客户端的 MCP 服务器配置文件中添加一个条目（例如 `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"visual-inspector": {
"command": "node",
"args": ["C:/path/to/visual-inspector-mcp/index.js"]
}
}
}
```
### 示例工作流程
一旦服务器在您的 MCP 客户端中注册，典型的会话：
1. **"导航到我的开发服务器"** → 调用 `navigate` 并传入 `http://localhost:3000`
2. **"截图"** → 调用 `screenshot` 以查看当前渲染的 UI
3. **"点击汉堡菜单"** → 调用 `click` 并传入选择器，然后再次调用 `screenshot`
4. **"在移动宽度下检查"** → 调用 `resize` 并传入 `{ width: 375, height: 667 }`，然后调用 `screenshot`
5. **"有 JS 错误吗？"** → 调用 `console_logs` 并传入 `{ level: "error" }`
## 运行烟雾测试
一个自包含的端到端烟雾测试启动服务器作为子进程，通过 stdio 进行 MCP 通信，并测试所有五个工具：
```bash
npm test
```
测试写入 `test-full.png` 和 `test-element.png` 到工作目录，以证明截图功能正常。测试后可以删除这两个文件。
## 安全注意事项
- 服务器启动一个 **无头** Chromium 实例；它可以通过 `file://` URL 访问您的本地网络和文件系统。
- 仅与您信任的 MCP 客户端和会话注册。
- `click` 标记为 `destructiveHint: true` - 行为良好的客户端应在生产页面上调用前确认。
- 由于所有工具都有 `openWorldHint: true`（真正的网络调用），请避免在不了解风险的情况下指向敏感的内部服务。
## 许可证
MIT - 请参阅 [LICENSE](./LICENSE) 获取详细信息。
