opus-tplink-mcp 1.0.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. opus_tplink_mcp-1.0.2/.env.example +11 -0
  2. opus_tplink_mcp-1.0.2/.github/dependabot.yml +17 -0
  3. opus_tplink_mcp-1.0.2/.github/workflows/ci.yml +56 -0
  4. opus_tplink_mcp-1.0.2/.github/workflows/publish.yml +54 -0
  5. opus_tplink_mcp-1.0.2/.gitignore +58 -0
  6. opus_tplink_mcp-1.0.2/.pre-commit-config.yaml +17 -0
  7. opus_tplink_mcp-1.0.2/CHANGELOG.md +56 -0
  8. opus_tplink_mcp-1.0.2/LICENSE +22 -0
  9. opus_tplink_mcp-1.0.2/PKG-INFO +301 -0
  10. opus_tplink_mcp-1.0.2/README.md +263 -0
  11. opus_tplink_mcp-1.0.2/docs/router/endpoints.txt +219 -0
  12. opus_tplink_mcp-1.0.2/pyproject.toml +137 -0
  13. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/__init__.py +27 -0
  14. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/_endpoints.py +246 -0
  15. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/catalog.py +714 -0
  16. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/config.py +70 -0
  17. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/features/__init__.py +226 -0
  18. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/features/access.py +180 -0
  19. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/features/admin.py +82 -0
  20. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/features/clients.py +110 -0
  21. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/features/core.py +290 -0
  22. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/features/ddns.py +56 -0
  23. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/features/device_log.py +188 -0
  24. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/features/dhcp.py +172 -0
  25. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/features/internet.py +109 -0
  26. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/features/lan.py +63 -0
  27. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/features/maintenance.py +139 -0
  28. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/features/nat.py +120 -0
  29. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/features/network.py +317 -0
  30. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/features/system.py +103 -0
  31. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/features/usb.py +138 -0
  32. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/features/vpn.py +250 -0
  33. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/features/wifi.py +167 -0
  34. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/features/wifi_extra.py +151 -0
  35. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/forms.py +491 -0
  36. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/journal.py +94 -0
  37. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/netcalc.py +87 -0
  38. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/py.typed +0 -0
  39. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/safety.py +562 -0
  40. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/server.py +116 -0
  41. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/tools.py +535 -0
  42. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/transport.py +391 -0
  43. opus_tplink_mcp-1.0.2/src/mcp_tplink_router/validate.py +151 -0
  44. opus_tplink_mcp-1.0.2/tests/__init__.py +1 -0
  45. opus_tplink_mcp-1.0.2/tests/conftest.py +72 -0
  46. opus_tplink_mcp-1.0.2/tests/fake_router.py +511 -0
  47. opus_tplink_mcp-1.0.2/tests/fixtures/shapes.json +2025 -0
  48. opus_tplink_mcp-1.0.2/tests/test_core.py +204 -0
  49. opus_tplink_mcp-1.0.2/tests/test_dhcp.py +264 -0
  50. opus_tplink_mcp-1.0.2/tests/test_encrypted_wire.py +71 -0
  51. opus_tplink_mcp-1.0.2/tests/test_forms_meta.py +10 -0
  52. opus_tplink_mcp-1.0.2/tests/test_multi_router.py +160 -0
  53. opus_tplink_mcp-1.0.2/tests/test_phase6.py +188 -0
  54. opus_tplink_mcp-1.0.2/tests/test_phase8.py +466 -0
  55. opus_tplink_mcp-1.0.2/tests/test_priority.py +210 -0
  56. opus_tplink_mcp-1.0.2/tests/test_transport.py +127 -0
  57. opus_tplink_mcp-1.0.2/tests/test_undo_keyfield.py +13 -0
@@ -0,0 +1,11 @@
1
+ # TP-Link Archer (BE series) - copy to .env (never commit .env)
2
+ TPLINK_HOST=192.168.0.1
3
+ # The plain admin password (the same one you type into the web UI)
4
+ TPLINK_PASSWORD=your_password_here
5
+ # Optional
6
+ # TPLINK_TIMEOUT=20
7
+ # TPLINK_JOURNAL_DIR=~/.local/state/mcp-tplink-router
8
+ # TPLINK_BACKUP_DIR=~/.local/state/mcp-tplink-router/backups
9
+ # TPLINK_DEVICE_LOG_DIR=~/.local/state/mcp-tplink-router/device-logs
10
+ # TPLINK_PROTECTED_MACS=00-00-5E-00-53-01 # devices whose VPN-client routing must never break silently
11
+ # TPLINK_ALLOW_FORBIDDEN=1 # lets router_raw_write send factory-reset/firmware-class ops (still needs a confirm token)
@@ -0,0 +1,17 @@
1
+ version: 2
2
+ updates:
3
+ - package-ecosystem: "pip"
4
+ directory: "/"
5
+ schedule:
6
+ interval: "weekly"
7
+ groups:
8
+ dev-dependencies:
9
+ patterns:
10
+ - "pytest*"
11
+ - "mypy"
12
+ - "ruff"
13
+
14
+ - package-ecosystem: "github-actions"
15
+ directory: "/"
16
+ schedule:
17
+ interval: "weekly"
@@ -0,0 +1,56 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main, master]
6
+ pull_request:
7
+ branches: [main, master]
8
+
9
+ jobs:
10
+ test:
11
+ runs-on: ubuntu-latest
12
+ strategy:
13
+ matrix:
14
+ python-version: ['3.10', '3.11', '3.12']
15
+
16
+ steps:
17
+ - uses: actions/checkout@v4
18
+
19
+ - name: Set up Python ${{ matrix.python-version }}
20
+ uses: actions/setup-python@v5
21
+ with:
22
+ python-version: ${{ matrix.python-version }}
23
+ cache: 'pip'
24
+
25
+ - name: Install dependencies
26
+ run: |
27
+ python -m pip install --upgrade pip
28
+ pip install -e ".[dev]"
29
+
30
+ - name: Lint with ruff
31
+ run: ruff check .
32
+
33
+ - name: Run tests (offline; a fake router, never the network)
34
+ run: pytest -q
35
+
36
+ security:
37
+ runs-on: ubuntu-latest
38
+ steps:
39
+ - uses: actions/checkout@v4
40
+
41
+ - name: Set up Python
42
+ uses: actions/setup-python@v5
43
+ with:
44
+ python-version: '3.11'
45
+
46
+ - name: Install dependencies
47
+ run: |
48
+ python -m pip install --upgrade pip
49
+ pip install bandit pip-audit
50
+
51
+ - name: Security check with bandit
52
+ run: bandit -r src/ -ll
53
+
54
+ - name: Dependency audit
55
+ run: pip-audit
56
+ continue-on-error: true
@@ -0,0 +1,54 @@
1
+ name: Publish to PyPI
2
+
3
+ # Runs when a GitHub release is published (tag vX.Y.Z). Uses PyPI Trusted Publishing (OIDC):
4
+ # no API token is stored in the repository.
5
+ on:
6
+ release:
7
+ types: [published]
8
+
9
+ permissions:
10
+ contents: read
11
+
12
+ jobs:
13
+ build:
14
+ runs-on: ubuntu-latest
15
+ steps:
16
+ - uses: actions/checkout@v4
17
+ - uses: actions/setup-python@v5
18
+ with:
19
+ python-version: "3.12"
20
+ - name: Tag must match the package version
21
+ run: |
22
+ tag="${GITHUB_REF_NAME#v}"
23
+ ver="$(python -c 'import tomllib;print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
24
+ echo "tag=$tag version=$ver"
25
+ test "$tag" = "$ver"
26
+ - name: Test
27
+ run: |
28
+ python -m pip install --upgrade pip
29
+ pip install -e ".[dev]"
30
+ pytest -q
31
+ - name: Build and check
32
+ run: |
33
+ pip install build twine
34
+ python -m build
35
+ twine check dist/*
36
+ - uses: actions/upload-artifact@v4
37
+ with:
38
+ name: dist
39
+ path: dist/
40
+
41
+ publish:
42
+ needs: build
43
+ runs-on: ubuntu-latest
44
+ environment:
45
+ name: pypi
46
+ url: https://pypi.org/project/opus-tplink-mcp/
47
+ permissions:
48
+ id-token: write
49
+ steps:
50
+ - uses: actions/download-artifact@v4
51
+ with:
52
+ name: dist
53
+ path: dist/
54
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,58 @@
1
+ # Environment
2
+ .env
3
+ .env.local
4
+
5
+ # Python
6
+ __pycache__/
7
+ *.py[cod]
8
+ *$py.class
9
+ *.so
10
+ .Python
11
+ build/
12
+ develop-eggs/
13
+ dist/
14
+ downloads/
15
+ eggs/
16
+ .eggs/
17
+ lib/
18
+ lib64/
19
+ parts/
20
+ sdist/
21
+ var/
22
+ wheels/
23
+ *.egg-info/
24
+ .installed.cfg
25
+ *.egg
26
+
27
+ # Virtual environments
28
+ .venv/
29
+ venv/
30
+ ENV/
31
+ env/
32
+
33
+ # IDE
34
+ .idea/
35
+ .vscode/
36
+ *.swp
37
+ *.swo
38
+ *~
39
+
40
+ # Testing
41
+ .pytest_cache/
42
+ .coverage
43
+ htmlcov/
44
+ .tox/
45
+ .nox/
46
+
47
+ # Playwright
48
+ playwright-report/
49
+ test-results/
50
+
51
+ # Debug
52
+ *.log
53
+ /tmp/
54
+ screenshots/
55
+
56
+ # OS
57
+ .DS_Store
58
+ Thumbs.db
@@ -0,0 +1,17 @@
1
+ repos:
2
+ - repo: https://github.com/pre-commit/pre-commit-hooks
3
+ rev: v4.5.0
4
+ hooks:
5
+ - id: trailing-whitespace
6
+ - id: end-of-file-fixer
7
+ - id: check-yaml
8
+ - id: check-added-large-files
9
+ - id: check-merge-conflict
10
+ - id: debug-statements
11
+
12
+ - repo: https://github.com/astral-sh/ruff-pre-commit
13
+ rev: v0.3.0
14
+ hooks:
15
+ - id: ruff
16
+ args: [--fix, --exit-non-zero-on-fix]
17
+ - id: ruff-format
@@ -0,0 +1,56 @@
1
+ # Changelog
2
+
3
+ ## 1.0.2 (2026-11-18)
4
+
5
+ ### Added
6
+ - **Archer BE3600 v2 (fw 1.0.4)** tested live: the full runbook (22 change types, each undone and
7
+ verified), MLO on/off, USB sharing and partitions, HTTPS remote management, reboot, and all reads.
8
+ - **Published on PyPI** (`pip install opus-tplink-mcp`, `uvx opus-tplink-mcp`) through a GitHub
9
+ workflow with Trusted Publishing (no stored token). An `opus-tplink-mcp` command was added next to
10
+ `mcp-tplink-router`.
11
+ - MLO on models that reboot after an MLO change (the router's `mloNetwork.reboot` flag): the dry
12
+ run says so, and the result reports `router_rebooting` instead of running the Wi-Fi health check
13
+ against a router that is going down.
14
+
15
+ ### Fixed
16
+ - `clients action=list` was empty on encrypted-protocol firmware (BE4800, BE3600). It now falls back
17
+ to the web UI's `smart_network?form=game_accelerator` `loadDevice` source.
18
+
19
+ ## 1.0.1 (2026-11-18)
20
+
21
+ ### Fixed
22
+ - **Encrypted protocol (e.g. Archer BE4800 1.0.x): requests are now sent exactly as the web UI sends
23
+ them.** Earlier versions went through `tplinkrouterc6u`'s JSON adapter (written for the BE805). That
24
+ adapter rebuilds the body with `dict(parse_qsl(...))`, which:
25
+ - collapsed repeated keys to their last value, so list fields such as MLO `selected_bands` reached
26
+ the router as a single band;
27
+ - dropped blank values, so clearing a field (e.g. the DMZ address) was silently ignored;
28
+ - copied every field into the URL query string, **including secrets such as Wi-Fi passwords**.
29
+ HTTPS still encrypted them on the wire, but they could appear in router or proxy URL logs.
30
+
31
+ The library is now used only for login and AES. The body goes out as the form string with
32
+ `Content-Type: application/x-www-form-urlencoded`. A regression test drives the real library class.
33
+ - **MLO on a BE4800 can now be switched on from off.** The router refused it because the adapter
34
+ above cut `selected_bands` down to one band. The MLO recipe now sends exactly the web UI's 7
35
+ fields (taken from a capture of the BE4800 web page's own requests). `band_select` is no longer
36
+ sent, because it is read-only and the UI never writes it. MLO also requires at least two bands.
37
+ - The DMZ "router keeps the address when cleared" quirk was an artifact of the same adapter, and
38
+ has been removed.
39
+
40
+ ### Changed
41
+ - `tplinkrouterc6u` is pinned to `>=5.23,<6`, since the fix depends on its class layout.
42
+
43
+ ### Verified live
44
+ - BE4800: MLO switched off and on twice through the tool. The Wi-Fi health check passed, per-band
45
+ `disabled_by` was intact, and the wireless-config diff was empty.
46
+ - BE4800: every write type previously verified on it was re-run (apply, verify, undo, verify
47
+ restored): 21 runbook operations plus advanced radio settings. The one exception is access
48
+ control, which is off-limits on that router. All 131 `router_get` sections and every tool's read
49
+ actions were swept. The only failures were 2 forms this model doesn't have (`afc`, `eco_mode`;
50
+ it uses `eco_mode_v2`), and those fail identically on the old path.
51
+ - The transport fails closed: if a future `tplinkrouterc6u` changes its class layout, requests stop
52
+ with an error instead of falling back to the JSON adapter.
53
+ - The BE9300 uses the plain protocol and is not affected.
54
+
55
+ ## 1.0.0 (2026-11-18)
56
+ - First public release.
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 the mcp-tplink-router authors (github.com/consigcody94/mcp-tplink-router)
4
+ Copyright (c) 2026 vehoelite
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining a copy
7
+ of this software and associated documentation files (the "Software"), to deal
8
+ in the Software without restriction, including without limitation the rights
9
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
+ copies of the Software, and to permit persons to whom the Software is
11
+ furnished to do so, subject to the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be included in all
14
+ copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
+ SOFTWARE.
@@ -0,0 +1,301 @@
1
+ Metadata-Version: 2.5
2
+ Name: opus-tplink-mcp
3
+ Version: 1.0.2
4
+ Summary: Complete, safety-first MCP server for TP-Link Archer (BE series) routers: 31 tools, dry runs, confirm tokens, journal and undo
5
+ Project-URL: Homepage, https://github.com/vehoelite/opus-tplink-mcp
6
+ Project-URL: Repository, https://github.com/vehoelite/opus-tplink-mcp
7
+ Project-URL: Documentation, https://github.com/vehoelite/opus-tplink-mcp#readme
8
+ Project-URL: Issues, https://github.com/vehoelite/opus-tplink-mcp/issues
9
+ Project-URL: Changelog, https://github.com/vehoelite/opus-tplink-mcp/releases
10
+ Author: vehoelite
11
+ Maintainer: vehoelite
12
+ License: MIT
13
+ License-File: LICENSE
14
+ Keywords: automation,home-automation,mcp,model-context-protocol,network,port-forwarding,router,tplink
15
+ Classifier: Development Status :: 4 - Beta
16
+ Classifier: Intended Audience :: Developers
17
+ Classifier: Intended Audience :: System Administrators
18
+ Classifier: License :: OSI Approved :: MIT License
19
+ Classifier: Operating System :: OS Independent
20
+ Classifier: Programming Language :: Python :: 3
21
+ Classifier: Programming Language :: Python :: 3.10
22
+ Classifier: Programming Language :: Python :: 3.11
23
+ Classifier: Programming Language :: Python :: 3.12
24
+ Classifier: Programming Language :: Python :: 3.13
25
+ Classifier: Topic :: Home Automation
26
+ Classifier: Topic :: System :: Networking
27
+ Classifier: Topic :: System :: Systems Administration
28
+ Classifier: Typing :: Typed
29
+ Requires-Python: >=3.10
30
+ Requires-Dist: mcp<2,>=1.5.0
31
+ Requires-Dist: python-dotenv>=1.0.0
32
+ Requires-Dist: requests>=2.31.0
33
+ Requires-Dist: tplinkrouterc6u<6,>=5.23
34
+ Provides-Extra: dev
35
+ Requires-Dist: pytest>=7.0.0; extra == 'dev'
36
+ Requires-Dist: ruff>=0.4.0; extra == 'dev'
37
+ Description-Content-Type: text/markdown
38
+
39
+ # opus-tplink-mcp
40
+
41
+ **A complete, safety-first MCP server for TP-Link Archer routers (Wi-Fi 7 / BE series).**
42
+ 31 tools covering virtually everything the router's web UI can do. Every change goes through
43
+ the same pipeline: **dry run → review → apply → verify → journal → undo**.
44
+
45
+ > Designed and re-engineered by **Claude Opus 5.5** (Anthropic), with **Fable 5.2** advising,
46
+ > for [vehoelite](https://github.com/vehoelite). Grown from
47
+ > [consigcody94/mcp-tplink-router](https://github.com/consigcody94/mcp-tplink-router) (MIT).
48
+ >
49
+ > Not affiliated with, endorsed by, or supported by TP-Link or Anthropic. "TP-Link" and "Archer"
50
+ > are trademarks of TP-Link. Use at your own risk: this software changes live network equipment.
51
+
52
+ ## Why this one
53
+
54
+ * **Everything, not just the basics.** All 238 forms the web UI uses are catalogued and reachable.
55
+ Every major feature also has a dedicated tool: WAN and IPv6, DoH/DoT, LAN, IPTV/VLAN, link
56
+ aggregation, DHCP, IP-MAC binding, VPN server and client, routing, access control, parental
57
+ controls, Wi-Fi (incl. WPS, MLO, OFDMA, guest), port forwarding, UPnP, DMZ, ALG, firewall,
58
+ EasyMesh, USB sharing, DDNS, backup/restore, firmware, diagnostics and administration.
59
+ * **Safe by construction.** Every write is a dry run first. Critical changes need a one-time
60
+ confirm token. Everything is journaled with before/after state and can be undone. Writes are
61
+ verified by re-reading the router, and a change the router silently ignores is reported as
62
+ `no_effect`, not "success".
63
+ * **Field-tested.** 84 write operations were exercised live across an Archer BE9300 (firmware
64
+ 1.2.4) and an Archer BE4800 (older, encrypted firmware): change, verify, undo, verify restored.
65
+ The BE4800 runs were repeated after the 1.0.1 transport fix (all but access control). An Archer
66
+ BE3600 (fw 1.0.4) passed the same runbook plus MLO and USB (see [Tested routers](#tested-routers)).
67
+ More than a dozen firmware quirks found that way are handled for you (see
68
+ [Firmware quirks](#firmware-quirks-handled)). `router_catalog` marks every operation `live`,
69
+ `ui` (from the web UI's code) or `none`.
70
+ * **Multi-router.** Manage several routers from one server, including older firmware that uses the
71
+ encrypted LuCI protocol (e.g. Archer BE4800 1.0.x).
72
+
73
+ ## Tools (31)
74
+
75
+ | Area | Tool | Highlights |
76
+ |---|---|---|
77
+ | Overview | `router_status` | WAN/LAN, internet state, Wi-Fi, clients, CPU/memory, firmware |
78
+ | | `router_get` / `router_catalog` / `router_raw_read` | Read any section or any of the 238 forms; per-operation risk tier and verification status |
79
+ | | `router_logs` | System log with level/type/text/time filters (never touches the router's own log filter) |
80
+ | | `device_log` | Everything about one MAC: lease, reservation, every log line mentioning it, parental-control sites and blocked attempts, access/VPN/IoT status, traffic. Plus a local per-device history beyond what the router keeps |
81
+ | Safety | `router_journal` / `router_undo` | Every change with before/after; undo with conflict detection |
82
+ | | `router_raw_write` | Escape hatch, gated by the catalog's risk tiers |
83
+ | Internet | `internet` | Connection type (DHCP, static, PPPoE, L2TP, PPTP, DS-Lite, v6plus, OCN), IPv6 (all modes), lease renew/release, **DNS-over-HTTPS / DNS-over-TLS**, MAC clone, WAN flow control, live speed / dual-NAT |
84
+ | LAN | `lan` | LAN IPv4/IPv6, port speed, **link aggregation (LACP)**, flow control, **IPTV / VLAN**, UDP proxy, NAT / hardware NAT boost, **ALG** |
85
+ | DHCP | `dhcp_server_set` / `dhcp_reservation` | Pool, lease, DNS; reservations with random-MAC detection |
86
+ | | `ip_mac_binding` | ARP binding, bind current devices, conflict checks |
87
+ | Wi-Fi | `wifi_set` | Per-band and guest SSIDs, passwords, channels, power, guest access/isolation, smart connect |
88
+ | | `wifi_extra` | **WPS** push button and PIN (returns the outcome and the paired MAC), Wi-Fi 7 MLO network, OFDMA/MU-MIMO, TWT, advanced radio settings, guest bandwidth/time limits, AFC |
89
+ | | `wifi_schedule` | Wi-Fi off periods |
90
+ | Mesh | `mesh` | EasyMesh status, devices, topology, naming/placing units, client steering, satellite reboot/unlink |
91
+ | VPN | `vpn_server` / `vpn_client` | OpenVPN / PPTP / L2TP / WireGuard servers and accounts; VPN-client profiles and per-device routing |
92
+ | Routing | `routing` | Static routes and the live routing table |
93
+ | Security | `access_control` / `parental_control` | Allow/block lists; HomeShield profiles, sites, pause internet |
94
+ | Ports | `port_forwarding` / `upnp` | Virtual servers, port triggering, DMZ; UPnP and its mappings |
95
+ | Clients | `clients` | Rename devices, per-device speed limits, IoT network isolation, game accelerator |
96
+ | USB | `usb` | Drives and partitions (scan, browse, share/hide a partition, eject), Samba/FTP/SFTP sharing, media server, Time Machine, USB 4G modem |
97
+ | DDNS | `ddns` | TP-Link DDNS, No-IP, DynDNS |
98
+ | Maintenance | `maintenance` | **Config backup and restore**, firmware (online, image upload, mesh satellites), **ping / traceroute**, operation mode, reboot schedule |
99
+ | Admin | `admin` | Admin password (RSA-encrypted like the web UI), remote management, HTTPS, local-management list, recovery e-mail, user permissions |
100
+ | System | `system` | **SPI firewall / ping replies**, LEDs, eco mode, time/NTP/DST, auto-update, QoS, device priority, reboot |
101
+
102
+ Read tools are annotated `readOnlyHint`; write tools are annotated `destructiveHint`.
103
+
104
+ ## How it talks to the router
105
+
106
+ * **Login:** `tplinkrouterc6u.TplinkRouterV1_11(...).authorize()` (RSA login), or the encrypted
107
+ `TplinkRouter` for older firmware. On the encrypted protocol the library is used only for login
108
+ and AES; the body still goes out as the web UI's form string. (The library's JSON adapter, made for
109
+ the BE805, collapses repeated keys, drops blank values and copies fields into the URL, so it is
110
+ bypassed. That adapter was why MLO couldn't be switched on through earlier versions on a BE4800.)
111
+ * **Requests:** our own `application/x-www-form-urlencoded` POST to
112
+ `/cgi-bin/luci/;stok=<stok>/admin/<module>?form=<form>`, the same requests the web UI sends. The
113
+ URL carries only `?form=`; `operation` and every field go in the body. Multipart is used for
114
+ backup, restore and firmware images.
115
+ * **One session per tool call:** the router allows one admin login, so each call logs in and
116
+ always logs out. If the web UI or the Tether app is logged in, log it out. (WPS pairing is the
117
+ one exception: it stays logged in until pairing ends, because logging out cancels WPS.)
118
+ * **Retries:** a failed login, or an ambiguous error while *reading or planning*, is retried once. A
119
+ write is **never resent**. If a write times out or the connection drops, the server logs in
120
+ again, re-reads, and reports whether the change was applied.
121
+
122
+ ## Safety model
123
+
124
+ | Tier | Examples | To apply |
125
+ |---|---|---|
126
+ | read | every read, ping/traceroute, config backup | nothing |
127
+ | normal | add a reservation, block a phone, change an SSID, WPS push | `apply=true` |
128
+ | critical | LAN IP, any WAN form, DHCP off, radio off, region, white-list access control, blocking **this machine**, VPN-client changes, admin / remote management, firmware, restore, reboot, operation mode, firewall off | `apply=true` **and** the `confirm_token` from the dry run |
129
+ | forbidden | factory reset, quick setup, cloud bind/unbind, debug shell | `router_raw_write` only, with `TPLINK_ALLOW_FORBIDDEN=1` in the server environment, plus a confirm token |
130
+
131
+ * **Dry run by default.** Without `apply=true` a write tool returns the plan, a field-level diff,
132
+ warnings, the risk tier and (for critical changes) a `confirm_token`. It sends nothing.
133
+ * **Confirm tokens** are an HMAC over the exact requests, which embed the values being replaced. A
134
+ token is valid for 5 minutes and is refused if the router changed since the dry run. Uploads are
135
+ bound to the file's SHA-256.
136
+ * **Forms** are read-merge-written, sending the field allowlist from the web UI's own code for that
137
+ form, or only the changed fields where the UI does that.
138
+ * **Table rows** are changed one at a time: re-load the table, find the row by its key, check it is
139
+ unchanged, then send the request with the fresh index.
140
+ * **Collateral check:** after every remove or update, the whole table is compared before and after.
141
+ If any other row vanished or changed, the result is `status: "collateral"`, the remaining steps
142
+ are not sent, and `router_undo` can re-add the lost rows.
143
+ * **Verification:** after a write the router is re-read, and the result is `applied`, a `mismatch`,
144
+ or `no_effect` (accepted but ignored).
145
+ * **Automatic backup:** before every critical change the router's config is downloaded to the backup
146
+ folder (`pre_change_backup` in the result; `TPLINK_AUTO_BACKUP=0` turns it off).
147
+ * **Wi-Fi health check:** after every Wi-Fi change the server re-reads the WPS PIN page, the read
148
+ that crashes when the band configuration is damaged. Transient timeouts while radios restart are
149
+ retried; a crash is reported loudly in `warnings_after` with the restore instructions.
150
+ * **Validation:** DHCP pools, reservations, bindings and routes are checked against the subnet, the
151
+ router's own IP, leases and conflicts. A **randomised/private MAC** gets a warning.
152
+ * **Journal:** `~/.local/state/mcp-tplink-router/journal.jsonl` (directory 0700, file 0600). The full
153
+ *before* state is fsynced before the first request; the exact fields sent (`wire`) and the
154
+ result follow. The journal keeps secrets so undo can restore them.
155
+ * **Undo:** `router_undo id=...` restores old values, removes inserts, re-adds removed rows and
156
+ swaps updates back. It refuses if the router changed since, unless you pass `force`. Reboots,
157
+ firmware and other one-way actions are not undoable.
158
+ * **Secrets** (PSKs, passwords, private/preshared keys, PINs, tokens) are masked in every result,
159
+ diff and error unless you pass `reveal=true`. Account passwords are read from files, never from
160
+ tool arguments.
161
+
162
+ ## Tested routers
163
+
164
+ | Router | Firmware | Protocol | Live-tested |
165
+ |---|---|---|---|
166
+ | Archer BE9300 | 1.2.4 | plain | full runbook (84 write types across both first routers), WPS, EasyMesh, USB, restore |
167
+ | Archer BE4800 | 1.0.x | encrypted | runbook, MLO, advanced radio, USB, all reads |
168
+ | Archer BE3600 v2 | 1.0.4 | encrypted | runbook, MLO (this model reboots after an MLO change), USB, HTTPS remote management, reboot, all reads |
169
+
170
+ Other Archer BE models with the same web UI (Archer BE*xxxx*, firmware from 2024 on) should work.
171
+ `router_catalog` shows which operations are confirmed live and which come from the web UI's code.
172
+
173
+ ## Install
174
+
175
+ ```bash
176
+ pip install opus-tplink-mcp # or: uvx opus-tplink-mcp
177
+ ```
178
+
179
+ From source: `python -m venv venv && venv/bin/pip install -e ".[dev]"`.
180
+
181
+ ## Configuration
182
+
183
+ Copy `.env.example` to `.env`, or pass the variables from your MCP client config.
184
+
185
+ | Variable | Default | Meaning |
186
+ |---|---|---|
187
+ | `TPLINK_HOST` | `192.168.0.1` | Router address (`https://...` if it redirects) |
188
+ | `TPLINK_PASSWORD` | | The **plain** admin password |
189
+ | `TPLINK_TIMEOUT` | `20` | Per-request timeout (s) |
190
+ | `TPLINK_JOURNAL_DIR` | `~/.local/state/mcp-tplink-router` | Journal (also the default parent of backups and device logs) |
191
+ | `TPLINK_BACKUP_DIR` | `<journal>/backups` | Where `maintenance action=backup` saves config files (mode 600) |
192
+ | `TPLINK_DEVICE_LOG_DIR` | `<journal>/device-logs` | Per-MAC histories written by `device_log action=record` |
193
+ | `TPLINK_AUTO_BACKUP` | `1` | Download a config backup before every critical change (`0` = off) |
194
+ | `TPLINK_PROTECTED_MACS` | | Comma-separated MACs whose VPN-client routing must not break silently (e.g. a filtered child's laptop). Changes affecting them are called out by name. |
195
+ | `TPLINK_ALLOW_FORBIDDEN` | unset | `1` lets `router_raw_write` send forbidden-tier operations |
196
+
197
+ MCP client entry (stdio):
198
+
199
+ ```json
200
+ {"command": "uvx", "args": ["opus-tplink-mcp"], "env": {"TPLINK_HOST": "192.168.0.1", "TPLINK_PASSWORD": "..."}}
201
+ ```
202
+
203
+ (or `"command": "/path/to/venv/bin/opus-tplink-mcp"` for a local install)
204
+
205
+ ### Several routers
206
+
207
+ `TPLINK_HOST`/`TPLINK_PASSWORD` is router `main`. To add more:
208
+
209
+ ```
210
+ TPLINK_ROUTERS=upstairs
211
+ TPLINK_UPSTAIRS_HOST=https://192.168.1.1
212
+ TPLINK_UPSTAIRS_PASSWORD_FILE=/path/to/router2.pw
213
+ TPLINK_UPSTAIRS_PROTOCOL=encrypted # older firmware (e.g. BE4800 1.0.x): encrypted LuCI
214
+ ```
215
+
216
+ * Every tool takes `router` (default `main`). `router_status` lists the configured routers.
217
+ * Journal entries record the router, and `router_undo` always targets the router the change was made on.
218
+ * Risk tiers are per router. VPN-client protection applies to `main`; on other routers,
219
+ access-control mode/enable and parental internet pause are critical. Removing the last
220
+ allowlisted device is critical on every router.
221
+ * Forms another firmware lacks return `no such callback`, with a hint.
222
+ * Multipart uploads/downloads (backup, restore, firmware) are implemented for the plain protocol.
223
+
224
+ ### A per-device log
225
+
226
+ `device_log action=record mac=...` appends only what is new since the last record: online/offline,
227
+ router log lines, parental-control sites and blocked attempts. Run it on a timer for a continuous
228
+ history that outlives the router's own (daily) data, then read it with `action=history`.
229
+
230
+ ## Firmware quirks handled
231
+
232
+ Found against a live BE9300 (fw 1.2.4); each one is encoded in the catalog or the tools:
233
+
234
+ * **WPS:** `option=connect` starts push-button pairing; `pbc`/`pin` only poll the status. The router
235
+ **cancels WPS when the admin session logs out**, so `wps_push` stays logged in and polls until a
236
+ device pairs or the window closes. Status replies take ~18 s.
237
+ * **Guest Wi-Fi:** only changed fields may be sent. A full write with blank `passwd_cycle` is refused.
238
+ * **DoH/DoT:** `server_list` must be sent as a repeated `server_list=` field and included with every
239
+ write ("no server found" otherwise). JSON wipes the list, and `server_list[]` is refused.
240
+ * **IPTV / link aggregation:** `port_settings` must always be sent as JSON, or the router returns
241
+ HTTP 500. Saving IPTV restarts the network for about 40 s.
242
+ * **OFDMA:** on routers with the combined setting, the standalone switch is ignored. Use
243
+ `ofdma_mimo` (`all` / `ofdma_only` / `disabled`).
244
+ * **IP-MAC binding:** refused while the IP is DHCP-reserved for another MAC. The router drops custom
245
+ names on bindings and reservations.
246
+ * **Speed limits** are stored verbatim (`on`/`off`). **WPS wait time** is read-only.
247
+ * **LAN IPv6 address** is recomputed by the router on every save.
248
+ * **MAC clone and WAN changes** reconnect the WAN, and the ISP may assign a **new public IP**.
249
+ Anything allowlisting your old IP (cloud firewalls, DNS-filter locations) will need updating.
250
+ * **Admin password** fields are RSA-encrypted with per-field keys from the read. The server
251
+ encrypts at send time, so the dry run's confirm token stays valid.
252
+ * **MLO network:** off = only `enable=off`. On = exactly the web UI's 7 fields, with `selected_bands`
253
+ as a repeated key and at least two bands (`band_select` is read-only, and the UI never sends it).
254
+ The recipe was taken from a capture of the BE4800 web page's own requests, then switched off/on
255
+ twice through the tool on a BE4800, with an empty wireless-config diff afterwards. A malformed MLO
256
+ write on a BE9300 once switched MLO off **and made the firmware drop an internal per-band field
257
+ (`disabled_by`)**: Wi-Fi kept working, but every WPS start failed ("Interface return exception")
258
+ until a config restore. After every Wi-Fi change the server now reads the WPS page as a health
259
+ check. Some models (Archer BE3600) **reboot after an MLO change**, as their web UI warns. The
260
+ server reads the router's capability flags, flags the change as critical in the dry run, and
261
+ reports `router_rebooting` instead of probing a router that is going down.
262
+ * **Connected clients** on encrypted-protocol firmware (BE4800, BE3600) are not in
263
+ `status?form=all`; they are read from the web UI's `loadDevice` source.
264
+ * **User-permission switches** are accepted but ignored for a normal admin login (`no_effect`).
265
+ * **Eco mode** takes `strong` / `medium` / `weak`; DST and the 24-hour clock use `dst_enable` /
266
+ `hour24_enable`.
267
+ * **USB sharing** is saved as ONE request (server name + `enable="on,off,off"` for Samba/FTP/FTP-internet);
268
+ per-service saves are refused. The server name can't be written on its own.
269
+ * **Fields the router keeps when blanked** (the custom WAN MAC) don't count as a failed restore.
270
+ * **TP-Link DDNS** has no refresh operation (it updates itself).
271
+
272
+ ## Known limitations
273
+
274
+ * `mesh action=pair` is **disabled**. In testing, starting the satellite search and a WPS session in
275
+ the same login locked a BE9300 up badly enough that a factory reset was needed. Pair satellites
276
+ with the router's WPS button, `wifi_extra action=wps_push`, or the web UI.
277
+ * `maintenance action=operation_mode` (router ↔ AP/repeater) is implemented but was not switched
278
+ live. With the router connected straight to an ISP box, AP mode can leave it unreachable.
279
+ * `usb action=eject` is accepted by the router, but in testing the partitions kept reading as
280
+ mounted until the drive was unplugged, so treat it as "safe to unplug" only after checking.
281
+ * **Not yet exercised live** (implemented from the web UI's code, covered by offline tests):
282
+ firmware image upload and online update (no newer firmware was available), Time Machine, DDNS
283
+ login, WPS client-PIN pairing, mesh satellite operations, adding WireGuard server
284
+ accounts (the router refuses the format tried so far), parental-control profile edits and
285
+ operation mode. Operations marked `ui` or `none` in
286
+ `router_catalog` fall in this group.
287
+
288
+ ## Development
289
+
290
+ ```bash
291
+ venv/bin/pytest -q # offline: a fake router; any socket/requests use fails the test
292
+ venv/bin/ruff check .
293
+ ```
294
+
295
+ * `docs/router/endpoints.txt` lists every form the web UI references.
296
+ * `tests/fixtures/shapes.json` holds live field *shapes* (no values) for the readable forms. The
297
+ catalog's writable fields are checked against it.
298
+
299
+ ## License
300
+
301
+ MIT. See [LICENSE](LICENSE).