微信开发者工具自动化 MCP 服务器

强大的微信小程序自动化测试解决方案，基于 Model Context Protocol 实现

✨ 核心特性

• 🚀 31个专业工具（full profile） - 覆盖连接、查询、交互、断言、导航、调试等完整测试场景

• 🤖 智能连接 - 支持 auto/launch/connect 三种模式，自动端口检测，无需手动配置

• 🔍 自动网络监控 - 连接时自动启动，实时拦截 wx.request/uploadFile/downloadFile

• ✅ 完整断言体系 - 3类断言工具（assert_text/assert_attribute/assert_state），覆盖文本、属性与状态校验

• 📸 丰富调试能力 - 支持页面截图、Console 监听、网络请求追踪、诊断工具

• 🏗️ 模块化架构 - 基于 chrome-devtools-mcp 架构模式，易于扩展和维护

• 🧩 可配置工具暴露 - 默认 core profile（20个工具），支持按类别开启 Console/Network/Debug

• 🧭 可靠元素定位 - 使用 opaque ref 与显式 target，通过页面 revision 和指纹校验拒绝误操作

• 📐 结构化协议结果 - 全部工具公开 outputSchema，成功与失败都返回版本化 structuredContent

• ⚡ 轻量协议启动 - tools/list 使用构建期静态 descriptor，工具实现和 automator 在首次有效调用时懒加载

• 🧪 全面测试覆盖 - 单元测试 + 集成测试，测试覆盖率 >80%

Related MCP server: weapp-agent-mcp

📦 安装

方式一：使用 npx（推荐）

无需安装，直接使用，npx 会自动下载并运行最新版本：

# 无需执行任何安装命令
# 直接在 Claude Desktop 配置中使用即可

方式二：全局安装

如果需要频繁使用或离线使用，可以全局安装：

npm install -g weixin-devtools-mcp

方式三：开发者安装（从源码）

如果需要修改源代码或参与开发：

# 克隆项目
git clone https://github.com/wooter-s/weixin-devtools-mcp.git
cd weixin-devtools-mcp

# 安装依赖
npm install

# 构建项目
npm run build

⚙️ 配置

在 Claude Desktop 配置文件中添加 MCP 服务器：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

配置方式一：使用 npx（推荐）

优点：无需安装，自动使用最新版本

{
  "mcpServers": {
    "weixin-devtools-mcp": {
      "command": "npx",
      "args": ["-y", "weixin-devtools-mcp"]
    }
  }
}

配置方式二：全局安装后使用

如果已全局安装，可以直接使用命令名：

{
  "mcpServers": {
    "weixin-devtools-mcp": {
      "command": "weixin-devtools-mcp"
    }
  }
}

配置方式三：开发者本地路径

如果从源码安装，推荐通过 Node.js 启动构建产物（跨平台）：

{
  "mcpServers": {
    "weixin-devtools-mcp": {
      "command": "node",
      "args": ["/path/to/weixin-devtools-mcp/build/server.js"]
    }
  }
}

工具 Profile 配置（v0.4+）

服务器支持按 profile 控制暴露工具，降低默认工具数量：

• core（默认）：20 个核心自动化工具

• full：31 个完整工具

• minimal：10 个最小工具

也支持按类别增减：

• --enable-categories=console,network,debug

• --disable-categories=console,network,debug,core

npx 配置示例（启用 full）：

{
  "mcpServers": {
    "weixin-devtools-mcp": {
      "command": "npx",
      "args": ["-y", "weixin-devtools-mcp", "--tools-profile=full"]
    }
  }
}

本地构建产物示例（在 core 基础上启用 network + debug）：

{
  "mcpServers": {
    "weixin-devtools-mcp": {
      "command": "node",
      "args": [
        "/path/to/weixin-devtools-mcp/build/server.js",
        "--enable-categories=network,debug"
      ]
    }
  }
}

🚀 快速开始

第一个自动化测试

// 1. 连接微信开发者工具（auto 策略）
connect_devtools({
  projectPath: "/path/to/your/miniprogram",
  strategy: "auto",
  verbose: true
})

// 2. 查找登录按钮，得到当前快照内的 opaque ref
const result = find_elements({
  locator: { kind: "testId", value: "login-btn" }
})

// 3. 点击登录按钮
click({ target: { kind: "ref", ref: result.data.elements[0].ref } })

// 4. 等待登录成功
wait_for({
  target: { kind: "selector", value: ".welcome-message" },
  timeout: 5000
})

// 5. 验证登录成功
assert_text({
  target: { kind: "selector", value: ".welcome-message" },
  text: "欢迎回来"
})

// 6. 获取页面截图（需在服务启动参数中启用 --enable-categories=debug）
screenshot({ path: "/tmp/login-success.png" })

🛠️ 功能概览

当前工具暴露采用 profile 机制：

• core（默认，20个）：

  • 连接/页面：connect_devtools、reconnect_devtools、disconnect_devtools、get_connection_status、get_current_page、get_page_snapshot、find_elements、wait_for

  • 交互：click、input_text、get_value、set_form_control

  • 断言：assert_text、assert_attribute、assert_state

  • 导航：navigate_to、navigate_back、switch_tab、relaunch

  • 脚本：evaluate_script

• 可选类别（默认关闭）：

  • console：list_console_messages、get_console_message

  • network：list_network_requests、get_network_request、stop_network_monitoring、clear_network_requests

  • debug：screenshot、diagnose_connection、check_environment、debug_page_elements、debug_connection_flow

• full profile：暴露全部 31 个工具。

💡 使用示例

示例 1：用户登录流程

// 连接到开发者工具
connect_devtools({
  projectPath: "/path/to/miniprogram",
  strategy: "auto"
})

// 输入用户名
input_text({
  target: { kind: "id", value: "username" },
  mode: "replace",
  text: "testuser"
})

// 输入密码
input_text({
  target: { kind: "id", value: "password" },
  mode: "replace",
  text: "password123"
})

// 点击登录按钮
click({ target: { kind: "selector", value: "button.login" } })

// 等待登录成功
wait_for({ target: { kind: "selector", value: ".welcome" }, timeout: 5000 })

// 验证欢迎消息
assert_text({
  target: { kind: "selector", value: ".welcome" },
  textContains: "欢迎"
})

// 检查网络请求（两阶段查询，需在服务启动参数中启用 --enable-categories=network）
const requests = list_network_requests({ urlPattern: "/api/login", successOnly: true })
get_network_request({ reqid: requests[0].reqid })

示例 2：表单填写和提交

// 填写文本输入框
input_text({ target: { kind: "id", value: "name" }, mode: "replace", text: "张三" })
input_text({ uid: "input#email", text: "zhangsan@example.com" })

// 选择下拉框
set_form_control({ target: { kind: "id", value: "city" }, value: "北京" })

// 切换开关
set_form_control({ target: { kind: "id", value: "agree" }, value: true })

// 设置滑块
set_form_control({ target: { kind: "id", value: "age" }, value: 25 })

// 提交表单
click({ target: { kind: "selector", value: "button.submit" } })

// 等待提交成功
wait_for({ target: { kind: "selector", value: ".success-toast" }, timeout: 3000 })

// 验证提交结果
assert_state({ target: { kind: "selector", value: ".success-toast" }, visible: true })
assert_text({ target: { kind: "selector", value: ".success-toast" }, text: "提交成功" })

// 截图保存结果
screenshot({ path: "/tmp/form-submit-success.png" })

📚 文档

• 📖 完整集成指南 - 详细的安装和配置步骤

• 🔧 页面工具 API - 页面查询和等待工具详细文档

• ✨ 最佳实践 - 编写高质量自动化测试的建议

• 🧪 测试指南 - 单元测试和集成测试说明

• 🏗️ 模块化架构 - 项目架构设计文档

• 📝 示例：登录自动化 - 登录流程自动化示例

• 🛒 示例：电商购物自动化 - 购物流程自动化示例

🔧 开发指南

构建和测试

项目采用分层测试架构，分为协议测试、工具测试和集成测试：

# 开发模式（监听文件变化）
npm run watch

# 运行单元测试（协议 + 工具 + 工具类）
npm test

# 分类运行单元测试
npm run test:protocol      # 协议层测试
npm run test:tools         # 工具逻辑测试

# 运行严格集成测试（需要微信开发者工具；环境或连接失败即失败）
npm run test:integration

# 本地探测模式（明确允许环境不满足时跳过）
npm run test:integration:optional

# 推荐：复用现有 DevTools 会话，避免反复重启项目（默认）
INTEGRATION_CLEANUP_MODE=reuse npm run test:integration

# 如需强制隔离环境（CI 或排查端口脏状态）
INTEGRATION_CLEANUP_MODE=force npm run test:integration

# 禁用跨 suite 会话复用（仅调试时建议）
INTEGRATION_REUSE_SESSION=false npm run test:integration

# 如需每个 suite 结束后强制断开（默认不强制）
INTEGRATION_FORCE_DISCONNECT_AFTER_EACH_SUITE=true npm run test:integration

# 运行所有测试（单元 + 集成）
npm run test:all

# 生成测试覆盖率报告
npm run test:coverage

# 使用 MCP Inspector 调试
npm run inspector

手工验证与诊断

• 诊断类脚本统一放在 scripts/diagnostics/

• 手工验证脚本主要放在 tests/manual/ 的能力子目录下，另有少量根级脚本用于通用验证

• 集成测试夹具项目固定为 playground/wx/，请勿移动或删除目录

• 夹具关键文件白名单：playground/wx/app.json、playground/wx/project.config.json

添加新工具

1. 在 src/tools/ 下创建或修改工具模块

2. 使用 ToolDefinition 框架定义工具

3. 在 src/tools/tools.ts 注册并由 src/tools/index.ts 转发

4. 运行 npm run build 重新生成静态 descriptor manifest

5. 编写单元测试（tests/tools/*.test.ts 或 tests/protocol/*.test.ts）

6. 编写集成测试（tests/integration/*.integration.test.ts）

7. 更新文档

贡献者开发说明请参考 CLAUDE.md

测试架构

项目采用三层测试架构（参考 chrome-devtools-mcp）：

• 协议层测试 (tests/protocol/) - 测试 MCP 服务器协议实现

• 工具逻辑测试 (tests/tools/) - 直接测试工具 handler，无需服务器

• 集成测试 (tests/integration/) - 端到端测试，需要真实环境

集成测试支持以下运行模式：

• INTEGRATION_CLEANUP_MODE=reuse：复用已有 DevTools 实例（默认）

• INTEGRATION_CLEANUP_MODE=smart：优雅关闭后重连

• INTEGRATION_CLEANUP_MODE=force：强制清理全部实例

• INTEGRATION_REUSE_SESSION=true/false：控制跨 suite 连接复用

• INTEGRATION_FORCE_DISCONNECT_AFTER_EACH_SUITE=true/false：控制每个 suite 结束后是否强制断连（默认 false）

性能与成功率基准

仓库提供版本化 workload、JSONL 原始样本、nearest-rank p50/p95、Wilson 95% 成功率区间以及严格的 before/after 对比器。先运行基础设施测试：

npm run bench:test

无需连接微信开发者工具的协议静态对比，可以针对两个依赖已安装、能独立启动的工程构建执行：

npm run bench:protocol:compare -- \
  --baseline-server /absolute/path/to/before/build/server.js \
  --optimized-server /absolute/path/to/after/build/server.js \
  --output-dir /absolute/path/to/new-empty-result-dir

该命令只启动并关闭自己创建的 MCP stdio 子进程，不检查、不连接、也不终止任何现有 DevTools 进程；参数错误场景会在 schema 校验阶段停止。两个构建内容相同或输出目录非空时，命令会拒绝执行。

若只保留了完整历史 JSONL，可用 --recorded-baseline-dir 只重跑 optimized。恢复模式不会伪造证据：跨时段延迟只作 indicative 对比；旧结果缺 benchmark harness 指纹时整体结论为 PARTIAL/INDICATIVE，不能充当发布门禁。coldListMs 是服务器已启动后客户端重建 schema 校验器的耗时；真正的进程冷启动使用 protocol_stdio_lifecycle.lifecycleMs。

当前实现的最终观察结果：完整 tools/list 响应体从 126,879 B 降至 80,173 B，client-validator-cold p95 从 137.5788 ms 降至 16.6693 ms；stdio lifecycleMs p95 从 601.2568 ms 降至 103.2416 ms，五个协议切片成功率均为 100%。这些 before/after 数字来自 legacy recorded baseline recovery，证据等级是 indicative/non-authoritative，严格结论仍为 PARTIAL，详见 v0.6.0 对比摘要。

同页异步重建的错误动作和 revision/ref 一致性提供独立合成回归：

npm run bench:dom-epoch:synthetic -- \
  --baseline-entry /absolute/path/to/before/build/MiniProgramContext.js \
  --optimized-entry build/MiniProgramContext.js \
  --output /absolute/path/to/new-result.json

只有历史结果时可改用 --recorded-baseline-result；未实际测过的 metadata baseline 会保持 notMeasured。该结果始终是 synthetic/non-authoritative，不能替代真实 DevTools churn 验证。

当前合成结果中，历史 post-snapshot 场景从 200 次错误动作降为 0，安全结果与 revision/ref 一致率从 0% 提升到 100%；新增 metadata-read 场景的 100 个优化后样本均正确丢弃 torn draft，发布 torn draft 为 0。该数据只证明确定性回归，不代表真实 DevTools 成功率。

Snapshot 实现还提供一个不接触 DevTools 的确定性 mock 微基准，输出原始 100 样本、nearest-rank p50/p95 与成功率：

npm run bench:snapshot:synthetic -- \
  --baseline-entry /absolute/path/to/before/build/core/snapshot.js \
  --optimized-entry build/core/snapshot.js

该结果明确标记为 synthetic/non-authoritative；默认 100 并发用于避开旧实现固定 1 秒等待造成的串行耗时，不能代替真实 DevTools 集成指标。

运行时资源所有权也提供不接触 DevTools 的合成回归基准：

npm run bench:runtime:synthetic -- \
  --baseline-entry /absolute/path/to/before/build/MiniProgramContext.js \
  --optimized-entry build/MiniProgramContext.js

当前版本的完整结果与权威边界见 v0.6.0 对比摘要。

涉及连接、页面、元素、Console 和 Network 的完整真实基准，需要先预检，再通过对应版本的 adapter 执行：

npm run bench:preflight -- \
  --phase baseline \
  --output benchmarks/results/v0.6.0/local/baseline-preflight.json

npm run bench:run -- --help

完整指标、adapter 合约、安全边界和结果目录约定见基准指南。没有真实执行的指标不得填零或使用单元测试结果代替。

📋 系统要求

• Node.js >= 22.0.0

• 微信开发者工具 已安装并开启自动化功能

• 操作系统 macOS / Windows

• Claude Desktop 用于运行 MCP 服务器

🤝 贡献指南

欢迎贡献代码、报告问题或提出建议！

1. Fork 本项目

2. 创建特性分支 (git checkout -b feature/AmazingFeature)

3. 提交更改 (git commit -m 'Add some AmazingFeature')

4. 推送到分支 (git push origin feature/AmazingFeature)

5. 开启 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情

🙏 致谢

• Model Context Protocol - MCP SDK

• miniprogram-automator - 微信小程序自动化 SDK

• chrome-devtools-mcp - 架构参考

📞 联系方式

• 问题反馈：GitHub Issues

• 文档入口：见上方“文档”与“使用示例”章节中的 GitHub 文档链接

⭐ 如果这个项目对你有帮助，欢迎给个 Star！