unifi-console-mcp

Write safety

The flow

Every configuration write goes through one engine:

  1. Read the object (and any lists the validator needs). A failed read blocks the write.
  2. Validate the request against what the console is known to accept, and against the rest of your configuration.
  3. Preview (confirm=false): returns before, after, diff, warnings, errors, used_by, the request that would be sent, a fingerprint and, if applying would be refused, apply_blocked_reason. Previews are always allowed.
  4. Apply (confirm=true with the fingerprint): the object is re-read; if it changed since the preview the write is refused. The attempt is written to the journal before anything is sent.
  5. Send, read back and verify. The result states verified, lists any mismatches, shows the diff, and gives the exact rollback call. Nothing is retried automatically.

Gates

  1. UNIFI_CONSOLE_ENABLE_WRITES=true in the server’s own environment.
  2. The entity key is in UNIFI_CONSOLE_WRITE_ENTITIES (default: none).
  3. confirm=true with the matching fingerprint.
  4. Tier C entities also need a non-empty approval_note, stored in the journal.

Tiers: A reversible, local effect. B changes how traffic or names resolve for several clients, or diagnostic settings. C can cut connectivity or expose the network.

Request body rules

Guards

Testing approach

Unit tests run against an in-memory fake console that reproduces known console behaviour (for example rejecting a PUT that omits a required key). Live checks touch only throwaway zz- objects, or one nominated client restored afterwards.