Overview
This skill guides you through adding new MCP tools to the existing UniFi MCP Server. Unlike building an MCP server from scratch, this focuses on extending the current implementation with new UniFi Network Controller functionality while maintaining the project's quality standards.
Project Context:
- Existing Tools: 343 MCP tools in local mode. The live count is what the registry reports; this figure is checked by
tests/unit/test_skill_tool_references.py, so the test fails if it drifts. - Test Coverage: the unit suite is the gate. Run
pytest tests/unit/ -q --cov=src --cov-fail-under=80from the repository root; the coverage gate is 80%. The exact test count changes with every change, so read it from that run rather than from this file. - Architecture: FastMCP + Pydantic v2 + async/await patterns
- API Support: Local gateway (full), Cloud V1/EA (limited)
- Quality Standards: 80% minimum test coverage, TDD required
Process
Phase 1: Research and Planning
1.1 Understand the Tool Request
Before implementation, clarify:
- What UniFi feature/endpoint needs to be exposed?
- Which API mode supports it (local, cloud-v1, cloud-ea)?
- What workflow does this enable for AI agents?
- How does this fit into existing tool categories?
Tool Categories in UniFi MCP Server:
- Device Management (list, control, upgrade)
- Client Management (block, unblock, statistics)
- Network Configuration (VLANs, subnets, DHCP)
- Firewall & Security (rules, zones, ACLs)
- WiFi/SSID Management (create, configure, statistics)
- QoS & Traffic (profiles, flows, DPI)
- Backup & Restore (automated backups, restore)
- Site Management (multi-site, aggregation)
- Topology & Monitoring (network maps, health)
1.2 Study UniFi API Documentation
Load UniFi API reference:
# Read the comprehensive UniFi API documentation
Read: docs/UNIFI_API.md
This document contains verified endpoints for UniFi Network v10.0.156+.
Critical considerations:
- Endpoint availability: Not all documented endpoints exist in all versions
- API mode differences: Local gateway vs Cloud APIs have different capabilities
- Response formats: Local API returns different structures than Cloud API
- Authentication: Local uses local credentials, Cloud uses API keys
1.3 Review Existing Patterns
Study similar tools in the codebase:
# Example: For a new device tool, read existing device tools
Read: src/tools/devices.py
Read: src/tools/device_control.py
# For network tools:
Read: src/tools/networks.py
Read: src/tools/network_config.py
# For testing patterns:
Read: tests/unit/tools/test_devices_tools.py
Key patterns to identify:
- How similar tools structure their inputs (Pydantic models)
- Response formatting (JSON with TypedDict or Pydantic response models)
- Error handling patterns
- Confirmation requirements for mutating operations
- Dry-run mode implementation
- Caching strategies (if applicable)
1.4 Verify API Endpoint Availability
CRITICAL: Not all documented API endpoints actually exist!
The UniFi MCP Server has discovered that many documented endpoints don't exist in real controllers. Before implementation:
- Check endpoint existence in
docs/UNIFI_API.mdverification notes - Test on real hardware if possible (U7 Express, UDM Pro, etc.)
- Document findings in code comments and API.md
Known endpoint issues:
- ZBF matrix endpoints don't exist (use Firewall Policies v2 instead)
- Some statistics endpoints are documented but not available
- Cloud APIs have very limited endpoint support vs local gateway
1.5 Create Implementation Plan
Document your plan covering:
Tool Definition:
- Tool name (follow naming convention:
{action}_{resource}) - Description (one-line summary for LLMs)
- Input parameters (with Pydantic model)
- Response format (TypedDict or Pydantic model)
- Error scenarios
Data Models:
- Pydantic models for request validation
- Response models (if complex data structure)
- Enums for allowed values
Testing Strategy:
- Unit test scenarios (minimum 10-15 tests)
- Mock API responses
- Edge cases (empty results, errors, pagination)
- Target coverage: 85%+ for new code
Documentation:
- Docstring with examples
- API.md section update
- README.md feature list update (if major feature)
Phase 2: Implementation
2.1 Create Pydantic Models (if needed)
Location: src/models/{feature}.py
from enum import Enum
from typing import Optional
from pydantic import BaseModel, Field, ConfigDict
class YourRequestModel(BaseModel):
"""Request model for your_tool operation.
Attributes:
site_id: UniFi site identifier
resource_id: Resource to operate on
options: Optional configuration parameters
"""
model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
site_id: str = Field(..., description="UniFi site ID (e.g., 'default')")
resource_id: str = Field(..., min_length=1, description="Resource identifier")
options: Optional[dict] = Field(None, description="Additional options")
class YourResponseModel(BaseModel):
"""Response from your_tool operation."""
success: bool
resource_id: str
message: str
Key requirements:
- Use Pydantic v2 syntax (
model_configinstead ofConfig) extra="forbid"to reject unknown fields- Comprehensive Field descriptions for LLM understanding
- Type hints for all fields
- Docstrings explaining purpose
2.2 Implement the MCP Tool
Location: src/tools/{category}.py (or a new module for a new feature area)
Tools are plain async functions. Every public async def in a module that src/main.py lists becomes a tool; there is no @mcp.tool() decorator. Each tool declares @read_tool or @write_tool (src/utils/tool_kind.py); registration fails without one, and UNIFI_READ_ONLY registers only read tools. The registry passes settings and hides it from the tool's public signature. Name helpers with a leading _ so they are not registered.
A read tool:
from typing import Any
from ..api.client import UniFiClient
from ..config import Settings
from ..utils import ValidationError, get_logger, sanitize_log_message, validate_site_id
from ..utils.tool_kind import read_tool
@read_tool
async def list_your_resources(site_id: str, settings: Settings) -> list[dict[str, Any]]:
"""List your resources on a site.
Args:
site_id: Site identifier (name or UUID)
settings: Application settings
Returns:
List of resource records
"""
site_id = validate_site_id(site_id)
logger = get_logger(__name__, settings.log_level)
async with UniFiClient(settings) as client:
if not client.is_authenticated:
await client.authenticate()
response = await client.get(f"/ea/sites/{site_id}/rest/your_resource")
data = response if isinstance(response, list) else response.get("data", [])
logger.info(sanitize_log_message(f"Listed {len(data)} resources for site {site_id}"))
return [YourModel(**item).model_dump() for item in data]
A write tool:
from ..utils.tool_kind import write_tool
from ..utils.validators import coerce_bool, validate_confirmation
@write_tool
async def update_your_resource(
site_id: str,
resource_id: str,
settings: Settings,
name: str | None = None,
confirm: bool | str = False,
dry_run: bool | str = False,
) -> dict[str, Any]:
"""Update a resource.
Args:
site_id: Site identifier (name or UUID)
resource_id: Resource identifier
settings: Application settings
name: New name (unchanged when omitted)
confirm: Must be true to apply the change (required unless dry_run)
dry_run: Preview the change without applying it
Returns:
The updated record, or the planned change on a dry run
"""
validate_confirmation(confirm, "update your resource", dry_run)
site_id = validate_site_id(site_id)
payload: dict[str, Any] = {}
if name is not None:
payload["name"] = name
if not payload:
raise ValidationError("No updates provided")
if coerce_bool(dry_run):
return {"dry_run": True, "operation": "update_your_resource", "payload": payload}
async with UniFiClient(settings) as client:
if not client.is_authenticated:
await client.authenticate()
response = await client.put(
f"/ea/sites/{site_id}/rest/your_resource/{resource_id}", json_data=payload
)
return response
Build paths with the Settings helpers (get_integration_path, get_protect_integration_path, get_v2_api_path) or the /ea/sites/{site_id}/... form that UniFiClient translates. Never hardcode /proxy/network/.... The tool-set skills (unifi-protect-tools, unifi-network-config-tools, unifi-security-tools, unifi-cloud-fleet-tools) list the paths and gotchas per area.
Implementation checklist:
- Public
async defwithsettings: Settings, declared@read_toolor@write_tool; helpers start with_ - Google-style docstring that lists every argument (MCP clients show it)
- Input validation with
src/utils/validators.py - Write tools:
confirmanddry_run,validate_confirmation()first, dry run returned before any request - Optional update arguments default to
None - No audit code in the tool (the registry wrapper audits every write)
- Errors from
src/utils/exceptions.py(ValidationErrorfor bad input); no broadexceptthat hides the cause
2.3 Register the Module
Location: src/main.py
- A new function in an existing module needs no registration.
- A new module: import it, add it to
_LOCAL_TOOL_MODULESor_CLOUD_TOOL_MODULES, and add it to theUNIFI_PROFILEsets that should include it. - Regenerate the risk-tier snapshot:
UPDATE_TOOL_TIERS=1 pytest tests/unit/fleet/test_tiers.py. Destructive tools need adelete_,remove_orbulk_delete_prefix or an entry inDESTRUCTIVE_TOOLS(src/tool_registry.py). A write tool with a risky word in its name needs an entry inDESTRUCTIVE_TOOLSorRISKY_NAME_EXEMPTIONS.
2.4 Follow Code Quality Standards
Run quality checks:
# Format code
black src/tools/your_file.py
isort src/tools/your_file.py
# Lint
ruff check src/tools/your_file.py --fix
# Type check
mypy src/tools/your_file.py
Phase 3: Test-Driven Development
3.1 Write Tests BEFORE Implementation
Location: tests/unit/test_{category}.py
CRITICAL: UniFi MCP Server requires Test-Driven Development (TDD)
- Write failing tests first
- Implement just enough to make tests pass
- Refactor and improve
- Achieve 85%+ coverage for new code
3.2 Test Structure
Location: tests/unit/tools/test_{module}_tools.py
from unittest.mock import AsyncMock, patch
import pytest
from src.config import Settings
from src.tools.your_category import update_your_resource
from src.utils.exceptions import ValidationError
@pytest.fixture
def settings(monkeypatch):
monkeypatch.setenv("UNIFI_API_KEY", "test-api-key")
monkeypatch.setenv("UNIFI_API_TYPE", "local")
monkeypatch.setenv("UNIFI_LOCAL_HOST", "192.168.2.1")
return Settings()
def _client(client_class, **responses):
client = AsyncMock()
client.is_authenticated = True
for method, value in responses.items():
setattr(client, method, AsyncMock(return_value=value))
client.__aenter__ = AsyncMock(return_value=client)
client.__aexit__ = AsyncMock(return_value=False) # a truthy value would swallow errors
client_class.return_value = client
return client
async def test_update_sends_only_changed_fields(settings):
with patch("src.tools.your_category.UniFiClient") as client_class:
client = _client(client_class, put={"data": [{"_id": "abc", "name": "new"}]})
await update_your_resource("default", "abc", settings, name="new", confirm=True)
assert client.put.await_args.kwargs["json_data"] == {"name": "new"}
async def test_update_refuses_without_confirm(settings):
with patch("src.tools.your_category.UniFiClient") as client_class:
with pytest.raises(ValidationError, match="confirm"):
await update_your_resource("default", "abc", settings, name="new")
client_class.assert_not_called()
async def test_update_dry_run_makes_no_request(settings):
with patch("src.tools.your_category.UniFiClient") as client_class:
result = await update_your_resource("default", "abc", settings, name="new", dry_run=True)
assert result["dry_run"] is True
client_class.assert_not_called()
asyncio_mode = auto is set, so tests need no asyncio marker. --strict-markers rejects any marker except integration.
Test coverage requirements:
- Successful operation (happy path)
- Confirmation requirement (for mutating ops)
- Dry-run mode
- Input validation (invalid site_id, etc.)
- Error handling (not found, API errors)
- Optional parameters
- Edge cases (empty results, pagination)
- Response format validation
Target: 85%+ coverage for new code
3.3 Run Tests
# Run your specific test file
pytest tests/unit/test_your_category.py -v
# Run with coverage
pytest tests/unit/test_your_category.py --cov=src/tools/your_category --cov-report=term-missing
# Ensure coverage meets target (85%+)
pytest tests/unit/test_your_category.py --cov=src/tools/your_category --cov-report=html
open htmlcov/index.html # Review coverage report
Phase 4: Documentation
4.1 Update API.md
Location: API.md
Add your tool to the appropriate section with complete documentation:
### your_tool_name
**Description**: Brief one-line description
**Purpose**: Detailed explanation of when and why to use this tool
**Parameters**:
- `site_id` (string, required): UniFi site identifier (e.g., "default")
- `resource_id` (string, required): Resource identifier to operate on
- `options` (object, optional): Additional configuration options
- `confirm` (boolean, optional): Required for mutating operations (default: false)
- `dry_run` (boolean, optional): Preview changes without applying (default: false)
**Returns**:
```json
{
"success": true,
"resource_id": "abc123",
"message": "Successfully processed resource",
"data": { /* resource details */ }
}
Dry-run response:
{
"success": true,
"dry_run": true,
"preview": {
"operation": "your_operation",
"resource_id": "abc123",
"changes": { /* preview of changes */ }
},
"message": "Dry-run completed. Set confirm=True to apply changes."
}
Examples:
# Example 1: Preview changes (dry-run)
result = await mcp.call_tool("your_tool_name", {
"site_id": "default",
"resource_id": "abc123",
"dry_run": True
})
# Example 2: Execute operation
result = await mcp.call_tool("your_tool_name", {
"site_id": "default",
"resource_id": "abc123",
"confirm": True
})
Error Handling:
ValidationError: Invalid input, or confirm=True missing on a writeResourceNotFoundError: The resource does not exist (HTTP 404)APIError: UniFi API returned another error (check the message)
API Endpoint: POST /api/s/{site}/rest/your_endpoint
Supported API Modes:
- ✅ Local Gateway API (full support)
- ⚠️ Cloud V1 API (limited support)
- ❌ Cloud EA API (not supported)
### 4.2 Update README.md (if major feature)
If adding a new feature category, update README.md:
```markdown
### Your New Feature Category
- **Feature Name**: Description of what it enables
- **Tools**: List of new tools
- **Use Cases**: Common scenarios where this is valuable
4.3 Update CHANGELOG.md
Add entry under "Unreleased" section:
## [Unreleased]
### Added
- New tool `your_tool_name` for managing XYZ (#123)
- Support for ABC feature in UniFi Network 10.0+
Phase 5: Quality Verification
5.1 Run Full Test Suite
# Run all tests
pytest tests/unit/
# Verify no regressions
pytest tests/unit/ --cov=src --cov-report=term-missing
# Check overall coverage (the CI gate is 80%)
pytest tests/unit/ --cov=src --cov-report=html
5.2 Code Quality Checks
# Format (auto-fix)
black src/ tests/
isort src/ tests/
# Lint (auto-fix where possible)
ruff check src/ tests/ --fix
# Type check
mypy src/
# Security scan
bandit -r src/
# Pre-commit hooks
pre-commit run --all-files
5.3 Manual Testing with MCP Inspector
# Start MCP Inspector
uv run mcp dev src/main.py
# Open http://localhost:5173
# Test your new tool with real inputs
# Verify responses match expectations
5.4 Test on Real Hardware (if possible)
If you have access to a UniFi controller:
- Configure local gateway API credentials
- Test tool with real data
- Verify API endpoint exists and returns expected format
- Document any discrepancies in API.md
Phase 6: Skills, A2A, prompts and resources sync
A new or changed tool or MCP resource must also update the artifacts that describe the surface to agents and to A2A orchestrators.
6.1 Creating or updating a skill
Skills live in skills/<name>/SKILL.md. Developer skills (the ones an agent loads while coding) are also copied to .claude/skills/<name>/ and .agents/skills/<name>/. The mintlify-docs skill is the exception: its source of truth is .mintlify/skills/mintlify-docs/SKILL.md.
To add a new skill:
-
Create
skills/<name>/SKILL.mdwith YAML frontmatter containing at leastnameanddescription. -
If it is a developer skill, copy it to
.claude/skills/<name>/SKILL.mdand.agents/skills/<name>/SKILL.md. -
If it names tools or arguments, use the explicit argument-list form so the skill-reference guards can check it.
-
Run the guards:
pytest tests/unit/test_skill_tool_references.py \ tests/unit/test_skill_parameter_references.py \ tests/unit/test_agent_docs.py -q
To update an existing skill, edit skills/<name>/SKILL.md and re-copy the developer-skill copies. Do not edit the copies directly; test_agent_docs.py fails when they differ from the source.
6.2 Updating the A2A configuration
The A2A agent card and capability manifest are derived from the live tool registry, but several hand-written sources shape what they advertise:
src/a2a/capabilities.py— capability names, module-to-domain map (_MODULE_DOMAINS), and the advertised API modes.src/a2a/agent_card.py— the card shape and safety-requirement logic.agent-card.json— the committed reference artifact.
When you add a tool in a new domain, change a tool's tier, or add/change an MCP resource:
-
Update
_MODULE_DOMAINSinsrc/a2a/capabilities.pyif the module is not already mapped. -
Regenerate the reference card:
python scripts/generate_agent_card.py -
Verify the card and the generator agree:
pytest tests/unit/a2a/test_agent_card.py \ tests/unit/a2a/test_agent_card_capabilities.py -q
Never hand-edit agent-card.json; the generator overwrites it and test_agent_card.py will fail if it does not match the source.
6.3 Updating the native prompt catalog
If a prompt workflow reads the new or changed tool:
-
Update
src/prompts/catalog.py— the workflow'sevidenceandrequirementstool lists. -
Update
docs/PROMPTS.mdwith the workflow's purpose and parameters. -
Verify with:
pytest tests/unit/prompts/test_prompt_catalog.py -q
A renamed tool can make a workflow disappear from prompts/list because the workflow is advertised only when every required tool is registered.
6.4 Updating MCP resources
MCP resources are registered in src/main.py with @mcp.resource("scheme://...") URI templates. They are advertised through the MCP handshake and included in the A2A agent card.
When you add, remove or rename a resource:
-
Add or update tests under
tests/unit/resources/for the resource class and themcp.resourceregistration. -
Update
docs/UNIFI_API.md"Supporting Resources" with the URI template, endpoint mapping, and status. -
Regenerate
agent-card.jsonso the A2A surface matches the live registry:python scripts/generate_agent_card.py -
If a skill references the resource URI, update the skill and its developer copies.
-
Run the drift guards and the A2A card tests:
pytest tests/unit/test_skill_tool_references.py \ tests/unit/test_skill_parameter_references.py \ tests/unit/test_agent_docs.py \ tests/unit/a2a/test_agent_card.py \ tests/unit/a2a/test_agent_card_capabilities.py -q
Quality Checklist
Before submitting:
Code Quality
- Tool follows naming convention (
{action}_{resource}) - Comprehensive docstring with examples
- Input validation using Pydantic models
- Confirmation required for mutating operations
- Dry-run mode implemented
- Actionable error messages
- Async/await used consistently
- Type hints throughout
- No hardcoded values (use constants)
- Follows existing code patterns
Testing
- TDD: Tests written before implementation
- 85%+ coverage for new code
- Tests cover happy path
- Tests cover error scenarios
- Tests cover edge cases
- Mock API responses properly
- No integration tests without real hardware
- All tests passing
Documentation
- API.md updated with complete tool documentation
- Examples provided in docstring and API.md
- Error handling documented
- API endpoint documented
- API mode support clearly indicated
- CHANGELOG.md updated
- README.md updated (if major feature)
- Relevant skill updated in
skills/<name>/SKILL.mdand developer-skill copies synced -
agent-card.jsonregenerated if the tool surface changed - Native prompt catalog updated if a workflow reads the tool
- MCP resource tests added or updated if a resource changed
-
docs/UNIFI_API.md"Supporting Resources" updated if a resource URI changed
Integration
- Tool registered in src/main.py
- Imports organized correctly
- No circular dependencies
- Compatible with existing tools
Quality Gates
-
blackformatting passes -
isortimport sorting passes -
rufflinting passes -
mypytype checking passes -
banditsecurity scan passes -
pytestall tests pass - Coverage ≥80% overall (CI gate), ≥85% for new code
- Pre-commit hooks pass
- MCP Inspector manual testing successful
Common Patterns in UniFi MCP Server
Copy a real tool rather than a sketch:
| Pattern | Copy from |
|---|---|
| Read tool, legacy API | list_wlans in src/tools/wifi.py |
| Read tool, integration API | list_acl_rules in src/tools/acls.py |
| Write tool with a partial update | update_protect_relay in src/tools/protect_relays.py |
| Read-modify-write update | update_port_profile in src/tools/port_profiles.py |
| Paginated list | list_protect_relays in src/tools/protect_relays.py (uses validate_limit_offset()) |
| Data across many controllers | fleet_fanout in src/fleet/fleet_tools.py (reads only) |
References
Project Documentation
README.md- Project overview and quick startAPI.md- Complete MCP tool referenceAGENTS.md- AI agent development guidelinesDEVELOPMENT_PLAN.md- Roadmap and feature planningdocs/archive/TESTING_PLAN.md- Testing strategy (archived)CONTRIBUTING.md- Contribution guidelines
UniFi API Documentation
docs/UNIFI_API.md- Verified endpoint documentation for v10.0.156+- UniFi Network Developer Documentation
Code Examples
src/tools/devices.py- Device management examplessrc/tools/firewall.py- Firewall rule management patternssrc/tools/firewall_policies.py- Zone-Based Firewall policiessrc/tools/qos.py- QoS profile management examplestests/unit/tools/test_protect_relays.py- Write-gate and dry-run test examples
Last Updated: 2026-10-13 Maintained By: UniFi MCP Server Team