@usex/mikrotik-mcp 5.18.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 (76) hide show
  1. package/README.md +213 -5
  2. package/dist/cli.js +3242 -835
  3. package/dist/index.js +169 -28
  4. package/dist/shared/{cli-97csvm6f.js → cli-426pkqe9.js} +8 -0
  5. package/dist/shared/{library-552hdvw2.js → library-73y8qdjr.js} +2619 -537
  6. package/dist/shared/{library-xbg1d52n.js → library-76naf20r.js} +1 -1
  7. package/dist/shared/{library-w5tyng4c.js → library-81amv3az.js} +1 -1
  8. package/dist/shared/{library-08g0pwc9.js → library-krajvnj9.js} +1 -1
  9. package/dist/shared/{library-gmx9pzx3.js → library-y9tt30y1.js} +11 -1
  10. package/dist/ui/aaa.html +8 -8
  11. package/dist/ui/connected-devices.html +8 -8
  12. package/dist/ui/dashboard.html +16 -16
  13. package/dist/ui/fabric.html +11 -11
  14. package/dist/ui/firewall-audit.html +8 -8
  15. package/dist/ui/firewall.html +9 -9
  16. package/dist/ui/interfaces.html +8 -8
  17. package/dist/ui/investigations.html +11 -11
  18. package/dist/ui/observability.html +77 -75
  19. package/dist/ui/operations.html +11 -11
  20. package/dist/ui/records.html +12 -12
  21. package/dist/ui/reports.html +11 -11
  22. package/dist/ui/round-trip.html +11 -11
  23. package/dist/ui/service-health.html +11 -11
  24. package/package.json +22 -22
  25. package/prompts/audit-routeros-containers.md +27 -0
  26. package/prompts/audit-vlan-segmentation.md +31 -0
  27. package/prompts/setup-guest-wifi.md +23 -24
  28. package/prompts/setup-routeros-container.md +36 -0
  29. package/prompts/setup-v2ray-container-proxy.md +68 -194
  30. package/prompts/setup-vlan-network.md +27 -33
  31. package/schemas/README.md +1 -1
  32. package/schemas/devtools-manifest.json +358 -16
  33. package/schemas/tool-catalog.json +1133 -144
  34. package/schemas/tools/add_container.json +42 -30
  35. package/schemas/tools/add_container_env.json +3 -4
  36. package/schemas/tools/add_container_mount.json +10 -4
  37. package/schemas/tools/apply_service_routing.json +23 -0
  38. package/schemas/tools/arm_service_routing.json +23 -0
  39. package/schemas/tools/configure_flight_recorder.json +30 -0
  40. package/schemas/tools/confirm_mcp_settings.json +19 -0
  41. package/schemas/tools/create_service_routing.json +78 -0
  42. package/schemas/tools/design_network_segment.json +22 -6
  43. package/schemas/tools/destroy_recovery_lab.json +18 -0
  44. package/schemas/tools/export_network_incident.json +14 -0
  45. package/schemas/tools/freeze_network_incident.json +14 -0
  46. package/schemas/tools/get_container.json +11 -4
  47. package/schemas/tools/get_flight_recorder.json +7 -0
  48. package/schemas/tools/get_mcp_settings.json +7 -0
  49. package/schemas/tools/get_mcp_settings_schema.json +7 -0
  50. package/schemas/tools/get_recovery_lab.json +7 -0
  51. package/schemas/tools/get_routeros_container_guide.json +22 -0
  52. package/schemas/tools/get_vlan_segmentation_guide.json +14 -0
  53. package/schemas/tools/list_container_envs.json +1 -1
  54. package/schemas/tools/list_container_mounts.json +7 -2
  55. package/schemas/tools/list_containers.json +2 -4
  56. package/schemas/tools/list_service_routing.json +7 -0
  57. package/schemas/tools/poll_recovery_lab.json +14 -0
  58. package/schemas/tools/prepare_recovery_lab.json +23 -0
  59. package/schemas/tools/preview_mcp_settings.json +94 -0
  60. package/schemas/tools/preview_service_routing.json +23 -0
  61. package/schemas/tools/probe_service_routing.json +14 -0
  62. package/schemas/tools/recovery_lab_inventory.json +7 -0
  63. package/schemas/tools/remove_container.json +11 -4
  64. package/schemas/tools/remove_container_env.json +7 -3
  65. package/schemas/tools/remove_container_mount.json +18 -2
  66. package/schemas/tools/rollback_mcp_settings.json +19 -0
  67. package/schemas/tools/service_routing_inventory.json +7 -0
  68. package/schemas/tools/set_container_config.json +4 -6
  69. package/schemas/tools/start_container.json +11 -4
  70. package/schemas/tools/start_recovery_lab.json +18 -0
  71. package/schemas/tools/stop_container.json +11 -4
  72. package/schemas/tools/update_container.json +46 -6
  73. package/schemas/tools/update_mcp_settings.json +110 -0
  74. /package/dist/shared/{cli-3zrj182m.js → cli-6wdstvdq.js} +0 -0
  75. /package/dist/shared/{cli-s423xk9v.js → cli-cvt06346.js} +0 -0
  76. /package/dist/shared/{cli-ff6yww2e.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."_
@@ -445,11 +540,11 @@ recall, API and dashboard regression tests.
445
540
  **Shared memory.** The **Memory → Shared memory** tab assigns an explicit scope to a knowledge
446
541
  entity, with a preview of who inherits its existing and future memories:
447
542
 
448
- | Scope | Intended knowledge | Included when recalling a device |
449
- | --- | --- | --- |
450
- | Device (default) | Its IPs, routes, MTUs, firmware and measured outcomes | Only for that exact entity |
451
- | Group | Policies for an explicit set of device entities | Only for listed members; no nested groups |
452
- | Shared | Fleet-wide safeguards, preferences and reusable lessons | Automatically for every selected device |
543
+ | Scope | Intended knowledge | Included when recalling a device |
544
+ | ---------------- | ------------------------------------------------------- | ----------------------------------------- |
545
+ | Device (default) | Its IPs, routes, MTUs, firmware and measured outcomes | Only for that exact entity |
546
+ | Group | Policies for an explicit set of device entities | Only for listed members; no nested groups |
547
+ | Shared | Fleet-wide safeguards, preferences and reusable lessons | Automatically for every selected device |
453
548
 
454
549
  Create a **dedicated policy entity**, not a copy of a router's observations. For example, after
455
550
  creating `fleet-policy` with `memory_create_entities`, read `memory_get_scope` and pass its
@@ -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
 
@@ -654,6 +818,50 @@ HTTP transports expose `POST /mcp` and `GET /health` with DNS-rebinding protecti
654
818
 
655
819
  ## Configuration
656
820
 
821
+ ### Update MCP settings through tools
822
+
823
+ The **MCP Settings** module (`mcp-settings`) manages host-side settings without
824
+ contacting a router, even when the dashboard is disabled:
825
+
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 |
834
+
835
+ Editable fields cover MCP tool pagination, App views and capability gating;
836
+ SSH pooling; dashboard retention/body capture/redaction; Memory enablement; and
837
+ startup update checks. Partial patches preserve omitted settings. For example,
838
+ preview `{"changes":{"ssh":{"keepAlive":true,"idleTimeout":60000}}}`,
839
+ then apply the same changes with the returned `revision` and `confirm:true` only
840
+ after user approval. Read back and confirm using the **new** revision and
841
+ `pending_id` (the update result's `pendingId`, also `pending.id` in readback).
842
+
843
+ Writes are unavailable in read-only mode. Devices, credentials, listener addresses,
844
+ file paths, access ceilings, tool restrictions and probe allowlists remain
845
+ operator-managed. These tools cannot disable redaction; enabling body capture
846
+ requires redaction. They return no credential values. Config files and backups
847
+ are written with owner-only permissions (`0600` on POSIX).
848
+
849
+ Dashboard and tool edits in the same process share one pending transaction; stale revisions and
850
+ conflicting edits are rejected. Unconfirmed tool updates roll back after **60s**
851
+ by default (configurable from 30–600s) **while the process remains alive**.
852
+ Never restart with a pending update: confirm first, then restart separately if
853
+ the preview requires it. MCP presentation, dashboard recorder and update-check
854
+ changes need a restart for full activation. Memory enablement is checked on the
855
+ next operation; SSH settings affect subsequent calls/new connections and new idle
856
+ timers without forcibly disconnecting existing sessions.
857
+
858
+ The saved config path is returned by the tools. If the server was started from
859
+ environment variables alone, use `--config <path>` on future starts; CLI/env
860
+ overrides can still take precedence. A configured value is not evidence of a
861
+ restart or of router connectivity.
862
+
863
+ ### Environment and CLI
864
+
657
865
  Settings come from `MIKROTIK_*` env vars or matching CLI flags (defaults → env → flags):
658
866
 
659
867
  | Variable | Flag | Default | Purpose |