@xiaou66/vite-plugin-vue-mcp-next 1.0.1 → 1.0.2

package/README.md

@@ -43,7 +43,7 @@ SSE: http://localhost:<vite-port>/__mcp/sse
 Streamable HTTP: http://localhost:<vite-port>/__mcp/mcp
 ```
 
-启动 Vite dev server 后，插件会按项目中已经存在的客户端入口自动写入项目级 MCP 配置，服务名默认是 `vue-mcp-next`。自动配置只会在缺少同名 server 条目时新增配置；如果用户已经配置了 `vue-mcp-next`，插件不会重复写入、覆盖原配置或改写用户自定义字段。
+启动 Vite dev server 后，插件会按项目中已经存在的客户端入口自动写入项目级 MCP 配置，服务名默认是 `vite-mcp-next`。自动配置只会在缺少同名 server 条目时新增配置；如果用户已经配置了历史默认名 `vue-mcp-next`，插件会把它迁移为 `vite-mcp-next` 并保留原配置内容。
 
 默认自动探测规则如下：
 
@@ -67,7 +67,7 @@ Cursor、Claude Code、Trae 等 JSON 配置客户端可以使用：
 ```json
 {
   "mcpServers": {
-    "vue-mcp-next": {
+    "vite-mcp-next": {
       "type": "sse",
       "url": "http://localhost:5173/__mcp/sse"
     }
@@ -78,12 +78,44 @@ Cursor、Claude Code、Trae 等 JSON 配置客户端可以使用：
 Codex 使用 TOML 配置：
 
 ```toml
-[mcp_servers.vue-mcp-next]
+[mcp_servers.vite-mcp-next]
 url = "http://localhost:5173/__mcp/mcp"
 ```
 
 `5173` 是示例端口。若 Vite 使用了其他端口，请替换为启动日志中打印的 MCP 地址。
 
+### 自动复制 AI 使用指南
+
+插件随 npm 包发布一份通用 Skill 文件：`skills/vite-mcp-next/SKILL.md`。Vite dev server 启动时，插件会在检测到项目中已经存在对应 AI 工具入口后，把这份静态文件复制到对应工具目录。插件不会在运行时拼接或生成 Skill 正文，包内 `skills/vite-mcp-next/SKILL.md` 是唯一内容来源。
+
+| 客户端      | 探测入口   | 自动复制目标                                   | 说明                                  |
+| ----------- | ---------- | ---------------------------------------------- | ------------------------------------- |
+| Codex       | `.codex/`  | `.codex/skills/vite-mcp-next/SKILL.md`         | 从包内 `skills/vite-mcp-next/SKILL.md` 复制 |
+| Claude Code | `.claude/` | `.claude/skills/vite-mcp-next/SKILL.md`        | 从包内 `skills/vite-mcp-next/SKILL.md` 复制 |
+| Cursor      | `.cursor/` | `.cursor/rules/vite-mcp-next.mdc`              | 从同一份 Skill 文件复制，作为项目规则参考 |
+| Trae        | `.trae/`   | 不自动复制                                     | 当前只自动写 MCP 配置，Rule 路径未作为首版稳定能力 |
+
+使用指南覆盖以下工具顺序：
+
+1. `list_pages`：先确认页面、runtime 和 CDP target
+2. `get_dom_tree` / `query_dom`：检查 DOM 结构
+3. `take_screenshot`：做视觉验证
+4. `get_console_logs`：排查 Console 报错
+5. `get_network_requests` / `get_network_request_detail`：排查接口请求
+6. `get_component_tree` / `get_component_state` / `get_router_info` / `get_pinia_tree` / `get_pinia_state`：检查 Vue 语义状态
+
+如果不希望插件复制任何 AI 使用指南，可以关闭：
+
+```ts
+vueMcpNext({
+  skill: {
+    autoConfig: false
+  }
+})
+```
+
+自动复制只会更新带有插件生成标记的文件；如果目标文件已经存在但不是插件生成的内容，插件会跳过并保留用户文件。没有使用某个 AI 工具时，对应入口目录不存在，插件不会创建该工具目录。
+
 ## 完整配置
 
 `mcpClients` 中的布尔值保留为开关语义：默认解析后为 `true`，但写入阶段会先做项目入口自动探测；用户在配置中显式写出 `true` 时表示强制创建对应客户端配置。
@@ -99,7 +131,10 @@ vueMcpNext({
     codex: true,
     claudeCode: true,
     trae: true,
-    serverName: 'vue-mcp-next'
+    serverName: 'vite-mcp-next'
+  },
+  skill: {
+    autoConfig: true
   },
   appendTo: undefined,
   runtime: {
@@ -155,6 +190,7 @@ vueMcpNext({
 | `printUrl`            | `boolean`                                                                                          | `true`                   | 是否在 Vite 启动日志中打印 MCP SSE 地址                                                     |
 | `mcpClients`          | `{ cursor?: boolean; codex?: boolean; claudeCode?: boolean; trae?: boolean; serverName?: string }` | 自动探测                 | 是否写入 Cursor、Codex、Claude Code、Trae 的项目级 MCP 配置；默认只处理项目中已有入口，显式 `true` 强制创建 |
 | `updateCursorMcpJson` | `boolean \| { enabled: boolean; serverName?: string }`                                             | 自动探测                 | 兼容旧配置；默认只在 `.cursor` 已存在时写入，建议新项目使用 `mcpClients`                           |
+| `skill`               | `{ autoConfig?: boolean }`                                                                         | `{ autoConfig: true }`   | 是否在检测到 Codex、Claude Code、Cursor 项目入口时自动复制包内 AI 使用指南                    |
 | `appendTo`            | `string \| RegExp`                                                                                 | `undefined`              | 非 HTML 入口注入点。配置后会在匹配入口模块前追加 runtime import                             |
 | `screenshot`          | `ScreenshotOptions`                                                                                | CDP 优先，snapdom 降级   | 页面截图配置，控制真截图、DOM 降级截图、体积上限和 snapdom 扩展                             |
 | `screenshot.type`     | `'path' \| 'base64'`                                                                               | `'path'`                 | 项目级控制截图返回文件路径还是 base64 数据                                                  |

package/dist/index.cjs

@@ -81,7 +81,8 @@ var VIRTUAL_SCREENSHOT_CONFIG_ID = "virtual:vite-plugin-vue-mcp-next/screenshot-
 var RESOLVED_VIRTUAL_SCREENSHOT_CONFIG_ID = `\0${VIRTUAL_SCREENSHOT_CONFIG_ID}`;
 var VIRTUAL_SNAPDOM_LOADER_ID = "virtual:vite-plugin-vue-mcp-next/snapdom-loader";
 var RESOLVED_VIRTUAL_SNAPDOM_LOADER_ID = `\0${VIRTUAL_SNAPDOM_LOADER_ID}`;
-var DEFAULT_MCP_CLIENT_SERVER_NAME = "vue-mcp-next";
+var DEFAULT_MCP_CLIENT_SERVER_NAME = "vite-mcp-next";
+var LEGACY_MCP_CLIENT_SERVER_NAMES = ["vue-mcp-next"];
 var RUNTIME_PAGE_RECONNECTED_EVENT = "vite-plugin-vue-mcp-next:page-reconnected";
 var DEFAULT_OPTIONS = {
   mcpPath: DEFAULT_MCP_PATH,
@@ -98,6 +99,9 @@ var DEFAULT_OPTIONS = {
     trae: true,
     serverName: DEFAULT_MCP_CLIENT_SERVER_NAME
   },
+  skill: {
+    autoConfig: true
+  },
   runtime: {
     mode: "auto",
     evaluate: {
@@ -155,6 +159,10 @@ function mergeOptions(options = {}) {
     ...options,
     updateCursorMcpJson: cursorConfig,
     mcpClients,
+    skill: {
+      ...DEFAULT_OPTIONS.skill,
+      ...options.skill
+    },
     runtime: {
       ...DEFAULT_OPTIONS.runtime,
       ...options.runtime,
@@ -1183,13 +1191,13 @@ function registerVueTools(server, ctx) {
         valueType: import_zod7.z.enum(["string", "number", "boolean", "object", "array"])
       }
     },
-    ({ componentName, path: path6, value, valueType }) => {
+    ({ componentName, path: path8, value, valueType }) => {
       if (!ctx.rpcServer) {
         return vueBridgeUnavailable();
       }
       void ctx.rpcServer.editComponentState({
         componentName,
-        path: path6,
+        path: path8,
         value,
         valueType
       });
@@ -1791,10 +1799,18 @@ async function updateCodexMcpClientConfig(options) {
 }
 function replaceOrAppendOwnedBlock(current, options) {
   const block = createCodexServerBlock(options);
-  const matcher = createOwnedBlockMatcher(options.serverName);
+  const matcher = createServerTableMatcher(options.serverName);
   if (matcher.test(current)) {
     return ensureTrailingNewline(current);
   }
+  const legacyServerName = options.legacyServerNames?.find(
+    (serverName) => createServerTableMatcher(serverName).test(current)
+  );
+  if (legacyServerName) {
+    return ensureTrailingNewline(
+      renameServerTableHeaders(current, legacyServerName, options.serverName)
+    );
+  }
   const separator = current.trim() ? "\n\n" : "";
   return `${trimEndNewline(current)}${separator}${block}`;
 }
@@ -1803,25 +1819,47 @@ function createCodexServerBlock(options) {
 url = ${quoteTomlString(options.mcpUrl)}
 `;
 }
-function createOwnedBlockMatcher(serverName) {
+function createServerTableMatcher(serverName) {
   const plainHeader = escapeRegExp(`[mcp_servers.${serverName}]`);
+  const plainChildHeader = escapeRegExp(`[mcp_servers.${serverName}.`);
   const quotedHeader = escapeRegExp(
     `[mcp_servers.${quoteTomlKey(serverName)}]`
   );
+  const quotedChildHeader = escapeRegExp(
+    `[mcp_servers.${quoteTomlKey(serverName)}.`
+  );
   return new RegExp(
-    `(?:^|\\n)(?:${plainHeader}|${quotedHeader})\\n[\\s\\S]*?(?=\\n\\[|$)`
+    `(?:^|\\n)(?:${plainHeader}|${plainChildHeader}|${quotedHeader}|${quotedChildHeader})`
   );
 }
 function createTableHeader(serverName) {
-  const key = /^[A-Za-z0-9_-]+$/.test(serverName) ? serverName : quoteTomlKey(serverName);
+  const key = createTableKey(serverName);
   return `[mcp_servers.${key}]`;
 }
+function createTableKey(serverName) {
+  return /^[A-Za-z0-9_-]+$/.test(serverName) ? serverName : quoteTomlKey(serverName);
+}
 function quoteTomlKey(value) {
   return quoteTomlString(value);
 }
 function quoteTomlString(value) {
   return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 }
+function renameServerTableHeaders(current, fromServerName, toServerName) {
+  return current.split("\n").map((line) => renameServerTableHeader(line, fromServerName, toServerName)).join("\n");
+}
+function renameServerTableHeader(line, fromServerName, toServerName) {
+  const toKey = createTableKey(toServerName);
+  const fromKeys = [fromServerName, quoteTomlKey(fromServerName)];
+  for (const fromKey of fromKeys) {
+    const prefix = `[mcp_servers.${fromKey}`;
+    const nextChar = line[prefix.length];
+    if (line.startsWith(prefix) && (nextChar === "]" || nextChar === ".")) {
+      return `[mcp_servers.${toKey}${line.slice(prefix.length)}`;
+    }
+  }
+  return line;
+}
 async function readOptionalTextFile(filePath) {
   try {
     return await import_promises2.default.readFile(filePath, "utf-8");
@@ -1863,18 +1901,38 @@ async function updateJsonMcpClientConfig(options) {
     if (Object.hasOwn(mcpServers, options.serverName)) {
       return;
     }
+    const migratedMcpServers = renameLegacyServer(mcpServers, options);
+    if (migratedMcpServers) {
+      config.mcpServers = migratedMcpServers;
+      await writeJsonConfig(options.configPath, config);
+      return;
+    }
     mcpServers[options.serverName] = { type: "sse", url: options.mcpUrl };
     config.mcpServers = mcpServers;
-    await import_promises3.default.mkdir(import_node_path5.default.dirname(options.configPath), { recursive: true });
-    await import_promises3.default.writeFile(
-      options.configPath,
-      `${JSON.stringify(config, null, 2)}
-`
-    );
+    await writeJsonConfig(options.configPath, config);
   } catch (error) {
     warnConfigFailure(options, formatError2(error));
   }
 }
+function renameLegacyServer(mcpServers, options) {
+  const legacyServerName = options.legacyServerNames?.find(
+    (name) => Object.hasOwn(mcpServers, name)
+  );
+  if (!legacyServerName) {
+    return void 0;
+  }
+  return Object.fromEntries(
+    Object.entries(mcpServers).map(([serverName, serverConfig]) => [
+      serverName === legacyServerName ? options.serverName : serverName,
+      serverConfig
+    ])
+  );
+}
+async function writeJsonConfig(configPath, config) {
+  await import_promises3.default.mkdir(import_node_path5.default.dirname(configPath), { recursive: true });
+  await import_promises3.default.writeFile(configPath, `${JSON.stringify(config, null, 2)}
+`);
+}
 async function readJsonConfig(configPath) {
   const raw = await readOptionalTextFile2(configPath);
   if (!raw.trim()) {
@@ -1910,76 +1968,83 @@ function isNodeError2(error) {
 // src/plugin/mcpClientConfig/index.ts
 async function updateMcpClientConfigs(root, sseUrl, streamableHttpUrl, options, userOptions = {}) {
   const serverName = options.serverName;
-  const jobs = [];
-  if (await shouldUpdateClientConfig({
-    root,
-    clientName: "cursor",
-    enabled: options.cursor,
-    entryPath: import_node_path6.default.join(root, ".cursor"),
-    entryKind: "directory",
-    userOptions
-  })) {
-    jobs.push(
-      updateJsonMcpClientConfig({
+  const legacyServerNames = getLegacyServerNames(serverName);
+  const descriptors = [
+    {
+      root,
+      clientName: "cursor",
+      enabled: options.cursor,
+      entryPath: import_node_path6.default.join(root, ".cursor"),
+      entryKind: "directory",
+      userOptions,
+      createJob: () => updateJsonMcpClientConfig({
         clientName: "Cursor",
         configPath: import_node_path6.default.join(root, ".cursor", "mcp.json"),
         mcpUrl: sseUrl,
-        serverName
+        serverName,
+        legacyServerNames
       })
-    );
-  }
-  if (await shouldUpdateClientConfig({
-    root,
-    clientName: "codex",
-    enabled: options.codex,
-    entryPath: import_node_path6.default.join(root, ".codex"),
-    entryKind: "directory",
-    userOptions
-  })) {
-    jobs.push(
-      updateCodexMcpClientConfig({
+    },
+    {
+      root,
+      clientName: "codex",
+      enabled: options.codex,
+      entryPath: import_node_path6.default.join(root, ".codex"),
+      entryKind: "directory",
+      userOptions,
+      createJob: () => updateCodexMcpClientConfig({
         configPath: import_node_path6.default.join(root, ".codex", "config.toml"),
         mcpUrl: streamableHttpUrl,
-        serverName
+        serverName,
+        legacyServerNames
       })
-    );
-  }
-  if (await shouldUpdateClientConfig({
-    root,
-    clientName: "claudeCode",
-    enabled: options.claudeCode,
-    entryPath: import_node_path6.default.join(root, ".mcp.json"),
-    entryKind: "file",
-    userOptions
-  })) {
-    jobs.push(
-      updateJsonMcpClientConfig({
+    },
+    {
+      root,
+      clientName: "claudeCode",
+      enabled: options.claudeCode,
+      entryPath: import_node_path6.default.join(root, ".mcp.json"),
+      entryKind: "file",
+      userOptions,
+      createJob: () => updateJsonMcpClientConfig({
         clientName: "Claude Code",
         configPath: import_node_path6.default.join(root, ".mcp.json"),
         mcpUrl: sseUrl,
-        serverName
+        serverName,
+        legacyServerNames
       })
-    );
-  }
-  if (await shouldUpdateClientConfig({
-    root,
-    clientName: "trae",
-    enabled: options.trae,
-    entryPath: import_node_path6.default.join(root, ".trae"),
-    entryKind: "directory",
-    userOptions
-  })) {
-    jobs.push(
-      updateJsonMcpClientConfig({
+    },
+    {
+      root,
+      clientName: "trae",
+      enabled: options.trae,
+      entryPath: import_node_path6.default.join(root, ".trae"),
+      entryKind: "directory",
+      userOptions,
+      createJob: () => updateJsonMcpClientConfig({
         clientName: "Trae",
         configPath: import_node_path6.default.join(root, ".trae", "mcp.json"),
         mcpUrl: sseUrl,
-        serverName
+        serverName,
+        legacyServerNames
       })
-    );
-  }
+    }
+  ];
+  const jobs = await createClientConfigJobs(descriptors);
   await Promise.all(jobs);
 }
+async function createClientConfigJobs(descriptors) {
+  const jobs = [];
+  for (const descriptor of descriptors) {
+    if (await shouldUpdateClientConfig(descriptor)) {
+      jobs.push(descriptor.createJob());
+    }
+  }
+  return jobs;
+}
+function getLegacyServerNames(serverName) {
+  return serverName === DEFAULT_MCP_CLIENT_SERVER_NAME ? LEGACY_MCP_CLIENT_SERVER_NAMES : [];
+}
 async function shouldUpdateClientConfig(options) {
   if (!options.enabled) {
     return false;
@@ -2016,6 +2081,157 @@ function isNodeError3(error) {
   return error instanceof Error && "code" in error;
 }
 
+// src/plugin/skillConfig/index.ts
+var import_promises6 = __toESM(require("fs/promises"), 1);
+var import_node_path8 = __toESM(require("path"), 1);
+
+// src/plugin/skillConfig/writers.ts
+var import_promises5 = __toESM(require("fs/promises"), 1);
+var import_node_path7 = __toESM(require("path"), 1);
+var GENERATED_SKILL_CONFIG_MARKER = "<!-- Generated by vite-plugin-vue-mcp-next. Safe to edit, but automatic updates only apply while this marker remains. -->";
+async function writeGeneratedTextFile(options) {
+  try {
+    const current = await readOptionalTextFile3(options.filePath);
+    if (current && !current.includes(GENERATED_SKILL_CONFIG_MARKER)) {
+      console.warn(
+        `[vite-plugin-vue-mcp-next] Skipped ${options.targetName} at ${options.filePath}: file is not generated by this plugin`
+      );
+      return;
+    }
+    await import_promises5.default.mkdir(import_node_path7.default.dirname(options.filePath), { recursive: true });
+    await import_promises5.default.writeFile(options.filePath, options.content);
+  } catch (error) {
+    console.warn(
+      `[vite-plugin-vue-mcp-next] Failed to update ${options.targetName} at ${options.filePath}: ${formatError4(error)}`
+    );
+  }
+}
+async function readOptionalTextFile3(filePath) {
+  try {
+    return await import_promises5.default.readFile(filePath, "utf-8");
+  } catch (error) {
+    if (isNodeError4(error) && error.code === "ENOENT") {
+      return "";
+    }
+    throw error;
+  }
+}
+function formatError4(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function isNodeError4(error) {
+  return error instanceof Error && "code" in error;
+}
+
+// src/plugin/skillConfig/index.ts
+var PACKAGE_NAME = "@xiaou66/vite-plugin-vue-mcp-next";
+var PACKAGED_SKILL_PATH = import_node_path8.default.join("skills", "vite-mcp-next", "SKILL.md");
+async function updateSkillConfigs(root, options) {
+  if (!options.autoConfig) {
+    return;
+  }
+  const descriptors = createSkillConfigDescriptors(root);
+  const skillContent = await safelyReadPackagedSkillContent(root);
+  if (!skillContent) {
+    return;
+  }
+  const jobs = await createSkillConfigJobs(descriptors, skillContent);
+  await Promise.all(jobs);
+}
+function createSkillConfigDescriptors(root) {
+  return [
+    {
+      entryPath: import_node_path8.default.join(root, ".codex"),
+      filePath: import_node_path8.default.join(root, ".codex", "skills", "vite-mcp-next", "SKILL.md"),
+      targetName: "Codex skill"
+    },
+    {
+      entryPath: import_node_path8.default.join(root, ".claude"),
+      filePath: import_node_path8.default.join(
+        root,
+        ".claude",
+        "skills",
+        "vite-mcp-next",
+        "SKILL.md"
+      ),
+      targetName: "Claude Code skill"
+    },
+    {
+      entryPath: import_node_path8.default.join(root, ".cursor"),
+      filePath: import_node_path8.default.join(root, ".cursor", "rules", "vite-mcp-next.mdc"),
+      targetName: "Cursor rule"
+    }
+  ];
+}
+async function createSkillConfigJobs(descriptors, content) {
+  const jobs = [];
+  for (const descriptor of descriptors) {
+    if (await hasDirectoryEntry(descriptor.entryPath)) {
+      jobs.push(
+        writeGeneratedTextFile({
+          filePath: descriptor.filePath,
+          content,
+          targetName: descriptor.targetName
+        })
+      );
+    }
+  }
+  return jobs;
+}
+async function readPackagedSkillContent(root) {
+  const candidates = getPackagedSkillCandidates(root);
+  for (const candidate of candidates) {
+    try {
+      return await import_promises6.default.readFile(candidate, "utf-8");
+    } catch (error) {
+      if (isNodeError5(error) && error.code === "ENOENT") {
+        continue;
+      }
+      throw error;
+    }
+  }
+  throw new Error(
+    `Cannot find packaged vite-mcp-next skill at ${candidates.join(", ")}`
+  );
+}
+async function safelyReadPackagedSkillContent(root) {
+  try {
+    return await readPackagedSkillContent(root);
+  } catch (error) {
+    console.warn(
+      `[vite-plugin-vue-mcp-next] Failed to read packaged AI skill: ${formatError5(error)}`
+    );
+    return void 0;
+  }
+}
+function getPackagedSkillCandidates(root) {
+  return [
+    import_node_path8.default.resolve(root, "node_modules", PACKAGE_NAME, PACKAGED_SKILL_PATH),
+    import_node_path8.default.resolve(process.cwd(), "node_modules", PACKAGE_NAME, PACKAGED_SKILL_PATH),
+    import_node_path8.default.resolve(process.cwd(), PACKAGED_SKILL_PATH)
+  ];
+}
+async function hasDirectoryEntry(entryPath) {
+  try {
+    const stat = await import_promises6.default.stat(entryPath);
+    return stat.isDirectory();
+  } catch (error) {
+    if (isNodeError5(error) && error.code === "ENOENT") {
+      return false;
+    }
+    console.warn(
+      `[vite-plugin-vue-mcp-next] Failed to inspect skill config entry at ${entryPath}: ${formatError5(error)}`
+    );
+    return false;
+  }
+}
+function formatError5(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function isNodeError5(error) {
+  return error instanceof Error && "code" in error;
+}
+
 // src/plugin/createPlugin.ts
 var import_vite_dev_rpc = require("vite-dev-rpc");
 function vueMcpNext(userOptions = {}) {
@@ -2087,6 +2303,7 @@ function vueMcpNext(userOptions = {}) {
         options.mcpClients,
         userOptions
       );
+      await updateSkillConfigs(root, options.skill);
       if (options.printUrl) {
         setTimeout(() => {
           console.log(`  \u279C  MCP:     SSE server is running at ${mcpSseUrl}`);