Permission System Redesign — Simpler, Safer, More Powerful

[sirkirby]

We've completely redesigned how permissions work across all three MCP servers (Network, Protect, Access). This is the biggest quality-of-life improvement since launch.

What Changed

Before: Tools were hidden from the agent when permissions were disabled. You had to configure up to 15+ environment variables (UNIFI_PERMISSIONS_<CATEGORY>_<ACTION>=true) just to enable basic functionality. The config.yaml shipped locked down, and most container users couldn't modify it.

After: Every tool is always visible and discoverable. Safety comes from the confirmation flow — mutations preview what they'll do and wait for approval. You control the system with just two concepts.

The Two Concepts

Permission Mode — your trust dial:

• UNIFI_TOOL_PERMISSION_MODE=confirm (default) — mutations require human approval
• UNIFI_TOOL_PERMISSION_MODE=bypass — full trust, no confirmation prompts
• Per-server overrides: UNIFI_NETWORK_TOOL_PERMISSION_MODE=bypass

Policy Gates — hard boundaries when you need them:

• UNIFI_POLICY_DELETE=false # No deletes, any server
• UNIFI_POLICY_NETWORK_UPDATE=true # Allow updates on Network
• UNIFI_POLICY_NETWORK_NETWORKS_UPDATE=false # But not VLAN/subnet changes

Three levels (most specific wins): global → server → category. If nothing is set, everything is allowed.

What This Means For You

Zero config? Everything works. All 160 tools across all servers are callable. Mutations ask for confirmation before executing. This is the safest default.

Power user? One env var: UNIFI_TOOL_PERMISSION_MODE=bypass. Done.

Enterprise/restricted? Set your policy gates. Denied tools return clear messages telling the agent exactly how to enable them — no more mysterious "unknown tool" errors.

Running containers? No more fighting with config.yaml. Everything is env vars. Docker Compose, Kubernetes, n8n — just set what you need.

Backwards Compatibility

• UNIFI_AUTO_CONFIRM=true still works (maps to bypass mode with a deprecation warning)
• UNIFI_PERMISSIONS_<CATEGORY>_<ACTION> still works (honored as fallback with deprecation warning)
• Both will be removed in a future release — migration is straightforward

By the Numbers

• 160 tools now visible (was 126 with default permissions)
• 0 env vars needed for a safe, fully functional setup
• ~700 lines of permission boilerplate removed from config files
• All 3 servers + relay + cloud worker tested end-to-end

###Also in This Release

• unifi_update_network fails with "Unknown tool" due to networks.update default permission #103 fix: Tool index no longer shows tools you can't use (now moot — everything is callable)
• bug: generate_skill_references.py writes Windows-1252 bytes on Windows #105 fix: Windows encoding bug in generate_skill_references.py
• Docker fix: Relay discovery now works correctly with internal service names

Thanks to @level99 and @JayDeeCo for the bug reports and feedback that drove this redesign. Your input on the issue thread directly shaped the final design.