TP-Link Easy Smart Switch MCP

Servidor MCP TypeScript + Bun para conmutadores TP-Link y Mercury Easy Smart. Funciona a través de la interfaz web del conmutador y no depende de SNMP.

Destino predeterminado: http://192.168.3.10

Instalar como plugin de Codex

Instala Bun primero y luego añade el marketplace independiente network-tools y este plugin:

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

Inicia una nueva tarea de Codex después de la instalación para que se carguen las herramientas MCP y la habilidad de gestión de conmutadores.

Related MCP server: packet-coders-mcp

Modelos probados

La implementación actual se ha probado con estas capturas de la interfaz web y llamadas de estado de solo lectura:

• TP-Link TL-SE2106 en 192.168.3.10, firmware 1.8.1 Build 20251128 Rel.57341

• Mercury SE106 Pro en 192.168.3.11, firmware 1.0.0 Build 20240812 Rel.65021

Otros conmutadores TP-Link o Mercury Easy Smart pueden funcionar si usan las mismas páginas de interfaz web y endpoints CGI, pero aún no se han verificado.

Características confirmadas del dispositivo

• La interfaz de gestión está disponible en HTTP 80

• El formulario de inicio de sesión envía a POST /logon.cgi

• Los campos de inicio de sesión son username y password cifrada

• La página de inicio de sesión carga /cryp_new.js

• Las variables conocidas de la interfaz web incluyen g_product, g_year y encryptType

• Algunos firmware exponen el token de solicitud como una asignación numérica sin comillas, por ejemplo g_tid=1320064778;, en lugar de una cadena entre comillas. Otras páginas pueden solo hacer referencia a top.g_tid, por lo que los analizadores deben distinguir asignaciones de referencias.

Herramientas

Herramientas de solo lectura:

• get_switch_status: Devuelve un resumen del estado del conmutador

• get_port_status: Devuelve el estado de los puertos

• get_vlan_status: Devuelve el estado de la VLAN de puerto, VLAN 802.1Q, PVID y VLAN MTU

• get_trunk_status: Devuelve el estado de agregación de enlaces (trunking/LAG) de los puertos

• search_mac_address: Consulta mac_address_search.cgi para una dirección MAC y devuelve el puerto/VLAN aprendido cuando el conmutador tiene una entrada

• analyze_topology: Analiza dos o más conmutadores en cascada e informa del puerto de enlace entre conmutadores, la relación ascendente/descendente y la relación de VLAN a través del enlace

El análisis de topología funciona iniciando sesión en cada conmutador y consultando el CGI de búsqueda de MAC para obtener la MAC de gestión del conmutador peer. Si un conmutador informa de la MAC del peer en un puerto, ese puerto se utiliza como evidencia de enlace entre conmutadores. Cuando la búsqueda de MAC no puede confirmar el enlace, la detección recurre a pares de puertos SFP/10G activos como una estimación de baja confianza, prefiriendo la superposición de VLAN y usando el tráfico en vivo como un criterio de desempate. Estos conmutadores Easy Smart no tienen LLDP, por lo que esta correlación dentro de la banda es la señal disponible.

Herramientas de configuración CGI:

• configure_mtu_vlan: Genera o envía mtuVlanSet.cgi desde VlanMtuRpm.htm

• configure_port_vlan: Genera o envía pvlanSet.cgi desde VlanPortBasicRpm.htm

• configure_8021q_vlan: Genera o envía qvlanSet.cgi desde Vlan8021QRpm.htm

• configure_vlan_pvid: Genera o envía vlanPvidSet.cgi desde Vlan8021QPvidRpm.htm

• configure_trunk_group: Genera o envía port_trunk_set.cgi / port_trunk_display.cgi desde PortTrunkRpm.htm

• save_configuration: Genera o envía POST savingconfig.cgi desde SavingConfigRpm.htm

Las herramientas de configuración usan por defecto apply: false, lo que devuelve una vista previa de la solicitud en seco y no envía nada. Para escrituras reales se requiere todo lo siguiente:

• apply: true

• confirm: "APPLY"

• Inicio de sesión correcto

• Validación de reglas de la interfaz web superada

• Un token/top.g_tid legible

Instalación

bun install

Ejecutar durante el desarrollo

bun run src/index.ts

Compilar un binario

Windows:

bun run build:win

Plataforma actual:

bun run build

El resultado de la compilación se escribe en dist/.

Si un cliente MCP todavía informa de una versión anterior del servidor durante initialize, su command probablemente apunta a un ejecutable antiguo. Actualízalo a dist/tplink-easy-smart-switch-mcp.exe y reinicia el cliente.

Depurar MCP

Lista las herramientas MCP:

bun run debug

Llama a la herramienta de estado del conmutador:

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

Llama a la herramienta de estado de puertos:

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

Vista previa de las solicitudes de configuración sin enviarlas:

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 '{}'

Muestras de páginas

Las capturas de desarrollo de solo lectura se almacenan en:

• examples/tplink-192.168.3.10: conmutador TP-Link Easy Smart en 192.168.3.10

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

Incluyen páginas de VLAN, agregación de enlaces, respaldo/restauración de configuración y guardado de configuración, además de pvlan.js, qvlan.js y menuList.js. Estas muestras no contienen valores de SessionID ni contraseñas.

También puedes enviar JSON-RPC sin procesar:

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

Ejemplo de cliente MCP

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

Notas

El contenido de las páginas se analiza con un analizador DOM y se normaliza en resúmenes de título, formulario, marco, enlace, tabla y texto. Los datos de estado se extraen principalmente de variables JavaScript en páginas como MainRpm.htm, VlanPortBasicRpm.htm, Vlan8021QRpm.htm, Vlan8021QPvidRpm.htm, VlanMtuRpm.htm y PortTrunkRpm.htm.

En el firmware probado de TP-Link TL-SE2106 y Mercury SE106 Pro, MacSearchRpm.htm es un formulario de búsqueda en lugar de un volcado completo de la tabla de reenvío. Por lo tanto, la funcionalidad MAC compatible es search_mac_address, que sigue la lógica de la página y llama a mac_address_search.cgi con txt_macAddress_search, txt_vid_search y token.

La extracción de tokens admite g_tid entre comillas, g_tid numérico sin comillas y entradas token ocultas. El script de captura redacta tanto las asignaciones de g_tid entre comillas como las que no las llevan antes de guardar las muestras de desarrollo.

Las llamadas CGI de configuración usan un flujo de confirmación explícito. El desarrollo y la depuración usan por defecto el modo de prueba en seco. save_configuration también es una acción de escritura; sigue la lógica de la página de SavingConfigRpm.htm y usa POST savingconfig.cgi, pero no envía nada a menos que se confirme explícitamente.