CLAUDE.md

1# UniFi MCP Server - Claude Instructions
2 
3This file provides project-specific instructions for AI coding assistants working on the UniFi MCP Server.
4 
5## Project Overview
6 
7The UniFi MCP Server is a Model Context Protocol (MCP) server that exposes the UniFi Network Controller API, enabling AI agents and applications to interact with UniFi network infrastructure in a standardized way.
8 
9**Current Version**: v0.2.3
10**Python Version**: 3.10+
11**Framework**: FastMCP
12 
13## Quick Start for AI Assistants
14 
15### Before Starting Work
16 
171. **Read Key Documentation**:
18   - `README.md` - Project overview and features
19   - `AGENTS.md` - Universal AI agent guidelines
20   - `DEVELOPMENT_PLAN.md` - Roadmap and priorities
21   - `TODO.md` - Current tasks and phase breakdown
22   - `API.md` - Complete MCP tool documentation
23 
242. **Understand the Architecture**:
25   - `src/main.py` - MCP server entry point
26   - `src/api/` - UniFi API client
27   - `src/models/` - Pydantic data models
28   - `src/tools/` - MCP tool implementations
29   - `tests/unit/` - Unit tests (1,156 tests passing)
30 
31### Development Workflow
32 
331. **Feature Development**:
34   - Create feature branch: `git checkout -b feature/your-feature`
35   - Follow TDD: Write tests first, then implementation
36   - Maintain 80% minimum test coverage for new code
37   - Use Pydantic models for all data structures
38   - Add comprehensive docstrings (Google style)
39 
402. **Code Quality**:
41   - Run tests: `pytest tests/unit/`
42   - Format: `black src/ tests/` and `isort src/ tests/`
43   - Lint: `ruff check src/ tests/ --fix`
44   - Type check: `mypy src/`
45   - Pre-commit: `pre-commit run --all-files`
46 
473. **Safety Mechanisms**:
48   - All mutating operations require `confirm=True`
49   - Implement dry-run mode for preview
50   - Add audit logging for operations
51   - Validate all user inputs
52   - Never commit secrets or credentials
53 
54### Technology Stack
55 
56- **Language**: Python 3.10+
57- **Framework**: FastMCP (MCP server framework)
58- **API Client**: httpx (async HTTP)
59- **Data Validation**: Pydantic v2
60- **Testing**: pytest with asyncio support
61- **Caching**: Redis (optional)
62- **Monitoring**: agnost.ai (optional)
63 
64### API Modes
65 
66The server supports three UniFi API access modes:
67 
681. **Local Gateway API** (Recommended): Full feature support
69   - `UNIFI_API_TYPE=local`
70   - `UNIFI_LOCAL_HOST=192.168.2.1`
71 
722. **Cloud V1 API**: Stable, aggregate statistics only
73   - `UNIFI_API_TYPE=cloud-v1`
74 
753. **Cloud EA API**: Early Access, aggregate statistics only
76   - `UNIFI_API_TYPE=cloud-ea`
77 
78### Current Development Focus
79 
80**Version 0.2.3** (Current):
81 
82- ✅ P1 API bug fixes (QoS audit_action, Site Manager decorator, Topology warnings, Backup client methods)
83- ✅ P2 RADIUS & Guest Portal — Complete CRUD (get/update for RADIUS accounts and hotspot packages)
84 
85**Version 0.2.2** (Complete ✅):
86 
87- ✅ Port Profile & Switch Port Management (8 tools)
88- ✅ Security hardening (dependency updates, PII removal)
89- ✅ API endpoint fixes (RADIUS, firewall, WLAN, network)
90- ✅ Bug fixes (dry_run, list handling, type hints)
91 
92**Version 0.2.0** (Complete ✅):
93 
94- ✅ Zone-Based Firewall (7 working tools)
95- ✅ Traffic Flow Monitoring (15 tools)
96- ✅ Advanced QoS (11 tools)
97- ✅ Backup & Restore (8 tools)
98- ✅ Multi-Site Aggregation (4 tools)
99- ✅ ACL & Traffic Filtering (7 tools)
100- ✅ Site Management (9 tools)
101- ✅ RADIUS & Guest Portal (10 tools — full CRUD)
102- ✅ Network Topology (5 tools)
103 
104**Total**: 86+ MCP tools, 1,156 tests passing
105 
106### Important Constraints
107 
1081. **UniFi Network 9.0+ Required**: Some features require Network 9.0+
1092. **Local API Recommended**: Cloud APIs have limited functionality
1103. **Endpoint Verification**: Some documented API endpoints may not exist in all versions
1114. **Testing**: Integration tests require real UniFi hardware
112 
113### Getting Help
114 
115- **Issues**: [GitHub Issues](https://github.com/enuno/unifi-mcp-server/issues)
116- **Documentation**: See `API.md` for complete tool reference
117- **Examples**: Check `docs/examples/` for AI assistant prompts
118 
119## Key Principles
120 
1211. **Safety First**: Never perform destructive operations without confirmation
1222. **Quality Over Speed**: Maintain high test coverage and code quality
1233. **Clarity**: Write self-documenting code with clear docstrings
1244. **Consistency**: Follow existing patterns and conventions
1255. **Security**: Never commit credentials, validate all inputs
126 
127## Additional Resources
128 
129- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribution guidelines
130- [SECURITY.md](SECURITY.md) - Security policy and best practices
131- [AGENTS.md](AGENTS.md) - Detailed AI agent guidelines
132- [TESTING_PLAN.md](docs/archive/TESTING_PLAN.md) - Testing strategy
133- [DEVELOPMENT_PLAN.md](DEVELOPMENT_PLAN.md) - Complete roadmap
134 
135---
136 
137**Last Updated**: 2026-02-18
138**Maintained By**: Development Team
139