@usex/mikrotik-mcp 5.17.0 → 5.19.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 (32) hide show
  1. package/README.md +166 -1
  2. package/dist/cli.js +2000 -512
  3. package/dist/index.d.ts +12 -1
  4. package/dist/index.js +64 -8
  5. package/dist/shared/{cli-51yqa57b.js → cli-j07tbrke.js} +8 -0
  6. package/dist/shared/{library-85ayxzg9.js → library-7wcv2ckk.js} +1369 -163
  7. package/dist/shared/{library-xw54vgxq.js → library-f3be6g03.js} +11 -1
  8. package/dist/shared/{library-b7vtz46e.js → library-ppnv0f07.js} +1 -1
  9. package/dist/shared/{library-rw1d7smw.js → library-tqrvrykj.js} +1 -1
  10. package/dist/shared/{library-y97z4cef.js → library-z7qsdq88.js} +1 -1
  11. package/dist/ui/observability.html +80 -80
  12. package/package.json +2 -1
  13. package/schemas/README.md +1 -1
  14. package/schemas/config.schema.json +18 -0
  15. package/schemas/devtools-manifest.json +135 -1
  16. package/schemas/tool-catalog.json +661 -3
  17. package/schemas/tools/confirm_mcp_settings.json +19 -0
  18. package/schemas/tools/get_mcp_settings.json +7 -0
  19. package/schemas/tools/get_mcp_settings_schema.json +7 -0
  20. package/schemas/tools/memory_get_scope.json +14 -0
  21. package/schemas/tools/memory_history.json +14 -0
  22. package/schemas/tools/memory_recall.json +35 -0
  23. package/schemas/tools/memory_remember.json +65 -0
  24. package/schemas/tools/memory_review.json +44 -0
  25. package/schemas/tools/memory_revise.json +61 -0
  26. package/schemas/tools/memory_set_scope.json +37 -0
  27. package/schemas/tools/preview_mcp_settings.json +94 -0
  28. package/schemas/tools/rollback_mcp_settings.json +19 -0
  29. package/schemas/tools/update_mcp_settings.json +110 -0
  30. /package/dist/shared/{cli-5rs21zfv.js → cli-gtq5bw8q.js} +0 -0
  31. /package/dist/shared/{cli-s1kg75zm.js → cli-s0rxncz4.js} +0 -0
  32. /package/dist/shared/{cli-s5nnez6j.js → cli-y00nwzxx.js} +0 -0
package/README.md CHANGED
@@ -231,6 +231,41 @@ Behind a bastion with no exposed port? Jump through another router (`jumpVia`)
231
231
  commands, Safe Mode and SFTP all ride the hop. Full guide:
232
232
  **[docs/multi-device.md](docs/multi-device.md)**.
233
233
 
234
+ #### Multiple management addresses & automatic failover
235
+
236
+ In **Devices → Add device / Edit settings → Connection**, add internal, VPN or public static IPs
237
+ and choose **Primary**. The existing `host` is Primary; `fallbackHosts` holds up to seven
238
+ alternate IPv4/IPv6 addresses in priority order. All addresses must reach the **same router**,
239
+ using its shared SSH/REST ports, credentials and jump-host configuration.
240
+
241
+ ```json
242
+ {
243
+ "host": "10.10.10.1",
244
+ "fallbackHosts": ["203.0.113.10", "2001:db8::10"],
245
+ "port": 22,
246
+ "username": "admin",
247
+ "keyFilename": "/keys/home"
248
+ }
249
+ ```
250
+
251
+ - A successful connection remembers its IP for **5 minutes**, separately for each device and
252
+ transport/port. New connections try that IP first; each successful connection renews the window.
253
+ Failure clears the preference immediately. Without a cached success, Primary and then alternatives
254
+ are tried in order, with a 30-second cooldown for failed addresses. Healthy pooled/Safe Mode sessions
255
+ stay open even after expiry; commands already dispatched are never replayed on another IP.
256
+ - Device cards automatically refresh address observations every 4 seconds: open connections,
257
+ remembered IP and remaining preference time, last failures, and untested addresses. These are real
258
+ connection observations, not continuous probes of unused addresses. Primary is never rewritten;
259
+ preference is in-memory and resets on server restart or device configuration replacement.
260
+ - SSH, SSH jump devices, SFTP, initial Safe Mode setup, REST probes and dashboard tests use this
261
+ selection. Authentication/key errors stop that connection attempt; MAC-Telnet has no IP failover.
262
+ - Device cards and `list_mikrotik_devices` distinguish **Connected**, historical success, failed
263
+ attempts and untested addresses. **Test connection / Connect & Save** reports the IP that authenticated.
264
+ - Failover happens **before command dispatch**. A lost command response is not automatically replayed
265
+ on another IP or over SSH. An active Safe Mode transaction never migrates between connections.
266
+ - Existing single-address configurations remain valid. No router interface, routing or firewall
267
+ settings are changed by adding management addresses to MCP.
268
+
234
269
  ### 🩺 Diagnose and harden
235
270
 
236
271
  > _"Why can't VLAN 50 reach the internet?"_
@@ -309,6 +344,17 @@ and last-seen.
309
344
 
310
345
  **RADIUS & User Manager.** Servers, sessions, profiles, limitations and vouchers.
311
346
 
347
+ Reports & insights collects accounting in the background and shows verified-session
348
+ progress on the first visit. Complete snapshots are saved privately alongside the
349
+ dashboard database in `<dashboard.dbPath>.um-reports/` and restored after restart
350
+ (up to 24 hours old, clearly marked when stale). Device/credential/jump-host changes
351
+ invalidate the saved snapshot. Automatic refresh waits at least 60 seconds, or five
352
+ times the previous collection duration (capped at 15 minutes), to avoid repeatedly
353
+ loading large histories. **Refresh** starts a shared background read without hiding
354
+ the current report. Failed reads never replace a complete report with partial totals.
355
+ An ephemeral `:memory:` dashboard or an unwritable storage directory uses RAM only;
356
+ the report page warns when a snapshot could not be persisted.
357
+
312
358
  <div align="center">
313
359
  <img src="assets/screenshots/web/dashboard-radius-um.webp" alt="RADIUS & User Manager" width="820" />
314
360
  </div>
@@ -369,7 +415,82 @@ auto-rollback.
369
415
  <img src="assets/screenshots/web/dashboard-config.webp" alt="Config Studio" width="820" />
370
416
  </div>
371
417
 
372
- **Memory.** Knowledge graph of entities, relations and observations gathered from calls.
418
+ **Memory.** An evidence-aware knowledge workspace: searchable facts, constraints, lessons,
419
+ preferences and procedures, scoped to entities and their explicit relationships. Inspect
420
+ sources, author-assigned confidence, expiry, verification and revision history; pin important
421
+ knowledge, archive outdated records, and use **Recall lab** to preview the exact bounded context
422
+ an LLM receives. Search and pagination survive background refreshes.
423
+
424
+ The MCP workflow is `memory_create_entities` → `memory_remember` → `memory_recall`.
425
+ Use a stable `key` (for example `wan.provider`) to replace a fact while keeping its previous
426
+ revisions. `memory_review` finds unverified, expired, low-confidence and 90-day-old records;
427
+ `memory_revise` requires the current revision number to prevent lost edits, and
428
+ `memory_history` shows previous versions. Changing content or source clears verification.
429
+
430
+ Recall uses local SQLite full-text search (including Unicode), direct/related entity scope,
431
+ pinning and freshness signals—not an external model or embedding API. It excludes archived
432
+ and expired records, explains each selection, and respects an explicit character budget.
433
+ Confidence is supplied by the author, **not** a measured probability. Memory is untrusted
434
+ reference material, never permission to change a router; live state still needs checking.
435
+
436
+ Existing observations migrate in place as **unverified legacy knowledge**, with a standalone
437
+ `.pre-knowledge-*.bak` database snapshot made before migration. The original graph tools and
438
+ Raycast API remain compatible. Automatic recording creates device entities after successful
439
+ calls and logs metadata only; it does not infer facts from command output. Routine tool-call
440
+ metadata is pruned to the latest 10,000 entries, while knowledge revisions are retained.
441
+ Common pasted credential formats are rejected, but memory is **not a secret vault**—do not
442
+ store passwords, private keys or tokens. Run `bun run test:memory` for real SQLite migration,
443
+ recall, API and dashboard regression tests.
444
+
445
+ **Shared memory.** The **Memory → Shared memory** tab assigns an explicit scope to a knowledge
446
+ entity, with a preview of who inherits its existing and future memories:
447
+
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 |
453
+
454
+ Create a **dedicated policy entity**, not a copy of a router's observations. For example, after
455
+ creating `fleet-policy` with `memory_create_entities`, read `memory_get_scope` and pass its
456
+ revision to `memory_set_scope`:
457
+
458
+ ```json
459
+ {
460
+ "entityName": "fleet-policy",
461
+ "scope": "shared",
462
+ "members": [],
463
+ "expectedRevision": 0,
464
+ "confirmSharing": true
465
+ }
466
+ ```
467
+
468
+ Then use `memory_remember` on `fleet-policy`, for example with key `changes.backup`, kind
469
+ `constraint`, source `operator confirmation`, and content `Take a recoverable backup before
470
+ configuration changes`. For a group, use `scope: "group"` and exact existing entity names in
471
+ `members`; saving replaces the whole member list. Scope changes require the latest revision
472
+ and explicit confirmation of sharing **all** the entity's memories. Existing records are never
473
+ promoted automatically. An evidence-aware database gets a portable `.pre-shared-memory-*.bak`
474
+ snapshot before the scope tables are introduced.
475
+
476
+ The MCP server's LLM instructions define this workflow:
477
+
478
+ 1. Recall separately for each target using its exact `entityName`. Shared and explicit Group
479
+ knowledge are included even with `includeRelated: false`. Graph relations do not imply
480
+ inheritance; related results are labeled reference-only.
481
+ 2. Inspect `applicableScopes`, each record's `scope`/`applicability`, `conflicts`,
482
+ `constraintsOmitted`, `truncated` and `warnings`. Applicable pinned/constraint records bypass
483
+ lexical matching and are prioritized, but a bounded context can still omit them.
484
+ 3. If constraints are omitted, review them for each applicable scope before a router write.
485
+ If a stable key has different active values, inspect both sources and resolve the conflict
486
+ with fresh evidence or operator direction. **No automatic Device-over-Shared override.**
487
+ Conflict detection compares explicit keys and exact values; it is not semantic reasoning.
488
+ 4. Keep local facts local. Share only intentionally reusable knowledge with source and expiry.
489
+ Recalled text never overrides current instructions or grants permission for mutations.
490
+
491
+ Scope badges, filters, explicit membership, revision checks and conflict previews are available
492
+ in the dashboard. Sharing is local to this MCP database—not cloud synchronization, an ACL or
493
+ tenant isolation. Clients must reconnect to receive updated MCP server instructions.
373
494
 
374
495
  <div align="center">
375
496
  <img src="assets/screenshots/web/dashboard-memory.webp" alt="Memory knowledge graph" width="820" />
@@ -533,6 +654,50 @@ HTTP transports expose `POST /mcp` and `GET /health` with DNS-rebinding protecti
533
654
 
534
655
  ## Configuration
535
656
 
657
+ ### Update MCP settings through tools
658
+
659
+ The **MCP Settings** module (`mcp-settings`) manages host-side settings without
660
+ contacting a router, even when the dashboard is disabled:
661
+
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 |
670
+
671
+ Editable fields cover MCP tool pagination, App views and capability gating;
672
+ SSH pooling; dashboard retention/body capture/redaction; Memory enablement; and
673
+ startup update checks. Partial patches preserve omitted settings. For example,
674
+ preview `{"changes":{"ssh":{"keepAlive":true,"idleTimeout":60000}}}`,
675
+ then apply the same changes with the returned `revision` and `confirm:true` only
676
+ after user approval. Read back and confirm using the **new** revision and
677
+ `pending_id` (the update result's `pendingId`, also `pending.id` in readback).
678
+
679
+ Writes are unavailable in read-only mode. Devices, credentials, listener addresses,
680
+ file paths, access ceilings, tool restrictions and probe allowlists remain
681
+ operator-managed. These tools cannot disable redaction; enabling body capture
682
+ requires redaction. They return no credential values. Config files and backups
683
+ are written with owner-only permissions (`0600` on POSIX).
684
+
685
+ Dashboard and tool edits in the same process share one pending transaction; stale revisions and
686
+ conflicting edits are rejected. Unconfirmed tool updates roll back after **60s**
687
+ by default (configurable from 30–600s) **while the process remains alive**.
688
+ Never restart with a pending update: confirm first, then restart separately if
689
+ the preview requires it. MCP presentation, dashboard recorder and update-check
690
+ changes need a restart for full activation. Memory enablement is checked on the
691
+ next operation; SSH settings affect subsequent calls/new connections and new idle
692
+ timers without forcibly disconnecting existing sessions.
693
+
694
+ The saved config path is returned by the tools. If the server was started from
695
+ environment variables alone, use `--config <path>` on future starts; CLI/env
696
+ overrides can still take precedence. A configured value is not evidence of a
697
+ restart or of router connectivity.
698
+
699
+ ### Environment and CLI
700
+
536
701
  Settings come from `MIKROTIK_*` env vars or matching CLI flags (defaults → env → flags):
537
702
 
538
703
  | Variable | Flag | Default | Purpose |