@creatoria/miniapp-mcp 0.1.0

package/docs//347/254/254/344/270/200/347/211/210/346/234/254/346/226/271/346/241/210.md

@@ -0,0 +1,380 @@
+下面是一套从架构设计到可跑通代码的完整方案：将微信小程序官方自动化能力（miniprogram-automator）封装为 MCP（Model Context Protocol） 服务，参考 playwright-mcp 的“以工具集为中心”的方式，对外暴露“打开项目、页面操作、断言、截图、网络桩、录制/回放”等工具，让 AI+MCP 可以用自然语言驱动端到端自动化测试。
+
+要点先看
+	•	小程序自动化的底座：微信开发者工具 + miniprogram-automator（JS版官方SDK，提供 MiniProgram / Page / Element 操作、reLaunch、$ 选择器、tap、callWxMethod 等）  
+	•	MCP 形态：使用 TypeScript MCP SDK（@modelcontextprotocol/sdk）实现一组“工具”，与 playwright-mcp 思路一致（定义 tool 列表、JSON Schema 入参、幂等返回）  
+	•	运行前提：在微信开发者工具中开启 CLI/HTTP 调用，并用 cli 可执行程序打开自动化端口（Windows cli.bat / macOS cli）  
+
+⸻
+
+一、整体架构
+
+[AI 客户端（Claude / Cursor / 自研Agent）]
+                 │   （MCP 协议/stdio 或 SSE）
+                 ▼
+       [miniprogram-mcp 服务（Node / TS）]
+                 │     ├── 工具：launch、goto、tap、fill、assert、screenshot...
+                 │     └── 状态：每个会话的 IDE 进程、MiniProgram / Page 句柄
+                 ▼
+[微信开发者工具（开启 CLI/HTTP 端口）]  ←→ [小程序项目（本地）]
+                 │
+                 └── 使用 miniprogram-automator 与 IDE 自动化接口通讯
+
+为什么选这个组合？
+	•	miniprogram-automator 是官方 JS 自动化 SDK，抽象了 MiniProgram / Page / Element 能力（选择器/事件/属性/数据/注入代码/调用 wx.* 接口）；它通过 IDE 的自动化接口工作（要求 IDE 开启服务端口）  。
+	•	MCP 让这些能力以 标准化的工具 形式暴露，便于被各种 LLM/Agent 主机消费；playwright-mcp 已证明这种“把浏览器自动化封成工具”的设计成熟可行，我们沿用其“工具即原子动作”的模式  。
+	•	TypeScript MCP SDK 提供服务端脚手架、工具注册与校验、传输层（stdio/SSE），生态资料充足  。
+
+⸻
+
+二、工具（tools）设计
+
+对齐 playwright-mcp 的“细粒度工具 + 结构化入参 + 结构化输出”哲学，避免 LLM 需要长上下文记忆状态。  
+
+会话与上下文
+	•	每个 MCP 连接（host→server）对应一个 Session，服务端为之维护：
+	•	ide: 开发者工具进程/端口信息
+	•	miniProgram: automator.launch/connect() 的返回句柄
+	•	pages: 当前页面栈（miniProgram.currentPage() 等）
+	•	工具入参均显式传入关键参数（如 pagePath、selector），避免状态漂移。
+
+工具清单（核心）
+	1.	launch
+	•	输入：projectPath、cliPath?、autoPort?、headless?（仅控制 IDE 是否显示窗口）、udid?（真机调试用，留扩展）
+	•	效果：启动并连接 IDE 自动化端口，创建 miniProgram 句柄（automator.launch 或 connect）。
+	•	返回：sessionId、autoPort、idePid。
+	•	参考：automator.connect/launch、IDE 需开启 CLI/HTTP 调用  
+	2.	goto
+	•	输入：pagePath（如 /pages/index/index）、query?（对象或 a=1&b=2）、relaunch?（默认 true）
+	•	实现：miniProgram.reLaunch() 或 miniProgram.navigateTo() 后 page.waitFor()。
+	•	返回：pagePath、dataSnapshot（可选）、nodesSnapshot（可选）。
+	3.	query
+	•	输入：selector（CSS 风格 WXML 选择器，如 #loginBtn .primary）、all?
+	•	实现：page.$ / page.$$，读取基本属性（text、attr、rect、visible）。
+	•	返回：元素数组（handleId、text、attr、rect 等）。
+	•	参考：page.$ / element.attribute() / element.tap()  
+	4.	tap / longpress / scroll / input
+	•	输入：selector 或 handleId、text?、delta? 等
+	•	实现：element.tap()、element.longpress()、page.scroll()、element.input(text)（若不支持，退回 evaluate 设置值 + 触发 input 事件）。
+	•	返回：ok、afterSnapshot?。
+	5.	assert
+	•	输入：kind（textEquals / exists / visible / dataEquals / urlIncludes）、selector?、expected?、pageDataPath?
+	•	实现：读取元素/页面数据后断言，返回布尔与差异。
+	•	返回：pass、actual、message?。
+	6.	screenshot
+	•	输入：path?（相对工作目录）、fullPage?
+	•	实现：page.screenshot() 或 miniProgram.screenshot()（若可用）；否则走 IDE 截图接口（降级策略）。
+	•	返回：文件相对路径。
+	7.	callWx / inject
+	•	输入：api（如 login）、args；或注入一段 JS 到 AppService 运行
+	•	实现：miniProgram.callWxMethod(api, args)、miniProgram.evaluate(fn)（名称以官方能力为准）  
+	•	用途：登录、设置存储、打桩等。
+	8.	record_actions / replay_actions
+	•	输入：start/stop；或传入已录制 actions[]（tap/scroll/input 带时间戳）
+	•	实现：IDE 提供的录制转自动化脚本能力（如有）或在 MCP 层记录工具调用序列并回放；社区实践显示可依据“用户行为 JSON”回放到 automator 里执行  。
+	9.	network_mock（可选扩展）
+	•	方案：通过 inject 在 AppService 层重写 wx.request 以返回固定数据；或接入三方封装（如 mpx e2e 的 mock 能力）  。
+
+⸻
+
+三、参考实现（可直接落地）
+
+下面是一个 最小可用 的 MCP 服务实现（TypeScript）。目录结构：
+
+miniprogram-mcp/
+├─ src/
+│  ├─ server.ts
+│  ├─ tools.ts
+│  └─ state.ts
+├─ package.json
+├─ tsconfig.json
+└─ README.md
+
+package.json
+
+{
+  "name": "miniprogram-mcp",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "bin": {
+    "miniprogram-mcp": "./dist/server.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node ./dist/server.js",
+    "dev": "ts-node src/server.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.3.0",
+    "miniprogram-automator": "^0.12.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "ts-node": "^10.9.2",
+    "typescript": "^5.5.4"
+  }
+}
+
+MCP TS SDK 与 miniprogram-automator 版本可按需调整；miniprogram-automator最新稳定版在 0.12.1 左右（历史版本列表可见 UNPKG） 。
+
+src/state.ts
+
+import type { MiniProgram } from 'miniprogram-automator';
+
+export type SessionState = {
+  miniProgram?: MiniProgram;
+  idePid?: number;
+  autoPort?: number;
+  projectPath?: string;
+};
+
+class Store {
+  private map = new Map<string, SessionState>();
+  get(id: string) {
+    if (!this.map.has(id)) this.map.set(id, {});
+    return this.map.get(id)!;
+  }
+  set(id: string, s: SessionState) {
+    this.map.set(id, s);
+  }
+  delete(id: string) {
+    this.map.delete(id);
+  }
+}
+
+export const sessions = new Store();
+
+src/tools.ts
+
+import { z } from 'zod';
+import automator from 'miniprogram-automator';
+import type { Tool } from '@modelcontextprotocol/sdk/types';
+import { sessions } from './state.js';
+
+const LaunchInput = z.object({
+  projectPath: z.string(),
+  cliPath: z.string().optional(),
+  autoPort: z.number().int().optional(),
+  headless: z.boolean().optional()
+});
+
+export const launch: Tool = {
+  name: 'launch',
+  description: '启动并连接小程序自动化（需开启IDE CLI/HTTP）',
+  inputSchema: LaunchInput,
+  async handler({ input, meta }) {
+    const { projectPath, cliPath, autoPort } = LaunchInput.parse(input);
+    const sessionId = meta?.connectionId ?? 'default';
+
+    // prefer launch(): 自动拉起并连接 IDE；如仅连接已有端口则用 connect()
+    const miniProgram = await automator.launch({
+      projectPath,
+      cliPath,
+      // autoPort 可不传由 SDK 分配；传入时需保证与 IDE 一致
+      // idePath/headless 等参数按需补充
+    });
+
+    const state = sessions.get(sessionId);
+    state.miniProgram = miniProgram;
+    state.projectPath = projectPath;
+
+    return {
+      sessionId,
+      projectPath
+    };
+  }
+};
+
+const GotoInput = z.object({
+  pagePath: z.string(),
+  query: z.union([z.string(), z.record(z.string())]).optional(),
+  relaunch: z.boolean().optional()
+});
+
+export const goto: Tool = {
+  name: 'goto',
+  description: '跳转到指定页面（默认使用 reLaunch）',
+  inputSchema: GotoInput,
+  async handler({ input, meta }) {
+    const { pagePath, query, relaunch = true } = GotoInput.parse(input);
+    const sessionId = meta?.connectionId ?? 'default';
+    const { miniProgram } = sessions.get(sessionId);
+    if (!miniProgram) throw new Error('not launched');
+
+    const full = typeof query === 'string' || !query
+      ? pagePath + (typeof query === 'string' ? `?${query}` : '')
+      : pagePath + '?' + new URLSearchParams(query).toString();
+
+    const page = relaunch
+      ? await miniProgram.reLaunch(full)
+      : await miniProgram.navigateTo(full);
+
+    await page.waitFor(500);
+    return { pagePath: full };
+  }
+};
+
+const QueryInput = z.object({
+  selector: z.string(),
+  all: z.boolean().optional()
+});
+export const query: Tool = {
+  name: 'query',
+  description: '查询元素并返回基础属性',
+  inputSchema: QueryInput,
+  async handler({ input, meta }) {
+    const { selector, all } = QueryInput.parse(input);
+    const sessionId = meta?.connectionId ?? 'default';
+    const { miniProgram } = sessions.get(sessionId);
+    if (!miniProgram) throw new Error('not launched');
+    const page = await miniProgram.currentPage();
+
+    const els = all ? await page.$$(selector) : [await page.$(selector)];
+    const items = [];
+    for (const el of els) {
+      if (!el) continue;
+      items.push({
+        text: await el.text(),
+        attr: await el.attribute('class'),
+        rect: await el.rect(),
+        exists: true
+      });
+    }
+    return { count: items.length, items };
+  }
+};
+
+const TapInput = z.object({ selector: z.string() });
+export const tap: Tool = {
+  name: 'tap',
+  description: '点击元素',
+  inputSchema: TapInput,
+  async handler({ input, meta }) {
+    const { selector } = TapInput.parse(input);
+    const sessionId = meta?.connectionId ?? 'default';
+    const { miniProgram } = sessions.get(sessionId);
+    if (!miniProgram) throw new Error('not launched');
+    const page = await miniProgram.currentPage();
+    const el = await page.$(selector);
+    if (!el) throw new Error(`selector not found: ${selector}`);
+    await el.tap();
+    await page.waitFor(200);
+    return { ok: true };
+  }
+};
+
+const CallWxInput = z.object({ api: z.string(), args: z.any().optional() });
+export const callWx: Tool = {
+  name: 'call_wx',
+  description: '调用 wx.* 接口（例如 login、setStorage 等）',
+  inputSchema: CallWxInput,
+  async handler({ input, meta }) {
+    const { api, args } = CallWxInput.parse(input);
+    const sessionId = meta?.connectionId ?? 'default';
+    const { miniProgram } = sessions.get(sessionId);
+    if (!miniProgram) throw new Error('not launched');
+
+    // 若 SDK 暴露 callWxMethod：
+    // @ts-ignore
+    const result = await miniProgram.callWxMethod?.(api, args);
+    return { result };
+  }
+};
+
+export const tools: Tool[] = [launch, goto, query, tap, callWx];
+
+以上用法与 miniprogram-automator README 示例一致（launch/connect、reLaunch、page.$、element.attribute/tap），可以在此基础上继续扩展（input/scroll/assert/screenshot/inject）。 
+
+src/server.ts
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { tools } from './tools.js';
+
+const server = new McpServer({
+  name: 'miniprogram-mcp',
+  version: '0.1.0'
+});
+
+for (const t of tools) server.tool(t);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+以上是 TS SDK 标准写法（注册工具 → 通过 stdio 暴露），与各类“MCP 入门”/Azure 示例一致。 
+
+⸻
+
+四、使用前的环境要求与关键设置
+	1.	安装微信开发者工具（Win/macOS），并在设置 → 安全设置中开启 CLI/HTTP 调用。
+	•	Windows 可执行：cli.bat（安装目录内）
+	•	macOS 可执行：/Applications/wechatwebdevtools.app/Contents/MacOS/cli
+	•	可用命令测试端口：cli.bat --auto <项目路径> --auto-port <端口>（Win；mac 路径同理）  
+	2.	安装 Node 与依赖：npm i @modelcontextprotocol/sdk miniprogram-automator zod。
+	3.	项目路径：保证 app.json 与页面路径正确；goto 工具里的 pagePath 如 /pages/index/index。
+	4.	版本注意：早期资料指出 IDE 需高于 v1.02.1906042 才支持自动化端口；按最新 IDE 版本一般已满足。 
+
+⸻
+
+五、从 AI 客户端驱动一次“可购物车流程”的示例
+
+以 Claude Desktop / MCP Inspector 或任意支持 MCP 的 Host 为例：
+	•	连接 miniprogram-mcp（stdio）。
+	•	让 AI 逐步调用工具：
+
+	1.	启动
+
+{"tool":"launch","input":{"projectPath":"/Users/me/app","cliPath":"/Applications/wechatwebdevtools.app/Contents/MacOS/cli"}}
+
+	2.	进首页
+
+{"tool":"goto","input":{"pagePath":"/pages/index/index"}}
+
+	3.	查找并点击“加入购物车”
+
+{"tool":"query","input":{"selector":".sku-card .add-to-cart"}}
+{"tool":"tap","input":{"selector":".sku-card .add-to-cart"}}
+
+	4.	断言购物车角标变化（可在 assert 工具中比较元素 text 或页面 data）
+
+⸻
+
+六、对标 playwright-mcp 的“面向 AI 的工程化增强”
+
+playwright-mcp 暴露了辅助调试、可视化/快照、可复用脚本生成等工具；我们可在小程序端做同等增强。 
+
+	•	稳定选择器约定：在 WXML 增加 data-testid，MCP 工具优先按 [data-testid="xxx"] 定位，减少脆弱性。
+	•	结构化页面快照：额外提供 snapshot_page 工具：返回页面节点树（tag/class/id/text/children），让 AI 不依赖截图理解页面语义。
+	•	录制/回放：IDE/SDK 不直接提供录制？可在 MCP 层记录调用序列（或参考社区“用户行为 JSON 回放”实践）并存储为可重放脚本。 
+	•	网络桩/时间冻结：inject 重写 wx.request、Date.now，使用例可重复。可参考 mpx e2e 的封装理念。 
+	•	错误诊断：每次失败自动截屏 + 导出 page.data + 节点树。
+	•	安全与资源：限制工具写文件目录；对 inject 白名单（禁止访问敏感 API）。
+
+⸻
+
+七、CI 集成与“开发-提测-上线”流水线
+	•	本地/CI 环境：IDE 官方主要支持 Windows/macOS；CI 建议使用这两个 Runner。Linux 端执行 IDE 存在兼容性障碍，应谨慎评估。
+	•	流水线：
+	1.	miniprogram-ci 做编译/预览/上传（非 UI 自动化）  
+	2.	启动带桌面的 Runner（macOS/Windows），拉起 IDE，运行 miniprogram-mcp
+	3.	用“AI 驱动的自然语言测试”或“固定脚本回放”跑回归
+	4.	产出报告：整合截图、断言日志与用例覆盖（可上报到测试平台）
+
+⸻
+
+八、常见坑与策略
+	•	CLI/HTTP 未启用：launch/connect 失败；请在 IDE 安全设置中开启（上文已列路径）。 
+	•	页面未稳定：需要 waitFor / wait_for_selector 辅助工具（可扩展）避免竞态。
+	•	真机差异：miniprogram-automator 主要驱动 IDE 模拟器；涉及端能力/授权的场景优先用 call_wx + 模拟数据，或结合真机远程调试流程（文档有“Remote Debugging”指引）。 
+	•	选择器脆弱：落地时务必引入 data-testid 规范。
+	•	登录：通过 call_wx('login') 拿 code，或注入自定义 token（测试环境后端配合）。 
+
+⸻
+
+九、下一步增强路线图（建议）
+	1.	更丰富的工具面板：fill、scroll_into_view、longpress、drag、toast_detect、modal_action、storage_get/set/clear。
+	2.	可视化调试器：模仿 playwright-mcp 的“可视化节点树/截图”，帮助 AI 选择选择器。 
+	3.	测试报告与覆盖率：统一产物（JSON + HTML），并与需求/缺陷系统对接。
+	4.	多会话/多项目并行：Session 隔离 + 资源配额。
+	5.	与 mpx e2e 或 Minium 互补：对复杂 Mock/Hook 用 Minium（Python/JS 版本，兼容三端），MCP 作为编排层。 

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@creatoria/miniapp-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for WeChat Mini Program automation using miniprogram-automator",
+  "type": "module",
+  "packageManager": "pnpm@9.0.0",
+  "main": "dist/index.js",
+  "bin": {
+    "miniprogram-mcp": "dist/cli.js",
+    "creatoria-miniapp-mcp": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE",
+    "docs/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rn1024/creatoria-miniapp-mcp.git"
+  },
+  "homepage": "https://github.com/rn1024/creatoria-miniapp-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/rn1024/creatoria-miniapp-mcp/issues"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/server.js",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:unit": "jest tests/unit",
+    "test:integration": "jest tests/integration --runInBand",
+    "lint": "eslint . --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "update-readme": "tsx scripts/update-readme.ts",
+    "smoke-test": "bash scripts/smoke-test.sh",
+    "release:patch": "bash scripts/release.sh patch",
+    "release:minor": "bash scripts/release.sh minor",
+    "release:major": "bash scripts/release.sh major",
+    "release:prerelease": "bash scripts/release.sh prerelease",
+    "simulate:ai": "tsx tests/simulation/ai-mcp-simulator.ts",
+    "simulate:quick": "tsx tests/simulation/quick-ai-test.ts",
+    "simulate:scenario": "tsx tests/simulation/scenario-runner.ts",
+    "prepare": "husky install"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "wechat",
+    "miniprogram",
+    "automation",
+    "testing",
+    "miniprogram-automator"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "commander": "^12.1.0",
+    "miniprogram-automator": "^0.12.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.14.9",
+    "@typescript-eslint/eslint-plugin": "^7.13.1",
+    "@typescript-eslint/parser": "^7.13.1",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "husky": "^9.0.11",
+    "jest": "^29.7.0",
+    "prettier": "^3.3.2",
+    "ts-jest": "^29.1.5",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.20.6",
+    "typescript": "^5.5.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}