unifi-mcp-server: Skill for Claude Code

source-command-unifi-mcp-add-tool

Use this skill when the user asks to run the migrated source command unifi-mcp-add-tool.

Command Template

Scaffold a complete new MCP tool for the UniFi MCP Server.

This command creates all necessary files and code for a new tool following the project's architecture and standards.

Steps to execute:

1. Ask the user for tool details:

   • Tool name (e.g., "get_port_profile")
   • Tool category (e.g., "networks", "devices", "clients", "firewall")
   • Brief description of what the tool does
   • UniFi API endpoint it will use
   • Whether it's a read-only or mutating operation

2. Create or update the Pydantic model in src/models/:

   • If the model file for the category doesn't exist, create it
   • Add request/response models based on UniFi API schema
   • Include proper type hints and field descriptions
   • Add validators if needed

3. Create the tool function in src/tools/:

   • If the tool file for the category doesn't exist, create it
   • Implement async tool function with proper error handling
   • Add confirmation/dry-run support for mutating operations
   • Include comprehensive docstring with:
     • Description
     • Parameters
     • Returns
     • Raises
     • Example usage

4. Register the tool in src/main.py:

   • Add import statement
   • Register tool with FastMCP

5. Create comprehensive unit tests in tests/unit/:

   • Test file following naming convention: test_<category>_tools.py
   • Include tests for:
     • Success case with mocked API response
     • Error handling (authentication, network, API errors)
     • Validation of parameters
     • Confirmation/dry-run mode (if applicable)
   • Aim for 80%+ coverage

6. Update API.md documentation:

   • Add tool to appropriate category section
   • Include description, parameters, returns, example

7. Run validation:

   • Format code: black src/ tests/
   • Check tests: pytest tests/unit/test_<category>_tools.py -v
   • Verify registration: python -c "from src.main import mcp; print(mcp.list_tools())"