@usex/mikrotik-mcp 5.18.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 +213 -5
- package/dist/cli.js +3242 -835
- package/dist/index.js +169 -28
- package/dist/shared/{cli-97csvm6f.js → cli-426pkqe9.js} +8 -0
- package/dist/shared/{library-552hdvw2.js → library-73y8qdjr.js} +2619 -537
- package/dist/shared/{library-xbg1d52n.js → library-76naf20r.js} +1 -1
- package/dist/shared/{library-w5tyng4c.js → library-81amv3az.js} +1 -1
- package/dist/shared/{library-08g0pwc9.js → library-krajvnj9.js} +1 -1
- package/dist/shared/{library-gmx9pzx3.js → library-y9tt30y1.js} +11 -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 +77 -75
- 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 +358 -16
- package/schemas/tool-catalog.json +1133 -144
- 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/confirm_mcp_settings.json +19 -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_mcp_settings.json +7 -0
- package/schemas/tools/get_mcp_settings_schema.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_mcp_settings.json +94 -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/rollback_mcp_settings.json +19 -0
- 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/schemas/tools/update_mcp_settings.json +110 -0
- /package/dist/shared/{cli-3zrj182m.js → cli-6wdstvdq.js} +0 -0
- /package/dist/shared/{cli-s423xk9v.js → cli-cvt06346.js} +0 -0
- /package/dist/shared/{cli-ff6yww2e.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."_
|
|
@@ -445,11 +540,11 @@ recall, API and dashboard regression tests.
|
|
|
445
540
|
**Shared memory.** The **Memory → Shared memory** tab assigns an explicit scope to a knowledge
|
|
446
541
|
entity, with a preview of who inherits its existing and future memories:
|
|
447
542
|
|
|
448
|
-
| Scope
|
|
449
|
-
|
|
|
450
|
-
| Device (default) | Its IPs, routes, MTUs, firmware and measured outcomes
|
|
451
|
-
| Group
|
|
452
|
-
| Shared
|
|
543
|
+
| Scope | Intended knowledge | Included when recalling a device |
|
|
544
|
+
| ---------------- | ------------------------------------------------------- | ----------------------------------------- |
|
|
545
|
+
| Device (default) | Its IPs, routes, MTUs, firmware and measured outcomes | Only for that exact entity |
|
|
546
|
+
| Group | Policies for an explicit set of device entities | Only for listed members; no nested groups |
|
|
547
|
+
| Shared | Fleet-wide safeguards, preferences and reusable lessons | Automatically for every selected device |
|
|
453
548
|
|
|
454
549
|
Create a **dedicated policy entity**, not a copy of a router's observations. For example, after
|
|
455
550
|
creating `fleet-policy` with `memory_create_entities`, read `memory_get_scope` and pass its
|
|
@@ -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
|
|
|
@@ -654,6 +818,50 @@ HTTP transports expose `POST /mcp` and `GET /health` with DNS-rebinding protecti
|
|
|
654
818
|
|
|
655
819
|
## Configuration
|
|
656
820
|
|
|
821
|
+
### Update MCP settings through tools
|
|
822
|
+
|
|
823
|
+
The **MCP Settings** module (`mcp-settings`) manages host-side settings without
|
|
824
|
+
contacting a router, even when the dashboard is disabled:
|
|
825
|
+
|
|
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 |
|
|
834
|
+
|
|
835
|
+
Editable fields cover MCP tool pagination, App views and capability gating;
|
|
836
|
+
SSH pooling; dashboard retention/body capture/redaction; Memory enablement; and
|
|
837
|
+
startup update checks. Partial patches preserve omitted settings. For example,
|
|
838
|
+
preview `{"changes":{"ssh":{"keepAlive":true,"idleTimeout":60000}}}`,
|
|
839
|
+
then apply the same changes with the returned `revision` and `confirm:true` only
|
|
840
|
+
after user approval. Read back and confirm using the **new** revision and
|
|
841
|
+
`pending_id` (the update result's `pendingId`, also `pending.id` in readback).
|
|
842
|
+
|
|
843
|
+
Writes are unavailable in read-only mode. Devices, credentials, listener addresses,
|
|
844
|
+
file paths, access ceilings, tool restrictions and probe allowlists remain
|
|
845
|
+
operator-managed. These tools cannot disable redaction; enabling body capture
|
|
846
|
+
requires redaction. They return no credential values. Config files and backups
|
|
847
|
+
are written with owner-only permissions (`0600` on POSIX).
|
|
848
|
+
|
|
849
|
+
Dashboard and tool edits in the same process share one pending transaction; stale revisions and
|
|
850
|
+
conflicting edits are rejected. Unconfirmed tool updates roll back after **60s**
|
|
851
|
+
by default (configurable from 30–600s) **while the process remains alive**.
|
|
852
|
+
Never restart with a pending update: confirm first, then restart separately if
|
|
853
|
+
the preview requires it. MCP presentation, dashboard recorder and update-check
|
|
854
|
+
changes need a restart for full activation. Memory enablement is checked on the
|
|
855
|
+
next operation; SSH settings affect subsequent calls/new connections and new idle
|
|
856
|
+
timers without forcibly disconnecting existing sessions.
|
|
857
|
+
|
|
858
|
+
The saved config path is returned by the tools. If the server was started from
|
|
859
|
+
environment variables alone, use `--config <path>` on future starts; CLI/env
|
|
860
|
+
overrides can still take precedence. A configured value is not evidence of a
|
|
861
|
+
restart or of router connectivity.
|
|
862
|
+
|
|
863
|
+
### Environment and CLI
|
|
864
|
+
|
|
657
865
|
Settings come from `MIKROTIK_*` env vars or matching CLI flags (defaults → env → flags):
|
|
658
866
|
|
|
659
867
|
| Variable | Flag | Default | Purpose |
|