@usex/mikrotik-mcp 5.19.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.
- package/README.md +172 -8
- package/dist/cli.js +2751 -679
- package/dist/index.js +148 -27
- package/dist/shared/{library-7wcv2ckk.js → library-73y8qdjr.js} +2231 -540
- package/dist/shared/{library-tqrvrykj.js → library-76naf20r.js} +1 -1
- package/dist/shared/{library-ppnv0f07.js → library-81amv3az.js} +1 -1
- package/dist/shared/{library-z7qsdq88.js → library-krajvnj9.js} +1 -1
- package/dist/shared/{library-f3be6g03.js → library-y9tt30y1.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 +63 -61
- 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 +22 -22
- 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 +287 -16
- package/schemas/tool-catalog.json +785 -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 +78 -0
- package/schemas/tools/design_network_segment.json +22 -6
- package/schemas/tools/destroy_recovery_lab.json +18 -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_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_inventory.json +7 -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-426pkqe9.js} +0 -0
- /package/dist/shared/{cli-y00nwzxx.js → cli-6wdstvdq.js} +0 -0
- /package/dist/shared/{cli-s0rxncz4.js → cli-cvt06346.js} +0 -0
- /package/dist/shared/{cli-gtq5bw8q.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."_
|
|
@@ -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
|
|
|
@@ -659,14 +823,14 @@ HTTP transports expose `POST /mcp` and `GET /health` with DNS-rebinding protecti
|
|
|
659
823
|
The **MCP Settings** module (`mcp-settings`) manages host-side settings without
|
|
660
824
|
contacting a router, even when the dashboard is disabled:
|
|
661
825
|
|
|
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
|
|
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 |
|
|
670
834
|
|
|
671
835
|
Editable fields cover MCP tool pagination, App views and capability gating;
|
|
672
836
|
SSH pooling; dashboard retention/body capture/redaction; Memory enablement; and
|