TP-Link Easy Smart Switch MCP

TP-Link 및 Mercury Easy Smart 스위치용 TypeScript + Bun MCP 서버입니다. 스위치 웹 UI를 통해 작동하며 SNMP에 의존하지 않습니다.

기본 대상: http://192.168.3.10

Codex 플러그인으로 설치

먼저 Bun을 설치한 다음, 독립적인 network-tools 마켓플레이스와 이 플러그인을 추가하세요:

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

설치 후 새 Codex 작업을 시작하면 MCP 도구와 스위치 관리 스킬이 로드됩니다.

Related MCP server: mcp-omada

테스트된 모델

현재 구현체는 다음 Web UI 스냅샷과 읽기 전용 상태 호출로 테스트되었습니다:

• 192.168.3.10의 TP-Link TL-SE2106, 펌웨어 1.8.1 Build 20251128 Rel.57341

• 192.168.3.11의 Mercury SE106 Pro, 펌웨어 1.0.0 Build 20240812 Rel.65021

다른 TP-Link 또는 Mercury Easy Smart 스위치도 동일한 Web UI 페이지와 CGI 엔드포인트를 사용한다면 작동할 수 있지만 아직 검증되지는 않았습니다.

확인된 장치 특성

• 관리 UI는 HTTP 80에서 사용할 수 있습니다.

• 로그인 양식은 POST /logon.cgi로 전송됩니다.

• 로그인 필드는 username과 암호화된 password입니다.

• 로그인 페이지는 /cryp_new.js를 로드합니다.

• 알려진 Web UI 변수로는 g_product, g_year, encryptType이 있습니다.

• 일부 펌웨어는 요청 토큰을 따옴표로 묶인 문자열이 아닌 g_tid=1320064778;과 같은 숫자 할당으로 노출합니다. 다른 페이지는 top.g_tid만 참조할 수 있으므로 파서는 할당과 참조를 구분해야 합니다.

도구

읽기 전용 도구:

• get_switch_status: 스위치 상태 요약을 반환합니다.

• get_port_status: 포트 상태를 반환합니다.

• get_vlan_status: 포트 VLAN, 802.1Q VLAN, PVID 및 MTU VLAN 상태를 반환합니다.

• get_trunk_status: 포트 트렁킹/LAG 상태를 반환합니다.

• search_mac_address: mac_address_search.cgi에 하나의 MAC 주소를 조회하고 스위치에 항목이 있을 때 학습된 포트/VLAN을 반환합니다.

• analyze_topology: 두 대 이상의 캐스케이드 스위치를 분석하고 스위치 간 링크 포트, 업스트림/다운스트림 관계, 그리고 링크를 통한 VLAN 관계를 보고합니다.

토폴로지 분석은 각 스위치에 로그인하고 MAC 검색 CGI에 피어 스위치의 관리 MAC을 조회하는 방식으로 작동합니다. 스위치가 포트에서 피어 MAC을 보고하면 해당 포트를 스위치 간 링크 증거로 사용합니다. MAC 검색으로 링크를 확인할 수 없으면, 감지 기능은 활성 SFP/10G 포트 쌍을 낮은 신뢰도의 추측으로 폴백하고 VLAN 중복을 우선하며 라이브 트래픽을 타이브레이커로 사용합니다. 이 Easy Smart 스위치에는 LLDP가 없으므로 이 대역 내 상관 관계가 사용 가능한 신호입니다.

구성 CGI 도구:

• configure_mtu_vlan: VlanMtuRpm.htm에서 mtuVlanSet.cgi를 생성하거나 제출합니다.

• configure_port_vlan: VlanPortBasicRpm.htm에서 pvlanSet.cgi를 생성하거나 제출합니다.

• configure_8021q_vlan: Vlan8021QRpm.htm에서 qvlanSet.cgi를 생성하거나 제출합니다.

• configure_vlan_pvid: Vlan8021QPvidRpm.htm에서 vlanPvidSet.cgi를 생성하거나 제출합니다.

• configure_trunk_group: PortTrunkRpm.htm에서 port_trunk_set.cgi / port_trunk_display.cgi를 생성하거나 제출합니다.

• save_configuration: SavingConfigRpm.htm에서 POST savingconfig.cgi를 생성하거나 제출합니다.

구성 도구는 기본적으로 apply: false로 설정되어 있어 드라이런 요청 미리보기를 반환하고 아무것도 제출하지 않습니다. 실제 쓰기에는 다음이 모두 필요합니다:

• apply: true

• confirm: "APPLY"

• 로그인 성공

• Web UI 규칙 검증 통과

• 읽을 수 있는 token/top.g_tid

설치

bun install

개발 중 실행

bun run src/index.ts

바이너리 빌드

Windows:

bun run build:win

현재 플랫폼:

bun run build

빌드 출력은 dist/에 기록됩니다.

MCP 클라이언트가 initialize 중에 여전히 이전 서버 버전을 보고한다면, 해당 command가 이전 실행 파일을 가리키고 있을 가능성이 높습니다. dist/tplink-easy-smart-switch-mcp.exe로 업데이트하고 클라이언트를 다시 시작하세요.

MCP 디버깅

MCP 도구 나열:

bun run debug

스위치 상태 도구 호출:

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

포트 상태 도구 호출:

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

제출하지 않고 구성 요청 미리보기:

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

페이지 샘플

읽기 전용 개발 스냅샷은 다음 위치에 저장됩니다:

• examples/tplink-192.168.3.10: 192.168.3.10의 TP-Link Easy Smart 스위치

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

여기에는 VLAN, 트렁킹, 구성 백업/복원, 구성 저장 페이지와 함께 pvlan.js, qvlan.js, menuList.js가 포함됩니다. 이 샘플에는 SessionID 값이나 비밀번호가 포함되어 있지 않습니다.

원시 JSON-RPC를 보낼 수도 있습니다:

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

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

참고 사항

페이지 콘텐츠는 DOM 파서