Weapp Agent MCP

weapp-agent-mcp

Agent-first MCP server for WeChat Mini Program debugging, automation, and lightweight regression testing.

面向 agent 的微信小程序 MCP 服务 — 让 Claude Code / Cursor / Codex 等 agent 在对话中直接驱动微信开发者工具完成调试、UI 操作、页面巡检与轻量测试。

📖 Changelog · 🐛 Issues · 💬 Discussions

weapp-agent-mcp 是一个面向 agent 的微信小程序 MCP 服务，基于 miniprogram-automator 封装微信开发者工具自动化能力，用于页面调试、元素操作、轻量回归测试与恢复友好型排查。

它适合：

• agent 主开发 / 主调试
• 串行截图与页面巡检
• 轻量 scenario / report
• 基于稳定 selector 的自动化验证

它当前不应被宣传为：

• 并发截图通道
• 超长高压全链路回归引擎

文档导航

更完整的文档入口见 docs/README.md。

为什么选 weapp-agent-mcp

如果你已经在用 Claude Code / Cursor / Codex 等 agent 写小程序，传统的 miniprogram-automator 脚本式调用不够顺手 — 你得让 agent 写 node 脚本、跑、读输出、再调整。本项目把自动化能力直接暴露成 agent 工具调用，让 agent 在对话中可以：

• 🤖 零脚本调试 — 直接调用 mp_screenshot / page_snapshot / element_tap，不必中转脚本
• 🔁 恢复友好 — 内置 mp_healthCheck / mp_recoverConnection，断连后能自愈，长会话更稳
• 📋 轻量回归 — mp_runScenario + mp_generateScenarioReport 产出 markdown 报告，适合给 PR / oncall 用
• 🎯 稳定 selector 优先 — 设计上鼓励 qa-* 命名锚点，减少 UI 改版后的脚本碎裂

适用 / 不适用对比

前置要求

• 已安装微信开发者工具，支持命令行访问（cli / cli.bat）
• 本地已安装 Node.js 18+ 和 npm
• 有可以在开发者工具中打开的小程序项目
• 已在微信开发者工具中开启自动化测试与服务端口

快速开始

方式一：通过 npm / npx 接入（推荐，普通用户默认这样用）

不需要先把仓库拉到本地，也不需要自己手动构建 dist。只要本机有 Node.js 和 npx，就可以直接在 MCP 客户端里这样配置：

{

"mcpServers": { "weapp-agent-mcp": { "command": "npx", "args": [ "-y", "@chaixueyuan/weapp-agent-mcp" ], "env": { "WEAPP_WS_ENDPOINT": "ws://localhost:9420" } } } }

如果你希望在 Claude 等客户端里用更短的别名，也可以把 MCP server key 命名为 weapp-dev，但发布包名和服务名以 weapp-agent-mcp 为准。

可选：如果你习惯全局安装，也可以先执行：

npm install -g @chaixueyuan/weapp-agent-mcp

然后把 MCP 配置改成：

{

"mcpServers": { "weapp-agent-mcp": { "command": "weapp-agent-mcp", "env": { "WEAPP_WS_ENDPOINT": "ws://localhost:9420" } } } }

方式二：本地源码构建接入（仅开发者 / 贡献者）

只有在以下场景才需要这样用：

• 你正在开发这个仓库本身
• 你要调试尚未发布到 npm 的改动
• 你要在本地修改源码后立刻验证

npm install

npm run build node dist/index.js

{

"mcpServers": { "weapp-agent-mcp": { "command": "node", "args": [ "/absolute/path/to/weapp-agent-mcp/dist/index.js" ], "env": { "WEAPP_WS_ENDPOINT": "ws://localhost:9420" } } } }

本地开发

npm install

npm run dev

重要边界

• mp_screenshot 当前按串行单通道能力设计，不支持并发压测
• 复杂业务链建议拆成多个短 scenario，而不是一个超长 scenario
• page_snapshot、mp_screenshot、长 mp_runScenario 在连续复杂操作后可能超时
• 若出现连续失败，先运行 mp_healthCheck；仅当 needsRecovery=true 时执行 mp_recoverConnection
• 稳定性高度依赖业务页面提供清晰的 qa-* selector 或其他稳定定位锚点

MCP 客户端集成

Claude Code 自动批准工具权限

由于使用 Claude Code 调用 MCP 工具时，会触发工具调用权限申请，此时可能会丢失 MCP 与微信开发者工具的连接状态，由于获取控制台输出高度依赖连接状态，此时会无法连贯的获取输出日志，所以建议手动添加权限：

在项目目录下创建 .claude/settings.local.json 文件，或在已有文件添加以下内容后即可免确认直接调用工具，或者根据需要添加您允许免确认调用的工具：

{

"permissions": { "allow": [ "mcpweapp-agent-mcpmp_diagnoseConnection", "mcpweapp-agent-mcpmp_ensureConnection", "mcpweapp-agent-mcpmp_navigate", "mcpweapp-agent-mcpmp_screenshot", "mcpweapp-agent-mcpmp_callWx", "mcpweapp-agent-mcpmp_evaluate", "mcpweapp-agent-mcpmp_pollUntil", "mcpweapp-agent-mcpmp_getLogs", "mcpweapp-agent-mcpmp_runScenario", "mcpweapp-agent-mcpmp_generateScenarioReport", "mcpweapp-agent-mcpmp_currentPage", "mcpweapp-agent-mcpmp_healthCheck", "mcpweapp-agent-mcpmp_recoverConnection", "mcpweapp-agent-mcpmp_listProjects", "mcpweapp-agent-mcpmp_setDefaultProject", "mcpweapp-agent-mcppage_getElement", "mcpweapp-agent-mcppage_getElements", "mcpweapp-agent-mcppage_waitElement", "mcpweapp-agent-mcppage_waitElementGone", "mcpweapp-agent-mcppage_waitRoute", "mcpweapp-agent-mcppage_waitTimeout", "mcpweapp-agent-mcppage_expectRoute", "mcpweapp-agent-mcppage_expectVisible", "mcpweapp-agent-mcppage_expectElementText", "mcpweapp-agent-mcppage_expectCount", "mcpweapp-agent-mcppage_expectData", "mcpweapp-agent-mcppage_snapshot", "mcpweapp-agent-mcppage_getData", "mcpweapp-agent-mcppage_setData", "mcpweapp-agent-mcppage_callMethod", "mcpweapp-agent-mcpelement_tap", "mcpweapp-agent-mcpelement_touch", "mcpweapp-agent-mcpelement_swipe", "mcpweapp-agent-mcpelement_input", "mcpweapp-agent-mcpelement_callMethod", "mcpweapp-agent-mcpelement_getData", "mcpweapp-agent-mcpelement_setData", "mcpweapp-agent-mcpelement_getInnerElement", "mcpweapp-agent-mcpelement_getInnerElements", "mcpweapp-agent-mcpelement_getWxml", "mcpweapp-agent-mcpelement_getStyles", "mcpweapp-agent-mcpelement_scrollTo", "mcpweapp-agent-mcpelement_getAttributes", "mcpweapp-agent-mcpelement_getBoundingClientRect" ] } }

注意： 工具名称格式为 mcp__<服务器名称>__<工具名称>，请确保服务器名称与您的 MCP 配置中的名称一致。

可选：人工预启动微信开发者工具

默认流程无需 agent 手动执行 CLI：直接调用 mp_ensureConnection，本地端口未监听且允许 AutoLaunch 时，server 会自行执行 cli auto。下面的命令只用于人工排障，或显式设置 WEAPP_AUTOLAUNCH=false 后由用户自行预启动开发者工具。

💡 在开始之前：

1. 打开微信开发者工具
2. 进入 设置 → 安全设置 → 服务端口
3. 开启 "HTTP 调试" 和 "自动化测试"

人工使用命令行启动

使用命令行启动微信开发者工具并自动开启 WebSocket 服务：

macOS：

/Applications/wechatwebdevtools.app/Contents/MacOS/cli auto --project /path/to/your/project --auto-port 9420

Windows：

"C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat" auto --project C:\path\to\your\project --auto-port 9420

其中：

• --project 指定小程序项目目录路径（请替换为实际的项目路径）
• --auto-port 指定 automation websocket 端口（默认 9420）。注意：这个 flag 在 cli auto --help 输出里看不到，但官方 miniprogram-automator SDK 内部一直用，是有效参数

⚠️ 警告 由于沙箱机制，部分客户端不允许 MCP 访问项目目录以外的微信开发者工具的 cli，所以这里只介绍了使用 WebSocket 服务

环境变量配置

通过环境变量控制自动化工具如何连接到微信开发者工具：

注意： launch / 本地自动拉起最终都需要可解析的小程序项目目录。可通过 connection.projectPath、WEAPP_PROJECT_PATH、mp_setDefaultProject 的持久化默认值、最近项目或当前工作目录提供；显式设置的默认项目不会被后续活动会话覆盖。

工具调用可以通过 connection 对象覆盖这些默认值中的大部分。

连接模式说明

模式 A：连接已有 IDE（connect）

适用于你已经手动打开微信开发者工具，并且已经在 设置 → 安全设置 → 服务端口 中开启了自动化。

{

"mcpServers": { "weapp-agent-mcp": { "command": "npx", "args": ["-y", "@chaixueyuan/weapp-agent-mcp"], "env": { "WEAPP_WS_ENDPOINT": "ws://localhost:9420" } } } }

这个模式下：

• WEAPP_WS_ENDPOINT 必须指向可被 miniprogram-automator.connect() 连接的 websocket endpoint
• 不要把 IDE HTTP 端口误当成 websocket 端口
• 不要手动执行 cli open、cli auto、cli quit
• 默认直接调用 mp_ensureConnection；它会优先复用现有会话，并在本地端口未监听时按配置自愈
• 只想只读探测，或 ensure / recovery 已失败时，再调用 mp_diagnoseConnection
• 不要自动切端口；如需禁止 ensure 自动执行 cli auto，设置 WEAPP_AUTOLAUNCH=false

模式 B：由 MCP 拉起 IDE（launch）

适用于当前未打开 IDE，需要 MCP 通过 CLI 启动项目。

{

"mcpServers": { "weapp-agent-mcp": { "command": "npx", "args": ["-y", "@chaixueyuan/weapp-agent-mcp"], "env": { "WEAPP_AUTOMATOR_MODE": "launch", "WEAPP_PROJECT_PATH": "/path/to/project", "WECHAT_DEVTOOLS_CLI_PATH": "/Applications/wechatwebdevtools.app/Contents/MacOS/cli", "WEAPP_DEVTOOLS_PORT": "9420" } } } }

这个模式下：

• WEAPP_DEVTOOLS_PORT 表示 cli auto --auto-port 使用的自动化端口
• 只有在明确使用 launch 模式时，MCP 才应该启动 IDE
• 如果检测到同项目已经有 IDE 实例在运行，应停止自动 launch 并返回诊断信息
• connect 与 launch 两种模式不要混用

--port 和 --auto-port 的区别

微信开发者工具至少涉及两类端口：

• --port：IDE HTTP 服务端口
• --auto-port：自动化 websocket 端口

这两个端口不能混用。WEAPP_WS_ENDPOINT 必须指向自动化 websocket 端口，而不是 IDE HTTP 端口。

Codex / agent 使用规则

当用户已经打开微信开发者工具时：

1. 不要执行 cli open
2. 不要执行 cli quit
3. 默认直接调用 mp_ensureConnection，它会优先复用现有自动化会话
4. mp_diagnoseConnection 仅用于只读探测，或在 ensure / recovery 失败后补充诊断
5. 不要手动切端口；本地自动化端口未监听且 WEAPP_AUTOLAUNCH 未禁用时，mp_ensureConnection 可自行执行 cli auto
6. 不允许自动拉起时设置 WEAPP_AUTOLAUNCH=false

可用工具

应用工具（Application Tools）

• mp_diagnoseConnection – 只诊断当前连接目标，不启动 IDE、不修改项目状态
• mp_ensureConnection – 确保自动化会话就绪，是连接链路默认入口；失败后再按返回指引诊断或恢复
• mp_navigate – 在小程序内导航，支持 navigateTo、redirectTo、reLaunch、switchTab 或 navigateBack
• mp_screenshot – 捕获屏幕截图并返回（或保存到磁盘）
• mp_callWx – 调用微信小程序 API 方法（如 wx.showToast）
• mp_evaluate – 向小程序 AppService 注入并执行函数代码，适合做显式运行时读取
• mp_pollUntil – 轮询 AppService 条件，命中后可执行动作并采集前后状态快照
• mp_getLogs – 获取小程序控制台日志，支持按 type、contains、since、limit 过滤，并返回日志监听状态（如 listenerAttached、lastLogAt、sessionId）
• mp_runScenario – 按顺序执行一组最小测试步骤，当前支持 navigate、tap、input、waitRoute、expect*、snapshot、getLogs、screenshot
• mp_generateScenarioReport – 执行 scenario 并输出 markdown 报告；可选写入 outputPath，适合产出轻量回归测试记录，并可引用截图路径
• mp_currentPage – 获取当前页面信息（路径、查询参数、尺寸和滚动位置），withData 为 true 时额外返回页面数据
• mp_healthCheck – 聚合连接、页面、项目路径和日志监听状态，判断当前是否健康、是否需要恢复
• mp_recoverConnection – 按标准顺序执行恢复，并返回恢复动作、恢复前后状态与最新 health
• mp_listProjects – 列出微信开发者工具中的最近项目，方便选择项目目录
• mp_setDefaultProject – 设置默认的小程序项目路径，设置后下次连接会自动使用该项目

页面工具（Page Tools）

• page_getElement – 通过选择器获取页面元素，返回元素摘要信息（tagName、text、value、size、offset）；设置 withWxml: true 可额外返回完整 outerWxml；支持 [index=N] 语法选择第 N 个元素
• page_getElements – 通过选择器获取页面元素数组，返回每个元素的摘要信息；limit 默认/最大 100；设置 withWxml: true 可额外返回每个元素的完整 outerWxml；支持 [index=N] 语法
• page_waitElement – 等待元素出现在页面上（⚠️ 不适用于自定义组件内部元素）；支持 [index=N] 语法；增加超时和重试间隔参数
• page_waitElementGone – 等待元素从页面上消失；支持 [index=N] 语法；支持超时和重试间隔参数
• page_waitRoute – 等待当前页面路径变为指定值，适合确认导航真正完成；支持超时和重试间隔参数
• page_waitTimeout – 等待指定的毫秒数
• page_expectRoute – 断言当前页面路径是否等于预期值
• page_expectVisible – 断言页面上是否存在可定位到的元素；支持 [index=N] 语法
• page_expectElementText – 断言元素文本是否等于或包含预期值；支持 [index=N] 语法
• page_expectCount – 断言页面上匹配选择器的元素数量是否等于预期值
• page_expectData – 断