Cline rules

1# Cline Rules for UniFi MCP Server
2 
3## Project Overview
4This is a Python-based MCP (Model Context Protocol) server providing access to UniFi Network Controller API.
5- **Tech Stack**: Python 3.10+, FastMCP, asyncio, Pydantic, Redis (optional caching), agnost.ai (optional tracking)
6- **Architecture**: Async-first MCP server with 40+ tools, 4 resource endpoints, webhook support
7- **Purpose**: Enable AI agents to interact with UniFi network infrastructure via standardized MCP
8- **API Status**: Uses UniFi Early Access API (read-only operations currently; write operations available in v1 Stable)
9 
10## Core Development Principles
11 
12### 1. Documentation and Code Quality
13- **ALWAYS** update docstrings when modifying functions
14- Follow Google-style docstrings for all public APIs
15- Maintain comprehensive inline comments for complex logic
16- Update relevant documentation files (README.md, API.md, CONTRIBUTING.md) when adding features
17- All code changes MUST pass pre-commit hooks before committing
18 
19### 2. Async Programming Standards
20- Use `async/await` for ALL I/O-bound operations (API calls, database queries, file operations)
21- **NEVER** use blocking synchronous calls in async contexts
22- Leverage `asyncio.gather()` for concurrent operations
23- Implement proper exception handling with `try/except` blocks in async functions
24- Use `async with` for context managers (HTTP clients, database connections)
25 
26### 3. Type Safety and Validation
27- **ALWAYS** use type hints for function parameters and return values
28- Leverage Pydantic models for complex data structures and validation
29- Use `Optional[T]` or `T | None` for nullable parameters
30- Implement input validation at tool boundaries using Pydantic
31- Run `mypy` type checking before submitting PRs
32 
33### 4. Testing Requirements
34- Target: 80%+ code coverage for all new features
35- Write unit tests for individual functions using pytest
36- Create integration tests for API interactions (mark with `@pytest.mark.integration`)
37- Mock external dependencies (UniFi API, Redis) in unit tests
38- Use fixtures for common test setup and teardown
39- **NEVER** commit code that breaks existing tests
40 
41### 5. Security and Safety
42- **CRITICAL**: All mutating operations MUST require `confirm=True` parameter
43- Implement dry-run mode (`dry_run=True`) for preview-before-apply functionality
44- Log all operations to `audit.log` with timestamps and user context
45- Mask sensitive data (passwords, API keys) in logs using utility functions
46- Validate all user inputs at API boundaries
47- Follow principle of least privilege for API access
48 
49## Project Structure Conventions
50 
51### Directory Organization
52```
53src/
54├── main.py              # MCP server entry point (registers 40+ tools)
55├── config/              # Configuration management (Pydantic Settings)
56├── api/                 # UniFi API client (rate limiting, retries, auth)
57├── models/              # Pydantic models for data structures
58│   ├── device.py        # Device models
59│   ├── client.py        # Client models
60│   ├── network.py       # Network models
61│   ├── site.py          # Site models
62│   └── ...              # Additional domain models
63├── tools/               # MCP tool implementations (40+ tools)
64│   ├── clients.py       # Client query tools
65│   ├── devices.py       # Device management
66│   ├── networks.py      # Network configuration
67│   ├── firewall.py      # Firewall rules
68│   ├── wifi.py          # WiFi/SSID management
69│   ├── dpi.py           # DPI statistics
70│   └── ...              # Additional tool modules
71├── resources/           # MCP resource endpoints (4 resources)
72├── webhooks/            # Webhook handlers (HMAC verification)
73├── utils/               # Utility functions, validators, exceptions
74│   ├── exceptions.py    # Custom exception classes
75│   ├── validators.py    # Input validation helpers
76│   ├── audit.py         # Audit logging
77│   └── logger.py        # Logging utilities
78└── cache.py             # Redis caching implementation
79tests/
80├── unit/                # Unit tests (fast, no external deps)
81└── integration/         # Integration tests (require UniFi controller)
82```
83 
84### File Naming
85- Use snake_case for Python files: `device_control.py`, `network_config.py`
86- Group related tools in single files (e.g., all device tools in `devices.py`)
87- Test files mirror source structure: `tests/unit/tools/test_devices.py`
88 
89## Coding Standards
90 
91### Function Design
92- Keep functions focused on single responsibility
93- Prefer small, composable functions over large monoliths
94- Use descriptive function names: `create_firewall_rule()` not `create()`
95- Limit function parameters (max 5-7); use Pydantic models for complex inputs
96- Return explicit types; avoid returning `Any` or untyped dicts
97 
98### Error Handling
99```python
100from src.utils.exceptions import (
101    APIError,
102    AuthenticationError,
103    RateLimitError,
104    ResourceNotFoundError,
105    ValidationError,
106    NetworkError,
107    ConfirmationRequiredError
108)
109 
110# GOOD: Specific exception handling with context
111try:
112    result = await unifi_api.get_devices(site_id)
113except RateLimitError as e:
114    logger.warning(f"Rate limit exceeded, retry after {e.retry_after}s")
115    raise  # Re-raise for MCP protocol handling
116except AuthenticationError as e:
117    logger.error(f"Authentication failed: {e}")
118    raise  # Invalid API credentials
119except ResourceNotFoundError as e:
120    logger.error(f"Site not found: {e.resource_id}")
121    raise  # Resource doesn't exist
122except NetworkError as e:
123    logger.error(f"Network error: {e}")
124    raise APIError(f"Failed to connect to UniFi controller: {str(e)}")
125except APIError as e:
126    logger.error(f"API error {e.status_code}: {e.message}")
127    raise  # Re-raise API errors
128```
129 
130### MCP Tool Implementation Pattern
131```python
132from typing import Optional
133from fastmcp import FastMCP
134from src.utils.exceptions import (
135    ConfirmationRequiredError,
136    ValidationError,
137    APIError
138)
139from src.utils import get_logger
140from src.cache import cache
141 
142mcp = FastMCP("UniFi MCP Server")
143logger = get_logger(__name__)
144 
145@mcp.tool()
146async def example_tool(
147    site_id: str,
148    param1: str,
149    optional_param: Optional[int] = None,
150    confirm: bool = False,
151    dry_run: bool = False
152) -> dict:
153    """
154    Brief description of what the tool does.
155 
156    Args:
157        site_id: UniFi site identifier
158        param1: Description of param1
159        optional_param: Description of optional parameter
160        confirm: Required True for mutating operations
161        dry_run: Preview changes without applying
162 
163    Returns:
164        Dictionary containing operation results
165 
166    Raises:
167        ConfirmationRequiredError: If mutating operation lacks confirm=True
168        ValidationError: If input validation fails
169        APIError: If UniFi API request fails
170    """
171    # Validate inputs
172    if not site_id or not param1:
173        raise ValidationError("site_id and param1 are required")
174 
175    # Check confirmation for mutating operations
176    if not confirm and not dry_run:
177        raise ConfirmationRequiredError("example_tool")
178 
179    # Log operation (audit logging for mutating operations)
180    logger.info(f"Executing example_tool: site={site_id}, dry_run={dry_run}")
181 
182    # Implement logic
183    if dry_run:
184        preview = await generate_preview(site_id, param1)
185        return {"status": "preview", "changes": preview}
186 
187    try:
188        result = await perform_operation(site_id, param1)
189    except APIError as e:
190        logger.error(f"API operation failed: {e}")
191        raise
192 
193    # Invalidate cache if needed
194    await cache.invalidate(f"cache_key:{site_id}")
195 
196    return {"status": "success", "data": result}
197```
198 
199### Pydantic Model Usage
200```python
201from pydantic import BaseModel, Field, validator
202from src.models.device import Device
203 
204class DeviceResponse(BaseModel):
205    """Response model for device operations."""
206    device: Device
207    site_id: str = Field(..., description="Site identifier")
208    updated_at: str = Field(..., description="ISO timestamp")
209 
210    @validator('site_id')
211    def validate_site_id(cls, v):
212        if not v or len(v) < 1:
213            raise ValueError('site_id cannot be empty')
214        return v
215```
216 
217### Caching Strategy
218- Use Redis for caching when `REDIS_HOST` is configured
219- Set appropriate TTLs per resource type:
220  - Sites: 300s (5 minutes)
221  - Devices: 60s (1 minute)
222  - Clients: 30s (30 seconds - frequent changes)
223  - Networks: 300s (5 minutes)
224  - WLANs: 300s (5 minutes)
225  - Firewall rules: 300s (5 minutes)
226  - DPI stats: 120s (2 minutes)
227  - Alerts/Events: 30s (30 seconds - time-sensitive)
228- Invalidate cache on mutating operations
229- Handle cache misses gracefully (fallback to API)
230- Graceful degradation: server works without Redis (caching disabled)
231 
232## Git Workflow
233 
234### Commit Messages
235Follow Conventional Commits:
236```
237feat: add WiFi statistics tool
238fix: correct device restart timeout handling
239docs: update API.md with new firewall endpoints
240test: add integration tests for port forwarding
241refactor: simplify client management code
242```
243 
244### Branch Naming
245- Feature branches: `feature/wifi-statistics`
246- Bug fixes: `fix/device-restart-timeout`
247- Documentation: `docs/api-reference-update`
248 
249### Pull Request Requirements
2501. All tests pass (`pytest`)
2512. Code coverage meets 80% threshold
2523. Type checking passes (`mypy src/`)
2534. Pre-commit hooks pass (black, isort, ruff, bandit)
2545. Documentation updated (if applicable)
2556. CHANGELOG.md updated for user-facing changes
256 
257## Development Tools
258 
259### Required Commands
260```bash
261# Install dependencies
262uv pip install -e &quot;.[dev]&quot;
263 
264# Run tests
265pytest                          # All tests
266pytest -m unit                  # Unit tests only
267pytest -m integration          # Integration tests only
268pytest --cov=src --cov-report=html --cov-report=term-missing  # With coverage
269 
270# Code quality
271black src/ tests/               # Format code
272isort src/ tests/               # Sort imports
273ruff check src/ tests/ --fix   # Lint and fix
274mypy src/                       # Type check
275bandit -r src/                  # Security scan
276 
277# Development server
278uv run mcp dev src/main.py      # With MCP Inspector (http://localhost:5173)
279 
280# Production server
281uv run python src/main.py       # Standard MCP server
282```
283 
284### Testing with MCP Inspector
285```bash
286# Start development server
287uv run mcp dev src/main.py
288 
289# MCP Inspector opens at http://localhost:5173
290# Use to interactively test tools and resources
291```
292 
293### Pre-commit Hooks
294```bash
295# Install all hooks (including commit-msg for conventional commits)
296pre-commit install
297pre-commit install --hook-type commit-msg
298 
299# Manual run (run before committing)
300pre-commit run --all-files
301 
302# Run specific hook
303pre-commit run black --all-files
304pre-commit run ruff --all-files
305pre-commit run mypy --all-files
306```
307 
308**Hooks include:**
309- `black` - Code formatting
310- `isort` - Import sorting
311- `ruff` - Linting and auto-fixing
312- `mypy` - Type checking
313- `bandit` - Security scanning
314- `detect-secrets` - Secret detection
315- `commitlint` - Conventional commit validation
316 
317## Common Patterns
318 
319### API Client Usage
320```python
321from src.api.client import UniFiClient
322from src.config import Settings
323 
324# Load settings from environment
325settings = Settings()
326 
327# Create client (handles rate limiting, retries, authentication)
328async with UniFiClient(
329    api_key=settings.unifi_api_key,
330    host=settings.unifi_host,
331    api_type=settings.unifi_api_type,
332    site=settings.unifi_site
333) as client:
334    devices = await client.get_devices(site_id="default")
335    # Client handles:
336    # - Rate limiting (respects UNIFI_RATE_LIMIT)
337    # - Automatic retries (UNIFI_MAX_RETRIES)
338    # - Authentication (X-API-Key header)
339    # - Error handling (APIError exceptions)
340    # - Timeout management (UNIFI_TIMEOUT)
341```
342 
343### Resource Definition
344```python
345import json
346from fastmcp import FastMCP
347 
348mcp = FastMCP("UniFi MCP Server")
349 
350@mcp.resource("sites://{site_id}/devices")
351async def list_devices_resource(site_id: str) -> str:
352    """Expose devices as MCP resource.
353 
354    Args:
355        site_id: UniFi site identifier
356 
357    Returns:
358        JSON string of devices list
359    """
360    # Check cache first
361    cached = await cache.get(f"devices:{site_id}")
362    if cached:
363        return cached
364 
365    devices = await get_devices(site_id)
366    result = json.dumps(devices, indent=2)
367 
368    # Cache result
369    await cache.set(f"devices:{site_id}", result, ttl=60)
370 
371    return result
372```
373 
374### Webhook Handler
375```python
376import hmac
377import hashlib
378from src.webhooks.receiver import WebhookReceiver
379from src.webhooks.handlers import handle_device_event
380 
381# Webhook receiver with HMAC verification
382receiver = WebhookReceiver(
383    secret=settings.webhook_secret,
384    logger=logger
385)
386 
387@receiver.handler("device.connected")
388async def on_device_connected(event: dict):
389    """Handle device connection events.
390 
391    Args:
392        event: Webhook event payload (validated HMAC)
393    """
394    logger.info(f"Device connected: {event.get('device_mac')}")
395 
396    # Invalidate relevant caches
397    site_id = event.get('site_id', 'default')
398    await cache.invalidate(f"devices:{site_id}")
399    await cache.invalidate(f"clients:{site_id}")
400 
401    # Process event
402    await handle_device_event(event)
403```
404 
405### Webhook Security
406- **ALWAYS** verify HMAC signatures when `WEBHOOK_SECRET` is set
407- Use `hmac.compare_digest()` for constant-time comparison
408- Log all webhook events for audit purposes
409- Handle webhook failures gracefully (don't crash server)
410 
411## AI Agent Guidance
412 
413### When Adding New Features
4141. Review existing patterns in similar tools (e.g., check `devices.py` when adding device features)
4152. Check `src/models/` for existing Pydantic models - reuse or extend them
4163. Follow the MCP tool implementation pattern above
4174. Add comprehensive tests (both unit and integration) targeting 80%+ coverage
4185. Update API.md with new tool documentation
4196. Add examples to docstrings
4207. **Important**: If adding write operations, remember Early Access API is read-only; document limitation
421 
422### When Fixing Bugs
4231. Write a failing test that reproduces the bug
4242. Fix the bug using minimal changes
4253. Verify all tests pass
4264. Add regression test if needed
4275. Check exception types match expected behavior (use custom exceptions from `src.utils.exceptions`)
428 
429### When Refactoring
4301. Ensure tests provide adequate coverage before refactoring
4312. Refactor in small, atomic commits
4323. Run tests frequently during refactoring
4334. Update documentation if interfaces change
4345. Ensure Pydantic models remain backward compatible or version them
435 
436### API Read-Only Limitation
437**IMPORTANT**: The UniFi Early Access API is currently read-only for write operations. When implementing mutating tools:
438- Document that write operations may not be available until v1 Stable
439- Implement preview mode (`dry_run=True`) to show what would change
440- Return clear error messages if API returns 403 Forbidden
441- Monitor UniFi API release notes for v1 Stable availability
442 
443## Critical Reminders
444 
445### Security & Safety
446- **NEVER** commit API keys, passwords, or sensitive data
447- **ALWAYS** use `confirm=True` for operations that modify network state
448- **NEVER** expose sensitive data in logs (use masking utilities from `src.utils`)
449- **ALWAYS** verify webhook HMAC signatures when `WEBHOOK_SECRET` is set
450- **NEVER** hardcode credentials - always use environment variables
451 
452### Code Quality
453- **ALWAYS** write tests for new features (target 80%+ coverage)
454- **NEVER** merge code that fails type checking (`mypy`) or linting (`ruff`)
455- **ALWAYS** update documentation (API.md, docstrings) alongside code changes
456- **NEVER** use synchronous blocking calls in async contexts
457- **ALWAYS** validate inputs using Pydantic models (from `src.models/`)
458- **ALWAYS** use custom exception types from `src.utils.exceptions`
459 
460### Development Workflow
461- **ALWAYS** run pre-commit hooks before committing
462- **ALWAYS** run full test suite before pushing
463- **ALWAYS** use conventional commit messages
464- **NEVER** bypass CI/CD checks
465- **ALWAYS** request human review for security-related changes
466 
467### API Considerations
468- **REMEMBER** Early Access API is read-only for write operations
469- **ALWAYS** implement `dry_run=True` for mutating operations
470- **ALWAYS** respect rate limits (100 req/min for Early Access)
471- **ALWAYS** handle rate limit errors gracefully (429 with Retry-After)
472 
473## Environment Variables
474 
475Reference `.env.example` for all configuration options:
476 
477### Required Variables
478```
479UNIFI_API_KEY=<required>              # UniFi API key from unifi.ui.com
480```
481 
482### UniFi API Configuration
483```
484UNIFI_API_TYPE=cloud                  # or "local" for gateway proxy
485UNIFI_HOST=api.ui.com                 # or local gateway IP (e.g., 192.168.2.1)
486UNIFI_PORT=443                        # API port
487UNIFI_VERIFY_SSL=true                 # SSL verification (false for self-signed)
488UNIFI_SITE=default                    # Default site identifier
489UNIFI_RATE_LIMIT=100                  # Max requests per minute (Early Access: 100)
490UNIFI_TIMEOUT=30                      # Request timeout in seconds
491UNIFI_MAX_RETRIES=3                   # Maximum retry attempts
492```
493 
494### Redis Caching (Optional)
495```
496REDIS_HOST=localhost                  # Redis host (optional)
497REDIS_PORT=6379                       # Redis port
498REDIS_DB=0                            # Redis database number
499REDIS_PASSWORD=                       # Redis password (if required)
500```
501 
502### Webhook Support (Optional)
503```
504WEBHOOK_SECRET=<secret>               # HMAC secret for webhook verification
505```
506 
507### Performance Tracking with agnost.ai (Optional)
508```
509AGNOST_ENABLED=false                  # Enable agnost.ai tracking
510AGNOST_ORG_ID=                        # Organization ID from app.agnost.ai
511AGNOST_ENDPOINT=https://api.agnost.ai # Agnost API endpoint
512AGNOST_DISABLE_INPUT=false            # Disable input parameter tracking
513AGNOST_DISABLE_OUTPUT=false           # Disable output/result tracking
514```
515 
516### Logging
517```
518LOG_LEVEL=INFO                        # Logging level (DEBUG, INFO, WARNING, ERROR)
519```
520 
521## Additional Resources
522 
523### Project Documentation
524- **README.md** - Project overview, installation, usage
525- **API.md** - Complete API documentation (40+ tools, 4 resources)
526- **CONTRIBUTING.md** - Contribution guidelines
527- **SECURITY.md** - Security policy and best practices
528- **AGENTS.md** - AI agent-specific guidelines
529- **MCP_TOOLBOX.md** - MCP Toolbox analytics dashboard guide
530 
531### External Resources
532- **UniFi API**: [Official UniFi API Documentation](https://developer.ui.com/site-manager-api/gettingstarted)
533- **MCP Specification**: https://modelcontextprotocol.io/
534- **FastMCP Documentation**: https://gofastmcp.com/
535- **Pydantic Documentation**: https://docs.pydantic.dev/
536- **agnost.ai**: https://docs.agnost.ai (performance tracking)
537 
538### Docker Deployment
539```bash
540# Using Docker Compose (recommended - includes Redis + MCP Toolbox)
541docker-compose up -d
542 
543# Standalone Docker container
544docker run -i \
545  -e UNIFI_API_KEY=your-key \
546  -e UNIFI_API_TYPE=cloud \
547  ghcr.io/enuno/unifi-mcp-server:latest
548 
549# Note: Don't use -d flag for MCP client integration (needs stdin/stdout)
550```
551 
552### Tool Count
553- **40+ MCP Tools** organized across:
554  - Device management (query, control, statistics)
555  - Network configuration (create, update, delete)
556  - Client management (query, block, reconnect)
557  - Firewall rules (CRUD operations)
558  - WiFi/SSID management (create, update, statistics)
559  - Port forwarding (create, delete, list)
560  - DPI statistics (site-wide, top apps, per-client)
561  - ACLs, Firewall Zones, WANs, Vouchers, Applications
562- **4 MCP Resources**: sites, devices, clients, networks
563 
564---
565Generated for Cline AI coding assistant
566Version: 0.1.3 (Jan 2025)
567