@usex/mikrotik-mcp 5.16.0 → 5.18.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 (40) hide show
  1. package/README.md +180 -5
  2. package/dist/cli.js +7298 -4293
  3. package/dist/index.d.ts +12 -1
  4. package/dist/index.js +54 -16
  5. package/dist/shared/cli-97csvm6f.js +25 -0
  6. package/dist/shared/cli-ff6yww2e.js +13 -0
  7. package/dist/shared/cli-s423xk9v.js +7 -0
  8. package/dist/shared/{library-pdyv4a32.js → library-08g0pwc9.js} +1 -1
  9. package/dist/shared/{library-0ysgbdj6.js → library-552hdvw2.js} +6244 -4454
  10. package/dist/shared/library-gmx9pzx3.js +17 -0
  11. package/dist/shared/library-w5tyng4c.js +7 -0
  12. package/dist/shared/library-xbg1d52n.js +13 -0
  13. package/dist/ui/client-check.html +80 -0
  14. package/dist/ui/observability.html +136 -75
  15. package/package.json +20 -7
  16. package/schemas/README.md +1 -1
  17. package/schemas/config.schema.json +18 -0
  18. package/schemas/devtools-manifest.json +11996 -0
  19. package/schemas/tool-catalog.json +755 -3
  20. package/schemas/tools/apply_router_migration.json +27 -0
  21. package/schemas/tools/close_client_check.json +14 -0
  22. package/schemas/tools/compare_client_checks.json +24 -0
  23. package/schemas/tools/create_client_check.json +25 -0
  24. package/schemas/tools/create_support_bundle.json +41 -0
  25. package/schemas/tools/delete_support_bundle.json +18 -0
  26. package/schemas/tools/export_support_bundle.json +19 -0
  27. package/schemas/tools/inspect_router_migration.json +7 -0
  28. package/schemas/tools/list_client_checks.json +7 -0
  29. package/schemas/tools/list_router_migrations.json +7 -0
  30. package/schemas/tools/list_support_bundles.json +7 -0
  31. package/schemas/tools/memory_get_scope.json +14 -0
  32. package/schemas/tools/memory_history.json +14 -0
  33. package/schemas/tools/memory_recall.json +35 -0
  34. package/schemas/tools/memory_remember.json +65 -0
  35. package/schemas/tools/memory_review.json +44 -0
  36. package/schemas/tools/memory_revise.json +61 -0
  37. package/schemas/tools/memory_set_scope.json +37 -0
  38. package/schemas/tools/preview_router_migration.json +62 -0
  39. package/schemas/tools/undo_router_migration.json +18 -0
  40. /package/dist/shared/{cli-gee7615j.js → cli-3zrj182m.js} +0 -0
package/README.md CHANGED
@@ -1,20 +1,20 @@
1
1
  <div align="center">
2
2
  <img src="assets/logo.svg" alt="@usex/mikrotik-mcp" width="440" />
3
- <p><strong>Drive one or more MikroTik routers in plain language — 901 risk-annotated tools your AI can call, over SSH.</strong><br/>
3
+ <p><strong>Drive one or more MikroTik routers in plain language — 924 risk-annotated tools your AI can call, over SSH.</strong><br/>
4
4
  Firewall · routing · DHCP/DNS · wireless · QoS · a complete VPN suite · transactional Safe Mode · live attack detection · and an observability dashboard that watches every call.</p>
5
5
 
6
6
  <p>
7
7
  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-7C3AED.svg"></a>
8
8
  <img alt="Runtime: Bun" src="https://img.shields.io/badge/runtime-Bun%20%E2%89%A5%201.3-06B6D4.svg">
9
9
  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-strict-6366F1.svg">
10
- <img alt="MCP" src="https://img.shields.io/badge/MCP-901%20tools-1F2937.svg">
10
+ <img alt="MCP" src="https://img.shields.io/badge/MCP-924%20tools-1F2937.svg">
11
11
  <a href="docs/"><img alt="Docs" src="https://img.shields.io/badge/docs-reference-7C3AED.svg"></a>
12
12
  </p>
13
13
  </div>
14
14
 
15
15
  ---
16
16
 
17
- `@usex/mikrotik-mcp` turns **MikroTik RouterOS** into **901 [Model Context Protocol](https://modelcontextprotocol.io)
17
+ `@usex/mikrotik-mcp` turns **MikroTik RouterOS** into **924 [Model Context Protocol](https://modelcontextprotocol.io)
18
18
  tools** any MCP client (Claude Desktop, Claude Code, Cursor, …) can call to read and
19
19
  configure your router by talking to it. It reaches the device over **plain SSH** — no
20
20
  agent, no package to install on RouterOS — runs on **[Bun](https://bun.sh)**, and
@@ -46,6 +46,21 @@ Then just ask:
46
46
 
47
47
  ## Highlights
48
48
 
49
+ - **Client Check** — invite the affected phone/laptop with an expiring QR/link,
50
+ measure browser HTTP latency, loaded latency and bounded transfers, and compare
51
+ Wi-Fi/VPN runs in the dashboard. Optional investigation links keep evidence together.
52
+ Tests measure the path **to the MCP host**, not arbitrary internet speed, DNS leakage
53
+ or PMTU. [Guide and trust boundary](docs/network-workspaces.md#client-check)
54
+ - **Router Migration** — inspect both routers, map Ethernet ports, preview supported
55
+ configuration and review omitted sections. Fresh-state checks, local snapshots of
56
+ both routers, Safe Mode rehearsal and verified **inactive staging** protect the
57
+ target. Physical cutover, credentials and activation remain operator-controlled.
58
+ [Supported scope](docs/network-workspaces.md#router-migration)
59
+ - **Support Bundles** — prepare a time-bounded report from saved investigations,
60
+ event metadata, snapshot inventories and client measurements. Raw tool bodies,
61
+ secrets and personal labels stay out; network identifiers become consistent aliases.
62
+ Review before downloading self-contained HTML or JSON. Nothing is uploaded.
63
+ [Privacy and export](docs/network-workspaces.md#support-bundles)
49
64
  - **MCP App workspaces** — 13 host-themed views, with dedicated investigation,
50
65
  round-trip, service-health, L2 fabric, operations and report workspaces alongside
51
66
  the existing device, interface, firewall and record views. Responsive grids,
@@ -71,7 +86,7 @@ Then just ask:
71
86
  Uses existing NetFlow/IPFIX exports; never enables capture or changes router settings.
72
87
  Missing telemetry remains unknown, not a fabricated blocking hop.
73
88
  [Flow-path guide](docs/client-flow-paths.md)
74
- - 🧰 **901 tools, one per RouterOS scope** — L2 (bridge, VLAN, wireless, PoE),
89
+ - 🧰 **924 tools, one per RouterOS scope** — L2 (bridge, VLAN, wireless, PoE),
75
90
  L3 (addressing, routing, DHCP, DNS), security (firewall, NAT, address-lists,
76
91
  certificates), QoS, and system ops (users, logs, backups, scheduler).
77
92
  - 🛡️ **Attack detection** — reads every device's log, correlates brute force,
@@ -216,6 +231,41 @@ Behind a bastion with no exposed port? Jump through another router (`jumpVia`)
216
231
  commands, Safe Mode and SFTP all ride the hop. Full guide:
217
232
  **[docs/multi-device.md](docs/multi-device.md)**.
218
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
+
219
269
  ### 🩺 Diagnose and harden
220
270
 
221
271
  > _"Why can't VLAN 50 reach the internet?"_
@@ -294,6 +344,17 @@ and last-seen.
294
344
 
295
345
  **RADIUS & User Manager.** Servers, sessions, profiles, limitations and vouchers.
296
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
+
297
358
  <div align="center">
298
359
  <img src="assets/screenshots/web/dashboard-radius-um.webp" alt="RADIUS & User Manager" width="820" />
299
360
  </div>
@@ -354,7 +415,82 @@ auto-rollback.
354
415
  <img src="assets/screenshots/web/dashboard-config.webp" alt="Config Studio" width="820" />
355
416
  </div>
356
417
 
357
- **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.
358
494
 
359
495
  <div align="center">
360
496
  <img src="assets/screenshots/web/dashboard-memory.webp" alt="Memory knowledge graph" width="820" />
@@ -389,6 +525,36 @@ For frontend development, `bun run dev:dashboard` connects
389
525
  the UI on port 9191 to the existing dashboard backend on port 9091.
390
526
  See the [dashboard design system](docs/dashboard-design.md).
391
527
 
528
+ ### DevFrame developer tools
529
+
530
+ Run the dashboard backend and the DevTools frontend in **two terminals** from
531
+ the repository root:
532
+
533
+ ```sh
534
+ # Terminal 1 — MCP server and dashboard API
535
+ bun run start:dev --dashboard --dashboard-port 9091 --config /path/to/devices.json
536
+
537
+ # Terminal 2 — dashboard frontend with DevFrame enabled
538
+ bun run dev:tools
539
+ ```
540
+
541
+ Open **http://127.0.0.1:9191/** and authorize the DevFrame dock with the one-time
542
+ code printed in the development terminal when prompted. If the port is occupied,
543
+ run `bun run dev:tools --port 9194` and open **http://127.0.0.1:9194/** instead.
544
+ The backend stays on port **9091**; `start:dev` alone does not enable DevFrame.
545
+
546
+ - **Data Inspector:** explore tool schemas, modules, prompts, App View coverage,
547
+ device requirements, navigation and build diagnostics.
548
+ - **Devframe Inspector:** enable **Settings → Advanced → Show Devframe Inspector**,
549
+ then filter **Functions** by `mikrotik:` for read-only MCP inspection queries.
550
+ - **A11y Inspector:** audit the current dashboard page for accessibility issues.
551
+
552
+ After changing tool declarations, run `bun run gen:schemas` to refresh the public
553
+ inspection data. Run `bun run build:ui` to populate build-artifact diagnostics.
554
+ DevFrame is development-only: it is not embedded in production builds, does not
555
+ load device credentials, and does not expose another router-execution endpoint.
556
+ See the [DevTools guide](docs/devtools.md) for search examples and security boundaries.
557
+
392
558
  **Access Scope settings** can be edited directly in the dashboard: configure risk
393
559
  ceilings, router allow/block lists and tool-name patterns, preview permission
394
560
  decisions without executing tools, then review and apply with a 60-second
@@ -466,6 +632,15 @@ MCP **prompts** are one-click guided workflows — authored as Markdown in
466
632
 
467
633
  See **[docs/prompts.md](docs/prompts.md)**.
468
634
 
635
+ Browse the live library under **Workspace → Prompts** in the dashboard, or run
636
+ **Prompt Library** in Raycast (also available in the Fleet Menu Bar). Search and
637
+ filter workflows, fill their required inputs, add your own request and target
638
+ router, then preview and copy the completed brief into an MCP-connected assistant.
639
+ Nothing runs on a router while composing. The dashboard links open ChatGPT/Claude
640
+ without including your request in the URL; paste and send it yourself. Raycast also
641
+ offers **Ask Raycast AI for a Plan** when AI access is available: this sends the
642
+ request to Raycast AI for advice, not MCP tool execution.
643
+
469
644
  ## Transports
470
645
 
471
646
  | Transport | When | Run |