@weapp-vite/mcp 1.1.1 → 1.2.0

package/README.md

@@ -43,6 +43,8 @@ await handle.close?.()
 - `search_source_code`: 在包源码中检索关键词
 - `run_package_script`: 在指定包目录执行 `pnpm run <script>`
 - `run_weapp_vite_cli`: 执行 `node packages/weapp-vite/bin/weapp-vite.js ...`
+- `take_weapp_screenshot`: 面向“小程序截图 / 页面快照”语义，执行 `weapp-vite screenshot --json`
+- `compare_weapp_screenshot`: 面向“截图对比 / diff / baseline / 视觉回归”语义，执行 `weapp-vite compare --json`
 - `run_repo_command`: 执行仓库级命令（`pnpm/node/git/rg`）
 
 ## 主要 Resources

package/dist/index.d.mts

@@ -6,16 +6,19 @@ declare const EXPOSED_PACKAGES: {
     readonly 'weapp-vite': {
         readonly id: "weapp-vite";
         readonly label: "weapp-vite";
+        readonly packageName: "weapp-vite";
         readonly relativePath: string;
     };
     readonly wevu: {
         readonly id: "wevu";
         readonly label: "wevu";
+        readonly packageName: "wevu";
         readonly relativePath: string;
     };
     readonly 'wevu-compiler': {
         readonly id: "wevu-compiler";
         readonly label: "wevu-compiler";
+        readonly packageName: "@wevu/compiler";
         readonly relativePath: string;
     };
 };
@@ -26,7 +29,7 @@ declare const DEFAULT_MAX_FILE_CHARS = 80000;
 declare const DEFAULT_MAX_RESULTS = 200;
 declare const SKIPPED_DIR_NAMES: Set<string>;
 
-interface ExposedPackageSummary {
+interface ResolvedExposedPackage {
     id: ExposedPackageId;
     label: string;
     packageName: string;
@@ -38,9 +41,14 @@ interface ExposedPackageSummary {
         readme?: string;
         changelog?: string;
     };
+    sourceRoot?: string;
+    cliPath?: string;
+}
+
+interface ExposedPackageSummary extends ResolvedExposedPackage {
 }
 declare function loadPackageSummary(workspaceRoot: string, id: ExposedPackageId): Promise<ExposedPackageSummary>;
-declare function loadExposedCatalog(workspaceRoot: string): Promise<ExposedPackageSummary[]>;
+declare function loadExposedCatalog(workspaceRoot: string): Promise<ResolvedExposedPackage[]>;
 
 interface CommandResult {
     command: string;

package/dist/index.d.ts

@@ -6,16 +6,19 @@ declare const EXPOSED_PACKAGES: {
     readonly 'weapp-vite': {
         readonly id: "weapp-vite";
         readonly label: "weapp-vite";
+        readonly packageName: "weapp-vite";
         readonly relativePath: string;
     };
     readonly wevu: {
         readonly id: "wevu";
         readonly label: "wevu";
+        readonly packageName: "wevu";
         readonly relativePath: string;
     };
     readonly 'wevu-compiler': {
         readonly id: "wevu-compiler";
         readonly label: "wevu-compiler";
+        readonly packageName: "@wevu/compiler";
         readonly relativePath: string;
     };
 };
@@ -26,7 +29,7 @@ declare const DEFAULT_MAX_FILE_CHARS = 80000;
 declare const DEFAULT_MAX_RESULTS = 200;
 declare const SKIPPED_DIR_NAMES: Set<string>;
 
-interface ExposedPackageSummary {
+interface ResolvedExposedPackage {
     id: ExposedPackageId;
     label: string;
     packageName: string;
@@ -38,9 +41,14 @@ interface ExposedPackageSummary {
         readme?: string;
         changelog?: string;
     };
+    sourceRoot?: string;
+    cliPath?: string;
+}
+
+interface ExposedPackageSummary extends ResolvedExposedPackage {
 }
 declare function loadPackageSummary(workspaceRoot: string, id: ExposedPackageId): Promise<ExposedPackageSummary>;
-declare function loadExposedCatalog(workspaceRoot: string): Promise<ExposedPackageSummary[]>;
+declare function loadExposedCatalog(workspaceRoot: string): Promise<ResolvedExposedPackage[]>;
 
 interface CommandResult {
     command: string;

package/dist/index.mjs

@@ -1,6 +1,7 @@
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import fs$1 from 'node:fs/promises';
+import { createRequire } from 'node:module';
 import path from 'node:path';
 import fs from 'node:fs';
 import { spawn } from 'node:child_process';
@@ -17,17 +18,20 @@ const EXPOSED_PACKAGES = {
   "weapp-vite": {
     id: "weapp-vite",
     label: "weapp-vite",
+    packageName: "weapp-vite",
     relativePath: path.join("packages", "weapp-vite")
   },
   "wevu": {
     id: "wevu",
     label: "wevu",
-    relativePath: path.join("packages", "wevu")
+    packageName: "wevu",
+    relativePath: path.join("packages-runtime", "wevu")
   },
   "wevu-compiler": {
     id: "wevu-compiler",
     label: "wevu-compiler",
-    relativePath: path.join("packages", "wevu-compiler")
+    packageName: "@wevu/compiler",
+    relativePath: path.join("packages-runtime", "wevu-compiler")
   }
 };
 const DEFAULT_TIMEOUT_MS = 12e4;
@@ -80,10 +84,6 @@ function resolveSubPath(root, relativePath) {
   return assertInsideRoot(root, path.resolve(root, relativePath));
 }
 
-async function readJsonFile(filePath) {
-  const content = await fs$1.readFile(filePath, "utf8");
-  return JSON.parse(content);
-}
 async function pathExists(filePath) {
   try {
     await fs$1.access(filePath);
@@ -92,17 +92,40 @@ async function pathExists(filePath) {
     return false;
   }
 }
-async function loadPackageSummary(workspaceRoot, id) {
+async function toWorkspaceRelativePath(workspaceRoot, absolutePath) {
+  const [realWorkspaceRoot, realAbsolutePath] = await Promise.all([
+    fs$1.realpath(workspaceRoot),
+    fs$1.realpath(absolutePath)
+  ]);
+  const relativePath = path.relative(realWorkspaceRoot, realAbsolutePath);
+  if (!relativePath || relativePath === ".") {
+    return ".";
+  }
+  return relativePath;
+}
+async function readPackageJson(filePath) {
+  const content = await fs$1.readFile(filePath, "utf8");
+  return JSON.parse(content);
+}
+function createWorkspaceRequire(workspaceRoot) {
+  return createRequire(path.join(workspaceRoot, "__weapp_vite_mcp__.cjs"));
+}
+async function resolveMonorepoPackage(workspaceRoot, id) {
   const config = EXPOSED_PACKAGES[id];
   const absolutePath = assertInsideRoot(workspaceRoot, path.join(workspaceRoot, config.relativePath));
   const packageJsonPath = path.join(absolutePath, "package.json");
-  const packageJson = await readJsonFile(packageJsonPath);
+  if (!await pathExists(packageJsonPath)) {
+    return void 0;
+  }
+  const packageJson = await readPackageJson(packageJsonPath);
   const readmePath = path.join(absolutePath, "README.md");
   const changelogPath = path.join(absolutePath, "CHANGELOG.md");
+  const sourceRoot = await pathExists(path.join(absolutePath, "src")) ? absolutePath : void 0;
+  const cliPath = id === "weapp-vite" ? await pathExists(path.join(absolutePath, "bin", "weapp-vite.js")) ? path.join(absolutePath, "bin", "weapp-vite.js") : void 0 : void 0;
   return {
     id,
     label: config.label,
-    packageName: packageJson.name ?? config.label,
+    packageName: packageJson.name ?? config.packageName,
     version: packageJson.version ?? "0.0.0",
     absolutePath,
     relativePath: config.relativePath,
@@ -110,14 +133,73 @@ async function loadPackageSummary(workspaceRoot, id) {
     docs: {
       readme: await pathExists(readmePath) ? readmePath : void 0,
       changelog: await pathExists(changelogPath) ? changelogPath : void 0
+    },
+    sourceRoot,
+    cliPath
+  };
+}
+async function resolveInstalledPackage(workspaceRoot, id) {
+  const config = EXPOSED_PACKAGES[id];
+  const workspaceRequire = createWorkspaceRequire(workspaceRoot);
+  let packageJsonPath;
+  try {
+    packageJsonPath = workspaceRequire.resolve(`${config.packageName}/package.json`);
+  } catch {
+    return void 0;
+  }
+  const absolutePath = path.dirname(packageJsonPath);
+  const relativePath = await toWorkspaceRelativePath(workspaceRoot, absolutePath);
+  const packageJson = await readPackageJson(packageJsonPath);
+  const docsRoot = path.join(absolutePath, "dist", "docs");
+  const installedReadmePath = path.join(docsRoot, "README.md");
+  const installedChangelogPath = path.join(docsRoot, "CHANGELOG.md");
+  const sourceRoot = await pathExists(path.join(absolutePath, "src")) ? absolutePath : void 0;
+  let cliPath;
+  if (id === "weapp-vite") {
+    const binEntry = typeof packageJson.bin === "string" ? packageJson.bin : packageJson.bin?.["weapp-vite"];
+    if (typeof binEntry === "string" && binEntry.trim()) {
+      const resolvedCliPath = path.resolve(absolutePath, binEntry);
+      if (await pathExists(resolvedCliPath)) {
+        cliPath = resolvedCliPath;
+      }
     }
+  }
+  return {
+    id,
+    label: config.label,
+    packageName: packageJson.name ?? config.packageName,
+    version: packageJson.version ?? "0.0.0",
+    absolutePath,
+    relativePath,
+    scripts: Object.keys(packageJson.scripts ?? {}),
+    docs: {
+      readme: await pathExists(installedReadmePath) ? installedReadmePath : void 0,
+      changelog: await pathExists(installedChangelogPath) ? installedChangelogPath : void 0
+    },
+    sourceRoot,
+    cliPath
   };
 }
-async function loadExposedCatalog(workspaceRoot) {
-  const summaries = await Promise.all(
-    Object.keys(EXPOSED_PACKAGES).map((id) => loadPackageSummary(workspaceRoot, id))
+async function resolveExposedPackage(workspaceRoot, id) {
+  return await resolveMonorepoPackage(workspaceRoot, id) ?? await resolveInstalledPackage(workspaceRoot, id) ?? Promise.reject(new Error(`\u672A\u627E\u5230\u66B4\u9732\u5305\uFF1A${id}`));
+}
+async function resolveExposedPackages(workspaceRoot) {
+  const resolved = await Promise.allSettled(
+    Object.keys(EXPOSED_PACKAGES).map((id) => resolveExposedPackage(workspaceRoot, id))
   );
-  return summaries.sort((a, b) => a.id.localeCompare(b.id));
+  return resolved.flatMap((result) => {
+    if (result.status === "fulfilled") {
+      return [result.value];
+    }
+    return [];
+  }).sort((a, b) => a.id.localeCompare(b.id));
+}
+
+async function loadPackageSummary(workspaceRoot, id) {
+  return resolveExposedPackage(workspaceRoot, id);
+}
+async function loadExposedCatalog(workspaceRoot) {
+  return resolveExposedPackages(workspaceRoot);
 }
 
 const ALLOWED_COMMANDS = /* @__PURE__ */ new Set([
@@ -318,8 +400,12 @@ function toToolError(error) {
 
 const packageIds = Object.keys(EXPOSED_PACKAGES);
 const packageIdSchema = z.enum(packageIds);
-function resolvePackageRoot(workspaceRoot, packageId) {
-  return assertInsideRoot(workspaceRoot, path.join(workspaceRoot, EXPOSED_PACKAGES[packageId].relativePath));
+async function resolvePackageRoot(workspaceRoot, packageId) {
+  const resolved = await resolveExposedPackage(workspaceRoot, packageId);
+  if (!resolved.sourceRoot) {
+    throw new Error(`\u5F53\u524D\u5DE5\u4F5C\u533A\u4E2D\u7684 ${packageId} \u4E0D\u5305\u542B\u6E90\u7801\u76EE\u5F55\uFF0C\u8BF7\u6539\u4E3A\u4F18\u5148\u8BFB\u53D6\u672C\u5730\u968F\u5305\u6587\u6863\u3002`);
+  }
+  return assertInsideRoot(workspaceRoot, resolved.sourceRoot);
 }
 function toDocsUri(packageId, fileName) {
   return `weapp-vite://docs/${packageId}/${fileName}`;
@@ -327,6 +413,25 @@ function toDocsUri(packageId, fileName) {
 async function readTextFile(filePath) {
   return fs$1.readFile(filePath, "utf8");
 }
+async function runWeappViteCliTool(workspaceRoot, input) {
+  const cliPath = (await resolveExposedPackage(workspaceRoot, "weapp-vite")).cliPath;
+  if (!cliPath) {
+    throw new Error("\u5F53\u524D\u5DE5\u4F5C\u533A\u4E2D\u7684 weapp-vite \u672A\u66B4\u9732 CLI \u5165\u53E3");
+  }
+  const finalArgs = [cliPath, input.subCommand];
+  if (input.projectPath) {
+    finalArgs.push(resolveSubPath(workspaceRoot, input.projectPath));
+  }
+  if (input.platform) {
+    finalArgs.push("--platform", input.platform);
+  }
+  if (Array.isArray(input.args) && input.args.length > 0) {
+    finalArgs.push(...input.args);
+  }
+  return runCommand(workspaceRoot, "node", finalArgs, {
+    timeoutMs: input.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  });
+}
 async function createWeappViteMcpServer(options) {
   const workspaceRoot = resolveWorkspaceRoot(options?.workspaceRoot);
   const server = new McpServer({
@@ -357,7 +462,7 @@ async function createWeappViteMcpServer(options) {
     }
   }, async ({ packageId, directory, maxResults }) => {
     try {
-      const packageRoot = resolvePackageRoot(workspaceRoot, packageId);
+      const packageRoot = await resolvePackageRoot(workspaceRoot, packageId);
       const files = await listFilesInDirectory(packageRoot, directory ?? "src", maxResults ?? DEFAULT_MAX_RESULTS);
       return toToolResult({
         packageId,
@@ -381,7 +486,7 @@ async function createWeappViteMcpServer(options) {
     }
   }, async ({ packageId, filePath, startLine, endLine, maxChars }) => {
     try {
-      const packageRoot = resolvePackageRoot(workspaceRoot, packageId);
+      const packageRoot = await resolvePackageRoot(workspaceRoot, packageId);
       const { filePath: absolutePath, content } = await readFileContent(packageRoot, filePath, {
         startLine,
         endLine,
@@ -417,7 +522,7 @@ async function createWeappViteMcpServer(options) {
         if (allMatches.length >= safeMax) {
           break;
         }
-        const packageRoot = resolvePackageRoot(workspaceRoot, id);
+        const packageRoot = await resolvePackageRoot(workspaceRoot, id);
         const matches = await searchTextInDirectory(packageRoot, query, {
           relativeDirectory: directory ?? "src",
           maxResults: safeMax - allMatches.length
@@ -447,9 +552,9 @@ async function createWeappViteMcpServer(options) {
     }
   }, async ({ packageId, script, args, timeoutMs }) => {
     try {
-      const cwdRelative = EXPOSED_PACKAGES[packageId].relativePath;
+      const resolvedPackage = await resolveExposedPackage(workspaceRoot, packageId);
       const result = await runCommand(workspaceRoot, "pnpm", ["run", script, ...args ?? []], {
-        cwdRelative,
+        cwdRelative: resolvedPackage.relativePath,
         timeoutMs: timeoutMs ?? DEFAULT_TIMEOUT_MS
       });
       return toToolResult(result);
@@ -469,21 +574,103 @@ async function createWeappViteMcpServer(options) {
     }
   }, async ({ subCommand, projectPath, platform, args, timeoutMs }) => {
     try {
-      const cliPath = path.join("packages", "weapp-vite", "bin", "weapp-vite.js");
-      const finalArgs = [cliPath, subCommand];
-      if (projectPath) {
-        finalArgs.push(resolveSubPath(workspaceRoot, projectPath));
+      const result = await runWeappViteCliTool(workspaceRoot, {
+        subCommand,
+        projectPath,
+        platform,
+        args,
+        timeoutMs
+      });
+      return toToolResult(result);
+    } catch (error) {
+      return toToolError(error);
+    }
+  });
+  server.registerTool("take_weapp_screenshot", {
+    title: "Take Weapp Screenshot",
+    description: "\u5F53\u7528\u6237\u63D0\u5230\u622A\u56FE\u3001\u9875\u9762\u5FEB\u7167\u3001\u8FD0\u884C\u65F6\u622A\u56FE\u65F6\uFF0C\u4F18\u5148\u8C03\u7528\u6B64\u5DE5\u5177\u6267\u884C weapp-vite screenshot",
+    inputSchema: {
+      projectPath: z.string().describe("\u76F8\u5BF9 workspace \u6839\u8DEF\u5F84\uFF0C\u901A\u5E38\u662F dist/build/mp-weixin \u6216\u5177\u4F53\u5C0F\u7A0B\u5E8F\u9879\u76EE\u76EE\u5F55"),
+      page: z.string().optional().describe("\u622A\u56FE\u524D\u5148\u8DF3\u8F6C\u7684\u5C0F\u7A0B\u5E8F\u9875\u9762\u8DEF\u5F84"),
+      outputPath: z.string().optional().describe("\u622A\u56FE\u8F93\u51FA\u8DEF\u5F84\uFF0C\u5EFA\u8BAE\u5199\u5165 .tmp/ \u6216\u5DE5\u4F5C\u533A\u76F8\u5BF9\u8DEF\u5F84"),
+      timeoutMs: z.number().int().positive().max(9e5).optional()
+    }
+  }, async ({ projectPath, page, outputPath, timeoutMs }) => {
+    try {
+      const args = ["--json"];
+      if (page) {
+        args.push("--page", page);
       }
-      if (platform) {
-        finalArgs.push("--platform", platform);
+      if (outputPath) {
+        args.push("--output", outputPath);
       }
-      if (Array.isArray(args) && args.length > 0) {
-        finalArgs.push(...args);
+      const result = await runWeappViteCliTool(workspaceRoot, {
+        subCommand: "screenshot",
+        projectPath,
+        args,
+        timeoutMs
+      });
+      return toToolResult({
+        ...result,
+        projectPath,
+        page: page ?? null,
+        outputPath: outputPath ?? null,
+        recommendedIntent: "screenshot"
+      });
+    } catch (error) {
+      return toToolError(error);
+    }
+  });
+  server.registerTool("compare_weapp_screenshot", {
+    title: "Compare Weapp Screenshot",
+    description: "\u5F53\u7528\u6237\u63D0\u5230\u622A\u56FE\u5BF9\u6BD4\u3001diff\u3001baseline\u3001\u89C6\u89C9\u56DE\u5F52\u3001\u50CF\u7D20\u5BF9\u6BD4\u65F6\uFF0C\u4F18\u5148\u8C03\u7528\u6B64\u5DE5\u5177\u6267\u884C weapp-vite compare",
+    inputSchema: {
+      projectPath: z.string().describe("\u76F8\u5BF9 workspace \u6839\u8DEF\u5F84\uFF0C\u901A\u5E38\u662F dist/build/mp-weixin \u6216\u5177\u4F53\u5C0F\u7A0B\u5E8F\u9879\u76EE\u76EE\u5F55"),
+      baselinePath: z.string().describe("\u76F8\u5BF9 workspace \u6839\u8DEF\u5F84\u7684 baseline \u56FE\u7247\u8DEF\u5F84"),
+      page: z.string().optional().describe("\u622A\u56FE\u5BF9\u6BD4\u524D\u5148\u8DF3\u8F6C\u7684\u5C0F\u7A0B\u5E8F\u9875\u9762\u8DEF\u5F84"),
+      currentOutputPath: z.string().optional().describe("\u5F53\u524D\u622A\u56FE\u8F93\u51FA\u8DEF\u5F84"),
+      diffOutputPath: z.string().optional().describe("diff \u56FE\u7247\u8F93\u51FA\u8DEF\u5F84"),
+      threshold: z.number().min(0).max(1).optional(),
+      maxDiffPixels: z.number().int().min(0).optional(),
+      maxDiffRatio: z.number().min(0).max(1).optional(),
+      timeoutMs: z.number().int().positive().max(9e5).optional()
+    }
+  }, async ({ projectPath, baselinePath, page, currentOutputPath, diffOutputPath, threshold, maxDiffPixels, maxDiffRatio, timeoutMs }) => {
+    try {
+      const args = ["--json", "--baseline", baselinePath];
+      if (page) {
+        args.push("--page", page);
       }
-      const result = await runCommand(workspaceRoot, "node", finalArgs, {
-        timeoutMs: timeoutMs ?? DEFAULT_TIMEOUT_MS
+      if (currentOutputPath) {
+        args.push("--current-output", currentOutputPath);
+      }
+      if (diffOutputPath) {
+        args.push("--diff-output", diffOutputPath);
+      }
+      if (threshold != null) {
+        args.push("--threshold", String(threshold));
+      }
+      if (maxDiffPixels != null) {
+        args.push("--max-diff-pixels", String(maxDiffPixels));
+      }
+      if (maxDiffRatio != null) {
+        args.push("--max-diff-ratio", String(maxDiffRatio));
+      }
+      const result = await runWeappViteCliTool(workspaceRoot, {
+        subCommand: "compare",
+        projectPath,
+        args,
+        timeoutMs
+      });
+      return toToolResult({
+        ...result,
+        projectPath,
+        baselinePath,
+        page: page ?? null,
+        currentOutputPath: currentOutputPath ?? null,
+        diffOutputPath: diffOutputPath ?? null,
+        recommendedIntent: "compare"
       });
-      return toToolResult(result);
     } catch (error) {
       return toToolError(error);
     }
@@ -575,7 +762,7 @@ async function createWeappViteMcpServer(options) {
       }]
     };
   });
-  const catalog = await loadExposedCatalog(workspaceRoot);
+  const catalog = await resolveExposedPackages(workspaceRoot);
   for (const summary of catalog) {
     if (summary.docs.readme) {
       const uri = toDocsUri(summary.id, "README.md");
@@ -619,7 +806,7 @@ async function createWeappViteMcpServer(options) {
         throw new Error(`\u672A\u77E5 package\uFF1A${packageId}`);
       }
       const relativePath = decodeURIComponent(String(variables.path ?? ""));
-      const packageRoot = resolvePackageRoot(workspaceRoot, packageId);
+      const packageRoot = await resolvePackageRoot(workspaceRoot, packageId);
       const { content } = await readFileContent(packageRoot, relativePath, {
         maxChars: DEFAULT_MAX_FILE_CHARS
       });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@weapp-vite/mcp",
   "type": "module",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "mcp",
   "author": "ice breaker <1324318532@qq.com>",
   "license": "ISC",
@@ -31,7 +31,7 @@
     "node": "^20.19.0 || >=22.12.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.3.6"
   },
   "scripts": {