unifi-mcp: Instructions file for Codex

Project Rules

Non-Goals

This project is not:

• a general-purpose network management framework
• a UniFi controller replacement or admin dashboard
• a real-time monitoring or alerting service
• a CI/CD pipeline runner or deployment tool
• a web application with a frontend UI (dev consoles are debugging REPLs only)
• a database or persistent storage layer (all state lives on UniFi controllers)

Architecture Rules

Layering

• Tool functions MUST NOT contain business logic beyond argument validation and response formatting
• Tool functions MUST delegate to manager methods for all controller interactions
• Manager methods MUST NOT import from <app>.tools (no circular dependencies)
• All controller communication MUST flow through ConnectionManager
• Tool modules MUST import singletons from <app>.runtime, never instantiate directly
• Shared packages MUST NOT import from app packages (dependency flows downward only)
• App packages MUST NOT import from each other (no cross-app dependencies)

Singletons

• All shared objects (server, config, managers) MUST be created via @lru_cache factories in <app>/runtime.py
• Tests MUST monkey-patch the factory or alias before importing tool modules
• There MUST be exactly one ConnectionManager instance per server process

Tool Response Contract

All tools MUST return Dict[str, Any]:

{"success": True, "data": <result>}                                    # Success
{"success": False, "error": "<specific, actionable message>"}          # Error
{"success": True, "requires_confirmation": True, "preview": <payload>} # Mutation preview

• Exceptions MUST NOT escape tool functions. Catch, log with exc_info=True, return error dict.
• Error messages MUST include the operation that failed (e.g., "Failed to list devices: ..." not just str(e)).
• Raw tracebacks MUST NOT be exposed to MCP clients.

Confirmation System

All state-changing tools MUST implement preview-then-confirm:

• confirm=False (default): validate input, return preview payload
• confirm=True: execute the mutation on the controller
• Bypass mode injects confirm=True automatically
• Anchor: packages/unifi-mcp-shared/src/unifi_mcp_shared/confirmation.py