WeApp Dev — MCP-сервер для автоматизации мини-программ WeChat

Этот MCP-сервер даёт AI-ассистентам (через протокол MCP) возможность управлять симулятором мини-программ WeChat в официальном инструменте разработчика. По духу он похож на Playwright MCP, но заточен именно под экосистему WeChat.

Предварительные требования

• Установленный 微信开发者工具 (WeChat DevTools) — должна быть доступна команда cli (macOS/Linux) или cli.bat (Windows).
• Node.js 18+ и npm.
• Существующий проект мини-программы, который можно открыть в DevTools.

Установка и запуск

Быстрый старт (через npx, рекомендуется)

Сервер опубликован на npm как @yfme/weapp-dev-mcp. Не нужно клонировать репозиторий — просто выполни команду:

npx -y \
  -p @modelcontextprotocol/sdk@1.17.2 \
  -p fastmcp@3.23.0 \
  -p @yfme/weapp-dev-mcp \
  weapp-dev-mcp

Важно: Параметры -p фиксируют версии SDK и FastMCP, чтобы избежать ошибки «Server does not support completions», которая возникает в более новых версиях. weapp-dev-mcp — это имя CLI, экспортируемое пакетом.

Установка локально или глобально

npm install --save-dev \
  @modelcontextprotocol/sdk@1.17.2 \
  fastmcp@3.23.0 \
  @yfme/weapp-dev-mcp
npx weapp-dev-mcp

Можно также установить глобально (npm install -g ...) и запускать напрямую.

Только для разработки самого сервера имеет смысл запускать node dist/index.js.

Настройка MCP-клиента (Claude Desktop и др.)

Добавь в конфигурационный файл MCP-клиента следующий блок:

{
  "mcpServers": {
    "weapp-dev": {
      "command": "npx",
      "args": [
        "-y",
        "-p", "@modelcontextprotocol/sdk@1.17.2",
        "-p", "fastmcp@3.23.0",
        "-p", "@yfme/weapp-dev-mcp",
        "weapp-dev-mcp"
      ],
      "env": {
        "WEAPP_WS_ENDPOINT": "ws://localhost:9420"
      }
    }
  }
}

Запуск微信开发者工具 и WebSocket-сервера

Перед использованием сервера необходимо запустить DevTools и включить WebSocket:

1. Открой 微信开发者工具 → Настройки → Безопасность → Сервисные порты.

2. Включи «HTTP-отладку» и «Автоматизацию тестирования».

3. Запусти DevTools через CLI с указанием проекта и порта WebSocket:

   macOS / Linux:

   /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
   

Примечание: Из-за песочницы некоторые MCP-клиенты не могут напрямую вызывать cli. Поэтому рекомендуется использовать WebSocket-режим, задав WEAPP_WS_ENDPOINT.

Переменные окружения

Важно: В режиме launch путь к проекту необходимо передавать через параметр connection.projectPath при вызове инструментов (например, через mp_ensureConnection). Этот путь сохраняется на время сессии.

Доступные MCP-инструменты

Прикладные (Application)

• mp_ensureConnection — проверяет/создаёт сессию автоматизации. Можно принудительно переподключиться или изменить настройки.
• mp_navigate — навигация внутри мини-программы: navigateTo, redirectTo, reLaunch, switchTab, navigateBack.
• mp_screenshot — делает скриншот и возвращает его (или сохраняет на диск).
• mp_callWx — вызывает API мини-программы (например wx.showToast).
• mp_getLogs — забирает логи из консоли; опционально очищает их.

Страницы (Page)

• page_getElement — получает элемент по CSS-селектору.
• page_waitElement — ждёт появления элемента на странице (⚠️ не работает для элементов внутри кастомных компонентов).
• page_waitTimeout — ждёт указанное количество миллисекунд.
• page_getData — получает данные страницы (можно указать путь).
• page_setData — обновляет данные через setData.
• page_callMethod — вызывает метод, объявленный на странице.

Элементы (Element)

• element_tap — тап по элементу (CSS-селектор).
• element_input — ввод текста (для <input> и <textarea>).
• element_callMethod — вызов метода кастомного компонента (требуется ID-селектор).
• element_getData / element_setData — чтение/запись данных кастомного компонента (требуется ID-селектор).
• element_getInnerElement / element_getInnerElements — получение вложенных элементов внутри компонента.
• element_getSize — ширина и высота элемента.
• element_getWxml — WXML элемента.

Каждый инструмент принимает опциональный блок connection, позволяющий переопределить настройки подключения на лету.

Советы по использованию

• Перед началом обязательно включи автоматизацию в DevTools (Настройки → Безопасность → Сервисные порты).
• Начинай с вызова mp_ensureConnection — он покажет статус соединения и информацию о странице.
• Для одноразовых сценариев установи WEAPP_AUTOCLOSE=true.
• Пути навигации указывай абсолютными (/pages/mine/mine).
• Для tabBar используй switchTab, для обычных страниц — navigateTo.

Работа с кастомными компонентами

Кастомные компоненты обязательно должны иметь атрибут id. Используй ID-селектор (например #my-component).

Способ 1 (рекомендуется): поле innerSelector

Применимо для element_tap, element_input, element_getSize, element_getWxml:

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

Способ 2: инструменты для вложенных элементов

Используй element_getInnerElement или element_getInnerElements с targetSelector:

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

Известные ограничения

• page_waitElement не может найти элементы внутри кастомных компонентов. Вместо этого используй page_waitTimeout + перебор через element_getInnerElements.
• Методы element_callMethod, element_getData, element_setData требуют, чтобы у компонента был задан id.
• Ошибка «Server does not support completions» решается фиксацией версий SDK и FastMCP (как описано выше) — в будущем будет исправлено в самом пакете.