@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.
- package/README.md +180 -5
- package/dist/cli.js +7298 -4293
- package/dist/index.d.ts +12 -1
- package/dist/index.js +54 -16
- package/dist/shared/cli-97csvm6f.js +25 -0
- package/dist/shared/cli-ff6yww2e.js +13 -0
- package/dist/shared/cli-s423xk9v.js +7 -0
- package/dist/shared/{library-pdyv4a32.js → library-08g0pwc9.js} +1 -1
- package/dist/shared/{library-0ysgbdj6.js → library-552hdvw2.js} +6244 -4454
- package/dist/shared/library-gmx9pzx3.js +17 -0
- package/dist/shared/library-w5tyng4c.js +7 -0
- package/dist/shared/library-xbg1d52n.js +13 -0
- package/dist/ui/client-check.html +80 -0
- package/dist/ui/observability.html +136 -75
- package/package.json +20 -7
- package/schemas/README.md +1 -1
- package/schemas/config.schema.json +18 -0
- package/schemas/devtools-manifest.json +11996 -0
- package/schemas/tool-catalog.json +755 -3
- package/schemas/tools/apply_router_migration.json +27 -0
- package/schemas/tools/close_client_check.json +14 -0
- package/schemas/tools/compare_client_checks.json +24 -0
- package/schemas/tools/create_client_check.json +25 -0
- package/schemas/tools/create_support_bundle.json +41 -0
- package/schemas/tools/delete_support_bundle.json +18 -0
- package/schemas/tools/export_support_bundle.json +19 -0
- package/schemas/tools/inspect_router_migration.json +7 -0
- package/schemas/tools/list_client_checks.json +7 -0
- package/schemas/tools/list_router_migrations.json +7 -0
- package/schemas/tools/list_support_bundles.json +7 -0
- package/schemas/tools/memory_get_scope.json +14 -0
- package/schemas/tools/memory_history.json +14 -0
- package/schemas/tools/memory_recall.json +35 -0
- package/schemas/tools/memory_remember.json +65 -0
- package/schemas/tools/memory_review.json +44 -0
- package/schemas/tools/memory_revise.json +61 -0
- package/schemas/tools/memory_set_scope.json +37 -0
- package/schemas/tools/preview_router_migration.json +62 -0
- package/schemas/tools/undo_router_migration.json +18 -0
- /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 —
|
|
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-
|
|
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 **
|
|
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
|
-
- 🧰 **
|
|
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.**
|
|
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 |
|