@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.
- package/README.md +180 -8
- package/dist/cli.js +3452 -729
- package/dist/index.js +148 -27
- package/dist/shared/{library-ppnv0f07.js → library-588vnctn.js} +1 -1
- package/dist/shared/{library-7wcv2ckk.js → library-6tvh3gq1.js} +2837 -545
- package/dist/shared/{library-tqrvrykj.js → library-g8far2nz.js} +1 -1
- package/dist/shared/{library-f3be6g03.js → library-k6m2bxjr.js} +1 -1
- package/dist/shared/{library-z7qsdq88.js → library-wj2xfx8h.js} +1 -1
- package/dist/ui/aaa.html +8 -8
- package/dist/ui/connected-devices.html +8 -8
- package/dist/ui/dashboard.html +16 -16
- package/dist/ui/fabric.html +11 -11
- package/dist/ui/firewall-audit.html +8 -8
- package/dist/ui/firewall.html +9 -9
- package/dist/ui/interfaces.html +8 -8
- package/dist/ui/investigations.html +11 -11
- package/dist/ui/observability.html +66 -62
- package/dist/ui/operations.html +11 -11
- package/dist/ui/records.html +12 -12
- package/dist/ui/reports.html +11 -11
- package/dist/ui/round-trip.html +11 -11
- package/dist/ui/service-health.html +11 -11
- package/package.json +24 -23
- package/prompts/audit-routeros-containers.md +27 -0
- package/prompts/audit-vlan-segmentation.md +31 -0
- package/prompts/setup-guest-wifi.md +23 -24
- package/prompts/setup-routeros-container.md +36 -0
- package/prompts/setup-v2ray-container-proxy.md +68 -194
- package/prompts/setup-vlan-network.md +27 -33
- package/schemas/README.md +1 -1
- package/schemas/devtools-manifest.json +327 -16
- package/schemas/tool-catalog.json +898 -109
- package/schemas/tools/add_container.json +42 -30
- package/schemas/tools/add_container_env.json +3 -4
- package/schemas/tools/add_container_mount.json +10 -4
- package/schemas/tools/apply_service_routing.json +23 -0
- package/schemas/tools/arm_service_routing.json +23 -0
- package/schemas/tools/configure_flight_recorder.json +30 -0
- package/schemas/tools/create_service_routing.json +91 -0
- package/schemas/tools/design_network_segment.json +22 -6
- package/schemas/tools/destroy_recovery_lab.json +18 -0
- package/schemas/tools/disconnect_ovpn_session.json +20 -0
- package/schemas/tools/export_network_incident.json +14 -0
- package/schemas/tools/freeze_network_incident.json +14 -0
- package/schemas/tools/get_container.json +11 -4
- package/schemas/tools/get_flight_recorder.json +7 -0
- package/schemas/tools/get_recovery_lab.json +7 -0
- package/schemas/tools/get_routeros_container_guide.json +22 -0
- package/schemas/tools/get_vlan_segmentation_guide.json +14 -0
- package/schemas/tools/list_container_envs.json +1 -1
- package/schemas/tools/list_container_mounts.json +7 -2
- package/schemas/tools/list_containers.json +2 -4
- package/schemas/tools/list_ovpn_sessions.json +7 -0
- package/schemas/tools/list_service_routing.json +7 -0
- package/schemas/tools/poll_recovery_lab.json +14 -0
- package/schemas/tools/prepare_recovery_lab.json +23 -0
- package/schemas/tools/preview_service_routing.json +23 -0
- package/schemas/tools/probe_service_routing.json +14 -0
- package/schemas/tools/recovery_lab_inventory.json +7 -0
- package/schemas/tools/remove_container.json +11 -4
- package/schemas/tools/remove_container_env.json +7 -3
- package/schemas/tools/remove_container_mount.json +18 -2
- package/schemas/tools/service_routing_address_page.json +19 -0
- package/schemas/tools/service_routing_inventory.json +7 -0
- package/schemas/tools/service_routing_traffic.json +14 -0
- package/schemas/tools/set_container_config.json +4 -6
- package/schemas/tools/start_container.json +11 -4
- package/schemas/tools/start_recovery_lab.json +18 -0
- package/schemas/tools/stop_container.json +11 -4
- package/schemas/tools/update_container.json +46 -6
- /package/dist/shared/{cli-j07tbrke.js → cli-h065ap70.js} +0 -0
- /package/dist/shared/{cli-s0rxncz4.js → cli-se3tgt7t.js} +0 -0
- /package/dist/shared/{cli-y00nwzxx.js → cli-t311px0m.js} +0 -0
- /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
|
|
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
|