TP-Link Easy Smart Switch MCP

TypeScript + Bun MCP-Server für TP-Link- und Mercury-Easy-Smart-Switches. Er arbeitet über die Web-UI des Switches und ist nicht von SNMP abhängig.

Standardziel: http://192.168.3.10

Als Codex-Plugin installieren

Installieren Sie zuerst Bun, und fügen Sie dann den unabhängigen network-tools-Marketplace und dieses Plugin hinzu:

codex plugin marketplace add qwe7002-ai/net-tool-plugins --ref main
codex plugin add tplink-easy-smart-switch-mcp@net-tool-plugins

Starten Sie nach der Installation eine neue Codex-Aufgabe, damit die MCP-Tools und der Switch-Management-Skill geladen werden.

Related MCP server: mcp-omada

Getestete Modelle

Die aktuelle Implementierung wurde mit diesen Web-UI-Snapshots und schreibgeschützten Statusabfragen getestet:

• TP-Link TL-SE2106 unter 192.168.3.10, Firmware 1.8.1 Build 20251128 Rel.57341

• Mercury SE106 Pro unter 192.168.3.11, Firmware 1.0.0 Build 20240812 Rel.65021

Andere TP-Link- oder Mercury-Easy-Smart-Switches funktionieren möglicherweise, wenn sie dieselben Web-UI-Seiten und CGI-Endpunkte verwenden, wurden aber noch nicht verifiziert.

Bestätigte Geräteeigenschaften

• Management-UI ist über HTTP 80 verfügbar

• Anmeldeformular sendet an POST /logon.cgi

• Anmeldefelder sind username und verschlüsseltes password

• Anmeldeseite lädt /cryp_new.js

• Bekannte Web-UI-Variablen umfassen g_product, g_year und encryptType

• Einige Firmware-Versionen legen das Anforderungstoken als nackte numerische Zuweisung wie g_tid=1320064778; statt als Zeichenfolge mit Anführungszeichen offen. Andere Seiten verweisen möglicherweise nur auf top.g_tid, daher müssen Parser Zuweisungen von Referenzen unterscheiden.

Werkzeuge

Schreibgeschützte Werkzeuge:

• get_switch_status: Einen Statusüberblick des Switches zurückgeben

• get_port_status: Portstatus zurückgeben

• get_vlan_status: Port-VLAN-, 802.1Q-VLAN-, PVID- und MTU-VLAN-Status zurückgeben

• get_trunk_status: Port-Trunking-/LAG-Status zurückgeben

• search_mac_address: mac_address_search.cgi für eine MAC-Adresse abfragen und den gelernten Port/das gelernte VLAN zurückgeben, wenn der Switch einen Eintrag hat

• analyze_topology: Zwei oder mehr kaskadierte Switches analysieren und den Inter-Switch-Link-Port, die Upstream-/Downstream-Beziehung und die VLAN-Beziehung über den Link melden

Die Topologieanalyse funktioniert, indem sie sich bei jedem Switch anmeldet und die MAC-Such-CGI nach der Verwaltungs-MAC des anderen Switches abfragt. Wenn ein Switch die Peer-MAC auf einem Port meldet, wird dieser Port als Inter-Switch-Link-Nachweis verwendet. Wenn die MAC-Suche den Link nicht bestätigen kann, greift die Erkennung auf aktive SFP-/10G-Portpaare als Schätzung mit geringer Konfidenz zurück, bevorzugt VLAN-Überlappung und nutzt Live-Datenverkehr als Tiebreaker. Diese Easy Smart Switches haben kein LLDP, daher ist diese In-Band-Korrelation das verfügbare Signal.

Konfigurations-CGI-Werkzeuge:

• configure_mtu_vlan: mtuVlanSet.cgi aus VlanMtuRpm.htm erzeugen oder absenden

• configure_port_vlan: pvlanSet.cgi aus VlanPortBasicRpm.htm erzeugen oder absenden

• configure_8021q_vlan: qvlanSet.cgi aus Vlan8021QRpm.htm erzeugen oder absenden

• configure_vlan_pvid: vlanPvidSet.cgi aus Vlan8021QPvidRpm.htm erzeugen oder absenden

• configure_trunk_group: port_trunk_set.cgi / port_trunk_display.cgi aus PortTrunkRpm.htm erzeugen oder absenden

• save_configuration: POST savingconfig.cgi aus SavingConfigRpm.htm erzeugen oder absenden

Konfigurationswerkzeuge verwenden standardmäßig apply: false, was eine Dry-Run-Anfragevorschau zurückgibt und nichts übermittelt. Echte Schreibvorgänge erfordern alle folgenden Bedingungen:

• apply: true

• confirm: "APPLY"

• Erfolgreiche Anmeldung

• Die Web-UI-Regelvalidierung wurde bestanden

• Ein lesbares token/top.g_tid

Installation

bun install

Während der Entwicklung ausführen

bun run src/index.ts

Eine Binärdatei erstellen

Windows:

bun run build:win

Aktuelle Plattform:

bun run build

Die Build-Ausgabe wird nach dist/ geschrieben.

Wenn ein MCP-Client während initialize weiterhin eine ältere Serverversion meldet, zeigt sein command wahrscheinlich auf eine alte ausführbare Datei. Aktualisieren Sie ihn auf dist/tplink-easy-smart-switch-mcp.exe und starten Sie den Client neu.

MCP debuggen

MCP-Werkzeuge auflisten:

bun run debug

Das Werkzeug für den Switch-Status aufrufen:

bun run debug -- --tool get_switch_status --host 192.168.3.10 --username admin --password your-password
bun run debug -- --tool get_switch_status --host 192.168.3.11

Das Werkzeug für den Portstatus aufrufen:

bun run debug -- --tool get_port_status --host 192.168.3.10 --username admin --password your-password

Konfigurationsanfragen in der Vorschau anzeigen, ohne sie zu übermitteln:

bun run debug -- --tool configure_mtu_vlan --params '{ "enabled": true }'
bun run debug -- --tool configure_port_vlan --params '{ "mode": "set", "vid": 1, "ports": "1,2" }'
bun run debug -- --tool configure_8021q_vlan --params '{ "mode": "set", "vid": 20, "name": "main", "untaggedPorts": "3", "taggedPorts": "5,6" }'
bun run debug -- --tool configure_vlan_pvid --params '{ "pvid": 20, "ports": "3" }'
bun run debug -- --tool configure_trunk_group --params '{ "mode": "set", "group": 1, "ports": "1,2" }'
bun run debug -- --tool save_configuration --params '{}'

Seitenbeispiele

Schreibgeschützte Entwicklungs-Snapshots sind gespeichert in:

• examples/tplink-192.168.3.10: TP-Link Easy Smart Switch unter 192.168.3.10

• examples/mercury-192.168.3.11: Mercury SE106 Pro unter 192.168.3.11

Sie enthalten VLAN-, Trunking-, Konfigurations-Backup-/Wiederherstellungs- und Konfigurationsspeicher-Seiten sowie pvlan.js, qvlan.js und menuList.js. Diese Beispiele enthalten keine SessionID-Werte oder Passwörter.

Sie können auch rohes JSON-RPC senden:

bun run debug -- --raw '{ "jsonrpc": "2.0", "id": 99, "method": "tools/list", "params": {} }'

MCP-Client-Beispiel

{
  "mcpServers": {
    "tplink-easy-smart-switch": {
      "command": "C:\\path\\to\\tplink-easy-smart-switch-mcp.exe",
      "env": {
        "TPLINK_HOST": "192.168.3.10",
        "TPLINK_USERNAME": "admin",
        "TPLINK_PASSWORD": "your-password"
      }
    }
  }
}

Hinweise

Seiteninhalte werden mit einem DOM-Parser geparst und in Zusammenfassungen für Titel, Formulare, Frames, Links, Tabellen und Text normalisiert. Statusdaten werden hauptsächlich aus JavaScript-Variablen in Seiten wie MainRpm.htm, VlanPortBasicRpm.htm, Vlan8021QRpm.htm, Vlan8021QPvidRpm.htm, VlanMtuRpm.htm und PortTrunkRpm.htm extrahiert.

Bei der getesteten Firmware des TP-Link TL-SE2106 und des Mercury SE106 Pro ist MacSearchRpm.htm ein Suchformular und kein vollständiger Forwarding-Table-Dump. Die unterstützte MAC-Funktion ist daher search_mac_address, die der Seitenlogik folgt und mac_address_search.cgi mit txt_macAddress_search, txt_vid_search und token aufruft.

Die Token-Extraktion unterstützt zitierte g_tid-Werte, nackte numerische g_tid-Werte und versteckte token-Eingaben. Das Erfassungsskript schwärzt sowohl zitierte als auch nackte g_tid-Zuweisungen, bevor es Entwicklungsbeispiele speichert.

Konfigurations-CGI-Aufrufe verwenden einen expliziten Bestätigungsablauf. Entwicklung und Debugging verwenden standardmäßig den Dry-Run-Modus. save_configuration ist ebenfalls eine Schreibaktion; sie folgt der Seitenlogik aus SavingConfigRpm.htm und verwendet POST savingconfig.cgi, übermittelt jedoch nur bei ausdrücklicher Bestätigung.