@creatoria/miniapp-mcp 0.1.3 → 0.2.2

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

@@ -1,8 +1,8 @@
-下面是一套从架构设计到可跑通代码的完整方案：将微信小程序官方自动化能力（miniprogram-automator）封装为 MCP（Model Context Protocol） 服务，参考 playwright-mcp 的“以工具集为中心”的方式，对外暴露“打开项目、页面操作、断言、截图、网络桩、录制/回放”等工具，让 AI+MCP 可以用自然语言驱动端到端自动化测试。
+下面是一套从架构设计到可跑通代码的完整方案：将微信小程序官方自动化能力（miniprogram-automator）封装为 MCP（Model Context Protocol） 服务，采用“以工具集为中心”的方式，对外暴露“打开项目、页面操作、断言、截图、网络桩、录制/回放”等工具，让 AI+MCP 可以用自然语言驱动端到端自动化测试。
 
 要点先看
 	•	小程序自动化的底座：微信开发者工具 + miniprogram-automator（JS版官方SDK，提供 MiniProgram / Page / Element 操作、reLaunch、$ 选择器、tap、callWxMethod 等）  
-	•	MCP 形态：使用 TypeScript MCP SDK（@modelcontextprotocol/sdk）实现一组“工具”，与 playwright-mcp 思路一致（定义 tool 列表、JSON Schema 入参、幂等返回）  
+	•	MCP 形态：使用 TypeScript MCP SDK（@modelcontextprotocol/sdk）实现一组“工具”，定义 tool 列表、JSON Schema 入参、幂等返回  
 	•	运行前提：在微信开发者工具中开启 CLI/HTTP 调用，并用 cli 可执行程序打开自动化端口（Windows cli.bat / macOS cli）  
 
 ⸻
@@ -22,14 +22,14 @@
 
 为什么选这个组合？
 	•	miniprogram-automator 是官方 JS 自动化 SDK，抽象了 MiniProgram / Page / Element 能力（选择器/事件/属性/数据/注入代码/调用 wx.* 接口）；它通过 IDE 的自动化接口工作（要求 IDE 开启服务端口）  。
-	•	MCP 让这些能力以 标准化的工具 形式暴露，便于被各种 LLM/Agent 主机消费；playwright-mcp 已证明这种“把浏览器自动化封成工具”的设计成熟可行，我们沿用其“工具即原子动作”的模式  。
+	•	MCP 让这些能力以 标准化的工具 形式暴露，便于被各种 LLM/Agent 主机消费；这种“工具即原子动作”的模式已经在浏览器自动化场景被验证成熟，我们沿用相同理念  。
 	•	TypeScript MCP SDK 提供服务端脚手架、工具注册与校验、传输层（stdio/SSE），生态资料充足  。
 
 ⸻
 
 二、工具（tools）设计
 
-对齐 playwright-mcp 的“细粒度工具 + 结构化入参 + 结构化输出”哲学，避免 LLM 需要长上下文记忆状态。  
+遵循“细粒度工具 + 结构化入参 + 结构化输出”的设计哲学，避免 LLM 需要长上下文记忆状态。  
 
 会话与上下文
 	•	每个 MCP 连接（host→server）对应一个 Session，服务端为之维护：
@@ -340,9 +340,9 @@ await server.connect(transport);
 
 ⸻
 
-六、对标 playwright-mcp 的“面向 AI 的工程化增强”
+六、面向 AI 的工程化增强
 
-playwright-mcp 暴露了辅助调试、可视化/快照、可复用脚本生成等工具；我们可在小程序端做同等增强。 
+成熟的浏览器自动化平台普遍提供辅助调试、可视化/快照、可复用脚本生成等工具；我们可在小程序端做同等增强。 
 
 	•	稳定选择器约定：在 WXML 增加 data-testid，MCP 工具优先按 [data-testid="xxx"] 定位，减少脆弱性。
 	•	结构化页面快照：额外提供 snapshot_page 工具：返回页面节点树（tag/class/id/text/children），让 AI 不依赖截图理解页面语义。
@@ -374,7 +374,7 @@ playwright-mcp 暴露了辅助调试、可视化/快照、可复用脚本生成
 
 九、下一步增强路线图（建议）
 	1.	更丰富的工具面板：fill、scroll_into_view、longpress、drag、toast_detect、modal_action、storage_get/set/clear。
-	2.	可视化调试器：模仿 playwright-mcp 的“可视化节点树/截图”，帮助 AI 选择选择器。 
+	2.	可视化调试器：提供节点树/截图，帮助 AI 选择选择器。 
 	3.	测试报告与覆盖率：统一产物（JSON + HTML），并与需求/缺陷系统对接。
 	4.	多会话/多项目并行：Session 隔离 + 资源配额。
 	5.	与 mpx e2e 或 Minium 互补：对复杂 Mock/Hook 用 Minium（Python/JS 版本，兼容三端），MCP 作为编排层。 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@creatoria/miniapp-mcp",
-  "version": "0.1.3",
+  "version": "0.2.2",
   "description": "MCP server for WeChat Mini Program automation using miniprogram-automator",
   "type": "module",
   "packageManager": "pnpm@9.0.0",
@@ -47,6 +47,7 @@
     "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",
+    "generate:schemas": "tsx scripts/generate-tool-schemas.ts",
     "prepare": "husky install"
   },
   "keywords": [
@@ -79,7 +80,8 @@
     "ts-jest": "^29.1.5",
     "ts-node": "^10.9.2",
     "tsx": "^4.20.6",
-    "typescript": "^5.5.2"
+    "typescript": "^5.5.2",
+    "zod-to-json-schema": "^3.22.4"
   },
   "engines": {
     "node": ">=18.0.0"

package/docs/SIMPLE_USAGE.md

@@ -1,210 +0,0 @@
-# 极简使用方式
-
-## 🎯 像 Playwright MCP 一样简单
-
-### 1. Claude Desktop 配置（推荐）
-
-**只需要这一行配置：**
-
-```json
-{
-  "mcpServers": {
-    "miniprogram": {
-      "command": "npx",
-      "args": ["-y", "@creatoria/miniapp-mcp"]
-    }
-  }
-}
-```
-
-**就这样！** 🎉
-
-### 2. 它会自动做什么？
-
-✅ **自动检测项目路径**
-- 当前目录有 `project.config.json` 或 `app.json`？使用当前目录
-- 没有？检查 `dist/`, `build/`, `miniprogram/`, `src/` 子目录
-- 找到了？自动使用
-
-✅ **自动使用默认配置**
-- CLI 路径：`/Applications/wechatwebdevtools.app/Contents/MacOS/cli` (macOS)
-- 端口：`9420`
-- 功能：全部启用
-
-✅ **环境变量覆盖**（可选）
-```bash
-export MCP_PROJECT_PATH=/path/to/your/miniprogram
-export MCP_PORT=9421
-```
-
-✅ **配置文件覆盖**（可选）
-项目根目录放 `.mcp.json`：
-```json
-{
-  "projectPath": "./dist",
-  "port": 9420
-}
-```
-
----
-
-## 📋 三种使用场景
-
-### 场景 1: 零配置（项目根目录有小程序）
-
-```
-my-project/
-├── project.config.json    ← 自动检测到这个
-├── app.json
-└── pages/
-```
-
-**Claude Desktop 配置：**
-```json
-{
-  "mcpServers": {
-    "miniprogram": {
-      "command": "npx",
-      "args": ["-y", "@creatoria/miniapp-mcp"]
-    }
-  }
-}
-```
-
-在 `my-project/` 目录下打开 Claude Desktop，它会自动找到小程序。
-
----
-
-### 场景 2: 小程序在子目录
-
-```
-my-project/
-├── dist/
-│   ├── project.config.json    ← 自动检测到这个
-│   └── app.json
-└── src/
-```
-
-**Claude Desktop 配置：**
-```json
-{
-  "mcpServers": {
-    "miniprogram": {
-      "command": "npx",
-      "args": ["-y", "@creatoria/miniapp-mcp"]
-    }
-  }
-}
-```
-
-在 `my-project/` 目录下打开 Claude Desktop，它会自动找到 `dist/` 目录。
-
----
-
-### 场景 3: 手动指定路径
-
-```json
-{
-  "mcpServers": {
-    "miniprogram": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@creatoria/miniapp-mcp",
-        "--project-path",
-        "./custom-path"
-      ]
-    }
-  }
-}
-```
-
----
-
-## 🆚 对比
-
-### ❌ 以前（复杂）
-```json
-{
-  "mcpServers": {
-    "miniprogram": {
-      "command": "miniprogram-mcp",
-      "args": [
-        "--project-path", "/absolute/long/path/to/project",
-        "--cli-path", "/Applications/wechatwebdevtools.app/Contents/MacOS/cli",
-        "--port", "9420",
-        "--capabilities", "core,assert,snapshot"
-      ]
-    }
-  }
-}
-```
-
-### ✅ 现在（极简）
-```json
-{
-  "mcpServers": {
-    "miniprogram": {
-      "command": "npx",
-      "args": ["-y", "@creatoria/miniapp-mcp"]
-    }
-  }
-}
-```
-
----
-
-## 🧪 本地测试（npm link）
-
-```bash
-# 1. 在项目目录执行
-npm link
-
-# 2. 使用相同的简洁配置
-{
-  "mcpServers": {
-    "miniprogram": {
-      "command": "miniprogram-mcp"
-    }
-  }
-}
-```
-
----
-
-## 🔍 调试信息
-
-当 MCP 服务器启动时，会在 stderr 输出：
-
-```
-Auto-detected project path: /path/to/your/miniprogram
-Loaded config from: /path/to/.mcp.json
-Loaded config from environment: projectPath, port
-```
-
-查看 Claude Desktop 日志：
-- macOS: `~/Library/Logs/Claude/`
-- 找到最新的 mcp-server-miniprogram.log
-
----
-
-## ✨ 发布后的最终体验
-
-**发布到 npm 后，用户只需：**
-
-1. 在小程序项目根目录创建 Claude Desktop 配置
-2. 复制这个配置：
-   ```json
-   {
-     "mcpServers": {
-       "miniprogram": {
-         "command": "npx",
-         "args": ["-y", "@creatoria/miniapp-mcp"]
-       }
-     }
-   }
-   ```
-3. 重启 Claude Desktop
-4. 完成！🎉
-
-**就像 Playwright MCP 一样简单！**