unifi-mcp-server: Instructions file for Gemini CLI

UniFi MCP Server - Google Gemini AI Configuration

This document provides Google Gemini-specific instructions for developing, testing, and extending the UniFi MCP Server. For universal agent rules and conventions, refer to AGENTS.md.

---

Quick Start with Gemini CLI

Prerequisites

# Install Gemini CLI
npm install -g @google/generative-ai-cli

# Set up API key (get from Google AI Studio)
export GEMINI_API_KEY="your-api-key"

# Or add to .env
echo "GEMINI_API_KEY=your-api-key" >> .gemini/.env

Configuration

Create .gemini/settings.json in project root:

{
  "model": {
    "name": "gemini-2.5-pro",
    "temperature": 0.3
  },
  "context": {
    "fileName": ["GEMINI.md", "AGENTS.md", "API.md", "README.md"]
  },
  "mcpServers": {
    "unifi": {
      "command": "uv",
      "args": ["--directory", ".", "run", "python", "src/main.py"],
      "env": {
        "UNIFI_API_KEY": "${UNIFI_API_KEY}",
        "UNIFI_API_TYPE": "cloud"
      }
    }
  }
}

---

Project Context for Gemini

Technology Stack

• Language: Python 3.10+
• Framework: FastMCP (Model Context Protocol server)
• API Client: Async UniFi Network API
• Testing: pytest, pytest-asyncio, pytest-cov
• Caching: Redis (optional, with async client)
• Validation: Pydantic v2 models
• Code Quality: black, isort, ruff, mypy, pre-commit

Architecture Overview

src/
├── main.py              # MCP server entry point (55 tools)
├── api/                 # UniFi API client with rate limiting
├── models/              # Pydantic data models
│   └── zbf.py          # Zone-Based Firewall models
├── tools/               # MCP tool implementations (read + write)
├── resources/           # MCP resource definitions
├── cache.py             # Redis caching layer
├── webhooks/            # Event handlers
└── utils/               # Validators and helpers

---

Gemini-Specific Development Guidelines

1. Code Generation Standards