Weapp Agent MCP server

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 操作、页面巡检与轻量测试。

<!-- TODO: 这里放一段 5-10 秒 demo GIF：agent 调用 mpscreenshot + pageexpectVisible 完成一次页面巡检。建议 ≤ 1.5MB，命名 docs/demo.gif -->

📖 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 在对话中可以：

• 🤖 零脚本调试 — 直接调用 mpscreenshot / pagesnapshot / element_tap，不必中转脚本
• 🔁 恢复友好 — 内置 mphealthCheck / mprecoverConnection，断连后能自愈，长会话更稳
• 📋 轻量回归 — mprunScenario + mpgenerateScenarioReport 产出 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
• pagesnapshot、mpscreenshot、长 mp_runScenario 在连续复杂操作后可能超时
• 若出现连续失败，先运行 mphealthCheck；仅当 needsRecovery=true 时执行 mprecoverConnection
• 稳定性高度依赖业务页面提供清晰的 qa-* selector 或其他稳定定位锚点

MCP 客户端集成

Claude Code 自动批准工具权限

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

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

Shortened. The full README is on GitHub.