@xiaou66/vite-plugin-vue-mcp-next 0.0.2 → 0.0.5

package/README.md

@@ -11,6 +11,7 @@
 | 页面列表 | Vite entry + Runtime | Vite entry + Runtime + CDP target | 用于多页面和多 tab 场景下选择调试目标 |
 | DOM tree | Runtime Hook | CDP 优先，Hook 兜底 | 可返回裁剪后的运行时 DOM 结构 |
 | DOM selector 查询 | Runtime Hook | CDP 优先，Hook 兜底 | 可按 selector 返回节点文本、属性和布局信息 |
+| 页面截图 | snapdom DOM 截图 | CDP 真截图优先，snapdom 降级 | 返回视口、整页或指定元素的 base64 图片，并标记截图来源 |
 | Console 日志 | Runtime Hook | CDP 优先，Hook 兜底 | 采集 `log/info/warn/error/debug` 和运行时日志 |
 | Evaluate 控制台执行 | Runtime Hook | CDP 优先，Hook 兜底 | 默认关闭，必须显式开启 |
 | Network 请求 | Runtime Hook | CDP 优先，Hook 兜底 | 返回请求 URL、query、body、status、headers、response body |
@@ -35,26 +36,27 @@ export default defineConfig({
 })
 ```
 
-启动 Vite 后，默认 MCP SSE 入口为：
+启动 Vite 后，默认会暴露两个 MCP 入口：
 
 ```text
-http://localhost:<vite-port>/__mcp/sse
+SSE: http://localhost:<vite-port>/__mcp/sse
+Streamable HTTP: http://localhost:<vite-port>/__mcp/mcp
 ```
 
-启动 Vite dev server 后，插件会自动写入常见 AI 客户端的项目级 MCP 配置，服务名默认是 `vue-mcp-next`。自动配置只新增或更新本插件的 server 条目，不会删除已有 MCP Server。
+启动 Vite dev server 后，插件会自动写入常见 AI 客户端的项目级 MCP 配置，服务名默认是 `vue-mcp-next`。自动配置只会在缺少同名 server 条目时新增配置；如果用户已经配置了 `vue-mcp-next`，插件不会重复写入或覆盖原配置。
 
-| 客户端 | 自动配置文件 |
-|---|---|
-| Cursor | `.cursor/mcp.json` |
-| Codex | `.codex/config.toml` |
-| Claude Code | `.mcp.json` |
-| Trae | `.trae/mcp.json` |
+| 客户端 | 自动配置文件 | 默认端点 |
+|---|---|---|
+| Cursor | `.cursor/mcp.json` | SSE |
+| Codex | `.codex/config.toml` | Streamable HTTP |
+| Claude Code | `.mcp.json` | SSE |
+| Trae | `.trae/mcp.json` | SSE |
 
-实际端口以启动日志中的 `MCP: Server is running at ...` 为准。
+实际端口以启动日志中的 `MCP: SSE server is running at ...` 和 `MCP: Streamable HTTP server is running at ...` 为准。
 
 ### 手动配置 MCP 客户端
 
-如果你不想使用自动配置，或需要把地址复制到其他支持 HTTP MCP 的客户端，可以手动配置当前 Vite dev server 的 SSE 地址。
+如果你不想使用自动配置，或需要把地址复制到其他支持 HTTP MCP 的客户端，可以手动配置当前 Vite dev server 的 MCP 地址。
 
 Cursor、Claude Code、Trae 等 JSON 配置客户端可以使用：
 
@@ -62,6 +64,7 @@ Cursor、Claude Code、Trae 等 JSON 配置客户端可以使用：
 {
   "mcpServers": {
     "vue-mcp-next": {
+      "type": "sse",
       "url": "http://localhost:5173/__mcp/sse"
     }
   }
@@ -72,7 +75,7 @@ Codex 使用 TOML 配置：
 
 ```toml
 [mcp_servers.vue-mcp-next]
-url = "http://localhost:5173/__mcp/sse"
+url = "http://localhost:5173/__mcp/mcp"
 ```
 
 `5173` 是示例端口。若 Vite 使用了其他端口，请替换为启动日志中打印的 MCP 地址。
@@ -120,6 +123,17 @@ vueMcpNext({
   },
   console: {
     maxRecords: 1000
+  },
+  screenshot: {
+    prefer: 'auto',
+    maxBytes: 5 * 1024 * 1024,
+    snapdom: {
+      options: {
+        scale: 1,
+        useProxy: undefined
+      },
+      plugins: []
+    }
   }
 })
 ```
@@ -128,12 +142,13 @@ vueMcpNext({
 
 | 配置 | 类型 | 默认值 | 说明 |
 |---|---|---|---|
-| `mcpPath` | `string` | `'/__mcp'` | MCP 服务挂载路径，实际 SSE 地址是 `${mcpPath}/sse` |
+| `mcpPath` | `string` | `'/__mcp'` | MCP 服务挂载路径，实际 SSE 地址是 `${mcpPath}/sse`，Streamable HTTP 地址是 `${mcpPath}/mcp` |
 | `host` | `string` | `'localhost'` | 打印 MCP 地址和写入 MCP 客户端配置时使用的 host |
 | `printUrl` | `boolean` | `true` | 是否在 Vite 启动日志中打印 MCP SSE 地址 |
 | `mcpClients` | `{ cursor?: boolean; codex?: boolean; claudeCode?: boolean; trae?: boolean; serverName?: string }` | 全部启用 | 是否自动写入 Cursor、Codex、Claude Code、Trae 的项目级 MCP 配置 |
 | `updateCursorMcpJson` | `boolean | { enabled: boolean; serverName?: string }` | `true` | 兼容旧配置，建议新项目使用 `mcpClients` |
 | `appendTo` | `string | RegExp` | `undefined` | 非 HTML 入口注入点。配置后会在匹配入口模块前追加 runtime import |
+| `screenshot` | `ScreenshotOptions` | CDP 优先，snapdom 降级 | 页面截图配置，控制真截图、DOM 降级截图、体积上限和 snapdom 扩展 |
 
 `appendTo` 适合 playground、框架包装入口、或不希望通过 `transformIndexHtml` 注入的场景：
 
@@ -240,6 +255,60 @@ Hook Network 覆盖 `fetch` 和 `XMLHttpRequest`。CDP Network 更接近 Chrome
 
 DOM 默认跳过 `script`、`style`、`noscript`，并隐藏 password input 的值。这样做是为了避免 MCP 上下文被大页面或敏感字段污染。
 
+### Screenshot 配置
+
+`take_screenshot` 默认优先使用 CDP 真截图；没有 CDP 时，`prefer: 'auto'` 会降级到 `snapdom` DOM 截图。`source: 'snapdom'` 表示 DOM 渲染截图，不等同于浏览器真实像素截图。
+
+```ts
+vueMcpNext({
+  screenshot: {
+    prefer: 'auto',
+    maxBytes: 5 * 1024 * 1024,
+    snapdom: {
+      options: {
+        scale: 2,
+        useProxy: 'http://localhost:3000/proxy?url=',
+        exclude: ['[data-no-screenshot]']
+      },
+      plugins: [
+        '/src/screenshot/snapdom-watermark.ts',
+        {
+          path: '@/screenshot/snapdom-mask-sensitive',
+          exportName: 'createMaskPlugin',
+          options: {
+            selectors: ['.token', '.password']
+          }
+        }
+      ],
+      filter: '/src/screenshot/snapdom-filter.ts',
+      fallbackURL: '/src/screenshot/snapdom-fallback-url.ts'
+    }
+  }
+})
+```
+
+`screenshot.snapdom.options` 继承 `snapdom` 的可序列化 options，常用字段包括 `scale`、`quality`、`cache`、`embedFonts`、`localFonts`、`useProxy`、`exclude`。`useProxy` 适合处理跨域图片或字体资源。
+
+`plugins`、`filter`、`fallbackURL` 必须使用 Vite import 路径。不要在 `vite.config.ts` 中直接传函数，因为配置运行在 Node 侧，而截图执行发生在浏览器 runtime。
+
+```ts
+// /src/screenshot/snapdom-mask-sensitive.ts
+export function createMaskPlugin(options: { selectors: string[] }) {
+  return {
+    name: 'mask-sensitive',
+    afterClone(context: { clone: Document }) {
+      for (const selector of options.selectors) {
+        context.clone.querySelectorAll(selector).forEach((node) => {
+          node.textContent = '******'
+        })
+      }
+    }
+  }
+}
+```
+
+`snapdom` 降级截图可能受跨域图片、跨域 iframe、video、WebGL/canvas 污染、复杂 CSS 和字体加载时序影响。需要最高准确度时，请配置 CDP。
+
 ## MCP 工具清单
 
 ### 页面工具
@@ -260,8 +329,9 @@ DOM 默认跳过 `script`、`style`、`noscript`，并隐藏 password input 的
 |---|---|---|---|
 | `get_dom_tree` | `pageId?`、`maxDepth?`、`maxNodes?` | `source`、`snapshot` | 获取裁剪后的 DOM tree |
 | `query_dom` | `pageId?`、`selector`、`limit?` | `source`、`nodes` | 按 selector 查询元素摘要 |
+| `take_screenshot` | `pageId?`、`target?`、`selector?`、`format?`、`prefer?` | `source`、`mimeType`、`data`、`width`、`height` | 页面截图，CDP 优先，snapdom 降级 |
 
-CDP 可用时输出 `source: 'cdp'`，否则使用 Runtime Hook 输出 `source: 'hook'`。
+CDP 可用时 DOM 工具输出 `source: 'cdp'`，否则使用 Runtime Hook 输出 `source: 'hook'`。截图工具输出 `source: 'cdp' | 'snapdom'`。
 
 ### Console 工具
 
@@ -366,7 +436,8 @@ pnpm run play
 
 ```text
 Local: http://localhost:3456/
-MCP: Server is running at http://localhost:3456/__mcp/sse
+MCP: SSE server is running at http://localhost:3456/__mcp/sse
+MCP: Streamable HTTP server is running at http://localhost:3456/__mcp/mcp
 ```
 
 当前 playground 页面入口为：
@@ -436,12 +507,13 @@ CDP 验证通过时，以下工具返回中应出现 `source: 'cdp'`：
 当前实现已通过以下验证：
 
 - MCP SSE 服务可连接
-- `tools/list` 可枚举 16 个 MCP 工具
+- `tools/list` 可枚举 17 个 MCP 工具
 - `list_pages` 可返回 Vite entry、runtime 页面和 CDP target
 - Runtime Hook 可读取 DOM、Console、Network
 - Runtime Hook 可执行已授权表达式
 - Vue Runtime Bridge 可读取组件树、Router、Pinia tree/state
 - CDP 可读取 DOM tree、selector 查询、Evaluate、Console、Network
+- CDP 可执行真截图，CDP 不可用时可使用 snapdom DOM 截图降级
 - `pnpm run check` 通过
 - `git diff --check` 通过