Vite MCP Server

Blowback

Vite MCP Server 现已更名为 Blowback

Blowback 致力于支持各种前端开发服务，而不仅仅是 Vite

一个模型上下文协议（MCP）服务，可将前端开发服务与 Claude Desktop 和 Cursor 等 AI 工具集成。

使用方法

命令（Claude Code）：

claude mcp add blowback -s project -e PROJECT_ROOT=/path/to/your/project -- npx -y blowback-context

或使用 JSON 配置：

• Claude Code：{PROJECT_ROOT}/.mcp.json
• Cursor：{PROJECT_ROOT}/.cursor/mcp.json

{
  "mcpServers": {
    "blowback": {
      "command": "npx",
      "args": ["-y", "blowback-context"],
      "env": {
        "PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

环境变量

• PROJECT_ROOT：项目根目录路径（可选，默认为当前工作目录）
• ENABLE_BASE64：在工具响应中包含 Base64 编码的图像（默认值：false / 启用后会影响令牌用量和上下文窗口）

主要功能

• 将本地开发服务与 MCP 服务集成
• 通过 MCP 捕获并传输浏览器控制台日志
• 基于检查点的日志管理
• 截图捕获和 SQLite 数据库管理
• HMR（热模块替换）事件监控
• 浏览器自动化和元素检查

init 提示词

init 提示词可指导 AI 助手有效使用以下功能：

Cursor Chat 不支持 MCP 提示词功能，因此无法使用此功能。（建议使用 Claude Code） 如有需要，请手动输入以下提示词：

你可以通过在 head 中插入 <meta name="__mcp_checkpoint" data-id=""> 来创建当前状态的命名快照，从而使用检查点功能。 data-id 属性是检查点的唯一标识符。

在检查点处于活动状态时，浏览器中生成的控制台日志会附带检查点 ID，并且可以单独查询。

注意：在某些开发环境中，保存文件时会触发热重载，因此请仔细考虑 meta 标签变更与希望观察的变更之间的顺序。请务必在进行希望跟踪的变更前设置检查点 meta 标签。

你可以使用 capture-screenshot 工具截图。捕获的截图存储在 @.mcp_screenshot/ 目录中。

工具

HMR 工具

工具名称	描述
get-hmr-events	获取最近的 HMR 事件
check-hmr-status	检查 HMR 状态

注意：HMR 连接是可选的，并非必需。启动浏览器后会自动开始监控 HMR 事件。

浏览器工具

工具名称	描述
start-browser	启动浏览器实例并导航至开发服务器。HMR 监控会自动开始
capture-screenshot	捕获当前页面或特定元素的截图。返回截图 ID 和资源 URI
get-element-properties	获取特定元素的属性和状态信息
get-element-styles	获取特定元素的样式信息
get-element-dimensions	获取特定元素的尺寸和位置信息
monitor-network	在指定时长内监控浏览器中的网络请求
get-element-html	获取特定元素及其子元素的 HTML 内容
get-console-logs	获取浏览器会话的控制台日志，并支持可选筛选
execute-browser-commands	安全地执行预定义的浏览器命令

帮助工具

工具名称	描述
how-to-use	提供有关如何使用服务特定功能的说明

资源

截图

用于查询所有已捕获截图的资源。你可以使用不同条件查询 capture-screenshot 工具捕获的截图引用 ID。

与引用 ID 对应的图像存储在 {PROJECT_ROOT}/.mcp_screenshot/ 目录中。

• URI：screenshot://
• 返回所有截图的列表

按 URL 查询截图

一项用于根据 URL 路径查询特定截图的资源。

注意：从 1.0 版本开始，默认禁用通过资源返回的 Blob 响应，改为返回文件引用信息

• URI 模板：screenshot://{+path}
• 示例：screenshot://localhost:5173/about
• 使用不带协议（http://、https://）的 URL 路径

数据存储结构

截图存储

• 截图图片：存储在 {PROJECT_ROOT}/.mcp_screenshot/ 目录中
• 元数据：在临时目录中的 SQLite 数据库内管理
• 建议将 .mcp_screenshot/ 目录添加到 .gitignore

日志管理系统

• 捕获浏览器控制台日志并保存到文件中，以供查询
• 仅在检查点处于活动状态时保存检查点日志

检查点系统

检查点的工作方式

• 检查点用于管理特定版本的快照、日志、截图等
• 将 <meta name="__mcp_checkpoint" data-id=""> 插入 head 后，会使用 data-id 属性作为标识符，分别记录数据

架构和数据流

核心组件

1. MCP 服务：使用 Model Context Protocol SDK 向 AI 工具提供工具和资源的中央模块。

2. 浏览器自动化：使用 Playwright 控制 Chrome，以进行视觉检查、截图捕获和 DOM 操作。

3. 检查点系统：维护浏览器状态快照，以便进行比较和测试。

4. SQLite 数据库：高效管理截图元数据，并支持快速按 URL 查询。

数据源和状态管理

服务维护多个重要的数据存储：

• HMR 事件记录：跟踪开发服务的近期 HMR 事件（更新、错误）。
• 控制台消息日志：捕获浏览器控制台输出，以便调试。
• 检查点存储：存储具名的浏览器状态快照，包括 DOM 快照。
• 截图存储：将图片保存在项目目录中，并使用 SQLite 管理元数据。

通信流程

1. MCP 客户端 → 开发服务：

   • MCP 客户端更改源代码，开发服务检测到更改
   • 开发服务自动更新浏览器或发出 HMR 事件

2. Web 浏览器 → MCP 服务：

   • 通过 Playwright 捕获 HMR 事件和控制台日志
   • MCP 服务查询浏览器当前状态或捕获截图

3. MCP 服务 → MCP 客户端：

   • 服务将 HMR 事件转换为结构化响应
   • 提供工具，供 MCP 客户端查询 HMR 状态、捕获截图等

状态维护

服务维护以下对象的引用：

• 当前浏览器和页面实例
• 近期 HMR 事件