weapp-agent-mcp

weapp-agent-mcp

WeChat ミニプログラムのデバッグ、自動化、軽量なリグレッションテストに特化した、エージェントファーストの MCP サーバーです。

エージェント向けの WeChat ミニプログラム MCP サービス — Claude Code / Cursor / Codex などのエージェントが、会話中に WeChat 開発者ツールを直接操作して、デバッグ、UI 操作、ページの巡回、軽量なテストを実行できます。

📖 変更履歴 · 🐛 イシュー · 💬 ディスカッション

weapp-agent-mcp は、エージェント向けの WeChat ミニプログラム MCP サービスです。 miniprogram-automator を基盤に WeChat 開発者ツールの自動化機能をラップし、ページのデバッグ、要素の操作、軽量なリグレッションテスト、復旧しやすいトラブルシューティングに使用します。

次の用途に適しています：

• エージェントを中心とした開発・デバッグ
• 連続したスクリーンショット撮影とページ巡回
• 軽量なシナリオ／レポート
• 安定したセレクターに基づく自動検証

現時点では、次のような用途として紹介すべきではありません：

• 並列スクリーンショット撮影
• 長時間・高負荷のエンドツーエンドリグレッションテストエンジン

ドキュメント案内

詳細なドキュメントについては、docs/README.md をご覧ください。

weapp-agent-mcp を選ぶ理由

Claude Code / Cursor / Codex などのエージェントを使ってミニプログラムを開発している場合、従来の miniprogram-automator によるスクリプトベースの呼び出しは使い勝手がよくありません。エージェントに Node スクリプトを書かせ、実行し、出力を読み取り、再度調整する必要があります。このプロジェクトでは、自動化機能をエージェントのツール呼び出しとして直接公開するため、エージェントは会話中に次のことを実行できます：

• 🤖 スクリプト不要のデバッグ — mp_screenshot / page_snapshot / element_tap を直接呼び出せるため、スクリプトを介する必要がありません
• 🔁 復旧しやすい設計 — mp_healthCheck / mp_recoverConnection を内蔵しており、接続が切れた後も自動復旧できるため、長時間のセッションでも安定します
• 📋 軽量なリグレッションテスト — mp_runScenario + mp_generateScenarioReport で markdown レポートを生成でき、PR / oncall に適しています
• 🎯 安定したセレクターを優先 — qa-* 形式の名前付きアンカーを推奨する設計により、UI の変更後にスクリプトが壊れるリスクを減らします

適用範囲／不適用範囲の比較

シナリオ	適用可否
エージェントによるデバッグ／巡回の直接実行	✅ 主な用途
従来型のスクリプトベースの e2e テストの作成	⚪ ネイティブの miniprogram-automator SDK を直接使うほうが軽量です
並列スクリーンショット撮影／負荷テスト	❌ 不適 — スクリーンショット機能は直列実行を前提に設計されています
長時間のセッション／複数回のデバッグ	✅ health / recover ツールで補完できます
CI での長いエンドツーエンドリグレッションテスト	⚠️ 短いシナリオに分割すれば使用できます。非常に長いテストには専用のフレームワークを推奨します

前提条件

• WeChat 開発者ツールがインストール済みで、コマンドラインからアクセスできること（cli / cli.bat）
• Node.js 18+ と npm がローカルにインストール済みであること
• 開発者ツールで開けるミニプログラムのプロジェクトがあること
• WeChat 開発者ツールで自動テストとサーバーポートが有効になっていること

クイックスタート

方法 1：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 サーバーのキーを 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"
      }
    }
  }
}

方法 2：ローカルソースからビルドして接続（開発者／コントリビューター向け）

次のような場合にのみ、この方法を使用してください：

• このリポジトリ自体を開発している
• 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 は現在、直列の単一チャネル機能として設計されており、並列負荷テストには対応していません
• 複雑な業務フローは、1 つの非常に長いシナリオではなく、複数の短いシナリオに分割してください
• page_snapshot、mp_screenshot、長時間の mp_runScenario は、複雑な操作を連続して行うとタイムアウトする可能性があります
• 失敗が続く場合は、まず mp_healthCheck を実行してください。needsRecovery=true の場合に限り、mp_recoverConnection を実行します
• 安定性は、業務ページに明確な qa-* セレクターや、その他の安定した識別アンカーが用意されているかどうかに大きく左右されます

MCP クライアントとの連携

Claude Code でツールの権限を自動承認する

Claude Code から MCP ツールを呼び出すと、ツール呼び出しの権限確認が表示されます。その際、MCP と WeChat 開発者ツールの接続状態が失われる可能性があります。コンソール出力の取得は接続状態に大きく依存するため、ログを継続して取得できなくなる場合があります。そのため、権限を手動で追加することをおすすめします：

プロジェクトディレクトリに .claude/settings.local.json ファイルを作成するか、既存のファイルに次の内容を追加すると、確認なしでツールを直接呼び出せるようになります。必要に応じて、確認なしで呼び出すことを許可するツールを追加してください：

{
  "permissions": {
    "allow": [
      "mcp__weapp-agent-mcp__mp_diagnoseConnection",
      "mcp__weapp-agent-mcp__mp_ensureConnection",
      "mcp__weapp-agent-mcp__mp_navigate",
      "mcp__weapp-agent-mcp__mp_screenshot",
      "mcp__weapp-agent-mcp__mp_callWx",
      "mcp__weapp-agent-mcp__mp_evaluate",
      "mcp__weapp-agent-mcp__mp_pollUntil",
      "mcp__weapp-agent-mcp__mp_getLogs",
      "mcp__weapp-agent-mcp__mp_runScenario",
      "mcp__weapp-agent-mcp__mp_generateScenarioReport",
      "mcp__weapp-agent-mcp__mp_currentPage",
      "mcp__weapp-agent-mcp__mp_healthCheck",
      "mcp__weapp-agent-mcp__mp_recoverConnection",
      "mcp__weapp-agent-mcp__mp_listProjects",
      "mcp__weapp-agent-mcp__mp_setDefaultProject",
      "mcp__weapp-agent-mcp__page_getElement",
      "mcp__weapp-agent-mcp__page_getElements",
      "mcp__weapp-agent-mcp__page_waitElement",
      "mcp__weapp-agent-mcp__page_waitElementGone",
      "mcp__weapp-agent-mcp__page_waitRoute",
      "mcp__weapp-agent-mcp__page_waitTimeout",
      "mcp__weapp-agent-mcp__page_expectRoute",
      "mcp__weapp-agent-mcp__page_expectVisible",
      "mcp__weapp-agent-mcp__page_expectElementText",
      "mcp__weapp-agent-mcp__page_expectCount",
      "mcp__weapp-agent-mcp__page_expectData",
      "mcp__weapp-agent-mcp__page_snapshot",
      "mcp__weapp-agent-mcp__page_getData",
      "mcp__weapp-agent-mcp__page_setData",
      "mcp__weapp-agent-mcp__page_callMethod",
      "mcp__weapp-agent-mcp__element_tap",
      "mcp__weapp-agent-mcp__element_touch",
      "mcp__weapp-agent-mcp__element_swipe",
      "mcp__weapp-agent-mcp__element_input",
      "mcp__weapp-agent-mcp__element_callMethod",
      "mcp__weapp-agent-mcp__element_getData",
      "mcp__weapp-agent-mcp__element_setData",
      "mcp__weapp-agent-mcp__element_getInnerElement",
      "mcp__weapp-agent-mcp__element_getInnerElements",
      "mcp__weapp-agent-mcp__element_getWxml",
      "mcp__weapp-agent-mcp__element_getStyles",
      "mcp__weapp-agent-mcp__element_scrollTo",
      "mcp__weapp-agent-mcp__element_getAttributes",
      "mcp__weapp-agent-mcp__element_getBoundingClientRect"
    ]
  }
}

注意： ツール名の形式は mcp__<服务器名称>__<工具名称> です。サーバー名が MCP の設定と一致していることを確認してください。

任意：WeChat 開発者ツールを手動で事前起動する

通常の手順では、エージェントが CLI を手動で実行する必要はありません。mp_ensureConnection を直接呼び出すと、ローカルポートがリッスンしておらず、AutoLaunch が許可されている場合、サーバーが自動的に cli auto を実行します。以下のコマンドは、手動でトラブルシューティングを行う場合や、WEAPP_AUTOLAUNCH=false を明示的に設定してユーザー自身が開発者ツールを事前起動する場合にのみ使用します。

💡 開始する前に：

1. WeChat 開発者ツールを開きます
2. 設定 → セキュリティ設定 → サービスポートに移動します
3. **「HTTP デバッグ」と「自動テスト」**を有効にします

コマンドラインで手動起動する

コマンドラインを使用して WeChat 開発者ツールを起動し、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）。このフラグは cli auto --help の出力には表示されませんが、公式の miniprogram-automator SDK 内部で以前から使用されており、有効なパラメーターです

⚠️ 警告 サンドボックスの仕組みにより、一部のクライアントでは、プロジェクトディレクトリ外にある WeChat 開発者ツールの cli への MCP アクセスが許可されません。そのため、ここでは WebSocket サービスを使用する方法のみを紹介しています

环境变量配置

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

变量	说明
WEAPP_WS_ENDPOINT	【推荐】 已运行的开发者工具自动化 WebSocket 端点。设置后，服务器使用 connect 模式而不是启动新实例。示例：ws://localhost:9420
WECHAT_DEVTOOLS_CLI_PATH	微信开发者工具 CLI 路径（如果默认路径有效则可选）。
WEAPP_AUTOMATOR_MODE	强制使用 launch 或 connect 模式。除非提供了 WEAPP_WS_ENDPOINT，否则默认为 launch。
WEAPP_DEVTOOLS_PORT	launch 模式下传给 cli auto --auto-port 的自动化端口。不会在失败后自动切到其他端口。
WEAPP_DEVTOOLS_TIMEOUT	启动超时时间（毫秒，默认 30000）。
WEAPP_AUTO_ACCOUNT	传递给 --auto-account 用于自动登录。
WEAPP_DEVTOOLS_TICKET	启动时传递给 --ticket。
WEAPP_TRUST_PROJECT	设置为 true 以在启动时包含 --trust-project。
WEAPP_DEVTOOLS_ARGS	启动时的额外 CLI 参数（空格分隔）。
WEAPP_DEVTOOLS_CWD	传递给开发者工具进程的工作目录。
WEAPP_AUTOCLOSE	设置为 true 时，每次工具调用后关闭开发者工具会话。
WEAPP_AUTOLAUNCH	本地 connect 目标端口未监听时是否允许 mp_ensureConnection 使用 cli auto 拉起开发者工具；默认允许，设为 false 禁用。不会自动切换端口或拉起远程目标。
WEAPP_LAUNCH_TIMEOUT	启动超时时间（毫秒，默认 45000）
WEAPP_CONNECT_TIMEOUT	连接超时时间（毫秒，默认 45000）
WEAPP_PROJECT_PATH	小程序项目路径（可选）

注意： 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 – 断言当前页面指定 data 路径的值是否与预期相等
• page_snapshot – 返回当前页面的轻量结构快照，聚合 route、query、指定 data 路径和值，以及关键选择器的元素摘要；不默认处理页面 title，标题校验请用明确选择器配合 page_expectElementText
• page_getData – 获取当前页面的数据对象，可选择指定子数据路径
• page_setData – 使用 setData 更新当前页面的数据
• page_callMethod – 调用当前页面实例上暴露的方法

元素工具（Element Tools）

• element_tap – 通过 CSS 选择器模拟点击 WXML 元素；支持 [index=N] 语法选择第 N 个元素
• element_touch – 对元素执行真实触摸事件；支持 start / move / end / sequence 四种模式，坐标基于元素左上角，默认取元素中心；支持 [index=N] 语法
• element_swipe – 对元素执行真实滑动手势；支持 up / down / left / right，可指定距离和持续时间；支持 [index=N] 语法
• element_input – 向元素输入文本（适用于 input 和 textarea 组件）
• element_callMethod – 调用自定义组件实例的方法
• element_getData – 获取自定义组件实例的渲染数据
• element_setData – 设置自定义组件实例的渲染数据
• element_getInnerElement – 获取元素内的元素（相当于 element.$(selector)），返回元素摘要信息；设置 withWxml: true 可额外返回完整 outerWxml
• element_getInnerElements – 获取元素内的元素数组（相当于 element.$$(selector)），返回元素摘要信息；limit 默认/最大 100；设置 withWxml: true 可额外返回每个元素的完整 outerWxml
• element_getWxml – 获取元素 WXML（内部或外部）
• element_getStyles – 获取元素的 CSS 样式值，names 参数为样式名数组（如 ['color', 'fontSize']）
• element_scrollTo – 滚动 scroll-view 组件到指定位置（x, y）
• element_getAttributes – 获取元素的特性值，names 参数为特性名数组（如 ['class', 'id', 'data-index']）
• element_getBoundingClientRect – 获取元素相对于视口的边界矩形信息（left、top、width、height、right、bottom），考虑 CSS transform 变换（目前仅支持 ID 选择器、类选择器）

每个工具都接受可选的 connection 块来覆盖环境默认值（项目路径、CLI 路径、WebSocket 端点等）。

使用技巧

一般提示

• 连接前，在微信开发者工具中启用自动化（设置 → 安全设置 → 服务端口）
• 默认先调用 mp_ensureConnection 建立或复用会话；只读探测或连接失败排查再用 mp_diagnoseConnection
• 使用 WEAPP_AUTOCLOSE=true 适合无状态的一次性交互
• 导航时始终使用绝对路径（以 / 开头）：/pages/mine/mine
• tabBar 页面使用 switchTab，普通页面使用 navigateTo
• switchTab 只应视为一种导航动作，不应默认作为底部 tab UI 选中态的判断依据；很多项目会自定义底部 tab

操作自定义组件

操作自定义组件时，有两种方法：

方法一：使用 innerSelector 参数（推荐）

适用于 element_tap、element_input、element_getWxml 等工具：

{
  "selector": "#my-component",
  "innerSelector": ".inner-button"
}

• selector：自定义组件的选择器
• innerSelector：组件内部元素的选择器

方法二：使用元素内查询工具

适用于 element_getInnerElement 和 element_getInnerElements：

{
  "selector": "#my-component",
  "targetSelector": ".inner-button"
}

限制说明

• page_waitElement 不适用于自定义组件内部元素。请使用 page_waitTimeout 配合元素查询工具进行轮询检查。
• 页面跳转校验可优先使用 page_waitRoute，比单纯 mp_navigate 后固定等待更稳。
• 临时弹层、loading、toast 等消失场景可使用 page_waitElementGone。

自动启动功能（AutoLaunch）

本地 connect 目标端口未监听时，mp_ensureConnection 默认会使用 cli auto 拉起开发者工具。设置 WEAPP_AUTOLAUNCH=false 可显式禁用。远程 wsEndpoint 不会触发本机自动拉起。

当前安全策略是：

1. 如果用户已经手动打开 IDE，应优先使用 connect
2. 本地 connect 端口未监听时，MCP 可自动执行 cli auto，但不自动切模式、不自动切端口
3. autoLaunch=false 或远程 wsEndpoint 时不会自动启动 IDE
4. 如果检测到 DevTools 已在运行，会优先阻止重复拉起

配置示例

{
  "mcpServers": {
    "weapp-agent-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@chaixueyuan/weapp-agent-mcp"
      ],
      "env": {
        "WEAPP_AUTOLAUNCH": "true",
        "WEAPP_PROJECT_PATH": "D:\\path\\to\\your\\project"
      }
    }
  }
}

工作流程

1. 首次连接时，检测到本地自动化端口未监听且未设置 WEAPP_AUTOLAUNCH=false
2. 检查 9420 端口是否有服务
3. 无服务则自动启动开发者工具（使用 cli.bat auto --project <path> --auto-port 9420）
4. 按 WEAPP_LAUNCH_TIMEOUT 等待开发者工具就绪（默认 45 秒）
5. 建立 WebSocket 连接
6. 后续连接自动复用现有连接

提示：使用 mp_setDefaultProject 设置默认项目后，下次连接无需再次选择项目。