vite-plugin-copilot-dev-mcp

专为 Vite 驱动的前端项目设计的 AI 研发辅助探针与 MCP (Model Context Protocol) 智能网关。

通过将本插件接入 Vite 开发环境，它能在浏览器运行时中作为静默探针，实时捕获 Vue/React 组件崩溃、白屏报错、未捕获 Promise 异常及网络失败；并利用 Vite 内部 SourceMap 将混淆后的堆栈精准还原为本地真实源码位置与代码切片。

配合标准 MCP 协议网关，让你的 AI IDE（Cursor, Claude Desktop, Cline, Antigravity） 拥有洞察前端运行现场的“上帝视角”，实现免复制粘贴的一键智能诊断与反向控制！

🌟 核心特性

• 🚀 极简接入：仅需在 vite.config.ts 中注册插件，无侵入、零业务代码污染。
• 🔍 运行时全场景捕获：拦截 console.error、window.onerror、unhandledrejection 以及 fetch/XHR 异常（基于 Response.clone 流克隆，零副作用）。
• 🎯 源码级精准定位：结合 Vite ModuleGraph 与 source-map / @babel/code-frame，将转译后的报错行列自动还原至原始 TSX / Vue 源码，并截取上下文代码块。
• 🤖 原生 MCP 双模支持：支持 HTTP SSE 与 Stdio 接入，完美适配 Cursor、Claude Desktop 等主流 AI 工具。
• ⚡ 智能自适应与零断连：
  • 端口自适应：自动感知项目端口（5173、5174、3000 等），IDE 免配端口。
  • 待机兜底：前端项目未启动时，MCP 代理在本地待机响应，IDE 永远保持绿灯在线，绝不报红断连；项目启动后秒级自动热连接。
• 🛠️ 反向控制能力：AI 可直接通过 MCP Tools 触发 Vite 服务重启、清空预构建缓存、强制热重载指定模块。

📦 安装

npm i -D vite-plugin-copilot-dev-mcp
# 或使用 pnpm
pnpm i -D vite-plugin-copilot-dev-mcp
# 或使用 yarn
yarn add -D vite-plugin-copilot-dev-mcp

🚀 快速接入

1. 在 vite.config.ts 中引入插件

import { defineConfig } from 'vite'
import copilotDev from 'vite-plugin-copilot-dev-mcp'

export default defineConfig({
  plugins: [
    copilotDev({
      // 浏览器探针监控配置（可选，默认均已开启）
      browserMonitor: {
        console: { error: true, warn: false },
        window: { onerror: true, unhandledrejection: true },
        network: { error: false, timeout: false },
      },
      // MCP 服务配置
      mcp: {
        enabled: true,
      },
    }),
  ],
})

运行 npm run dev 启动你的 Vite 开发服务器即可！

🤖 接入 AI IDE (配置 MCP)

在你的 AI 工具中将本插件添加为 MCP Server。推荐以下两种方式：

方式一：Stdio 全局智能自适应（⭐ 强烈推荐，全球通用）

在你的 MCP 配置文件（如 mcp_config.json 或 Claude Desktop 配置）中添加：

{
  "mcpServers": {
    "vite-copilot": {
      "command": "npx",
      "args": ["-y", "vite-plugin-copilot-dev-mcp"]
    }
  }
}

✨ 为什么推荐该方式？

1. 零路径硬编码：无需指定本地文件绝对路径；
2. 零端口硬编码：无论当前项目跑在 5173 还是 3000 端口，代理自动探测当前工作区端口；
3. 项目未启动不报红：Vite 没启动时自动进入待机模式，IDE 永远亮绿灯，项目启动后秒级自愈连接！

方式二：HTTP SSE 直连 (推荐 Cursor / Cline 等原生支持 HTTP 的工具)

如果你的 IDE 支持 SSE (Server-Sent Events) 连接方式：

• Type / Protocol: SSE
• Name: vite-copilot
• URL: http://127.0.0.1:5173/__vite-plugin-copilot-dev-mcp/sse

(注：如果你的 Vite 运行在其他端口，请将 5173 替换为你实际的端口号)

📚 MCP 能力清单

1. MCP Resources (只读资源)

| Resource URI | 描述 | 说明 | | :--- | :--- | :--- | | vite://status | Vite 服务连接状态 | 查看当前 Vite Dev Server 是否在线及端口信息 | | vite://errors/browser | 浏览器运行时报错列表 | 包含错误类型、堆栈、SourceMap 还原的本地源码切片 | | vite://errors/build | 编译与构建告警/错误 | Vite 内部捕获的语法错误、Rollup 警告及致命崩溃信息 | | vite://config/resolved | Vite 生效配置 | 查看当前运行时完整解析后的 Vite 配置（插件列表、Alias、Proxy 等） | | vite://transform/{filePath} | 模块转换后代码 | 查看文件经过 Vite 插件管线编译后的真实产物（支持动态按需编译） | | vite://module-graph/{filePath} | 模块依赖图谱 | 查询某个文件的上游引用者（importers）与下游依赖（importedModules） |

2. MCP Tools (操作工具)

AI 可直接调用以下工具辅助开发调试：

• restart_dev_server：安全重启 Vite Dev Server（配置变更或状态异常时使用）。
• clear_vite_cache：一键清理 node_modules/.vite 预构建依赖缓存并安全重启服务。
• invalidate_module：强制使指定模块失效并触发 HMR / Full-reload（用于强刷模块状态）。

3. MCP Prompts (场景化智能诊断)

• diagnose_browser_crash：自动打包最近的浏览器崩溃日志、源码切片与环境参数，驱动大模型给出根因分析与修复补丁。
• diagnose_build_error：自动打包构建错误与 Vite 配置，驱动大模型分析打包失败原因并给出配置修复方案。

💬 体验示例

配置成功后，你可以在 AI 对话框中直接提问：

💬 "我刚才在页面上点击了提交按钮白屏了，调用 MCP 看看浏览器报了什么错，并帮我修复源码。"

AI 会自动读取 vite://errors/browser，获取还原到原始 src/components/Form.vue:42 行的代码切片，并直接在编辑器中给出精准的代码修复补丁！

📄 开源协议 (License)

MIT License © 2026 jinjie0703