Tools
plan_rollout
Plan a Staged Fleet Rollout · Risk: read
Previews a fleet-wide change WITHOUT touching anything: which devices are selected, how they split into canary → wave → fleet, the exact commands each will run, and a rough duration. This is the tool to call before start_rollout, and the output is what a human should approve. targets is an explicit device list or a selector (all, tags, versionBelow, exclude). Put the router you reach the others THROUGH last in an explicit list — wave order follows the order given. Completely side-effect-free: no device is contacted.
| Parameter | Required | Definition |
|---|---|---|
commands | Yes | RouterOS commands to apply to every device (array, or newline-separated) {"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"string"}]} |
targets | Yes | Device names, or a selector like {"tags":["branch"]} {"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"object","properties":{"all":{"description":"Every configured, enabled device","type":"boolean"},"tags":{"description":"Devices carrying ALL of these config tags","type":"array","items":{"type":"string"}},"versionBelow":{"description":"Devices whose RouterOS version is below this, e.g. \"7.14\" (uses the capability cache)","type":"string"},"exclude":{"description":"Device names to leave out — composable","type":"array","items":{"type":"string"}}},"additionalProperties":false}]} |
strategy | No | {"type":"object","properties":{"canary":{"description":"Devices in wave 1 (default 1)","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"wavePercent":{"description":"Percent of the remaining devices in wave 2 (default 25)","type":"integer","minimum":1,"maximum":100},"soakSeconds":{"description":"Wait after each wave's health check before continuing (default 30)","type":"integer","minimum":0,"maximum":9007199254740991},"onFailure":{"description":"What to do when a wave's gate fails (default halt-and-revert)","type":"string","enum":["halt-and-revert","halt-and-hold","continue"]}},"additionalProperties":false} |
label | No | What this change is, e.g. "ntp servers" {"type":"string"} |
start_rollout
Start a Staged Fleet Rollout · Risk: dangerous
Applies a change across the whole selection as canary → wave → fleet, with a health gate and a soak between waves. Each device is snapshotted, changed inside Safe Mode, verified still reachable, and only then committed. The gate checks the devices just changed AND the ones not yet touched — a change that breaks the wider network shows up as an untouched router going dark, which no per-device check sees. On failure the default (halt-and-revert) restores every device this rollout already changed, newest first, and skips the rest; halt-and-hold stops and changes nothing back; continue presses on and reports the failures. High blast radius — run plan_rollout first and show a human the output. Returns a rollout id; follow it with rollout_status, stop it with abort_rollout.
| Parameter | Required | Definition |
|---|---|---|
service_contracts | No | Optional service contracts: must pass before any change and after every wave. Probes originate from the MCP host, not the router. Unknown blocks the gate. {"maxItems":10,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"device":{"type":"string","minLength":1}},"required":["id","device"],"additionalProperties":false}} |
commands | Yes | RouterOS commands to apply to every device {"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"string"}]} |
targets | Yes | {"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"object","properties":{"all":{"description":"Every configured, enabled device","type":"boolean"},"tags":{"description":"Devices carrying ALL of these config tags","type":"array","items":{"type":"string"}},"versionBelow":{"description":"Devices whose RouterOS version is below this, e.g. \"7.14\" (uses the capability cache)","type":"string"},"exclude":{"description":"Device names to leave out — composable","type":"array","items":{"type":"string"}}},"additionalProperties":false}]} |
strategy | No | {"type":"object","properties":{"canary":{"description":"Devices in wave 1 (default 1)","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"wavePercent":{"description":"Percent of the remaining devices in wave 2 (default 25)","type":"integer","minimum":1,"maximum":100},"soakSeconds":{"description":"Wait after each wave's health check before continuing (default 30)","type":"integer","minimum":0,"maximum":9007199254740991},"onFailure":{"description":"What to do when a wave's gate fails (default halt-and-revert)","type":"string","enum":["halt-and-revert","halt-and-hold","continue"]}},"additionalProperties":false} |
label | No | {"type":"string"} |
confirm | Yes | Must be true to execute — false returns the plan instead {"default":false,"type":"boolean"} |
rollout_status
Rollout Status · Risk: read
Reports the state of a rollout — current wave, per-device stage (pending / applied / failed / reverted / skipped), and every gate result so far. Omit rollout_id to list the rollouts still in flight. Reads local state only; no device is contacted.
| Parameter | Required | Definition |
|---|---|---|
rollout_id | No | Rollout id from start_rollout {"type":"string"} |
abort_rollout
Abort a Rollout · Risk: write
Stops a rollout now and restores every device it already changed, newest first — unlike a gate failure this is unconditional, so it reverts even when the rollout was started with onFailure=halt-and-hold. Devices not yet touched are simply skipped. If a revert itself fails the report names the device and the snapshot to restore it from.
| Parameter | Required | Definition |
|---|---|---|
rollout_id | Yes | Rollout id from start_rollout {"type":"string"} |
reason | No | Recorded in the rollout history {"type":"string"} |