@xiaou66/vite-plugin-vue-mcp-next 0.0.3 → 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 |
@@ -122,6 +123,17 @@ vueMcpNext({
   },
   console: {
     maxRecords: 1000
+  },
+  screenshot: {
+    prefer: 'auto',
+    maxBytes: 5 * 1024 * 1024,
+    snapdom: {
+      options: {
+        scale: 1,
+        useProxy: undefined
+      },
+      plugins: []
+    }
   }
 })
 ```
@@ -136,6 +148,7 @@ vueMcpNext({
 | `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` 注入的场景：
 
@@ -242,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 工具清单
 
 ### 页面工具
@@ -262,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 工具
 
@@ -439,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` 通过
 

package/dist/index.cjs

@@ -53,11 +53,13 @@ var DEFAULT_MASK_HEADERS = [
 
 // src/constants.ts
 var DEFAULT_MCP_PATH = "/__mcp";
+var DEFAULT_SCREENSHOT_MAX_BYTES = 5 * 1024 * 1024;
 var MCP_TOOL_NAMES = {
   listPages: "list_pages",
   getPageState: "get_page_state",
   getDomTree: "get_dom_tree",
   queryDom: "query_dom",
+  takeScreenshot: "take_screenshot",
   getConsoleLogs: "get_console_logs",
   clearConsoleLogs: "clear_console_logs",
   evaluateScript: "evaluate_script",
@@ -74,6 +76,8 @@ var MCP_TOOL_NAMES = {
 };
 var VIRTUAL_RUNTIME_ID = "virtual:vite-plugin-vue-mcp-next/runtime";
 var RESOLVED_VIRTUAL_RUNTIME_ID = `\0${VIRTUAL_RUNTIME_ID}`;
+var VIRTUAL_SCREENSHOT_CONFIG_ID = "virtual:vite-plugin-vue-mcp-next/screenshot-config";
+var RESOLVED_VIRTUAL_SCREENSHOT_CONFIG_ID = `\0${VIRTUAL_SCREENSHOT_CONFIG_ID}`;
 var DEFAULT_MCP_CLIENT_SERVER_NAME = "vue-mcp-next";
 var DEFAULT_OPTIONS = {
   mcpPath: DEFAULT_MCP_PATH,
@@ -113,6 +117,14 @@ var DEFAULT_OPTIONS = {
   },
   console: {
     maxRecords: DEFAULT_CONSOLE_MAX_RECORDS
+  },
+  screenshot: {
+    prefer: "auto",
+    maxBytes: DEFAULT_SCREENSHOT_MAX_BYTES,
+    snapdom: {
+      options: {},
+      plugins: []
+    }
   }
 };
 function mergeMcpClientOptions(cursorConfig, mcpClients) {
@@ -163,6 +175,21 @@ function mergeOptions(options = {}) {
     console: {
       ...DEFAULT_OPTIONS.console,
       ...options.console
+    },
+    screenshot: {
+      ...DEFAULT_OPTIONS.screenshot,
+      ...options.screenshot,
+      snapdom: {
+        ...DEFAULT_OPTIONS.screenshot.snapdom,
+        ...options.screenshot?.snapdom,
+        options: {
+          ...DEFAULT_OPTIONS.screenshot.snapdom.options,
+          ...options.screenshot?.snapdom?.options
+        },
+        plugins: options.screenshot?.snapdom?.plugins ?? [
+          ...DEFAULT_OPTIONS.screenshot.snapdom.plugins
+        ]
+      }
     }
   };
 }
@@ -717,9 +744,225 @@ function getPathname(url) {
   }
 }
 
+// src/mcp/tools/screenshot.ts
+var import_zod5 = require("zod");
+
+// src/cdp/cdpScreenshot.ts
+async function cdpCaptureScreenshot(options) {
+  if (options.target === "element") {
+    return captureElementScreenshot(options);
+  }
+  if (options.target === "fullPage") {
+    return captureFullPageScreenshot(options);
+  }
+  return captureViewportScreenshot(options);
+}
+async function captureViewportScreenshot(options) {
+  const metrics = await options.client.Page.getLayoutMetrics();
+  const width = Math.ceil(metrics.cssLayoutViewport.clientWidth);
+  const height = Math.ceil(metrics.cssLayoutViewport.clientHeight);
+  const result = await options.client.Page.captureScreenshot(
+    omitUndefined({
+      format: options.format,
+      quality: createQuality(options),
+      captureBeyondViewport: false
+    })
+  );
+  return { data: result.data, width, height };
+}
+async function captureFullPageScreenshot(options) {
+  const metrics = await options.client.Page.getLayoutMetrics();
+  const width = Math.ceil(metrics.cssContentSize.width);
+  const height = Math.ceil(metrics.cssContentSize.height);
+  const result = await options.client.Page.captureScreenshot(
+    omitUndefined({
+      format: options.format,
+      quality: createQuality(options),
+      captureBeyondViewport: true,
+      clip: { x: 0, y: 0, width, height, scale: 1 }
+    })
+  );
+  return { data: result.data, width, height };
+}
+async function captureElementScreenshot(options) {
+  if (!options.selector) {
+    throw new Error("selector is required when target is element");
+  }
+  const rect = await getElementRect(options.client, options.selector);
+  const result = await options.client.Page.captureScreenshot(
+    omitUndefined({
+      format: options.format,
+      quality: createQuality(options),
+      captureBeyondViewport: true,
+      clip: {
+        x: rect.x,
+        y: rect.y,
+        width: rect.width,
+        height: rect.height,
+        scale: 1
+      }
+    })
+  );
+  return { data: result.data, width: rect.width, height: rect.height };
+}
+async function getElementRect(client, selector) {
+  const result = await client.Runtime.evaluate({
+    expression: createElementRectExpression(selector),
+    awaitPromise: true,
+    returnByValue: true
+  });
+  if (result.exceptionDetails) {
+    throw new Error(result.exceptionDetails.text || "element query failed");
+  }
+  const value = result.result.value;
+  if (!isElementRect(value)) {
+    throw new Error(`element not found: ${selector}`);
+  }
+  return value;
+}
+function createElementRectExpression(selector) {
+  return `(() => {
+  const el = document.querySelector(${JSON.stringify(selector)});
+  if (!el) return null;
+  const rect = el.getBoundingClientRect();
+  return {
+    x: rect.x + window.scrollX,
+    y: rect.y + window.scrollY,
+    width: rect.width,
+    height: rect.height
+  };
+})()`;
+}
+function createQuality(options) {
+  return options.format === "png" ? void 0 : options.quality;
+}
+function omitUndefined(value) {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, item]) => item !== void 0)
+  );
+}
+function isElementRect(value) {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const rect = value;
+  return typeof rect.x === "number" && typeof rect.y === "number" && typeof rect.width === "number" && rect.width > 0 && typeof rect.height === "number" && rect.height > 0;
+}
+
+// src/mcp/tools/screenshot.ts
+var DEFAULT_SCREENSHOT_TARGET = "viewport";
+var DEFAULT_SCREENSHOT_FORMAT = "png";
+var screenshotInputSchema = {
+  pageId: import_zod5.z.string().optional(),
+  target: import_zod5.z.enum(["viewport", "fullPage", "element"]).optional(),
+  selector: import_zod5.z.string().optional(),
+  format: import_zod5.z.enum(["png", "jpeg", "webp"]).optional(),
+  prefer: import_zod5.z.enum(["auto", "cdp", "runtime"]).optional(),
+  quality: import_zod5.z.number().optional(),
+  scale: import_zod5.z.number().optional(),
+  snapdom: import_zod5.z.record(import_zod5.z.string(), import_zod5.z.unknown()).optional()
+};
+function registerScreenshotTools(server, ctx) {
+  server.registerTool(
+    MCP_TOOL_NAMES.takeScreenshot,
+    {
+      description: "Take a page screenshot using CDP or snapdom fallback.",
+      inputSchema: screenshotInputSchema
+    },
+    async (input) => handleTakeScreenshot(ctx, input)
+  );
+}
+async function handleTakeScreenshot(ctx, input) {
+  const target = input.target ?? DEFAULT_SCREENSHOT_TARGET;
+  const format = input.format ?? DEFAULT_SCREENSHOT_FORMAT;
+  const prefer = input.prefer ?? ctx.options.screenshot.prefer;
+  if (target === "element" && !input.selector) {
+    return createToolError("selector is required when target is element");
+  }
+  if (prefer !== "runtime") {
+    const cdp = await connectCdpForPage(ctx, input.pageId);
+    if (cdp) {
+      try {
+        const screenshot = await cdpCaptureScreenshot({
+          client: cdp.client,
+          target,
+          selector: input.selector,
+          format,
+          quality: input.quality
+        });
+        return createScreenshotResponse(ctx, {
+          source: "cdp",
+          target,
+          format,
+          data: screenshot.data,
+          width: screenshot.width,
+          height: screenshot.height,
+          mimeType: createMimeType(format),
+          byteLength: getBase64ByteLength(screenshot.data)
+        });
+      } finally {
+        await closeCdpClient(cdp.client);
+      }
+    }
+    if (prefer === "cdp") {
+      return createToolError("CDP screenshot is unavailable");
+    }
+  }
+  return createRuntimeScreenshot(ctx, input, { target, format });
+}
+async function createRuntimeScreenshot(ctx, input, normalized) {
+  const result = await requestRuntimeData(ctx, (event) => {
+    void ctx.rpcServer?.takeScreenshot({
+      event,
+      target: normalized.target,
+      selector: input.selector,
+      format: normalized.format,
+      quality: input.quality,
+      scale: input.scale,
+      snapdom: {
+        ...ctx.options.screenshot.snapdom,
+        options: {
+          ...ctx.options.screenshot.snapdom.options,
+          ...input.snapdom
+        }
+      }
+    });
+  });
+  if (isScreenshotTooLarge(ctx, result)) {
+    return createToolError(
+      `screenshot is too large: ${String(result.byteLength)} bytes`
+    );
+  }
+  if (!isPlainRecord(result)) {
+    return createToolError("runtime screenshot returned an invalid response");
+  }
+  return createToolResponse(result);
+}
+function createScreenshotResponse(ctx, result) {
+  if (result.byteLength > ctx.options.screenshot.maxBytes) {
+    return createToolError(
+      `screenshot is too large: ${String(result.byteLength)} bytes`
+    );
+  }
+  return createToolResponse(result);
+}
+function isScreenshotTooLarge(ctx, result) {
+  return isPlainRecord(result) && "byteLength" in result && typeof result.byteLength === "number" && result.byteLength > ctx.options.screenshot.maxBytes;
+}
+function isPlainRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function createMimeType(format) {
+  return `image/${format}`;
+}
+function getBase64ByteLength(data) {
+  const padding = data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0;
+  return Math.ceil(data.length * 3 / 4) - padding;
+}
+
 // src/mcp/tools/vue.ts
 var import_nanoid2 = require("nanoid");
-var import_zod5 = require("zod");
+var import_zod6 = require("zod");
 function registerVueTools(server, ctx) {
   server.registerTool(
     MCP_TOOL_NAMES.getComponentTree,
@@ -732,7 +975,7 @@ function registerVueTools(server, ctx) {
     MCP_TOOL_NAMES.getComponentState,
     {
       description: "Get Vue component state.",
-      inputSchema: { componentName: import_zod5.z.string() }
+      inputSchema: { componentName: import_zod6.z.string() }
     },
     async ({ componentName }) => requestVueData(ctx, (event) => {
       void ctx.rpcServer?.getInspectorState({ event, componentName });
@@ -743,10 +986,10 @@ function registerVueTools(server, ctx) {
     {
       description: "Edit Vue component state.",
       inputSchema: {
-        componentName: import_zod5.z.string(),
-        path: import_zod5.z.array(import_zod5.z.string()),
-        value: import_zod5.z.string(),
-        valueType: import_zod5.z.enum(["string", "number", "boolean", "object", "array"])
+        componentName: import_zod6.z.string(),
+        path: import_zod6.z.array(import_zod6.z.string()),
+        value: import_zod6.z.string(),
+        valueType: import_zod6.z.enum(["string", "number", "boolean", "object", "array"])
       }
     },
     ({ componentName, path: path5, value, valueType }) => {
@@ -766,7 +1009,7 @@ function registerVueTools(server, ctx) {
     MCP_TOOL_NAMES.highlightComponent,
     {
       description: "Highlight a Vue component.",
-      inputSchema: { componentName: import_zod5.z.string() }
+      inputSchema: { componentName: import_zod6.z.string() }
     },
     ({ componentName }) => {
       if (!ctx.rpcServer) {
@@ -794,7 +1037,7 @@ function registerVueTools(server, ctx) {
     MCP_TOOL_NAMES.getPiniaState,
     {
       description: "Get Pinia store state.",
-      inputSchema: { storeName: import_zod5.z.string() }
+      inputSchema: { storeName: import_zod6.z.string() }
     },
     async ({ storeName }) => requestVueData(ctx, (event) => {
       void ctx.rpcServer?.getPiniaState({ event, storeName });
@@ -837,6 +1080,7 @@ function createMcpServer(ctx, vite) {
   });
   registerPageTools(server, ctx, vite);
   registerDomTools(server, ctx);
+  registerScreenshotTools(server, ctx);
   registerConsoleTools(server, ctx);
   registerEvaluateTools(server, ctx);
   registerNetworkTools(server, ctx);
@@ -919,6 +1163,10 @@ function createServerVueRuntimeRpc(ctx) {
     onEvaluateScriptUpdated: (event, data) => {
       void ctx.hooks.callHook(event, data);
     },
+    takeScreenshot: () => void 0,
+    onScreenshotTaken: (event, data) => {
+      void ctx.hooks.callHook(event, data);
+    },
     getInspectorTree: () => void 0,
     onInspectorTreeUpdated: (event, data) => {
       void ctx.hooks.callHook(event, data);
@@ -1210,13 +1458,19 @@ function createRuntimeInjectionController(options, getConfig) {
       if (importee === VIRTUAL_RUNTIME_ID) {
         return RESOLVED_VIRTUAL_RUNTIME_ID;
       }
+      if (importee === VIRTUAL_SCREENSHOT_CONFIG_ID) {
+        return RESOLVED_VIRTUAL_SCREENSHOT_CONFIG_ID;
+      }
       return void 0;
     },
     load(id) {
-      if (id !== RESOLVED_VIRTUAL_RUNTIME_ID) {
-        return void 0;
+      if (id === RESOLVED_VIRTUAL_RUNTIME_ID) {
+        return "import { startRuntimeClient } from '@xiaou66/vite-plugin-vue-mcp-next/runtime/client';\nvoid startRuntimeClient();";
+      }
+      if (id === RESOLVED_VIRTUAL_SCREENSHOT_CONFIG_ID) {
+        return createScreenshotConfigModule(options);
       }
-      return "import { startRuntimeClient } from '@xiaou66/vite-plugin-vue-mcp-next/runtime/client';\nvoid startRuntimeClient();";
+      return void 0;
     },
     transformIndexHtml(html) {
       if (options.appendTo) {
@@ -1251,6 +1505,32 @@ ${code}`;
     }
   };
 }
+function createScreenshotConfigModule(options) {
+  const paths = collectScreenshotImportPaths(options);
+  const imports = paths.map((item, index) => `import * as m${String(index)} from ${JSON.stringify(item)};`).join("\n");
+  const entries = paths.map((item, index) => `${JSON.stringify(item)}: m${String(index)}`).join(",\n  ");
+  return `${imports}
+export const screenshotModuleRegistry = {
+  ${entries}
+};
+`;
+}
+function collectScreenshotImportPaths(options) {
+  const paths = /* @__PURE__ */ new Set();
+  for (const plugin of options.screenshot.snapdom.plugins) {
+    paths.add(getPluginPath(plugin));
+  }
+  if (options.screenshot.snapdom.filter) {
+    paths.add(options.screenshot.snapdom.filter);
+  }
+  if (options.screenshot.snapdom.fallbackURL) {
+    paths.add(options.screenshot.snapdom.fallbackURL);
+  }
+  return [...paths];
+}
+function getPluginPath(plugin) {
+  return typeof plugin === "string" ? plugin : plugin.path;
+}
 
 // src/plugin/mcpClientConfig/index.ts
 var import_node_path4 = __toESM(require("path"), 1);
@@ -1336,11 +1616,11 @@ var import_node_path3 = __toESM(require("path"), 1);
 async function updateJsonMcpClientConfig(options) {
   try {
     const config = await readJsonConfig(options.configPath);
-    if (!isPlainRecord(config)) {
+    if (!isPlainRecord2(config)) {
       warnConfigFailure(options, "config root must be a JSON object");
       return;
     }
-    const mcpServers = isPlainRecord(config.mcpServers) ? config.mcpServers : {};
+    const mcpServers = isPlainRecord2(config.mcpServers) ? config.mcpServers : {};
     if (Object.hasOwn(mcpServers, options.serverName)) {
       return;
     }
@@ -1373,7 +1653,7 @@ async function readOptionalTextFile2(filePath) {
     throw error;
   }
 }
-function isPlainRecord(value) {
+function isPlainRecord2(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function warnConfigFailure(options, reason) {