legacy-switch-mcp 0.1.0__tar.gz

legacy_switch_mcp-0.1.0/.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      minor-and-patch:
+        update-types: ["minor", "patch"]
+    labels: ["dependencies"]
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      actions:
+        patterns: ["*"]
+    labels: ["dependencies"]

legacy_switch_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv python install ${{ matrix.python }}
+      - run: uv sync --extra dev --python ${{ matrix.python }}
+      - run: uv run --python ${{ matrix.python }} pytest

legacy_switch_mcp-0.1.0/.github/workflows/dependabot-automerge.yml

@@ -0,0 +1,22 @@
+# Auto-merge patch/minor Dependabot PRs once CI is green.
+# OFF until the repository variable AUTO_MERGE_DEPENDABOT is set to "true". Set it only after the repo is public
+# and a ruleset requires the CI checks: without a required check, --auto would merge immediately.
+name: Dependabot auto-merge
+on: pull_request
+permissions:
+  contents: write
+  pull-requests: write
+jobs:
+  automerge:
+    if: github.actor == 'dependabot[bot]' && vars.AUTO_MERGE_DEPENDABOT == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - id: meta
+        uses: dependabot/fetch-metadata@v3
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+      - if: steps.meta.outputs.update-type != 'version-update:semver-major'
+        run: gh pr merge --auto --squash "$PR_URL"
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

legacy_switch_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,18 @@
+# Publish to PyPI when a GitHub release is published. Uses PyPI trusted publishing (OIDC): no token is stored anywhere.
+# One-time setup on pypi.org: add a "pending publisher" for this repo, workflow publish.yml, environment "pypi".
+name: Publish
+on:
+  release:
+    types: [published]
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

legacy_switch_mcp-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/

legacy_switch_mcp-0.1.0/AGENTS.md

@@ -0,0 +1,28 @@
+# Working on legacy-switch-mcp (people and agents)
+
+MCP server for old smart switches (D-Link DGS-1100, USRobotics 7724). Changes are **plan, then apply**; nothing is written to a switch otherwise.
+Layout: `src/legacy_switch_mcp/` (server, per-vendor web sessions, change planners, safety, maintenance), `tests/` (fake switches, no hardware), `scripts/` (hardware-only), `docs/`.
+
+## Commands
+```bash
+uv sync --extra dev
+uv run pytest                      # 112 tests, ~1 s, fake switches only
+```
+CI runs the same on Python 3.11, 3.12 and 3.13: do not use newer-only features.
+
+## Rules that matter most
+- **Never post to a switch outside the allow-lists** in `dlinkweb.py` / `webui.py`, and never add a write path without a fake-switch test first. A write is "proven" only after a round trip on an unused, unprotected port; label it so in the README status table with the date, and say "fake-tested only" otherwise.
+- **Do not run anything in `scripts/` or point tools at a real switch** unless the maintainer asked for it in this session. Maintenance stays off (`SWITCH_MCP_ENABLE_MAINTENANCE` unset) by default.
+- **Nothing real in the repo**: fixtures, docs, tests, commit messages, issues and PRs use RFC 5737 addresses (192.0.2.x, 198.51.100.x, 203.0.113.x) and `00-00-5E-00-53-xx` MACs. No real hostnames, serials, passwords, tokens or personal names. Config and state live in `~/.config/switch-mcp` and `~/.local/state/switch-mcp`, never here.
+- **Redact by value, not by key name.** When showing config or command output, mask anything shaped like a secret (long random strings, `user:key@host` URLs, `Authorization` headers) instead of trusting that a field is named "password". If a secret is exposed, say so and treat it as leaked.
+- **Credentials are the maintainer's to create.** Do not mint, rotate or store tokens or keys yourself; give the exact command instead. Never put credentials in git config, remotes or files in this repo.
+
+## Working method
+- **Verify, don't trust.** Run the tests, read the actual diff, and check claimed results yourself before saying something is done. A confident summary is not evidence; report failures and skipped steps plainly, with the output.
+- **Branch, don't commit to `main`.** Work on a branch, run `uv run pytest` before pushing, and open a PR. Commits keep the existing author identity; agent-assisted commits end with a `Co-Authored-By:` trailer naming the agent.
+- **Keep the MCP footprint small.** Every registered tool adds its description to every request of a session. Keep descriptions short, register only usable tools, and re-measure the token table in the README if the tool set changes.
+- **Reproduce before fixing.** Add a failing fake-switch test for a bug first. The fakes only know what has been learned; when hardware disagrees with a fake, fix the fake too so the regression fails a test (see "Found on hardware" in the README).
+- **Docs follow code.** `docs/ADDING-SWITCHES.md` is the process for new models and vendors; `docs/PROTOCOL.md` holds wire formats. Update them in the same change.
+
+## Dependencies
+Dependabot opens weekly PRs (`uv`, `github-actions`). A bump is acceptable when CI is green; read the changelog for `mcp` (the SDK defines the tool schema) and re-run `tests/test_server.py` expectations for the registered tool set.

legacy_switch_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

legacy_switch_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ion9
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

legacy_switch_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.5
+Name: legacy-switch-mcp
+Version: 0.1.0
+Summary: MCP server for old smart switches (D-Link DGS-1100, USRobotics 7724): plan-then-apply VLAN, port and trunk changes with read-back verification and rollback
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<2,>=1.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# legacy-switch-mcp
+
+[![CI](https://github.com/Nebulous-Ideas/legacy-switch-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Nebulous-Ideas/legacy-switch-mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Python 3.11+](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue.svg)
+![MCP server](https://img.shields.io/badge/MCP-server-8A2BE2.svg)
+
+<!-- mcp-name: io.github.Nebulous-Ideas/legacy-switch-mcp -->
+
+> **Use at your own risk.** This tool can change VLANs, reboot switches and factory-reset them, and a bad change can cut you off from the switch.
+> It has been proven on hardware on exactly two models (USRobotics 7724, D-Link DGS-1100-08) and is fake-switch tested only elsewhere. Read the plan before applying it,
+> list your uplinks in `protected_ports`, and keep the maintenance switch off unless you need it. Provided as is, without warranty (see `LICENSE`).
+
+An MCP server for two old "smart" switch families that no other MCP covers: the **USRobotics 7724** (24-port gigabit, port-based VLANs) and the
+**D-Link DGS-1100** EasySmart series (802.1Q). Both are Cameo-built and share a UDP discovery protocol (see `docs/PROTOCOL.md`).
+
+It reads state and makes changes the careful way: **plan, then apply**. A plan writes nothing; it shows the exact differences and the risks (for VLANs:
+which connected ports would stop reaching each other, which ports leave the management VLAN). Applying needs the plan id and `confirm=true`, re-reads the switch
+and refuses if it changed, saves a snapshot, writes, reads back to verify, and returns a rollback plan.
+
+## Install
+No clone needed (needs [uv](https://docs.astral.sh/uv/)). First create `~/.config/switch-mcp/switches.json` and a password for each switch (see Setup below), then add the server to your MCP client:
+```bash
+claude mcp add switch -- uvx legacy-switch-mcp                                    # Claude Code
+claude mcp add switch --env SWITCH_MCP_TOOLSETS=read -- uvx legacy-switch-mcp     # look-only (fewest tokens)
+```
+Claude Desktop, Cursor and other clients take the same command in their JSON config:
+```json
+{"mcpServers": {"switch": {"command": "uvx", "args": ["legacy-switch-mcp"], "env": {"SWITCH_MCP_TOOLSETS": "read"}}}}
+```
+Until the package is on PyPI, use `uvx --from git+https://github.com/Nebulous-Ideas/legacy-switch-mcp legacy-switch-mcp`.
+
+## Tools
+| Tool | What it does |
+|---|---|
+| `list_switches`, `list_interfaces` | configured switches; IPv4 interfaces on this host |
+| `discover(interface)`, `probe(host)` | UDP discovery (broadcast+multicast), or ask one switch by IP |
+| `get_state(switch)` | parsed state: VLANs, ports, mirror (and D-Link system/trunk) |
+| `read_page(switch, page)`, `overview(switch)` | raw page data |
+| `backup_state`, `list_snapshots`, `describe_switch` | save the parsed state; list saved states; markdown description for a wiki |
+| `backup_config`, `backup_firmware`, `list_files` | download the configuration (both) / firmware (D-Link) file into the state directory, mode 0600; the content is never returned |
+| `plan_password`, `plan_ip`, `plan_reboot`, `plan_factory_reset`, `plan_restore_config` | maintenance plans (both vendors; reboot D-Link only). **Applying needs the server started with `SWITCH_MCP_ENABLE_MAINTENANCE=1`** |
+| `plan_vlan_group`, `plan_port`, `plan_mirror`, `plan_trunk`, `plan_system` | USRobotics changes (plan only) |
+| `dlink_plan_vlan`, `dlink_plan_vlan_delete`, `dlink_plan_pvid`, `dlink_plan_port`, `dlink_plan_mirror`, `dlink_plan_trunk`, `dlink_plan_trunk_delete`, `dlink_plan_system`, `dlink_plan_save` | D-Link changes (plan only) |
+| `apply_plan(plan_id, confirm=true)` | apply a plan from this server session |
+
+## Setup
+```bash
+uv sync --extra dev && uv run pytest
+mkdir -p ~/.config/switch-mcp && cp switches.example.json ~/.config/switch-mcp/switches.json   # then edit the addresses
+```
+Passwords are never tool arguments and are never returned. Provide each as `SWITCH_MCP_PASSWORD_<NAME>` (name upper-cased, `-` becomes `_`) or in
+`~/.config/switch-mcp/passwords.json` (`{"usr-switch": "..."}`, mode 0600; a looser mode is refused).
+
+**Factory-default passwords** (so a reset switch is usable): both vendors document `admin` as the default (USRobotics quick-install guide; D-Link
+EasySmart manuals, which also give 10.90.90.90 as the default D-Link address and 192.168.0.1 for the USRobotics). Change it after a reset.
+This repository contains no other credentials; tests use a throwaway `pw`.
+
+Register with Claude Code only for switch work (every MCP server adds its tool descriptions to every request of the session):
+```bash
+claude mcp add switch -- uv run --project /path/to/legacy-switch-mcp legacy-switch-mcp
+```
+
+### Keeping the session cost small
+Only the tools that can be used are registered. Measured with all 33 tools registered the schema text was about 4,350 tokens; now:
+| Setup | Tools | Tokens per request (approx.) |
+|---|---|---|
+| default: read + files + a set for each vendor in `switches.json`, maintenance off | 28 (both vendors) | 2,450 |
+| default + `SWITCH_MCP_ENABLE_MAINTENANCE=1` (adds the 5 maintenance plan tools) | 33 | 2,850 |
+| `SWITCH_MCP_TOOLSETS=read,files,dlink` (D-Link work only) | 23 | 1,800 |
+| `SWITCH_MCP_TOOLSETS=read` (look only, no plan or apply tools) | 10 | 600 |
+`SWITCH_MCP_TOOLSETS` takes a comma list of `read`, `files`, `usr`, `dlink`, `maintenance`, or `all`; `apply_plan` is registered whenever any plan set is. A typo is an error, not a silent fallback.
+Maintenance plan tools are not registered at all unless the maintenance switch is on (or `maintenance` is named in `SWITCH_MCP_TOOLSETS`); a registered one still refuses to apply without the switch.
+For day-to-day looking: `claude mcp add switch --env SWITCH_MCP_TOOLSETS=read -- uv run ...`; for a change session leave it unset; for maintenance add `--env SWITCH_MCP_ENABLE_MAINTENANCE=1`.
+
+## Testing
+```bash
+uv sync --extra dev && uv run pytest            # 112 tests against the fake switches; no hardware needed
+uv run python scripts/e2e_check.py <dlink-switch> <trunk-group> <port> <port>   # real MCP stdio check against a D-Link, on IDLE ports only
+```
+`e2e_check.py` starts the server as a client would, round-trips a system-location change and a trunk on the two idle ports you name (each rolled back), downloads a config, and
+checks that a reboot plan is refused while maintenance is off. Run it only against a switch where those ports have no link; it leaves the switch as it found it.
+Hardware-only checks (outages, factory reset, password) are in `scripts/maint.py`, `scripts/rotate_password.py` and `scripts/recover_after_reset.py`; see `docs/ADDING-SWITCHES.md` for the proof sequence.
+
+## Safety
+- **Protected ports**: list uplinks in `switches.json` (`"protected_ports": [24]`); plans that touch them are refused unless `allow_protected=true`.
+- **Rollback survives failure**: the rollback plan is written to disk before any write, so if the switch stops answering mid-change it can still be applied from a new session.
+- **Audit log**: every plan, refusal and apply is appended to `~/.local/state/switch-mcp/audit.jsonl` (no credentials).
+- **Maintenance is off by default.** Password, IP address, reboot, factory reset and config restore plan normally but refuse to apply unless the server was started with
+  `SWITCH_MCP_ENABLE_MAINTENANCE=1` (`claude mcp add switch --env SWITCH_MCP_ENABLE_MAINTENANCE=1 -- uv run ...`). The low-level writers refuse too. Passwords are generated by the server,
+  verified by logging in, stored in `passwords.json` (old one kept in `passwords.prev.json`; a `passwords.pending.json` exists while a change is in flight) and never shown or logged. An IP change refuses
+  unless `allow_ip_change=true`, if the address answers a ping, or if it is outside the gateway's subnet, and updates `switches.json` only after logging in at the new address. Reboot, reset and restore drop every port,
+  so they are refused while `protected_ports` exist unless `allow_protected=true`; a factory reset first saves the parsed state and the configuration file; a restore only accepts a file this server saved for the same switch (checksum checked).
+- Only ten D-Link CGIs (VLAN add/delete, PVID, port, mirror, system name/location/timeout, save, three trunk CGIs) and five USRobotics forms (VLAN group, port, mirror, trunk, system name/location/timeout)
+  can ever be posted in normal operation. Behind the maintenance switch: five more D-Link CGIs (password, IP, reboot, reset, restore) and four USRobotics forms (password, system with IP, reset, restore);
+  two D-Link CGIs only download a file. Firmware upgrade, 802.1Q-mode changes and anything else cannot be posted.
+- Plans live in server memory for 10 minutes; snapshots go to `~/.local/state/switch-mcp/`.
+- One web session at a time (these switches evict a second login), always logged out. If a human has the web page open, close it first.
+- The switches apply changes live; they may not keep them across a power loss unless saved from their own web page.
+
+## Status
+| Feature | State |
+|---|---|
+| Discovery (both vendors) | proven on hardware |
+| Reads (both) | proven on hardware |
+| USRobotics writes: VLAN group, port, mirror | proven on hardware (round trips, switch left as found) |
+| USRobotics write: trunk | proven on hardware 2026-11-08 (ports 17+18, both idle; answers in ~11 s, so the write has a 45 s timeout) |
+| USRobotics write: system name/location/timeout | proven on hardware 2026-11-08 (location set and restored; the page also holds the IP settings, which are read back and re-sent unchanged, and did not change) |
+| D-Link writes: VLAN add/delete, PVID, port, mirror | proven on hardware 2026-11-08 (unused port 8, VLAN 999; every write verified by read-back and rolled back, switch left identical to its backup) |
+| D-Link writes: system name/location/timeout, save configuration | proven on hardware 2026-11-08 (location set and restored; save has no read-back) |
+| D-Link writes: trunks | proven on hardware 2026-11-08 (idle ports 6+7: trunking switched on, group created, then removed and trunking switched off; no ping loss on the other ports) |
+| The MCP tool layer (33 tools over stdio) | proven against a real D-Link with `scripts/e2e_check.py` (plan -> apply -> rollback through the registered tools, gate refusal, downloads) |
+
+### Found on hardware (the fake switches could not have told us)
+- **USRobotics login check was wrong**: the reply to a wrong password has no login form (it only appears on the next page), so every password looked valid. Logins now fetch a real page and require it not to be the login form. This also made "verify the new password by logging in" meaningful for the USRobotics.
+- **D-Link mirror disable**: posting only `cEn=0` to `PortMirroring.cgi` gets no answer at all and applies nothing (ReadTimeout, repeatable). The switch answers in 0.1 s when the form also carries the current sniffer port, mode and source ports. Fixed; the fake now hangs the same way so a regression fails a test.
+- **USRobotics trunk**: the write applies but takes about 11.4 s to answer, longer than the 10 s default timeout; it was reported as "lost contact" although it had worked. Trunk writes now wait up to 45 s.
+
+### Maintenance operations (behind `SWITCH_MCP_ENABLE_MAINTENANCE=1`)
+| Item | State |
+|---|---|
+| Config download (USRobotics `GET config.bin`, D-Link `backup.cgi` with `pswType`) | proven on hardware 2026-11-08, read-only. The D-Link file contains the admin password in clear text: it is stored 0600 and never returned |
+| Firmware download (D-Link `FWBackup.cgi`, ~740 KB) | proven on hardware 2026-11-08, read-only. The USRobotics web interface has no firmware page |
+| USRobotics system name/location/timeout | proven on hardware 2026-11-08 (location changed and restored; the IP settings were re-sent unchanged and did not change) |
+| Password change (both) | proven on hardware 2026-11-08 (run by the operator with `scripts/rotate_password.py`, verified: the old password is refused, the stored new one works) |
+| IP change (both) | proven on hardware 2026-11-08: D-Link 198.51.100.3 -> .4 -> .3 and USRobotics 192.0.2.3 -> .9 -> .3 (shown here as documentation addresses), each verified by logging in at the new address; `switches.json` updated, old address stopped answering |
+| Reboot (D-Link; the USRobotics has no reboot page) | proven on hardware: back in about 7 s, ~2 s of ping loss behind it, uptime reset, saved password survived (save the configuration first: `dlink_plan_save`) |
+| Factory reset + config restore, **D-Link** | proven on hardware: reset -> `10.90.90.90`/`admin` -> upload the saved config file -> back at its own address with its rotated password and a state identical to the pre-test backup (~4 s of cluster-link ping loss) |
+| Factory reset, **USRobotics** | proven on hardware, but the recovery is different: after the reset, uploading the switch's own `config.bin` (it reboots and answers a timeout) restored **none** of the VLAN groups (only group 1 remained), flow control (back to Enable), name/location, address (192.168.0.1) or password (`admin`). Recovery means re-applying a saved state (`backup_state`) over the web pages: `maintenance.reapply_usr_state`, used by `scripts/recover_after_reset.py usr-3com <state.json> --state`. The same steps were done by hand on 2026-11-08 and the switch ended identical to its backup; the packaged function itself is fake-switch tested only |
+| Config restore, USRobotics | the upload is accepted and the switch reboots (~30 s), but see above: do not rely on it to restore settings after a reset |
+
+### Operational notes from the outage tests
+- In the test setup the D-Link carried only a redundant second link and the USRobotics carried the main LAN plus the first link: a D-Link reboot/restore/reset cost a few seconds of ping loss on that link, a USRobotics reset/restore takes the whole LAN down for about a minute. Do one switch at a time.
+- After a USRobotics factory reset its password is `admin` again and the stored entry must say so before `plan_password` can rotate it (the recovery sets it; rotate again afterwards).
+- Reaching a reset switch at its factory address needs a temporary host route on the machine running the tools (`ip addr add <x>/32` + `ip route add <default>/32 dev <bridge>`), not a /8 or /24 alias that would capture other traffic.
+
+### Not implemented
+| Item | Why |
+|---|---|
+| Firmware upgrade (D-Link `FWUpgrade.cgi`; the vendor utility uses TFTP) | the upload protocol behind the button is unknown (the page only has buttons), and a bad image or a power cut during the write can brick the switch. `backup_firmware` keeps a copy of the running image. |
+| The vendor utility's SOAP/UDP channel for writes (`SetDeviceCfg`, TFTP) | not captured; the web channel covers everything above. |
+| DHCP (instead of a static address), 802.1Q mode switch | no need so far; the D-Link `set_ip.cgi` supports DHCP, which would make the switch's address unpredictable. |
+
+See `docs/ADDING-SWITCHES.md` for how to add another switch, another model or firmware, or a new vendor.
+
+## Related projects (other gear with no vendor API)
+- [tplink-easysmart-mcp](https://glama.ai/mcp/servers/ebenezer-isaac/tplink-easysmart-mcp): TP-Link Easy Smart switches over their web CGI, with dry-run, protected ports and lockout-aware failures.
+- A second TP-Link Easy Smart server (`tplink-easy-smart-switch-mcp`, by qwe7002-ai) and a Netgear XS512EM server (`netgear-xs512em`, by supere989); find them by name on GitHub.
+- [NetContext-MCP](https://github.com/hgursel/NetContext-MCP): SSH to older CLI switches (Cisco, Aruba) with legacy algorithms.
+
+The gated-write pattern here (dry run, risk checks, session-eviction caveat) follows the same approach; ideas flow both ways.
+
+See `docs/PROTOCOL.md` for the wire formats and the page/CGI map and `docs/IDEAS.md` for what was borrowed from the projects above and a sketch of a multi-vendor umbrella (an idea only).
+
+---
+A Nebulous Ideas project, built by the Nebulous Collective: the people and agents who work on it.

legacy_switch_mcp-0.1.0/README.md

@@ -0,0 +1,156 @@
+# legacy-switch-mcp
+
+[![CI](https://github.com/Nebulous-Ideas/legacy-switch-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Nebulous-Ideas/legacy-switch-mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Python 3.11+](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue.svg)
+![MCP server](https://img.shields.io/badge/MCP-server-8A2BE2.svg)
+
+<!-- mcp-name: io.github.Nebulous-Ideas/legacy-switch-mcp -->
+
+> **Use at your own risk.** This tool can change VLANs, reboot switches and factory-reset them, and a bad change can cut you off from the switch.
+> It has been proven on hardware on exactly two models (USRobotics 7724, D-Link DGS-1100-08) and is fake-switch tested only elsewhere. Read the plan before applying it,
+> list your uplinks in `protected_ports`, and keep the maintenance switch off unless you need it. Provided as is, without warranty (see `LICENSE`).
+
+An MCP server for two old "smart" switch families that no other MCP covers: the **USRobotics 7724** (24-port gigabit, port-based VLANs) and the
+**D-Link DGS-1100** EasySmart series (802.1Q). Both are Cameo-built and share a UDP discovery protocol (see `docs/PROTOCOL.md`).
+
+It reads state and makes changes the careful way: **plan, then apply**. A plan writes nothing; it shows the exact differences and the risks (for VLANs:
+which connected ports would stop reaching each other, which ports leave the management VLAN). Applying needs the plan id and `confirm=true`, re-reads the switch
+and refuses if it changed, saves a snapshot, writes, reads back to verify, and returns a rollback plan.
+
+## Install
+No clone needed (needs [uv](https://docs.astral.sh/uv/)). First create `~/.config/switch-mcp/switches.json` and a password for each switch (see Setup below), then add the server to your MCP client:
+```bash
+claude mcp add switch -- uvx legacy-switch-mcp                                    # Claude Code
+claude mcp add switch --env SWITCH_MCP_TOOLSETS=read -- uvx legacy-switch-mcp     # look-only (fewest tokens)
+```
+Claude Desktop, Cursor and other clients take the same command in their JSON config:
+```json
+{"mcpServers": {"switch": {"command": "uvx", "args": ["legacy-switch-mcp"], "env": {"SWITCH_MCP_TOOLSETS": "read"}}}}
+```
+Until the package is on PyPI, use `uvx --from git+https://github.com/Nebulous-Ideas/legacy-switch-mcp legacy-switch-mcp`.
+
+## Tools
+| Tool | What it does |
+|---|---|
+| `list_switches`, `list_interfaces` | configured switches; IPv4 interfaces on this host |
+| `discover(interface)`, `probe(host)` | UDP discovery (broadcast+multicast), or ask one switch by IP |
+| `get_state(switch)` | parsed state: VLANs, ports, mirror (and D-Link system/trunk) |
+| `read_page(switch, page)`, `overview(switch)` | raw page data |
+| `backup_state`, `list_snapshots`, `describe_switch` | save the parsed state; list saved states; markdown description for a wiki |
+| `backup_config`, `backup_firmware`, `list_files` | download the configuration (both) / firmware (D-Link) file into the state directory, mode 0600; the content is never returned |
+| `plan_password`, `plan_ip`, `plan_reboot`, `plan_factory_reset`, `plan_restore_config` | maintenance plans (both vendors; reboot D-Link only). **Applying needs the server started with `SWITCH_MCP_ENABLE_MAINTENANCE=1`** |
+| `plan_vlan_group`, `plan_port`, `plan_mirror`, `plan_trunk`, `plan_system` | USRobotics changes (plan only) |
+| `dlink_plan_vlan`, `dlink_plan_vlan_delete`, `dlink_plan_pvid`, `dlink_plan_port`, `dlink_plan_mirror`, `dlink_plan_trunk`, `dlink_plan_trunk_delete`, `dlink_plan_system`, `dlink_plan_save` | D-Link changes (plan only) |
+| `apply_plan(plan_id, confirm=true)` | apply a plan from this server session |
+
+## Setup
+```bash
+uv sync --extra dev && uv run pytest
+mkdir -p ~/.config/switch-mcp && cp switches.example.json ~/.config/switch-mcp/switches.json   # then edit the addresses
+```
+Passwords are never tool arguments and are never returned. Provide each as `SWITCH_MCP_PASSWORD_<NAME>` (name upper-cased, `-` becomes `_`) or in
+`~/.config/switch-mcp/passwords.json` (`{"usr-switch": "..."}`, mode 0600; a looser mode is refused).
+
+**Factory-default passwords** (so a reset switch is usable): both vendors document `admin` as the default (USRobotics quick-install guide; D-Link
+EasySmart manuals, which also give 10.90.90.90 as the default D-Link address and 192.168.0.1 for the USRobotics). Change it after a reset.
+This repository contains no other credentials; tests use a throwaway `pw`.
+
+Register with Claude Code only for switch work (every MCP server adds its tool descriptions to every request of the session):
+```bash
+claude mcp add switch -- uv run --project /path/to/legacy-switch-mcp legacy-switch-mcp
+```
+
+### Keeping the session cost small
+Only the tools that can be used are registered. Measured with all 33 tools registered the schema text was about 4,350 tokens; now:
+| Setup | Tools | Tokens per request (approx.) |
+|---|---|---|
+| default: read + files + a set for each vendor in `switches.json`, maintenance off | 28 (both vendors) | 2,450 |
+| default + `SWITCH_MCP_ENABLE_MAINTENANCE=1` (adds the 5 maintenance plan tools) | 33 | 2,850 |
+| `SWITCH_MCP_TOOLSETS=read,files,dlink` (D-Link work only) | 23 | 1,800 |
+| `SWITCH_MCP_TOOLSETS=read` (look only, no plan or apply tools) | 10 | 600 |
+`SWITCH_MCP_TOOLSETS` takes a comma list of `read`, `files`, `usr`, `dlink`, `maintenance`, or `all`; `apply_plan` is registered whenever any plan set is. A typo is an error, not a silent fallback.
+Maintenance plan tools are not registered at all unless the maintenance switch is on (or `maintenance` is named in `SWITCH_MCP_TOOLSETS`); a registered one still refuses to apply without the switch.
+For day-to-day looking: `claude mcp add switch --env SWITCH_MCP_TOOLSETS=read -- uv run ...`; for a change session leave it unset; for maintenance add `--env SWITCH_MCP_ENABLE_MAINTENANCE=1`.
+
+## Testing
+```bash
+uv sync --extra dev && uv run pytest            # 112 tests against the fake switches; no hardware needed
+uv run python scripts/e2e_check.py <dlink-switch> <trunk-group> <port> <port>   # real MCP stdio check against a D-Link, on IDLE ports only
+```
+`e2e_check.py` starts the server as a client would, round-trips a system-location change and a trunk on the two idle ports you name (each rolled back), downloads a config, and
+checks that a reboot plan is refused while maintenance is off. Run it only against a switch where those ports have no link; it leaves the switch as it found it.
+Hardware-only checks (outages, factory reset, password) are in `scripts/maint.py`, `scripts/rotate_password.py` and `scripts/recover_after_reset.py`; see `docs/ADDING-SWITCHES.md` for the proof sequence.
+
+## Safety
+- **Protected ports**: list uplinks in `switches.json` (`"protected_ports": [24]`); plans that touch them are refused unless `allow_protected=true`.
+- **Rollback survives failure**: the rollback plan is written to disk before any write, so if the switch stops answering mid-change it can still be applied from a new session.
+- **Audit log**: every plan, refusal and apply is appended to `~/.local/state/switch-mcp/audit.jsonl` (no credentials).
+- **Maintenance is off by default.** Password, IP address, reboot, factory reset and config restore plan normally but refuse to apply unless the server was started with
+  `SWITCH_MCP_ENABLE_MAINTENANCE=1` (`claude mcp add switch --env SWITCH_MCP_ENABLE_MAINTENANCE=1 -- uv run ...`). The low-level writers refuse too. Passwords are generated by the server,
+  verified by logging in, stored in `passwords.json` (old one kept in `passwords.prev.json`; a `passwords.pending.json` exists while a change is in flight) and never shown or logged. An IP change refuses
+  unless `allow_ip_change=true`, if the address answers a ping, or if it is outside the gateway's subnet, and updates `switches.json` only after logging in at the new address. Reboot, reset and restore drop every port,
+  so they are refused while `protected_ports` exist unless `allow_protected=true`; a factory reset first saves the parsed state and the configuration file; a restore only accepts a file this server saved for the same switch (checksum checked).
+- Only ten D-Link CGIs (VLAN add/delete, PVID, port, mirror, system name/location/timeout, save, three trunk CGIs) and five USRobotics forms (VLAN group, port, mirror, trunk, system name/location/timeout)
+  can ever be posted in normal operation. Behind the maintenance switch: five more D-Link CGIs (password, IP, reboot, reset, restore) and four USRobotics forms (password, system with IP, reset, restore);
+  two D-Link CGIs only download a file. Firmware upgrade, 802.1Q-mode changes and anything else cannot be posted.
+- Plans live in server memory for 10 minutes; snapshots go to `~/.local/state/switch-mcp/`.
+- One web session at a time (these switches evict a second login), always logged out. If a human has the web page open, close it first.
+- The switches apply changes live; they may not keep them across a power loss unless saved from their own web page.
+
+## Status
+| Feature | State |
+|---|---|
+| Discovery (both vendors) | proven on hardware |
+| Reads (both) | proven on hardware |
+| USRobotics writes: VLAN group, port, mirror | proven on hardware (round trips, switch left as found) |
+| USRobotics write: trunk | proven on hardware 2026-11-08 (ports 17+18, both idle; answers in ~11 s, so the write has a 45 s timeout) |
+| USRobotics write: system name/location/timeout | proven on hardware 2026-11-08 (location set and restored; the page also holds the IP settings, which are read back and re-sent unchanged, and did not change) |
+| D-Link writes: VLAN add/delete, PVID, port, mirror | proven on hardware 2026-11-08 (unused port 8, VLAN 999; every write verified by read-back and rolled back, switch left identical to its backup) |
+| D-Link writes: system name/location/timeout, save configuration | proven on hardware 2026-11-08 (location set and restored; save has no read-back) |
+| D-Link writes: trunks | proven on hardware 2026-11-08 (idle ports 6+7: trunking switched on, group created, then removed and trunking switched off; no ping loss on the other ports) |
+| The MCP tool layer (33 tools over stdio) | proven against a real D-Link with `scripts/e2e_check.py` (plan -> apply -> rollback through the registered tools, gate refusal, downloads) |
+
+### Found on hardware (the fake switches could not have told us)
+- **USRobotics login check was wrong**: the reply to a wrong password has no login form (it only appears on the next page), so every password looked valid. Logins now fetch a real page and require it not to be the login form. This also made "verify the new password by logging in" meaningful for the USRobotics.
+- **D-Link mirror disable**: posting only `cEn=0` to `PortMirroring.cgi` gets no answer at all and applies nothing (ReadTimeout, repeatable). The switch answers in 0.1 s when the form also carries the current sniffer port, mode and source ports. Fixed; the fake now hangs the same way so a regression fails a test.
+- **USRobotics trunk**: the write applies but takes about 11.4 s to answer, longer than the 10 s default timeout; it was reported as "lost contact" although it had worked. Trunk writes now wait up to 45 s.
+
+### Maintenance operations (behind `SWITCH_MCP_ENABLE_MAINTENANCE=1`)
+| Item | State |
+|---|---|
+| Config download (USRobotics `GET config.bin`, D-Link `backup.cgi` with `pswType`) | proven on hardware 2026-11-08, read-only. The D-Link file contains the admin password in clear text: it is stored 0600 and never returned |
+| Firmware download (D-Link `FWBackup.cgi`, ~740 KB) | proven on hardware 2026-11-08, read-only. The USRobotics web interface has no firmware page |
+| USRobotics system name/location/timeout | proven on hardware 2026-11-08 (location changed and restored; the IP settings were re-sent unchanged and did not change) |
+| Password change (both) | proven on hardware 2026-11-08 (run by the operator with `scripts/rotate_password.py`, verified: the old password is refused, the stored new one works) |
+| IP change (both) | proven on hardware 2026-11-08: D-Link 198.51.100.3 -> .4 -> .3 and USRobotics 192.0.2.3 -> .9 -> .3 (shown here as documentation addresses), each verified by logging in at the new address; `switches.json` updated, old address stopped answering |
+| Reboot (D-Link; the USRobotics has no reboot page) | proven on hardware: back in about 7 s, ~2 s of ping loss behind it, uptime reset, saved password survived (save the configuration first: `dlink_plan_save`) |
+| Factory reset + config restore, **D-Link** | proven on hardware: reset -> `10.90.90.90`/`admin` -> upload the saved config file -> back at its own address with its rotated password and a state identical to the pre-test backup (~4 s of cluster-link ping loss) |
+| Factory reset, **USRobotics** | proven on hardware, but the recovery is different: after the reset, uploading the switch's own `config.bin` (it reboots and answers a timeout) restored **none** of the VLAN groups (only group 1 remained), flow control (back to Enable), name/location, address (192.168.0.1) or password (`admin`). Recovery means re-applying a saved state (`backup_state`) over the web pages: `maintenance.reapply_usr_state`, used by `scripts/recover_after_reset.py usr-3com <state.json> --state`. The same steps were done by hand on 2026-11-08 and the switch ended identical to its backup; the packaged function itself is fake-switch tested only |
+| Config restore, USRobotics | the upload is accepted and the switch reboots (~30 s), but see above: do not rely on it to restore settings after a reset |
+
+### Operational notes from the outage tests
+- In the test setup the D-Link carried only a redundant second link and the USRobotics carried the main LAN plus the first link: a D-Link reboot/restore/reset cost a few seconds of ping loss on that link, a USRobotics reset/restore takes the whole LAN down for about a minute. Do one switch at a time.
+- After a USRobotics factory reset its password is `admin` again and the stored entry must say so before `plan_password` can rotate it (the recovery sets it; rotate again afterwards).
+- Reaching a reset switch at its factory address needs a temporary host route on the machine running the tools (`ip addr add <x>/32` + `ip route add <default>/32 dev <bridge>`), not a /8 or /24 alias that would capture other traffic.
+
+### Not implemented
+| Item | Why |
+|---|---|
+| Firmware upgrade (D-Link `FWUpgrade.cgi`; the vendor utility uses TFTP) | the upload protocol behind the button is unknown (the page only has buttons), and a bad image or a power cut during the write can brick the switch. `backup_firmware` keeps a copy of the running image. |
+| The vendor utility's SOAP/UDP channel for writes (`SetDeviceCfg`, TFTP) | not captured; the web channel covers everything above. |
+| DHCP (instead of a static address), 802.1Q mode switch | no need so far; the D-Link `set_ip.cgi` supports DHCP, which would make the switch's address unpredictable. |
+
+See `docs/ADDING-SWITCHES.md` for how to add another switch, another model or firmware, or a new vendor.
+
+## Related projects (other gear with no vendor API)
+- [tplink-easysmart-mcp](https://glama.ai/mcp/servers/ebenezer-isaac/tplink-easysmart-mcp): TP-Link Easy Smart switches over their web CGI, with dry-run, protected ports and lockout-aware failures.
+- A second TP-Link Easy Smart server (`tplink-easy-smart-switch-mcp`, by qwe7002-ai) and a Netgear XS512EM server (`netgear-xs512em`, by supere989); find them by name on GitHub.
+- [NetContext-MCP](https://github.com/hgursel/NetContext-MCP): SSH to older CLI switches (Cisco, Aruba) with legacy algorithms.
+
+The gated-write pattern here (dry run, risk checks, session-eviction caveat) follows the same approach; ideas flow both ways.
+
+See `docs/PROTOCOL.md` for the wire formats and the page/CGI map and `docs/IDEAS.md` for what was borrowed from the projects above and a sketch of a multi-vendor umbrella (an idea only).
+
+---
+A Nebulous Ideas project, built by the Nebulous Collective: the people and agents who work on it.

legacy_switch_mcp-0.1.0/docs/ADDING-SWITCHES.md

@@ -0,0 +1,74 @@
+# Adding or expanding supported switches
+
+Three kinds of work, from least to most:
+
+1. **Another switch of a family that is already supported** (another USRobotics 7724 or D-Link DGS-1100-08): a config entry, nothing else.
+2. **Another model or firmware of a supported family** (DGS-1100-16/24, a newer D-Link firmware, another Cameo-built switch): a few constants, some detection, new fixtures.
+3. **A new vendor** (TP-Link Easy Smart, Netgear, ...): a new session class, parser, planner and fake, following the same safety rails.
+
+Rule that applies to all three: **read first, write last, and never trust a fake switch alone**. Both vendors' write paths were found by reading the switch's own pages,
+and the fake switches (tests/fakeswitch.py, tests/fakedlink.py) only know what we already learned; on 2026-11-08 real hardware showed two behaviours the fakes could not
+have predicted (a mirror disable that hangs without the full form, a trunk write that takes 11 s). A write is "proven" only after a round trip on an unused port.
+
+## 1. Another switch of a supported family
+1. Make sure the host can reach it (the management VLAN or a routed path) and note its address. `discover(interface)` or `probe(host)` confirms the Cameo discovery reply.
+2. Add it to `~/.config/switch-mcp/switches.json`:
+   ```json
+   "lab-switch": {"host": "192.0.2.10", "vendor": "dlink", "protected_ports": []}
+   ```
+   `vendor` is `usrobotics` or `dlink`. Add every uplink and every port that carries your management path to `protected_ports` before any write.
+3. Give it a password: `SWITCH_MCP_PASSWORD_LAB_SWITCH` (name upper-cased, `-` becomes `_`) or an entry in `~/.config/switch-mcp/passwords.json` (mode 0600). Passwords are never tool arguments.
+4. Run `get_state lab-switch` and `backup_state lab-switch` before anything else. Read the port map (which port goes where) by matching the MAC table or the per-port counters, set `protected_ports`, then plan.
+
+## 2. Another model or firmware of a supported family
+What is model-specific today (search the code for these):
+- **D-Link**: `ROOT = "/DGS-1100-08_1.10.039/"` in `dlinkweb.py` (the firmware folder), `PORTS = 8`, `TRUNK_GROUPS`/`TRUNK_MAX_PORTS`, `TIMEOUT_MIN/MAX`, the speed and state tables, and the quad rule for trunk groups.
+  Find the real values on the switch: fetch `index.htm`; it contains `RT='/<model>_<firmware>/';`. `DS/const.js` holds `g_PortNum`, `g_TrunkNum`, `g_MaxTkPtNum`, `g_MinTmOut`, `g_MaxTmOut`.
+  A sensible refactor is to read `RT` from `index.htm` at login and the limits from `DS/const.js`, instead of hard-coding them; do that before adding a second D-Link model.
+- **USRobotics**: 24 ports and 15 VLAN groups appear in `webui.py` validation (`1 <= port <= 24`, `group` 1-15) and the trunk option sets are read from the page, not hard-coded.
+
+Steps:
+1. **Get the pages.** Log in with the existing session class (it handles the login hash/cookies) and save the pages to a scratch directory, read-only. For a D-Link: `index.htm` -> `Prefix.js` -> `en.js` -> `tree/treeitems.js` ->
+   the `iss/H_*.htm` pages and the `DS/*.js` data files. `en.js` maps menu names to page files (`HTML0125=ISD+'H_25_Mirroring.htm'`); each page ends in `submitForm(form, "<name>.cgi")`.
+   Do not run any page's buttons.
+2. **Diff against the supported model.** Compare data variable names (`ds_*`), form control names and CGI names with `docs/PROTOCOL.md`. Differences become constants or parsers; identical pages need no code.
+3. **Fixtures.** Save the data files as `tests/fixtures/dlink_<name>.js` with real MACs, serials and IPs replaced by documentation values (RFC 5737 addresses, `00-00-5E-00-53-xx` MACs). The repository is shared; the user's real switches live only in `~/.config`.
+4. **Tests before hardware.** Extend the fake to the new port count/limits and make the existing plan tests pass for the new model; add tests for anything the model does differently.
+5. **Hardware.** Read-only first (`get_state`, compare with the web page on screen). Then the proof sequence below on a port with no link and not in `protected_ports`.
+
+## 3. A new vendor
+Create one module per concern, mirroring what exists:
+| File | Job |
+|---|---|
+| `<vendor>web.py` | the session class: login (always logged out in `__exit__`, one session at a time through the shared lock), an allow-list of read pages, parsers, and **an allow-list of write endpoints that is the only thing `_post` accepts** |
+| `<vendor>changes.py` | `plan_*` functions (return `op`, `params`, `before`, `summary`, `risks`; they write nothing), plus `current(op, state, params)`, `target(op, params)`, `write(session, op, params)` and `inverse(op, params, before)` for apply and rollback |
+| `server.py` | `@mcp.tool()` wrappers named `<vendor>_plan_*`; the shared `apply_plan` and `backup_state` need no change |
+| `webui.open_session` | return the new session class for the new `vendor` value |
+| `tests/fake<vendor>.py` | an in-memory switch that mimics the real pages, including quirks you have measured |
+Reuse, do not reimplement: `safety.guard_protected` (protected ports), `safety.audit` (the audit log, no secrets), `changes.apply_plan` (re-read and refuse if the switch changed, snapshot, rollback plan written to disk **before** the write,
+read-back verification, lost-contact handling).
+
+How to find the write protocol of a vendor that has no API:
+1. Fetch the web UI's pages and read the JavaScript: form control names and the URL each form posts to are plain text. Where the UI is a single-page app, read its scripts and watch one request in the browser's network tab.
+2. Check what the vendor's own utility sends (the Cameo SmartConsole's SOAP/UDP channel was decoded this way; see `PROTOCOL.md`).
+3. Search for existing open-source drivers or MCP servers for the family (`docs/IDEAS.md` lists the TP-Link, Netgear and CLI-based ones) and read their request code before writing your own.
+4. Record the form names, the allowed values, and every client-side rule the page enforces in JavaScript before posting (the switch may not re-check them): repeat those rules in the `plan_*` function so a bad request fails at plan time.
+
+## The proof sequence for any new write (on an unused, unprotected port)
+1. `backup_state`, and write down the exact state you expect to return to.
+2. `plan_*` and read the plan; `apply_plan` with `confirm=true` only after reading it.
+3. Check the **read-back** (`verified: true`) and that nothing else changed (compare the full state against the backup: ports, VLANs, mirror, system).
+4. Apply the **rollback plan** and compare again. The switch must match the backup (ignoring uptime).
+5. If an apply returns "lost contact" or a timeout, do not repeat it blindly: read the state first, then probe the request by hand with a long timeout to see whether the switch is slow (trunks) or never answers (a field it expects is missing).
+6. Only then change the README status table from "fake switch only" to "proven on hardware", with the date.
+
+## Things that bit us
+- These switches evict a second web session: close any browser tab on the switch first, and never run two tools at once.
+- A form field that the page disables in JavaScript is not sent by a browser, but some CGIs still need it (D-Link mirror disable).
+- Slow writes are normal on old firmware (USRobotics trunk, ~11 s). Give such writes a long timeout, or a success will be reported as lost contact.
+- An empty value may be ignored rather than cleared (USRobotics VLAN description: a single space clears it).
+- Changes are live but may not survive a power cut until saved (D-Link: `dlink_plan_save`; USRobotics: from its own page).
+- Anything that can lock you out or drop the network (password, IP, reboot, reset, restore) belongs behind `webui.require_maintenance(...)`, with a plan that says what breaks, protected-port refusal, a saved backup first and a verification that does not depend on the session being changed. Firmware upgrade is still not implemented: capture the upload protocol from the vendor tool first.
+
+## Beyond switches
+`docs/IDEAS.md` sketches a multi-vendor umbrella (one server, one plan/apply core, vendor drivers behind it). The pieces above are exactly the seam it would use: a driver is a session class plus planners; the core owns safety, audit and rollback.

legacy_switch_mcp-0.1.0/docs/IDEAS.md

@@ -0,0 +1,29 @@
+# Ideas borrowed, and an umbrella that is only an idea
+
+## What came from other projects in this space
+Other MCP servers for gear with no vendor API (TP-Link Easy Smart, Netgear Smart Managed Plus, SSH to older CLI switches, UniFi controllers)
+have settled on a few habits. This project adopted the ones that fit two port-based/EasySmart switches:
+
+| Habit seen elsewhere | Here |
+|---|---|
+| Dry run before every write | `plan_*` tools: nothing is written until `apply_plan(confirm=true)` |
+| Protected ports | `protected_ports` per switch in `switches.json`; plans touching them are refused unless `allow_protected=true` |
+| Lockout-aware failure handling | the rollback plan is saved to disk BEFORE the write; if contact is lost afterwards, `apply_plan` reports it and the plan can be applied from a new session |
+| Session-eviction caveat | one web session at a time, always logged out; documented in the README |
+| JSONL audit log | `audit.jsonl` in the state directory: plans, refusals, applies, backups (never credentials) |
+| Documentation output for network gear | `describe_switch` returns markdown for a wiki page |
+| Backups before changes | a snapshot before every apply, plus `backup_state` and `list_snapshots` |
+
+## The umbrella idea (not built: no other hardware here to test against)
+The pieces that do not care about the vendor are already separate modules: the plan store and rollback (`changes.py`), the audit log and protected-port
+guard (`safety.py`), the reports (`reports.py`). A multi-vendor "legacy switch" server would add one driver per family behind a small interface:
+
+```
+discover(interface) -> list[SwitchInfo]
+state() -> dict                      # parsed, vendor-neutral where possible
+plan_* / write_*                     # the few forms a driver may post
+current(op, state, params), target(op, params), inverse(op, params, before)
+```
+
+`dlinkchanges.py` already has `current`/`target`/`inverse`/`write` in exactly that shape, so a TP-Link Easy Smart or Netgear driver (both have public
+protocol write-ups) could be added without touching the core. Without the hardware to prove writes, that would be guesswork, so it stays a note.