.cursorrules (deprecated)

1# Cursor Rules for UniFi MCP Server
2 
3You are an expert Python developer working on a production-grade MCP (Model Context Protocol) server for UniFi Network Controller integration. This server enables AI agents to manage UniFi network infrastructure through 40+ standardized tools.
4 
5## Project Context
6 
7**Technology Stack:**
8- Python 3.10+ with type hints and async/await patterns
9- FastMCP framework for MCP server implementation
10- Pydantic for data validation and schema generation
11- Redis for optional caching layer
12- pytest for testing (target 80%+ coverage)
13- Pre-commit hooks: black, isort, ruff, mypy, bandit
14 
15**Architecture:**
16- Async-first design for high concurrency
17- Tool-based API (40+ MCP tools across devices, networks, clients, firewall, WiFi, DPI)
18- Resource endpoints for read-only data access
19- Optional Redis caching with automatic invalidation
20- Webhook support for real-time event handling
21- Multi-site UniFi controller support
22 
23**Project Structure:**
24```
25unifi-mcp-server/
26├── src/
27│   ├── main.py              # MCP server registration and entry point
28│   ├── api/                 # UniFi API client with rate limiting
29│   ├── tools/               # MCP tool implementations (grouped by domain)
30│   ├── resources/           # MCP resource definitions
31│   ├── webhooks/            # Event handlers
32│   ├── config/              # Configuration management
33│   ├── utils/               # Validators, formatters, helpers
34│   └── cache.py             # Redis caching implementation
35├── tests/
36│   ├── unit/                # Fast, isolated tests with mocks
37│   └── integration/         # Tests requiring UniFi controller
38├── docs/
39│   └── AI-Coding/           # AI coding guidelines
40├── .env.example             # Environment variable template
41└── pyproject.toml           # Dependencies and project config
42```
43 
44## Core Coding Principles
45 
46### 1. Async-First Development
47- **ALWAYS** use `async def` for functions that perform I/O operations
48- Use `await` for API calls, database queries, file operations, HTTP requests
49- Leverage `asyncio.gather()` for concurrent operations
50- Use `async with` for context managers (UniFi client, Redis connections)
51- **NEVER** use blocking synchronous calls in async contexts
52- Consider using `anyio.to_thread.run_sync()` for CPU-intensive operations
53 
54### 2. Type Safety and Validation
55- **ALWAYS** provide type hints for all function parameters and return values
56- Use Pydantic models for complex input/output structures
57- Prefer explicit types over `Any` or untyped dicts
58- Use `Optional[T]` or `T | None` for nullable values
59- Leverage Pydantic's validation features (Field, validator decorators)
60- Run mypy before committing changes
61 
62### 3. Security-First Design
63- **CRITICAL**: All mutating operations MUST require `confirm=True` parameter
64- Implement `dry_run=True` mode for preview-before-apply
65- Log all operations to `audit.log` with context (user, timestamp, parameters)
66- Use password masking utilities for sensitive data in logs
67- Validate and sanitize all user inputs
68- Follow least-privilege principle for API access
69- Never commit API keys, passwords, or secrets to version control
70 
71### 4. Comprehensive Testing
72- Write tests FIRST for new features (TDD approach)
73- Target 80%+ code coverage for all new code
74- Use pytest fixtures for common setup
75- Mock external dependencies (UniFi API, Redis) in unit tests
76- Mark integration tests with `@pytest.mark.integration`
77- Test edge cases, error conditions, and validation failures
78- **NEVER** commit code that breaks existing tests
79 
80### 5. Documentation Standards
81- Write clear, comprehensive docstrings for all public functions
82- Use Google-style docstring format
83- Include Args, Returns, Raises sections
84- Provide usage examples in docstrings for complex tools
85- Update API.md when adding new tools or changing signatures
86- Keep README.md current with project capabilities
87 
88## MCP Tool Implementation Pattern
89 
90Every MCP tool should follow this structure:
91 
92```python
93from typing import Optional, Literal
94from pydantic import BaseModel, Field
95from fastmcp import FastMCP
96 
97mcp = FastMCP("UniFi MCP Server")
98 
99@mcp.tool()
100async def tool_name(
101    # Required parameters first
102    site_id: str,
103    resource_id: str,
104 
105    # Optional parameters with defaults
106    optional_param: Optional[str] = None,
107 
108    # Safety parameters for mutating operations
109    confirm: bool = False,
110    dry_run: bool = False
111) -> dict:
112    """
113    Clear, concise description of what the tool does.
114 
115    Args:
116        site_id: Always include site_id for multi-site support
117        resource_id: Specific resource identifier
118        optional_param: Description of optional parameter
119        confirm: REQUIRED True for mutating operations (safety)
120        dry_run: Preview changes without applying them
121 
122    Returns:
123        Dictionary with operation results. Specify structure.
124 
125    Raises:
126        MCPError: For all MCP-specific errors
127        ValueError: For invalid inputs
128        UniFiConnectionError: For API connection issues
129    """
130    # 1. Input validation
131    if not site_id:
132        raise ValueError("site_id is required")
133 
134    # 2. Safety checks for mutating operations
135    if not confirm and not dry_run:
136        raise MCPError("This operation requires confirm=True")
137 
138    # 3. Audit logging
139    logger.info(
140        f"tool_name: site={site_id}, id={resource_id}, dry_run={dry_run}",
141        extra={"operation": "tool_name", "site_id": site_id}
142    )
143 
144    # 4. Dry-run mode
145    if dry_run:
146        preview = await generate_preview(site_id, resource_id)
147        return {"status": "preview", "changes": preview}
148 
149    # 5. Execute operation
150    try:
151        result = await execute_operation(site_id, resource_id)
152    except UniFiAPIError as e:
153        logger.error(f"Operation failed: {e}")
154        raise MCPError(f"Failed to execute operation: {str(e)}")
155 
156    # 6. Cache invalidation (if applicable)
157    if result.get("success"):
158        await cache.invalidate(f"resource:{site_id}")
159 
160    # 7. Return structured result
161    return {
162        "status": "success",
163        "resource_id": resource_id,
164        "data": result
165    }
166```
167 
168## Development Workflow
169 
170### Before Starting Work
1711. Pull latest changes: `git pull origin main`
1722. Create feature branch: `git checkout -b feature/your-feature`
1733. Review existing patterns in similar files
174 
175### During Development
1761. Write tests first (TDD approach)
1772. Implement feature following patterns above
1783. Run tests frequently: `pytest -v`
1794. Check types: `mypy src/`
1805. Format code: `black src/ tests/` and `isort src/ tests/`
181 
182### Before Committing
1831. Run full test suite: `pytest --cov=src --cov-report=term-missing`
1842. Ensure coverage ≥80%: Check coverage report
1853. Run linter: `ruff check src/ tests/ --fix`
1864. Type check: `mypy src/`
1875. Run pre-commit hooks: `pre-commit run --all-files`
1886. Update documentation if needed
189 
190### Commit Message Format
191Follow Conventional Commits:
192```
193<type>: <short summary>
194 
195<optional body>
196```
197 
198Types: `feat`, `fix`, `docs`, `test`, `refactor`, `style`, `chore`
199 
200Examples:
201```
202feat: add DPI statistics tool for bandwidth analysis
203fix: correct device restart timeout handling
204docs: update API.md with WiFi management tools
205test: add integration tests for port forwarding
206refactor: simplify client blocking logic
207```
208 
209## Code Quality Checklist
210 
211Before submitting a PR, verify:
212- [ ] All tests pass (`pytest`)
213- [ ] Code coverage ≥80% (`pytest --cov`)
214- [ ] Type checking passes (`mypy src/`)
215- [ ] Linting passes (`ruff check src/ tests/`)
216- [ ] Code formatted (`black`, `isort`)
217- [ ] Security checks pass (`bandit -r src/`)
218- [ ] Pre-commit hooks pass
219- [ ] Documentation updated (docstrings, API.md)
220- [ ] CHANGELOG.md updated for user-facing changes
221- [ ] No hardcoded secrets or API keys
222- [ ] Audit logging added for mutating operations
223 
224## Common Mistakes to Avoid
225 
226❌ **DON'T:**
227- Use synchronous blocking calls in async functions
228- Omit type hints or use `Any` unnecessarily
229- Skip tests for new features
230- Forget `confirm=True` safety checks on mutating operations
231- Expose sensitive data in logs
232- Commit without running pre-commit hooks
233- Mix sync and async code improperly
234- Return untyped dicts when Pydantic models are appropriate
235 
236✅ **DO:**
237- Use async/await consistently
238- Provide comprehensive type hints
239- Write tests first (TDD)
240- Implement dry-run mode for dangerous operations
241- Mask passwords and keys in logs
242- Run full test suite before committing
243- Use `async with` for resource management
244- Define Pydantic models for complex data structures
245 
246## Environment Setup
247 
248Required environment variables (see `.env.example`):
249```bash
250# Required
251UNIFI_API_KEY=your-api-key-here
252UNIFI_API_TYPE=cloud  # or "local"
253UNIFI_HOST=api.ui.com  # or local gateway IP
254UNIFI_SITE=default
255 
256# Optional
257REDIS_HOST=localhost  # Enable caching
258REDIS_PORT=6379
259WEBHOOK_SECRET=your-secret  # Enable webhook HMAC verification
260```
261 
262## Quick Commands
263 
264```bash
265# Development
266uv run mcp dev src/main.py      # Run with MCP Inspector
267 
268# Testing
269pytest                          # Run all tests
270pytest -m unit                  # Unit tests only
271pytest -m integration           # Integration tests only
272pytest --cov=src --cov-report=html  # With coverage report
273 
274# Code Quality
275black src/ tests/               # Format
276isort src/ tests/               # Sort imports
277ruff check src/ tests/ --fix   # Lint and fix
278mypy src/                       # Type check
279bandit -r src/                  # Security scan
280 
281# Pre-commit
282pre-commit run --all-files      # Run all hooks
283```
284 
285## Key Resources
286 
287- **Project Documentation**: README.md, API.md, CONTRIBUTING.md, SECURITY.md
288- **MCP Specification**: https://modelcontextprotocol.io/
289- **FastMCP Docs**: https://gofastmcp.com/
290- **UniFi API**: Official UniFi Controller API documentation
291- **Pydantic**: https://docs.pydantic.dev/
292 
293## Remember
294 
295- **Safety First**: Require `confirm=True` for all network modifications
296- **Test Everything**: 80%+ coverage is not optional
297- **Type Everything**: Type hints improve code quality and catch bugs
298- **Document Well**: Future you (and other developers) will thank you
299- **Async Always**: This is an async-first project - respect the pattern
300- **Security Matters**: Never expose credentials or sensitive data
301 
302---
303 
304Generated for Cursor AI IDE
305UniFi MCP Server v0.1.2
306Python 3.10+ | FastMCP | Async-first Architecture
307