unifi-mcp-server: Instructions file for Codex

AI Agent Guidelines for UniFi MCP Server

Rules and workflows for every AI coding agent that contributes to the UniFi MCP Server. CLAUDE.md is the short version; the skills in .claude/skills/ cover each tool set in detail.

Table of Contents

• Core Principles
• Project Layout
• Workflow
• Writing a Tool
• Testing Requirements
• Security Guardrails
• UniFi API Guidelines
• Code Quality Standards
• Documentation Requirements
• Approval and Merge Policies
• XERJ (code search)

Core Principles

1. Safety first. No write operation runs without explicit confirmation, and every write supports a dry run. Validate inputs. Never commit or log secrets.
2. Evidence over assumption. Read the code before you describe it. UniFi endpoints differ between firmware versions, so a test against mocks proves the request shape, not that the endpoint exists. Say which one you verified.
3. Consistency. Copy the pattern of the nearest existing tool. Do not add a second way to do something the codebase already does.
4. Small, reviewable changes. One logical change per commit. Do not refactor code that the task does not need.

Project Layout

src/
├── main.py              # Entry point: tool module lists per API mode and profile, registration
├── tool_registry.py     # Tool wrapper: routing, risk tiers, read-only/dry-run, audit, cache
├── access.py            # Roles and the risk tiers each role may call
├── cache.py             # Redis read cache (optional)
├── memory.py            # Supermemory operator notes (optional)
├── config/config.py     # Settings (every environment variable) and URL path helpers
├── api/                 # UniFiClient, ProtectClient, SiteManagerClient, pool, rate limiter
├── tools/               # One module per feature area; every public async function is a tool
├── models/              # Pydantic models
├── resources/           # MCP resources
├── fleet/               # Multi-controller registry, router, tokens, fleet_* and admin tools
├── worker/              # Background health and sync workers
├── a2a/                 # A2A agent card and endpoints
└── utils/               # Validators, exceptions, audit log, metrics, SIEM export
tests/
├── conftest.py          # Clears UNIFI_* environment variables for every test
├── unit/                # Unit tests; tests/unit/tools/ holds the tool module tests
└── integration/         # Needs a real controller; marked with @pytest.mark.integration