Servidor MCP para Mini Programas de WeChat

Un servidor basado en FastMCP que automatiza las Herramientas de Desarrollo de WeChat a través de miniprogram-automator. Este servidor proporciona herramientas MCP que permiten a los asistentes de IA navegar, inspeccionar y manipular páginas de mini programas, similar a playwright-mcp, pero personalizado para el ecosistema de WeChat.

Requisitos previos

• Tener instaladas las Herramientas de Desarrollo de WeChat con soporte para acceso por línea de comandos (cli / cli.bat).

• Node.js 18+ y npm instalados localmente.

• Un proyecto de mini programa que se pueda abrir en las herramientas de desarrollo.

Inicio rápido (paquete npm)

@yfme/weapp-dev-mcp ha sido publicado en npm; los usuarios comunes no necesitan clonar el repositorio ni ejecutar manualmente node dist/index.js.

Ejecutar con npx

npx -y @yfme/weapp-dev-mcp

Instalar en el proyecto/globalmente

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

O como dependencia del proyecto:

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

Solo se recomienda ejecutar node dist/index.js directamente cuando se desarrolla dentro de este repositorio. Los usuarios generales deben iniciar siguiendo el método del paquete npm anterior.

Integración con clientes MCP

Configuración

Para usar este servidor en Claude Desktop u otros clientes MCP, añada lo siguiente al archivo de configuración:

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

Autorización automática de herramientas en Claude Code

Debido a que al usar Claude Code para invocar herramientas MCP se solicita permiso de ejecución, esto puede provocar la pérdida del estado de conexión entre el MCP y las Herramientas de Desarrollo de WeChat. Dado que la obtención de la salida de la consola depende en gran medida del estado de la conexión, no será posible obtener registros de forma coherente, por lo que se recomienda añadir permisos manualmente:

Cree un archivo .claude/settings.local.json en el directorio del proyecto, o añada el siguiente contenido a un archivo existente para permitir la invocación directa sin confirmación, o añada las herramientas que desee permitir:

{
  "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"
    ]
  }
}

Nota: El formato del nombre de la herramienta es mcp__<nombre-servidor>__<nombre-herramienta>. Asegúrese de que el nombre del servidor coincida con el de su configuración MCP.

Iniciar las Herramientas de Desarrollo de WeChat

Antes de usar el servidor MCP, debe iniciar las Herramientas de Desarrollo de WeChat y habilitar el servicio WebSocket.

💡 Antes de comenzar:

1. Abra las Herramientas de Desarrollo de WeChat.

2. Vaya a Configuración → Configuración de seguridad → Puerto de servicio.

3. Habilite "Depuración HTTP" y "Pruebas automatizadas".

Iniciar mediante línea de comandos

Use la línea de comandos para iniciar las Herramientas de Desarrollo de WeChat y habilitar automáticamente el servicio 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

Donde:

• El parámetro --project especifica la ruta del directorio del proyecto del mini programa (reemplácelo por la ruta real).

• El parámetro --auto-port especifica el puerto del servicio WebSocket (por defecto 9420).

⚠️ Advertencia Debido al mecanismo de sandbox, algunos clientes no permiten que el MCP acceda al CLI de las Herramientas de Desarrollo de WeChat fuera del directorio del proyecto, por lo que aquí solo se ha introducido el uso del servicio WebSocket.

Configuración de variables de entorno

Controle cómo la herramienta de automatización se conecta a las Herramientas de Desarrollo de WeChat mediante variables de entorno:

Nota: Al iniciar las herramientas de desarrollo (modo launch), debe proporcionar el directorio del proyecto del mini programa a través de los parámetros de la herramienta MCP: proporciónelo a través de connection.projectPath antes de realizar operaciones (por ejemplo, mediante mp_ensureConnection). Una vez establecido, este valor persistirá en llamadas posteriores.

Las llamadas a herramientas pueden sobrescribir la mayoría de estos valores predeterminados a través del objeto connection.

Herramientas disponibles

Herramientas de aplicación (Application Tools)

• mp_ensureConnection – Asegura que la sesión de automatización esté lista; permite forzar la reconexión o sobrescribir la configuración de conexión.

• mp_navigate – Navega dentro del mini programa, admite navigateTo, redirectTo, reLaunch, switchTab o navigateBack.

• mp_screenshot – Captura una captura de pantalla y la devuelve (o la guarda en el disco).

• mp_callWx – Llama a métodos de la API de mini programas de WeChat (como wx.showToast).

• mp_getLogs – Obtiene los registros de la consola del mini programa, con opción de borrarlos después de obtenerlos.

• mp_currentPage – Obtiene información de la página actual (ruta, parámetros de consulta, dimensiones, posición de desplazamiento); si withData es true, devuelve adicionalmente los datos de la página.

• mp_listProjects – Lista los proyectos recientes en las Herramientas de Desarrollo de WeChat para facilitar la selección del directorio del proyecto.

• mp_setDefaultProject – Establece la ruta predeterminada del proyecto del mini programa; una vez establecida, la próxima conexión usará automáticamente este proyecto.

Herramientas de página (Page Tools)

• page_getElement – Obtiene un elemento de la página mediante un selector, devuelve un resumen del elemento (tagName, text, value, size, offset); establecer withWxml: true devuelve adicionalmente el outerWxml completo; admite la sintaxis [index=N] para seleccionar el N-ésimo elemento.

• page_getElements – Obtiene una matriz de elementos de la página mediante un selector, devuelve un resumen de cada elemento; establecer withWxml: true devuelve adicionalmente el outerWxml completo de cada elemento; admite la sintaxis [index=N].

• page_waitElement – Espera a que un elemento aparezca en la página (⚠️ no aplicable a elementos dentro de componentes personalizados); admite la sintaxis [index=N]; añade parámetros de tiempo de espera e intervalo de reintento.

• page_waitTimeout – Espera un número específico de milisegundos.

• page_getData – Obtiene el objeto de datos de la página actual, se puede especificar una ruta (admite rutas anidadas como 'user.name').

• page_setData – Actualiza los datos de la página actual usando setData; añade la opción verify para verificar si los datos se actualizaron correctamente.

• page_callMethod – Llama a un método expuesto en la instancia de la página actual.

Herramientas de elemento (Element Tools)

• element_tap – Simula un clic en un elemento WXML mediante un selector CSS; admite la sintaxis [index=N] para seleccionar el N-ésimo elemento; admite clics con desplazamiento de coordenadas x/y; mayor estabilidad: espera a que el elemento sea interactivo y verifica automáticamente si la ruta de la página cambió después del clic.

• element_input – Introduce texto en un elemento (aplicable a componentes input y textarea).

• element_callMethod – Llama a un método de una instancia de componente personalizado.

• element_getData – Obtiene los datos de renderizado de una instancia de componente personalizado.

• element_setData – Establece los datos de renderizado de una instancia de componente personalizado.

• element_getInnerElement – Obtiene un elemento dentro de otro elemento (equivalente a element.$(selector)), devuelve un resumen del elemento; establecer withWxml: true devuelve adicionalmente el outerWxml completo.

• element_getInnerElements – Obtiene una matriz de elementos dentro de otro elemento (equivalente a element.$$(selector)), devuelve un resumen del elemento; establecer withWxml: true devuelve adicionalmente el outerWxml completo de cada elemento.

• element_getWxml – Obtiene el WXML de un elemento (interno o externo).

• element_getStyles – Obtiene los valores de estilo CSS de un elemento, el parámetro names es una matriz de nombres de estilo (como ['color', 'fontSize']).

• element_scrollTo – Desplaza un componente scroll-view a una posición específica (x, y).

• element_getAttributes – Obtiene los valores de los atributos de un elemento, el parámetro names es una matriz de nombres de atributos (como ['class', 'id', 'data-index']).

• element_getBoundingClientRect – Obtiene información del rectángulo delimitador del elemento en relación con la ventana gráfica (left, top, width, height, right, bottom), considerando transformaciones CSS (actualmente solo admite selectores de ID y clase).

Cada herramienta acepta un bloque connection opcional para sobrescribir los valores predeterminados del entorno (ruta del proyecto, ruta del CLI, punto final WebSocket, etc.).

Consejos de uso

Consejos generales

• Antes de conectar, habilite la automatización en las Herramientas de Desarrollo de WeChat (Configuración → Configuración de seguridad → Puerto de servicio).

• Se recomienda llamar primero a mp_ensureConnection para verificar la conexión y ver los detalles del sistema/página.

• Usar WEAPP_AUTOCLOSE=true es adecuado para interacciones únicas sin estado.

• Use siempre rutas absolutas al navegar (comenzando con /): /pages/mine/mine.

• Use switchTab para páginas de la barra de pestañas (tabBar) y navigateTo para páginas normales.

Operar con componentes personalizados

Al operar con componentes personalizados, hay dos métodos:

Método 1: Usar el parámetro innerSelector (recomendado)

Aplicable a herramientas como element_tap, element_input, element_getWxml, etc.:

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

• selector: Selector del componente personalizado.

• innerSelector: Selector del elemento dentro del componente.

Método 2: Usar herramientas de consulta dentro de elementos

Aplicable a element_getInnerElement y element_getInnerElements:

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

Limitaciones

• page_waitElement no es aplicable a elementos dentro de componentes personalizados. Utilice page_waitTimeout junto con herramientas de consulta de elementos para realizar comprobaciones de sondeo.

Función de inicio automático (AutoLaunch)

Cuando se configura WEAPP_AUTOLAUNCH=true, el servidor MCP puede detectar e iniciar automáticamente las Herramientas de Desarrollo de WeChat:

1. Detección automática de puerto: Detecta si hay un servicio ejecutándose en el puerto 9420.

2. Iniciar si no hay servicio: Si el puerto no está ocupado, llama automáticamente al CLI para iniciar las herramientas de desarrollo.

3. Selección de proyecto:

   • Si hay una configuración de proyecto predeterminada, se usa automáticamente.

   • Si no hay un proyecto predeterminado, se listan automáticamente los proyectos recientes para elegir.

   • Admite ingresar el número de proyecto (por ejemplo, 1) o la ruta completa.

Ejemplo de configuración

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

Flujo de trabajo

1. En la primera conexión, se detecta WEAPP_AUTOLAUNCH=true.

2. Se comprueba si hay un servicio en el puerto 9420.

3. Si no hay servicio, se inician automáticamente las herramientas de desarrollo (usando cli.bat auto --project <path> --auto-port 9420).

4. Se esperan 45 segundos para que las herramientas de desarrollo estén listas.

5. Se establece la conexión WebSocket.

6. Las conexiones posteriores reutilizan automáticamente la conexión existente.

Sugerencia: Después de configurar el proyecto predeterminado con mp_setDefaultProject, no es necesario volver a seleccionar el proyecto en la próxima conexión.