WeChat Mini Program MCP Server

Ein auf FastMCP basierender Server, der die WeChat Developer Tools über miniprogram-automator automatisiert. Der Server stellt MCP-Tools bereit, mit denen KI-Assistenten Mini-Programm-Seiten navigieren, prüfen und bearbeiten können – ähnlich wie playwright-mcp, aber speziell für das WeChat-Ökosystem angepasst.

Voraussetzungen

• WeChat Developer Tools sind installiert und unterstützen den Befehlszeilenzugriff (cli / cli.bat)

• Node.js 18+ und npm sind lokal installiert

• Ein Mini-Programm-Projekt, das in den Developer Tools geöffnet werden kann

Schnellstart (npm-Paket)

@yfme/weapp-dev-mcp wurde auf npm veröffentlicht. Normale Benutzer müssen das Repository nicht klonen oder node dist/index.js manuell ausführen.

Ausführung mit npx

npx -y @yfme/weapp-dev-mcp

Installation im Projekt/Global

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

Oder als Projektabhängigkeit:

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

Nur bei der Entwicklung innerhalb dieses Repositorys wird empfohlen, node dist/index.js direkt auszuführen. Allgemeine Benutzer sollten den oben genannten npm-Paket-Weg verwenden.

MCP-Client-Integration

Konfiguration

Um diesen Server in Claude Desktop oder anderen MCP-Clients zu verwenden, fügen Sie Folgendes zur Konfigurationsdatei hinzu:

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

Claude Code automatische Tool-Genehmigung

Da beim Aufruf von MCP-Tools mit Claude Code eine Genehmigungsanfrage für Tool-Aufrufe ausgelöst wird, kann dabei der Verbindungsstatus zwischen MCP und den WeChat Developer Tools verloren gehen. Da der Abruf von Konsolenausgaben stark vom Verbindungsstatus abhängt, kann es zu Problemen beim konsistenten Abruf von Protokollen kommen. Daher wird empfohlen, Berechtigungen manuell hinzuzufügen:

Erstellen Sie im Projektverzeichnis eine .claude/settings.local.json-Datei oder fügen Sie den folgenden Inhalt zu einer bestehenden Datei hinzu, um Tools ohne Bestätigung direkt aufzurufen, oder fügen Sie nach Bedarf die Tools hinzu, die Sie ohne Bestätigung aufrufen möchten:

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

Hinweis: Das Tool-Namensformat ist mcp__<Servername>__<Toolname>. Stellen Sie sicher, dass der Servername mit dem Namen in Ihrer MCP-Konfiguration übereinstimmt.

Starten der WeChat Developer Tools

Bevor Sie den MCP-Server verwenden, müssen Sie die WeChat Developer Tools starten und den WebSocket-Dienst aktivieren.

💡 Bevor Sie beginnen:

1. Öffnen Sie die WeChat Developer Tools

2. Gehen Sie zu Einstellungen → Sicherheitseinstellungen → Dienst-Port

3. Aktivieren Sie "HTTP-Debugging" und "Automatisierte Tests"

Starten über die Befehlszeile

Verwenden Sie die Befehlszeile, um die WeChat Developer Tools zu starten und den WebSocket-Dienst automatisch zu aktivieren:

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

Dabei gilt:

• Der Parameter --project gibt den Pfad zum Mini-Programm-Projektverzeichnis an (bitte durch den tatsächlichen Projektpfad ersetzen)

• Der Parameter --auto-port gibt den WebSocket-Dienst-Port an (Standard 9420)

⚠️ Warnung Aufgrund des Sandbox-Mechanismus erlauben einige Clients MCP nicht, auf die CLI der WeChat Developer Tools außerhalb des Projektverzeichnisses zuzugreifen, daher wurde hier nur die Verwendung des WebSocket-Dienstes beschrieben.

Umgebungsvariablen-Konfiguration

Steuern Sie über Umgebungsvariablen, wie das Automatisierungstool eine Verbindung zu den WeChat Developer Tools herstellt:

Hinweis: Beim Starten der Developer Tools (launch-Modus) muss das Mini-Programm-Projektverzeichnis über die MCP-Tool-Parameter bereitgestellt werden: Geben Sie es vor der Ausführung über connection.projectPath an (z. B. über mp_ensureConnection). Dieser Wert bleibt nach der Einrichtung für nachfolgende Aufrufe bestehen.

Tool-Aufrufe können die meisten dieser Standardwerte über das connection-Objekt überschreiben.

Verfügbare Tools

Anwendungstools (Application Tools)

• mp_ensureConnection – Stellt sicher, dass die Automatisierungssitzung bereit ist; optionales Erzwingen einer Neuverbindung oder Überschreiben der Verbindungseinstellungen

• mp_navigate – Navigation innerhalb des Mini-Programms, unterstützt navigateTo, redirectTo, reLaunch, switchTab oder navigateBack

• mp_screenshot – Erfasst einen Screenshot und gibt ihn zurück (oder speichert ihn auf der Festplatte)

• mp_callWx – Ruft WeChat Mini-Programm-API-Methoden auf (z. B. wx.showToast)

• mp_getLogs – Ruft Konsolenprotokolle des Mini-Programms ab, optional mit Löschung nach dem Abruf

• mp_currentPage – Ruft Informationen zur aktuellen Seite ab (Pfad, Abfrageparameter, Abmessungen, Scroll-Position); bei withData: true werden zusätzlich Seitendaten zurückgegeben

• mp_listProjects – Listet die letzten Projekte in den WeChat Developer Tools auf, um die Auswahl des Projektverzeichnisses zu erleichtern

• mp_setDefaultProject – Legt den Standardpfad für das Mini-Programm-Projekt fest; nach der Einstellung wird dieses Projekt bei der nächsten Verbindung automatisch verwendet

Seitentools (Page Tools)

• page_getElement – Ruft ein Seitenelement über einen Selektor ab und gibt eine Zusammenfassung des Elements zurück (tagName, text, value, size, offset); bei withWxml: true wird zusätzlich das vollständige outerWxml zurückgegeben; unterstützt die [index=N]-Syntax zur Auswahl des N-ten Elements

• page_getElements – Ruft ein Array von Seitenelementen über einen Selektor ab; bei withWxml: true wird zusätzlich das vollständige outerWxml für jedes Element zurückgegeben; unterstützt die [index=N]-Syntax

• page_waitElement – Wartet darauf, dass ein Element auf der Seite erscheint (⚠️ nicht für Elemente innerhalb benutzerdefinierter Komponenten geeignet); unterstützt die [index=N]-Syntax; zusätzliche Parameter für Timeout und Wiederholungsintervall

• page_waitTimeout – Wartet für eine angegebene Anzahl von Millisekunden

• page_getData – Ruft das Datenobjekt der aktuellen Seite ab, Pfad kann angegeben werden (unterstützt verschachtelte Pfade wie 'user.name')

• page_setData – Aktualisiert die Daten der aktuellen Seite mit setData; zusätzliche verify-Option zur Überprüfung, ob die Daten erfolgreich aktualisiert wurden

• page_callMethod – Ruft eine Methode auf, die auf der aktuellen Seiteninstanz verfügbar ist

Elementtools (Element Tools)

• element_tap – Simuliert einen Klick auf ein WXML-Element über einen CSS-Selektor; unterstützt die [index=N]-Syntax zur Auswahl des N-ten Elements; unterstützt Klicks mit x/y-Koordinaten-Offset; verbesserte Stabilität: wartet auf den interaktiven Status des Elements und überprüft nach dem Klick automatisch, ob sich der Seitenpfad geändert hat

• element_input – Gibt Text in ein Element ein (geeignet für input- und textarea-Komponenten)

• element_callMethod – Ruft eine Methode einer Instanz einer benutzerdefinierten Komponente auf

• element_getData – Ruft die Rendering-Daten einer Instanz einer benutzerdefinierten Komponente ab

• element_setData – Legt die Rendering-Daten einer Instanz einer benutzerdefinierten Komponente fest

• element_getInnerElement – Ruft ein Element innerhalb eines Elements ab (entspricht element.$(selector)) und gibt eine Zusammenfassung zurück; bei withWxml: true wird zusätzlich das vollständige outerWxml zurückgegeben

• element_getInnerElements – Ruft ein Array von Elementen innerhalb eines Elements ab (entspricht element.$$(selector)) und gibt eine Zusammenfassung zurück; bei withWxml: true wird zusätzlich das vollständige outerWxml für jedes Element zurückgegeben

• element_getWxml – Ruft das WXML eines Elements ab (intern oder extern)

• element_getStyles – Ruft CSS-Stilwerte eines Elements ab, der Parameter names ist ein Array von Stilnamen (z. B. ['color', 'fontSize'])

• element_scrollTo – Scrollt eine scroll-view-Komponente an eine angegebene Position (x, y)

• element_getAttributes – Ruft Attributwerte eines Elements ab, der Parameter names ist ein Array von Attributnamen (z. B. ['class', 'id', 'data-index'])

• element_getBoundingClientRect – Ruft Informationen zum Begrenzungsrechteck eines Elements relativ zum Viewport ab (left, top, width, height, right, bottom), unter Berücksichtigung von CSS-Transform-Transformationen (derzeit nur ID-Selektoren und Klassenselektoren unterstützt)

Jedes Tool akzeptiert einen optionalen connection-Block, um die Standardwerte der Umgebung (Projektpfad, CLI-Pfad, WebSocket-Endpunkt usw.) zu überschreiben.

Tipps zur Verwendung

Allgemeine Hinweise

• Aktivieren Sie vor der Verbindung die Automatisierung in den WeChat Developer Tools (Einstellungen → Sicherheitseinstellungen → Dienst-Port)

• Es wird empfohlen, zuerst mp_ensureConnection aufzurufen, um die Verbindung zu überprüfen und System-/Seiten-Details anzuzeigen

• Die Verwendung von WEAPP_AUTOCLOSE=true eignet sich für zustandslose Einmal-Interaktionen

• Verwenden Sie bei der Navigation immer absolute Pfade (beginnend mit /): /pages/mine/mine

• Verwenden Sie switchTab für tabBar-Seiten und navigateTo für normale Seiten

Bedienung benutzerdefinierter Komponenten

Es gibt zwei Methoden zur Bedienung benutzerdefinierter Komponenten:

Methode 1: Verwendung des innerSelector-Parameters (empfohlen)

Geeignet für Tools wie element_tap, element_input, element_getWxml usw.:

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

• selector: Selektor der benutzerdefinierten Komponente

• innerSelector: Selektor des internen Elements der Komponente

Methode 2: Verwendung von Element-Abfragetools

Geeignet für element_getInnerElement und element_getInnerElements:

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

Einschränkungen

• page_waitElement ist nicht für Elemente innerhalb benutzerdefinierter Komponenten geeignet. Bitte verwenden Sie page_waitTimeout in Verbindung mit Element-Abfragetools für eine Polling-Überprüfung.

Automatische Startfunktion (AutoLaunch)

Wenn WEAPP_AUTOLAUNCH=true konfiguriert ist, kann der MCP-Server die WeChat Developer Tools automatisch erkennen und starten:

1. Automatische Port-Erkennung: Erkennt, ob auf Port 9420 ein Dienst läuft

2. Starten, wenn kein Dienst vorhanden ist: Wenn der Port nicht belegt ist, wird die CLI automatisch aufgerufen, um die Developer Tools zu starten

3. Projektauswahl:

   • Wenn eine Standardprojektkonfiguration vorhanden ist, wird diese automatisch verwendet

   • Wenn kein Standardprojekt vorhanden ist, werden die letzten Projekte automatisch zur Auswahl aufgelistet

   • Unterstützt die Eingabe von Projektnummern (z. B. 1) oder vollständigen Pfaden

Konfigurationsbeispiel

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

Arbeitsablauf

1. Bei der ersten Verbindung wird WEAPP_AUTOLAUNCH=true erkannt

2. Überprüfung, ob auf Port 9420 ein Dienst läuft

3. Wenn kein Dienst vorhanden ist, werden die Developer Tools automatisch gestartet (mit cli.bat auto --project <path> --auto-port 9420)

4. Warten von 45 Sekunden, bis die Developer Tools bereit sind

5. Aufbau der WebSocket-Verbindung

6. Nachfolgende Verbindungen verwenden automatisch die bestehende Verbindung

Tipp: Nachdem Sie mit mp_setDefaultProject ein Standardprojekt festgelegt haben, müssen Sie bei der nächsten Verbindung kein Projekt mehr auswählen.