Unifi MCP Tool Builder

import pytest
from unittest.mock import AsyncMock, MagicMock, patch
from src.tools.your_category import your_tool_name

class TestYourToolName:
    """Test suite for your_tool_name."""

    @pytest.fixture
    def mock_context(self):
        """Mock FastMCP context with UniFi client."""
        context = MagicMock()
        client = AsyncMock()
        context.get.return_value = client
        return context, client

    @pytest.mark.asyncio
    async def test_successful_operation(self, mock_context):
        """Test successful tool execution."""
        context, client = mock_context
        client.request.return_value = {
            "data": {"_id": "abc123", "name": "test"}
        }

        result = await your_tool_name(
            site_id="default",
            resource_id="abc123",
            settings=context,
            confirm=True
        )

        assert result["success"] is True
        assert result["resource_id"] == "abc123"
        client.request.assert_called_once()

    @pytest.mark.asyncio
    async def test_requires_confirmation(self, mock_context):
        """Test that mutating operations require confirm=True."""
        context, client = mock_context

        with pytest.raises(PermissionError, match="Set confirm=True"):
            await your_tool_name(
                site_id="default",
                resource_id="abc123",
                settings=context,
                confirm=False
            )

    @pytest.mark.asyncio
    async def test_dry_run_mode(self, mock_context):
        """Test dry-run preview mode."""
        context, client = mock_context

        result = await your_tool_name(
            site_id="default",
            resource_id="abc123",
            settings=context,
            dry_run=True
        )

        assert result["dry_run"] is True
        assert "preview" in result
        client.request.assert_not_called()

    @pytest.mark.asyncio
    async def test_invalid_site_id(self, mock_context):
        """Test validation of site_id."""
        context, client = mock_context

        with pytest.raises(ValueError, match="Invalid site"):
            await your_tool_name(
                site_id="",
                resource_id="abc123",
                settings=context
            )

    @pytest.mark.asyncio
    async def test_resource_not_found(self, mock_context):
        """Test handling of not found errors."""
        context, client = mock_context
        client.request.side_effect = Exception("Resource not found")

        with pytest.raises(ValueError, match="not found"):
            await your_tool_name(
                site_id="default",
                resource_id="nonexistent",
                settings=context,
                confirm=True
            )

    @pytest.mark.asyncio
    async def test_with_optional_parameters(self, mock_context):
        """Test tool with optional parameters."""
        context, client = mock_context
        client.request.return_value = {"data": {"_id": "abc123"}}

        result = await your_tool_name(
            site_id="default",
            resource_id="abc123",
            options={"key": "value"},
            settings=context,
            confirm=True
        )

        assert result["success"] is True
        # Verify options were passed to API
        call_args = client.request.call_args
        assert call_args[1]["json"]["key"] == "value"

# 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

### 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 */ }
}

{
  "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."
}

# 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
})

### 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

## [Unreleased]

### Added
- New tool `your_tool_name` for managing XYZ (#123)
- Support for ABC feature in UniFi Network 10.0+

# Run all tests
pytest tests/unit/

# Verify no regressions
pytest tests/unit/ --cov=src --cov-report=term-missing

# Check overall coverage (should remain ≥78%)
pytest tests/unit/ --cov=src --cov-report=html

# 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

# 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

@mcp.tool()
async def list_resources(
    site_id: str,
    filters: dict | None = None,
    settings: Context = None,
) -> list[dict]:
    """List resources in the UniFi controller.

    This is a read-only operation requiring no confirmation.
    """
    client = settings.get("client")
    response = await client.request(
        method="GET",
        endpoint=f"/api/s/{site_id}/rest/resource",
        params=filters or {}
    )
    return response.get("data", [])

@mcp.tool()
async def update_resource(
    site_id: str,
    resource_id: str,
    updates: dict,
    settings: Context = None,
    confirm: bool = False,
    dry_run: bool = False,
) -> dict:
    """Update a resource (requires confirmation).

    Mutating operations always require confirm=True.
    """
    if not dry_run and not confirm:
        raise PermissionError("Set confirm=True to proceed")

    if dry_run:
        return {"dry_run": True, "preview": updates}

    client = settings.get("client")
    response = await client.request(
        method="PUT",
        endpoint=f"/api/s/{site_id}/rest/resource/{resource_id}",
        json=updates
    )
    return response

@mcp.tool()
async def list_large_dataset(
    site_id: str,
    limit: int = 100,
    offset: int = 0,
    settings: Context = None,
) -> dict:
    """List resources with pagination support."""
    client = settings.get("client")
    response = await client.request(
        method="GET",
        endpoint=f"/api/s/{site_id}/rest/resource",
        params={"limit": limit, "offset": offset}
    )

    return {
        "data": response.get("data", []),
        "total": response.get("meta", {}).get("total", 0),
        "limit": limit,
        "offset": offset
    }

@mcp.tool()
async def aggregate_across_sites(
    settings: Context = None,
) -> dict:
    """Aggregate data across all sites."""
    client = settings.get("client")

    # Get all sites
    sites_response = await client.request(
        method="GET",
        endpoint="/api/self/sites"
    )
    sites = sites_response.get("data", [])

    # Aggregate data
    results = []
    for site in sites:
        site_id = site["name"]
        site_data = await client.request(
            method="GET",
            endpoint=f"/api/s/{site_id}/rest/resource"
        )
        results.append({
            "site_id": site_id,
            "data": site_data.get("data", [])
        })

    return {"sites": results}