unifi-mcp-server: Instructions file for Codex

AI Agent Guidelines for UniFi MCP Server

This document provides universal rules, workflows, and best practices for all AI coding agents contributing to the UniFi MCP Server project. These guidelines ensure consistency, quality, and security across all AI-assisted development.

Table of Contents

• Core Principles
• File Structure and Organization
• Workflow Guidelines
• Do's and Don'ts
• Testing Requirements
• Security Guardrails
• Code Quality Standards
• Documentation Requirements
• Approval and Merge Policies

Core Principles

All AI agents must adhere to these fundamental principles:

1. Safety First

• Never perform destructive operations without explicit confirmation
• Always validate inputs and handle errors gracefully
• Implement proper authentication and authorization checks
• Never commit or expose sensitive data

2. Clarity and Transparency

• Write clear, self-documenting code with appropriate comments
• Document all decisions and trade-offs
• Tag AI-generated contributions appropriately
• Explain complex logic in docstrings

3. Consistency

• Follow the project's established patterns and conventions
• Maintain consistent code style (enforced by linting tools)
• Use consistent naming conventions throughout the codebase
• Adhere to the project's architecture and design patterns

4. Quality Over Speed

• Prioritize correctness and maintainability over quick delivery
• Include comprehensive tests for all code changes
• Ensure code passes all quality checks before submission
• Perform self-review before requesting human review

File Structure and Organization

Project Layout

unifi-mcp-server/
├── .github/
│   └── workflows/          # CI/CD pipeline definitions
├── src/
│   ├── __init__.py
│   ├── main.py            # MCP server entry point
│   ├── config/            # Configuration management
│   │   ├── __init__.py
│   │   ├── settings.py    # Pydantic settings models
│   │   └── config.yaml    # Default configuration
│   ├── api/               # UniFi API client
│   │   ├── __init__.py
│   │   ├── client.py      # HTTP client wrapper
│   │   └── endpoints.py   # API endpoint definitions
│   ├── tools/             # MCP tool definitions
│   │   ├── __init__.py
│   │   ├── devices.py     # Device management tools
│   │   ├── networks.py    # Network configuration tools
│   │   └── firewall.py    # Firewall rule tools
│   ├── resources/         # MCP resource definitions
│   │   ├── __init__.py
│   │   └── schemas.py     # Resource URI schemas
│   └── utils/             # Utility functions
│       ├── __init__.py
│       └── validators.py  # Input validation helpers
├── tests/
│   ├── __init__.py
│   ├── conftest.py        # Pytest fixtures
│   ├── unit/              # Unit tests
│   └── integration/       # Integration tests
├── docs/                  # Additional documentation
├── .env.example           # Environment variable template
├── .gitignore
├── .aiignore
├── pyproject.toml
├── README.md
└── ...