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