MCP-сервер для WeChat Mini Program

Сервер на базе FastMCP, автоматизирующий WeChat Developer Tools через miniprogram-automator. Сервер предоставляет инструменты MCP, позволяющие ИИ-ассистентам перемещаться, проверять и взаимодействовать со страницами мини-программ — аналогично playwright-mcp, но специально адаптировано для экосистемы WeChat.

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

• Установлены WeChat Developer Tools с поддержкой доступа через командную строку (cli / cli.bat)

• Локально установлены Node.js 18+ и npm

• Наличие проекта мини-программы, который можно открыть в Developer Tools

Быстрый старт (npm-пакет)

@yfme/weapp-dev-mcp опубликован в npm, обычным пользователям не нужно клонировать репозиторий или вручную запускать node dist/index.js.

Запуск через npx

npx -y @yfme/weapp-dev-mcp

Установка в проект/глобально

npm install -g @yfme/weapp-dev-mcp
weapp-dev-mcp

Или как зависимость проекта:

npm install --save-dev @yfme/weapp-dev-mcp
npx weapp-dev-mcp

Прямой запуск node dist/index.js рекомендуется только при разработке внутри этого репозитория. Обычным пользователям следует запускать пакет через npm, как описано выше.

Интеграция с MCP-клиентом

Конфигурация

Чтобы использовать этот сервер в Claude Desktop или другом MCP-клиенте, добавьте в файл конфигурации:

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

Автоматическое одобрение прав инструментов в Claude Code

Поскольку при вызове инструментов MCP через Claude Code запрашиваются права доступа, это может привести к потере состояния подключения между MCP и WeChat Developer Tools. Поскольку получение вывода консоли сильно зависит от состояния подключения, получение логов может стать нестабильным, поэтому рекомендуется вручную добавить права:

Создайте файл .claude/settings.local.json в директории проекта или добавьте следующее содержимое в существующий файл, чтобы вызывать инструменты без подтверждения (или добавьте только те инструменты, которые хотите разрешить):

{
  "permissions": {
    "allow": [
      "mcp__weapp-dev-mcp__mp_ensureConnection",
      "mcp__weapp-dev-mcp__mp_navigate",
      "mcp__weapp-dev-mcp__mp_screenshot",
      "mcp__weapp-dev-mcp__mp_callWx",
      "mcp__weapp-dev-mcp__mp_getLogs",
      "mcp__weapp-dev-mcp__mp_currentPage",
      "mcp__weapp-dev-mcp__mp_listProjects",
      "mcp__weapp-dev-mcp__mp_setDefaultProject",
      "mcp__weapp-dev-mcp__page_getElement",
      "mcp__weapp-dev-mcp__page_getElements",
      "mcp__weapp-dev-mcp__page_waitElement",
      "mcp__weapp-dev-mcp__page_waitTimeout",
      "mcp__weapp-dev-mcp__page_getData",
      "mcp__weapp-dev-mcp__page_setData",
      "mcp__weapp-dev-mcp__page_callMethod",
      "mcp__weapp-dev-mcp__element_tap",
      "mcp__weapp-dev-mcp__element_input",
      "mcp__weapp-dev-mcp__element_callMethod",
      "mcp__weapp-dev-mcp__element_getData",
      "mcp__weapp-dev-mcp__element_setData",
      "mcp__weapp-dev-mcp__element_getInnerElement",
      "mcp__weapp-dev-mcp__element_getInnerElements",
      "mcp__weapp-dev-mcp__element_getWxml",
      "mcp__weapp-dev-mcp__element_getStyles",
      "mcp__weapp-dev-mcp__element_scrollTo",
      "mcp__weapp-dev-mcp__element_getAttributes",
      "mcp__weapp-dev-mcp__element_getBoundingClientRect"
    ]
  }
}

Примечание: Формат имени инструмента: mcp__<имя_сервера>__<имя_инструмента>. Убедитесь, что имя сервера совпадает с именем в вашей конфигурации MCP.

Запуск WeChat Developer Tools

Перед использованием MCP-сервера необходимо запустить WeChat Developer Tools и включить службу WebSocket.

💡 Перед началом:

1. Откройте WeChat Developer Tools

2. Перейдите в Настройки → Безопасность → Порт службы

3. Включите "HTTP-отладка" и "Автоматизированное тестирование"

Запуск через командную строку

Используйте командную строку для запуска WeChat Developer Tools с автоматическим включением службы 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

Где:

• Параметр --project указывает путь к директории проекта мини-программы (замените на реальный путь)

• Параметр --auto-port указывает порт службы WebSocket (по умолчанию 9420)

⚠️ Предупреждение Из-за механизмов песочницы некоторые клиенты не позволяют MCP получать доступ к CLI WeChat Developer Tools вне директории проекта, поэтому здесь описан только способ использования службы WebSocket.

Конфигурация переменных окружения

Управляйте тем, как инструмент автоматизации подключается к WeChat Developer Tools, с помощью переменных окружения:

Примечание: При запуске Developer Tools (режим launch) необходимо предоставить директорию проекта мини-программы через параметры инструмента MCP: укажите через connection.projectPath перед выполнением операций (например, через mp_ensureConnection). Это значение будет сохраняться в последующих вызовах.

Большинство этих значений по умолчанию можно переопределить через объект connection при вызове инструментов.

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

Инструменты приложения (Application Tools)

• mp_ensureConnection – гарантирует готовность сессии автоматизации; опционально принудительное переподключение или переопределение настроек подключения

• mp_navigate – навигация внутри мини-программы, поддерживает navigateTo, redirectTo, reLaunch, switchTab или navigateBack

• mp_screenshot – делает скриншот и возвращает его (или сохраняет на диск)

• mp_callWx – вызов методов API WeChat Mini Program (например, wx.showToast)

• mp_getLogs – получение логов консоли мини-программы, опционально с очисткой после получения

• mp_currentPage – получение информации о текущей странице (путь, параметры запроса, размеры, позиция прокрутки), при withData: true дополнительно возвращает данные страницы

• mp_listProjects – список недавних проектов в WeChat Developer Tools для удобного выбора директории проекта

• mp_setDefaultProject – установка пути к проекту мини-программы по умолчанию, после чего он будет автоматически использоваться при следующем подключении

Инструменты страницы (Page Tools)

• page_getElement – получение элемента страницы по селектору, возвращает сводную информацию об элементе (tagName, text, value, size, offset); установка withWxml: true дополнительно возвращает полный outerWxml; поддерживает синтаксис [index=N] для выбора N-го элемента

• page_getElements – получение массива элементов страницы по селектору, возвращает сводную информацию; установка withWxml: true дополнительно возвращает полный outerWxml для каждого элемента; поддерживает синтаксис [index=N]

• page_waitElement – ожидание появления элемента на странице (⚠️ не работает для элементов внутри пользовательских компонентов); поддерживает синтаксис [index=N]; добавлены параметры тайм-аута и интервала повторных попыток

• page_waitTimeout – ожидание указанного количества миллисекунд

• page_getData – получение объекта данных текущей страницы, можно указать путь (поддерживает вложенные пути, например 'user.name')

• page_setData – обновление данных текущей страницы с помощью setData; добавлена опция verify для проверки успешности обновления данных

• page_callMethod – вызов метода, экспонированного в экземпляре текущей страницы

Инструменты элементов (Element Tools)

• element_tap – имитация нажатия на WXML-элемент через CSS-селектор; поддерживает синтаксис [index=N]; поддерживает смещение координат x/y; повышенная стабильность: ожидание интерактивного состояния элемента, автоматическая проверка изменения пути страницы после нажатия

• element_input – ввод текста в элемент (для компонентов input и textarea)

• element_callMethod – вызов метода экземпляра пользовательского компонента

• element_getData – получение данных рендеринга экземпляра пользовательского компонента

• element_setData – установка данных рендеринга экземпляра пользовательского компонента

• element_getInnerElement – получение элемента внутри элемента (аналог element.$(selector)), возвращает сводную информацию; установка withWxml: true дополнительно возвращает полный outerWxml

• element_getInnerElements – получение массива элементов внутри элемента (аналог element.$$(selector)), возвращает сводную информацию; установка 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-трансформации (в настоящее время поддерживаются только селекторы ID и классов)

Каждый инструмент принимает опциональный блок connection для переопределения значений по умолчанию (путь к проекту, путь к CLI, WebSocket-эндпоинт и т.д.).

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

Общие советы

• Перед подключением включите автоматизацию в WeChat Developer Tools (Настройки → Безопасность → Порт службы)

• Рекомендуется сначала вызвать mp_ensureConnection для проверки подключения и просмотра сведений о системе/странице

• Использование WEAPP_AUTOCLOSE=true подходит для одноразовых взаимодействий без сохранения состояния

• Всегда используйте абсолютные пути при навигации (начинающиеся с /): /pages/mine/mine

• Используйте switchTab для страниц tabBar и navigateTo для обычных страниц

Работа с пользовательскими компонентами

При работе с пользовательскими компонентами есть два способа:

Способ 1: Использование параметра innerSelector (рекомендуется)

Подходит для инструментов element_tap, element_input, element_getWxml и др.:

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

• selector: селектор пользовательского компонента

• innerSelector: селектор элемента внутри компонента

Способ 2: Использование инструментов поиска внутри элемента

Подходит для element_getInnerElement и element_getInnerElements:

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

Ограничения

• page_waitElement не работает для элементов внутри пользовательских компонентов. Используйте page_waitTimeout в сочетании с инструментами поиска элементов для циклической проверки.

Функция автоматического запуска (AutoLaunch)

При настройке WEAPP_AUTOLAUNCH=true MCP-сервер может автоматически обнаруживать и запускать WeChat Developer Tools:

1. Автоматическое обнаружение порта: проверка наличия службы на порту 9420

2. Запуск при отсутствии службы: если порт не занят, автоматический вызов CLI для запуска Developer Tools

3. Выбор проекта:

   • Если есть конфигурация проекта по умолчанию, используется автоматически

   • Если проекта по умолчанию нет, автоматически выводится список недавних проектов для выбора

   • Поддерживается ввод номера проекта (например, 1) или полного пути

Пример конфигурации

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

Рабочий процесс

1. При первом подключении обнаруживается WEAPP_AUTOLAUNCH=true

2. Проверяется наличие службы на порту 9420

3. Если службы нет, Developer Tools запускается автоматически (используется cli.bat auto --project <path> --auto-port 9420)

4. Ожидание 45 секунд до готовности Developer Tools

5. Установка WebSocket-соединения

6. Последующие подключения автоматически используют существующее соединение

Совет: После установки проекта по умолчанию через mp_setDefaultProject при следующем подключении не нужно будет снова выбирать проект.