@usex/mikrotik-mcp 5.19.0 → 5.20.0

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 (70) hide show
  1. package/README.md +172 -8
  2. package/dist/cli.js +2751 -679
  3. package/dist/index.js +148 -27
  4. package/dist/shared/{library-7wcv2ckk.js → library-73y8qdjr.js} +2231 -540
  5. package/dist/shared/{library-tqrvrykj.js → library-76naf20r.js} +1 -1
  6. package/dist/shared/{library-ppnv0f07.js → library-81amv3az.js} +1 -1
  7. package/dist/shared/{library-z7qsdq88.js → library-krajvnj9.js} +1 -1
  8. package/dist/shared/{library-f3be6g03.js → library-y9tt30y1.js} +1 -1
  9. package/dist/ui/aaa.html +8 -8
  10. package/dist/ui/connected-devices.html +8 -8
  11. package/dist/ui/dashboard.html +16 -16
  12. package/dist/ui/fabric.html +11 -11
  13. package/dist/ui/firewall-audit.html +8 -8
  14. package/dist/ui/firewall.html +9 -9
  15. package/dist/ui/interfaces.html +8 -8
  16. package/dist/ui/investigations.html +11 -11
  17. package/dist/ui/observability.html +63 -61
  18. package/dist/ui/operations.html +11 -11
  19. package/dist/ui/records.html +12 -12
  20. package/dist/ui/reports.html +11 -11
  21. package/dist/ui/round-trip.html +11 -11
  22. package/dist/ui/service-health.html +11 -11
  23. package/package.json +22 -22
  24. package/prompts/audit-routeros-containers.md +27 -0
  25. package/prompts/audit-vlan-segmentation.md +31 -0
  26. package/prompts/setup-guest-wifi.md +23 -24
  27. package/prompts/setup-routeros-container.md +36 -0
  28. package/prompts/setup-v2ray-container-proxy.md +68 -194
  29. package/prompts/setup-vlan-network.md +27 -33
  30. package/schemas/README.md +1 -1
  31. package/schemas/devtools-manifest.json +287 -16
  32. package/schemas/tool-catalog.json +785 -109
  33. package/schemas/tools/add_container.json +42 -30
  34. package/schemas/tools/add_container_env.json +3 -4
  35. package/schemas/tools/add_container_mount.json +10 -4
  36. package/schemas/tools/apply_service_routing.json +23 -0
  37. package/schemas/tools/arm_service_routing.json +23 -0
  38. package/schemas/tools/configure_flight_recorder.json +30 -0
  39. package/schemas/tools/create_service_routing.json +78 -0
  40. package/schemas/tools/design_network_segment.json +22 -6
  41. package/schemas/tools/destroy_recovery_lab.json +18 -0
  42. package/schemas/tools/export_network_incident.json +14 -0
  43. package/schemas/tools/freeze_network_incident.json +14 -0
  44. package/schemas/tools/get_container.json +11 -4
  45. package/schemas/tools/get_flight_recorder.json +7 -0
  46. package/schemas/tools/get_recovery_lab.json +7 -0
  47. package/schemas/tools/get_routeros_container_guide.json +22 -0
  48. package/schemas/tools/get_vlan_segmentation_guide.json +14 -0
  49. package/schemas/tools/list_container_envs.json +1 -1
  50. package/schemas/tools/list_container_mounts.json +7 -2
  51. package/schemas/tools/list_containers.json +2 -4
  52. package/schemas/tools/list_service_routing.json +7 -0
  53. package/schemas/tools/poll_recovery_lab.json +14 -0
  54. package/schemas/tools/prepare_recovery_lab.json +23 -0
  55. package/schemas/tools/preview_service_routing.json +23 -0
  56. package/schemas/tools/probe_service_routing.json +14 -0
  57. package/schemas/tools/recovery_lab_inventory.json +7 -0
  58. package/schemas/tools/remove_container.json +11 -4
  59. package/schemas/tools/remove_container_env.json +7 -3
  60. package/schemas/tools/remove_container_mount.json +18 -2
  61. package/schemas/tools/service_routing_inventory.json +7 -0
  62. package/schemas/tools/set_container_config.json +4 -6
  63. package/schemas/tools/start_container.json +11 -4
  64. package/schemas/tools/start_recovery_lab.json +18 -0
  65. package/schemas/tools/stop_container.json +11 -4
  66. package/schemas/tools/update_container.json +46 -6
  67. /package/dist/shared/{cli-j07tbrke.js → cli-426pkqe9.js} +0 -0
  68. /package/dist/shared/{cli-y00nwzxx.js → cli-6wdstvdq.js} +0 -0
  69. /package/dist/shared/{cli-s0rxncz4.js → cli-cvt06346.js} +0 -0
  70. /package/dist/shared/{cli-gtq5bw8q.js → cli-z1kavk0z.js} +0 -0
package/README.md CHANGED
@@ -46,6 +46,13 @@ Then just ask:
46
46
 
47
47
  ## Highlights
48
48
 
49
+ - **Service Routing:** per-family domain policies, VRF HTTPS exit checks and
50
+ explicitly authorized failover, with preview, backup and Safe Mode. [Guide](docs/service-routing.md)
51
+ - **Flight Recorder:** opt-in, durable pre/post-incident telemetry and log metadata,
52
+ with an evidence timeline and scoped JSON export. [Guide](docs/flight-recorder.md)
53
+ - **Recovery Lab:** reviewed portable restore/upgrade rehearsals, coverage and cleanup
54
+ evidence. Execution requires a separately deployed isolated CHR runner. [Guide](docs/recovery-lab.md)
55
+
49
56
  - **Client Check** — invite the affected phone/laptop with an expiring QR/link,
50
57
  measure browser HTTP latency, loaded latency and bounded transfers, and compare
51
58
  Wi-Fi/VPN runs in the dashboard. Optional investigation links keep evidence together.
@@ -223,6 +230,94 @@ mikrotik-mcp serve --config ./devices.json
223
230
  mikrotik-mcp devices # site-a (default) · site-b
224
231
  ```
225
232
 
233
+ #### Docker: one writable `devices.json` for all MCP settings
234
+
235
+ Use the published **[alimaster/mikrotik-mcp](https://hub.docker.com/r/alimaster/mikrotik-mcp)**
236
+ image (`5.19.0`, or the moving `latest` tag). Docker selects `linux/amd64` or
237
+ `linux/arm64` automatically; no local build is needed. Compose defaults to
238
+ `5.19.0`; set `MIKROTIK_IMAGE_TAG` explicitly to select a different release.
239
+
240
+ The Bun container reads **`/home/bun/.mikrotik-mcp/devices.json`** automatically.
241
+ Despite its name, this is the **complete MCP configuration**, not just the router
242
+ list: `mcp`, `dashboard`, `ssh`, `memory`, `tools`, `access`, `alerts`, `flows`,
243
+ `policy`, `schedules`, `attacks`, `serviceProbes`, `s3` and top-level settings live
244
+ in this same JSON. Config/Devices saves and MCP settings tools write back to it;
245
+ confirm **Keep changes** (or `confirm_mcp_settings`) before restarting a pending
246
+ safe-apply transaction. Listener/transport changes require a server restart.
247
+
248
+ Create a real JSON file on the host (no comments or trailing commas). For example:
249
+
250
+ ```json
251
+ {
252
+ "defaultDevice": "home",
253
+ "devices": {
254
+ "home": {
255
+ "host": "192.168.88.1",
256
+ "username": "automation",
257
+ "keyFilename": "/run/secrets/mikrotik_key"
258
+ }
259
+ },
260
+ "mcp": { "transport": "streamable-http", "host": "0.0.0.0", "port": 8000 },
261
+ "dashboard": { "enabled": true, "host": "0.0.0.0", "port": 9090 },
262
+ "ssh": { "keepAlive": true },
263
+ "memory": { "enabled": true },
264
+ "disableUpdateCheck": true
265
+ }
266
+ ```
267
+
268
+ ```bash
269
+ docker pull alimaster/mikrotik-mcp:5.19.0
270
+ docker run -d --name mikrotik-mcp --restart unless-stopped \
271
+ -p 127.0.0.1:8000:8000 -p 127.0.0.1:9090:9090 \
272
+ --mount type=volume,src=mikrotik-state,dst=/home/bun/.mikrotik-mcp \
273
+ --mount type=bind,src=/absolute/path/devices.json,dst=/home/bun/.mikrotik-mcp/devices.json \
274
+ --mount type=bind,src=/absolute/path/mikrotik_ed25519,dst=/run/secrets/mikrotik_key,readonly \
275
+ alimaster/mikrotik-mcp:5.19.0
276
+ ```
277
+
278
+ Dashboard: **http://localhost:9090** · MCP: **http://localhost:8000/mcp**.
279
+ The JSON mount must be **read-write**, must already exist, and must be readable
280
+ and writable by container **UID/GID 1000**. Keep it private (`0600`); it can contain
281
+ credentials. The SSH key only needs read access. On Linux, arrange matching
282
+ ownership/ACLs; do not make secrets world-readable. Mount a dedicated copy rather
283
+ than sharing the live service's file with a second writer.
284
+
285
+ The included Compose file binds `./devices.json` (or the absolute path in
286
+ `MIKROTIK_CONFIG_PATH`) and also persists application data:
287
+
288
+ ```bash
289
+ # Only creates a starter file when none exists; edit it before starting.
290
+ test -e devices.json || cp docker/devices.example.json devices.json
291
+ # Configure devices + dashboard.enabled in devices.json; mount your key in Compose.
292
+ docker compose pull mikrotik-mcp
293
+ docker compose up -d mikrotik-mcp
294
+ # Or use an existing file:
295
+ MIKROTIK_CONFIG_PATH=/absolute/path/devices.json docker compose up -d mikrotik-mcp
296
+ ```
297
+
298
+ - The starter JSON has no credentials and leaves the dashboard disabled. Docker
299
+ defaults are stored in JSON, so saved ports/settings are not silently replaced
300
+ by baked-in environment defaults on restart. Explicit CLI/env overrides still
301
+ win; remove conflicting `.env` values if JSON should be authoritative.
302
+ - If changing listener ports in JSON, update Docker's port mappings too. For
303
+ Compose set `MCP_PORT` / `DASHBOARD_PORT` to the **same** new ports; these only
304
+ control publishing, not application settings. Its healthcheck reads the JSON.
305
+ - The named state volume retains databases, Memory contents, reports, config
306
+ backups and history. These are **data**, not settings, and are not embedded in
307
+ JSON. Custom database/backup paths must also be mounted. Do not use
308
+ `docker compose down -v` if you want to retain this data.
309
+ - For the strongest crash safety, mount a **dedicated parent directory** containing
310
+ `devices.json` at `/home/bun/.mikrotik-mcp` instead of a single file; this preserves
311
+ atomic replacement and all state on the host. Single-file mounts use a private,
312
+ flushed `.bak-mounted-*` backup and an inode-preserving write when Linux rejects
313
+ rename with `EBUSY`. That fallback is not power-loss atomic; keep one writer and
314
+ retain backups. A read-only mount cannot persist edits. After replacing the host
315
+ file by rename in an editor, recreate a single-file-mounted container to remount
316
+ the new file.
317
+
318
+ See **[Docker deployment and persistence](docs/docker.md#persistent-devicesjson)**
319
+ for directory mounts, permissions and explicit configuration overrides.
320
+
226
321
  Every tool gains an optional `device` argument, and **Safe Mode is per-device**:
227
322
 
228
323
  > _"On site-a create a WireGuard interface, on site-b add it as a peer, then ping across."_
@@ -496,6 +591,75 @@ tenant isolation. Clients must reconnect to receive updated MCP server instructi
496
591
  <img src="assets/screenshots/web/dashboard-memory.webp" alt="Memory knowledge graph" width="820" />
497
592
  </div>
498
593
 
594
+ ### RouterOS container knowledge and safe operations
595
+
596
+ `get_routeros_container_guide` provides shared, version-aware guidance adapted from
597
+ the `routeros-container` skill. Topics: `all`, `prerequisites`, `images`, `networking`,
598
+ `lifecycle`, `security`, `troubleshooting`. It performs no router I/O and needs no
599
+ container package. The equivalent Markdown resource
600
+ `mikrotik://knowledge/routeros-container` remains available in read-only/curated
601
+ sessions even when the `container` tool module is disabled.
602
+
603
+ - `audit-routeros-containers`: read-only readiness, storage and isolation audit.
604
+ - `setup-routeros-container`: approval-first deployment and application verification.
605
+ - `setup-v2ray-container-proxy`: the same safety baseline for proxy/TUN gateways.
606
+
607
+ These prompts include the same guide in MCP, Dashboard and Raycast. Instructions
608
+ cover physical device-mode confirmation, separately approved package/reboot work,
609
+ architecture variants, storage/volume backup, VETH/IPv4/IPv6 isolation, shared-list
610
+ dependencies, bounded lifecycle polling and Device/Group/Shared Memory boundaries.
611
+ They never authorize automatic router changes.
612
+
613
+ Container tools reject ambiguous targets and unsafe image-source combinations.
614
+ Use exactly one `id` (stable `.id`), unique `name`, or exact `tag` for lifecycle
615
+ operations. Start/remove and runtime-setting changes require confirmed stopped
616
+ state. Writes are read back; timeouts remain unknown and are never blindly retried.
617
+ `add_container` requires a name, VETH and root path in addition to one image source.
618
+ Current mount creation uses `list`; `name` remains an explicit legacy alternative.
619
+ Likewise `envlist`/`mounts` are legacy alternatives to `envlists`/`mountlists`;
620
+ inspect the target schema before selecting syntax. `memory_high` (and its deprecated
621
+ `ram_high` input alias) sends the actual RouterOS `memory-high` property.
622
+
623
+ Environment listing retrieves metadata without values. Container command logs omit
624
+ arguments; default activity-history redaction masks env/value/command fields, and
625
+ container detail masks sensitive properties. Application log text may still contain
626
+ secrets: collect only bounded, reviewed logs. These safeguards are not retroactive
627
+ cleanup of older logs and do not make arbitrary raw-command output secret-safe.
628
+
629
+ ### VLAN knowledge and safe segmentation
630
+
631
+ The MCP includes a shared RouterOS VLAN guide adapted from the
632
+ `homelab-vlan-segmentation` skill. Read it with `get_vlan_segmentation_guide`
633
+ (`topic: "all"`, or `overview`, `discovery`, `layer2`, `policy`, `migration`,
634
+ `verification`) or the MCP resource `mikrotik://knowledge/vlan-segmentation`.
635
+ The tool belongs to `vlan-designer`; the reference resource remains available in
636
+ read-only/curated sessions and with Memory disabled. Reading it never contacts a router.
637
+
638
+ - **Audit:** `audit-vlan-segmentation` produces a read-only topology and prioritized
639
+ cleanup report, with unknown evidence and client-test gaps made explicit.
640
+ - **Plan:** `setup-vlan-network` and `setup-guest-wifi` include the same guide in
641
+ MCP, Dashboard → Prompts and Raycast → Prompts. They cover port/PVID/CPU membership,
642
+ SSID/package differences, IPv4 **and** IPv6 isolation, protected management,
643
+ remote routing, staged approval/rollback and real-client acceptance tests.
644
+ - **Remember:** store verified addresses/VLAN maps per Device. Share only intentionally
645
+ reusable safeguards, or explicit Group policies. No private topology is seeded and
646
+ the guide does not write Memory or grant authorization to change devices.
647
+
648
+ **Planner safety change:** `design_network_segment` is a partial IPv4 scaffold, not
649
+ an end-to-end isolation engine. It still defaults to `apply=false`. When
650
+ `internet=true`, `wan_interface` is now required to avoid unscoped NAT; use
651
+ `internet=false` when reusing existing NAT. `isolate_from` requires a reviewed
652
+ `isolation_before` forward-rule `.id`, checked again before writes. Non-/24 DHCP
653
+ requires an explicit valid `dhcp_range`; pools cannot include the gateway/network/
654
+ broadcast. Bridge/CPU tagged membership is deduplicated. Port admission/PVID,
655
+ filtering activation, SSIDs, INPUT/IPv6 policy and client verification remain separate
656
+ steps. Existing callers must supply these new prerequisites; incomplete requests
657
+ fail before writes. Apply is sequential, not idempotent, and has no automatic rollback.
658
+
659
+ Rebuild/redeploy the MCP version you actually run, then reconnect clients to refresh
660
+ their instructions/catalog. Editing this checkout alone does not upgrade an installed
661
+ service. No live router configuration is changed by loading these workflows.
662
+
499
663
  **What's new.** Release notes for the running server version, shown on first launch after
500
664
  an upgrade.
501
665
 
@@ -659,14 +823,14 @@ HTTP transports expose `POST /mcp` and `GET /health` with DNS-rebinding protecti
659
823
  The **MCP Settings** module (`mcp-settings`) manages host-side settings without
660
824
  contacting a router, even when the dashboard is disabled:
661
825
 
662
- | Tool | Purpose |
663
- | ------------------------- | ---------------------------------------------------------------------- |
664
- | `get_mcp_settings` | Read editable settings, revision, config path and pending change |
665
- | `get_mcp_settings_schema` | Discover allowed fields and validation limits |
666
- | `preview_mcp_settings` | Validate a partial patch and inspect its diff and restart requirements |
667
- | `update_mcp_settings` | Back up and atomically save an approved patch, with timed rollback |
668
- | `confirm_mcp_settings` | Keep the pending tool-created change after readback |
669
- | `rollback_mcp_settings` | Restore its local backup before confirmation |
826
+ | Tool | Purpose |
827
+ | ------------------------- | ----------------------------------------------------------------------------- |
828
+ | `get_mcp_settings` | Read editable settings, revision, config path and pending change |
829
+ | `get_mcp_settings_schema` | Discover allowed fields and validation limits |
830
+ | `preview_mcp_settings` | Validate a partial patch and inspect its diff and restart requirements |
831
+ | `update_mcp_settings` | Back up and persist an approved patch to the source JSON, with timed rollback |
832
+ | `confirm_mcp_settings` | Keep the pending tool-created change after readback |
833
+ | `rollback_mcp_settings` | Restore its local backup before confirmation |
670
834
 
671
835
  Editable fields cover MCP tool pagination, App views and capability gating;
672
836
  SSH pooling; dashboard retention/body capture/redaction; Memory enablement; and