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

package/dist/index.d.cts

@@ -33,6 +33,8 @@ interface VueMcpNextOptions {
     readonly updateCursorMcpJson?: boolean | CursorMcpConfig;
     /** 是否写入常见 AI 客户端的项目级 MCP 配置；默认按项目已有客户端入口自动探测。 */
     readonly mcpClients?: McpClientConfigOptions;
+    /** AI 使用指南自动安装配置，用于让 AI 客户端知道何时以及如何使用本 MCP。 */
+    readonly skill?: SkillConfigOptions;
     /** 非 HTML 入口的运行时脚本注入点，用于兼容不直接使用 `index.html` 的项目。 */
     readonly appendTo?: string | RegExp;
     /** 通用 DevTools 能力配置；Vue 专属能力不受该配置影响，始终走 Vue Runtime Bridge。 */
@@ -77,6 +79,16 @@ interface McpClientConfigOptions {
     /** MCP 客户端中展示的服务名，同一项目存在多个 MCP 服务时用于避免冲突。 */
     readonly serverName?: string;
 }
+/**
+ * AI 使用指南自动安装配置。
+ *
+ * 该配置只影响项目级 skill/rule 文件写入，不影响 MCP 服务是否启动；
+ * 独立开关可以让不希望插件修改 AI 客户端上下文的项目完全关闭自动安装。
+ */
+interface SkillConfigOptions {
+    /** 是否在 Vite dev server 启动时自动安装 AI 使用指南，默认开启。 */
+    readonly autoConfig?: boolean;
+}
 /**
  * 通用 DevTools 能力的运行模式。
  *
@@ -320,6 +332,8 @@ interface ResolvedVueMcpNextOptions {
     readonly updateCursorMcpJson: Required<CursorMcpConfig>;
     /** 已规范化的多客户端 MCP 配置写入策略，内部写入器只读取该对象。 */
     readonly mcpClients: Required<McpClientConfigOptions>;
+    /** 已补齐默认值的 AI 使用指南自动安装配置。 */
+    readonly skill: Required<SkillConfigOptions>;
     /** 非 HTML 入口注入点，未配置时 HTML 注入路径生效。 */
     readonly appendTo?: string | RegExp;
     /** 已补齐默认值的通用 DevTools 配置。 */
@@ -569,4 +583,4 @@ interface VueRuntimeRpc {
  */
 declare function vueMcpNext(userOptions?: VueMcpNextOptions): Plugin;
 
-export { type CdpOptions, type ConsoleOptions, type ConsoleRecord, type CursorMcpConfig, type DomOptions, type EvaluateOptions, type McpClientConfigOptions, type NetworkOptions, type NetworkRecord, type PageTarget, type ResolvedVueMcpNextOptions, type RuntimeMode, type RuntimeOptions, type VueMcpNextContext, type VueMcpNextOptions, vueMcpNext as default, vueMcpNext };
+export { type CdpOptions, type ConsoleOptions, type ConsoleRecord, type CursorMcpConfig, type DomOptions, type EvaluateOptions, type McpClientConfigOptions, type NetworkOptions, type NetworkRecord, type PageTarget, type ResolvedVueMcpNextOptions, type RuntimeMode, type RuntimeOptions, type SkillConfigOptions, type VueMcpNextContext, type VueMcpNextOptions, vueMcpNext as default, vueMcpNext };

package/dist/index.d.ts

@@ -33,6 +33,8 @@ interface VueMcpNextOptions {
     readonly updateCursorMcpJson?: boolean | CursorMcpConfig;
     /** 是否写入常见 AI 客户端的项目级 MCP 配置；默认按项目已有客户端入口自动探测。 */
     readonly mcpClients?: McpClientConfigOptions;
+    /** AI 使用指南自动安装配置，用于让 AI 客户端知道何时以及如何使用本 MCP。 */
+    readonly skill?: SkillConfigOptions;
     /** 非 HTML 入口的运行时脚本注入点，用于兼容不直接使用 `index.html` 的项目。 */
     readonly appendTo?: string | RegExp;
     /** 通用 DevTools 能力配置；Vue 专属能力不受该配置影响，始终走 Vue Runtime Bridge。 */
@@ -77,6 +79,16 @@ interface McpClientConfigOptions {
     /** MCP 客户端中展示的服务名，同一项目存在多个 MCP 服务时用于避免冲突。 */
     readonly serverName?: string;
 }
+/**
+ * AI 使用指南自动安装配置。
+ *
+ * 该配置只影响项目级 skill/rule 文件写入，不影响 MCP 服务是否启动；
+ * 独立开关可以让不希望插件修改 AI 客户端上下文的项目完全关闭自动安装。
+ */
+interface SkillConfigOptions {
+    /** 是否在 Vite dev server 启动时自动安装 AI 使用指南，默认开启。 */
+    readonly autoConfig?: boolean;
+}
 /**
  * 通用 DevTools 能力的运行模式。
  *
@@ -320,6 +332,8 @@ interface ResolvedVueMcpNextOptions {
     readonly updateCursorMcpJson: Required<CursorMcpConfig>;
     /** 已规范化的多客户端 MCP 配置写入策略，内部写入器只读取该对象。 */
     readonly mcpClients: Required<McpClientConfigOptions>;
+    /** 已补齐默认值的 AI 使用指南自动安装配置。 */
+    readonly skill: Required<SkillConfigOptions>;
     /** 非 HTML 入口注入点，未配置时 HTML 注入路径生效。 */
     readonly appendTo?: string | RegExp;
     /** 已补齐默认值的通用 DevTools 配置。 */
@@ -569,4 +583,4 @@ interface VueRuntimeRpc {
  */
 declare function vueMcpNext(userOptions?: VueMcpNextOptions): Plugin;
 
-export { type CdpOptions, type ConsoleOptions, type ConsoleRecord, type CursorMcpConfig, type DomOptions, type EvaluateOptions, type McpClientConfigOptions, type NetworkOptions, type NetworkRecord, type PageTarget, type ResolvedVueMcpNextOptions, type RuntimeMode, type RuntimeOptions, type VueMcpNextContext, type VueMcpNextOptions, vueMcpNext as default, vueMcpNext };
+export { type CdpOptions, type ConsoleOptions, type ConsoleRecord, type CursorMcpConfig, type DomOptions, type EvaluateOptions, type McpClientConfigOptions, type NetworkOptions, type NetworkRecord, type PageTarget, type ResolvedVueMcpNextOptions, type RuntimeMode, type RuntimeOptions, type SkillConfigOptions, type VueMcpNextContext, type VueMcpNextOptions, vueMcpNext as default, vueMcpNext };

package/dist/index.js

@@ -44,7 +44,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,
@@ -61,6 +62,9 @@ var DEFAULT_OPTIONS = {
     trae: true,
     serverName: DEFAULT_MCP_CLIENT_SERVER_NAME
   },
+  skill: {
+    autoConfig: true
+  },
   runtime: {
     mode: "auto",
     evaluate: {
@@ -118,6 +122,10 @@ function mergeOptions(options = {}) {
     ...options,
     updateCursorMcpJson: cursorConfig,
     mcpClients,
+    skill: {
+      ...DEFAULT_OPTIONS.skill,
+      ...options.skill
+    },
     runtime: {
       ...DEFAULT_OPTIONS.runtime,
       ...options.runtime,
@@ -1146,13 +1154,13 @@ function registerVueTools(server, ctx) {
         valueType: z7.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
       });
@@ -1754,10 +1762,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}`;
 }
@@ -1766,25 +1782,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 fs2.readFile(filePath, "utf-8");
@@ -1826,18 +1864,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 fs3.mkdir(path4.dirname(options.configPath), { recursive: true });
-    await fs3.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 fs3.mkdir(path4.dirname(configPath), { recursive: true });
+  await fs3.writeFile(configPath, `${JSON.stringify(config, null, 2)}
+`);
+}
 async function readJsonConfig(configPath) {
   const raw = await readOptionalTextFile2(configPath);
   if (!raw.trim()) {
@@ -1873,76 +1931,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: path5.join(root, ".cursor"),
-    entryKind: "directory",
-    userOptions
-  })) {
-    jobs.push(
-      updateJsonMcpClientConfig({
+  const legacyServerNames = getLegacyServerNames(serverName);
+  const descriptors = [
+    {
+      root,
+      clientName: "cursor",
+      enabled: options.cursor,
+      entryPath: path5.join(root, ".cursor"),
+      entryKind: "directory",
+      userOptions,
+      createJob: () => updateJsonMcpClientConfig({
         clientName: "Cursor",
         configPath: path5.join(root, ".cursor", "mcp.json"),
         mcpUrl: sseUrl,
-        serverName
+        serverName,
+        legacyServerNames
       })
-    );
-  }
-  if (await shouldUpdateClientConfig({
-    root,
-    clientName: "codex",
-    enabled: options.codex,
-    entryPath: path5.join(root, ".codex"),
-    entryKind: "directory",
-    userOptions
-  })) {
-    jobs.push(
-      updateCodexMcpClientConfig({
+    },
+    {
+      root,
+      clientName: "codex",
+      enabled: options.codex,
+      entryPath: path5.join(root, ".codex"),
+      entryKind: "directory",
+      userOptions,
+      createJob: () => updateCodexMcpClientConfig({
         configPath: path5.join(root, ".codex", "config.toml"),
         mcpUrl: streamableHttpUrl,
-        serverName
+        serverName,
+        legacyServerNames
       })
-    );
-  }
-  if (await shouldUpdateClientConfig({
-    root,
-    clientName: "claudeCode",
-    enabled: options.claudeCode,
-    entryPath: path5.join(root, ".mcp.json"),
-    entryKind: "file",
-    userOptions
-  })) {
-    jobs.push(
-      updateJsonMcpClientConfig({
+    },
+    {
+      root,
+      clientName: "claudeCode",
+      enabled: options.claudeCode,
+      entryPath: path5.join(root, ".mcp.json"),
+      entryKind: "file",
+      userOptions,
+      createJob: () => updateJsonMcpClientConfig({
         clientName: "Claude Code",
         configPath: path5.join(root, ".mcp.json"),
         mcpUrl: sseUrl,
-        serverName
+        serverName,
+        legacyServerNames
       })
-    );
-  }
-  if (await shouldUpdateClientConfig({
-    root,
-    clientName: "trae",
-    enabled: options.trae,
-    entryPath: path5.join(root, ".trae"),
-    entryKind: "directory",
-    userOptions
-  })) {
-    jobs.push(
-      updateJsonMcpClientConfig({
+    },
+    {
+      root,
+      clientName: "trae",
+      enabled: options.trae,
+      entryPath: path5.join(root, ".trae"),
+      entryKind: "directory",
+      userOptions,
+      createJob: () => updateJsonMcpClientConfig({
         clientName: "Trae",
         configPath: path5.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;
@@ -1979,6 +2044,157 @@ function isNodeError3(error) {
   return error instanceof Error && "code" in error;
 }
 
+// src/plugin/skillConfig/index.ts
+import fs6 from "fs/promises";
+import path7 from "path";
+
+// src/plugin/skillConfig/writers.ts
+import fs5 from "fs/promises";
+import path6 from "path";
+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 fs5.mkdir(path6.dirname(options.filePath), { recursive: true });
+    await fs5.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 fs5.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 = path7.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: path7.join(root, ".codex"),
+      filePath: path7.join(root, ".codex", "skills", "vite-mcp-next", "SKILL.md"),
+      targetName: "Codex skill"
+    },
+    {
+      entryPath: path7.join(root, ".claude"),
+      filePath: path7.join(
+        root,
+        ".claude",
+        "skills",
+        "vite-mcp-next",
+        "SKILL.md"
+      ),
+      targetName: "Claude Code skill"
+    },
+    {
+      entryPath: path7.join(root, ".cursor"),
+      filePath: path7.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 fs6.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 [
+    path7.resolve(root, "node_modules", PACKAGE_NAME, PACKAGED_SKILL_PATH),
+    path7.resolve(process.cwd(), "node_modules", PACKAGE_NAME, PACKAGED_SKILL_PATH),
+    path7.resolve(process.cwd(), PACKAGED_SKILL_PATH)
+  ];
+}
+async function hasDirectoryEntry(entryPath) {
+  try {
+    const stat = await fs6.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
 import { createRPCServer } from "vite-dev-rpc";
 function vueMcpNext(userOptions = {}) {
@@ -2050,6 +2266,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}`);