iflow-mcp_enuno-unifi-mcp-server 0.2.1__py3-none-any.whl

src/tools/traffic_matching_lists.py

@@ -0,0 +1,371 @@
+"""Traffic Matching List management MCP tools."""
+
+from typing import Any
+
+from ..api import UniFiClient
+from ..config import Settings
+from ..models.traffic_matching_list import TrafficMatchingList, TrafficMatchingListCreate
+from ..utils import (
+    ResourceNotFoundError,
+    ValidationError,
+    get_logger,
+    log_audit,
+    validate_confirmation,
+    validate_limit_offset,
+    validate_site_id,
+)
+
+
+async def list_traffic_matching_lists(
+    site_id: str,
+    settings: Settings,
+    limit: int | None = None,
+    offset: int | None = None,
+) -> list[dict[str, Any]]:
+    """List all traffic matching lists in a site (read-only).
+
+    Args:
+        site_id: Site identifier
+        settings: Application settings
+        limit: Maximum number of lists to return
+        offset: Number of lists to skip
+
+    Returns:
+        List of traffic matching list dictionaries
+    """
+    site_id = validate_site_id(site_id)
+    limit, offset = validate_limit_offset(limit, offset)
+    logger = get_logger(__name__, settings.log_level)
+
+    async with UniFiClient(settings) as client:
+        await client.authenticate()
+
+        response = await client.get(f"/integration/v1/sites/{site_id}/traffic-matching-lists")
+        lists_data: list[dict[str, Any]] = response.get("data", [])
+
+        # Apply pagination
+        paginated = lists_data[offset : offset + limit]
+
+        logger.info(f"Retrieved {len(paginated)} traffic matching lists for site '{site_id}'")
+        return [TrafficMatchingList(**lst).model_dump() for lst in paginated]
+
+
+async def get_traffic_matching_list(
+    site_id: str,
+    list_id: str,
+    settings: Settings,
+) -> dict[str, Any]:
+    """Get details for a specific traffic matching list.
+
+    Args:
+        site_id: Site identifier
+        list_id: Traffic matching list ID
+        settings: Application settings
+
+    Returns:
+        Traffic matching list dictionary
+
+    Raises:
+        ResourceNotFoundError: If list not found
+    """
+    site_id = validate_site_id(site_id)
+    logger = get_logger(__name__, settings.log_level)
+
+    async with UniFiClient(settings) as client:
+        await client.authenticate()
+
+        response = await client.get(
+            f"/integration/v1/sites/{site_id}/traffic-matching-lists/{list_id}"
+        )
+
+        if isinstance(response, dict) and "data" in response:
+            list_data = response["data"]
+        else:
+            list_data = response
+
+        if not list_data:
+            raise ResourceNotFoundError("traffic_matching_list", list_id)
+
+        logger.info(f"Retrieved traffic matching list {list_id}")
+        return TrafficMatchingList(**list_data).model_dump()  # type: ignore[no-any-return]
+
+
+async def create_traffic_matching_list(
+    site_id: str,
+    list_type: str,
+    name: str,
+    items: list[str],
+    settings: Settings,
+    confirm: bool = False,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    """Create a new traffic matching list.
+
+    Args:
+        site_id: Site identifier
+        list_type: List type (PORTS, IPV4_ADDRESSES, IPV6_ADDRESSES)
+        name: List name
+        items: List items (ports, IPs, etc.)
+        settings: Application settings
+        confirm: Confirmation flag (must be True to execute)
+        dry_run: If True, validate but don't create
+
+    Returns:
+        Created list dictionary or dry-run result
+
+    Raises:
+        ConfirmationRequiredError: If confirm is not True
+        ValidationError: If validation fails
+    """
+    site_id = validate_site_id(site_id)
+    validate_confirmation(confirm, "traffic matching list operation")
+    logger = get_logger(__name__, settings.log_level)
+
+    # Validate list type
+    valid_types = ["PORTS", "IPV4_ADDRESSES", "IPV6_ADDRESSES"]
+    if list_type not in valid_types:
+        raise ValidationError(f"Invalid list type '{list_type}'. Must be one of: {valid_types}")
+
+    # Validate items not empty
+    if not items or len(items) == 0:
+        raise ValidationError("Items list cannot be empty")
+
+    # Build list data
+    create_data = TrafficMatchingListCreate(type=list_type, name=name, items=items)
+
+    parameters = {
+        "site_id": site_id,
+        "type": list_type,
+        "name": name,
+        "items_count": len(items),
+    }
+
+    if dry_run:
+        logger.info(f"DRY RUN: Would create traffic matching list '{name}' in site '{site_id}'")
+        log_audit(
+            operation="create_traffic_matching_list",
+            parameters=parameters,
+            result="dry_run",
+            site_id=site_id,
+            dry_run=True,
+        )
+        return {"dry_run": True, "would_create": create_data.model_dump()}
+
+    try:
+        async with UniFiClient(settings) as client:
+            await client.authenticate()
+
+            response = await client.post(
+                f"/integration/v1/sites/{site_id}/traffic-matching-lists",
+                json_data=create_data.model_dump(),
+            )
+            created_list: dict[str, Any] = response.get("data", response)
+
+            logger.info(f"Created traffic matching list '{name}' in site '{site_id}'")
+            log_audit(
+                operation="create_traffic_matching_list",
+                parameters=parameters,
+                result="success",
+                site_id=site_id,
+            )
+
+            return created_list
+
+    except Exception as e:
+        logger.error(f"Failed to create traffic matching list '{name}': {e}")
+        log_audit(
+            operation="create_traffic_matching_list",
+            parameters=parameters,
+            result="failed",
+            site_id=site_id,
+        )
+        raise
+
+
+async def update_traffic_matching_list(
+    site_id: str,
+    list_id: str,
+    settings: Settings,
+    list_type: str | None = None,
+    name: str | None = None,
+    items: list[str] | None = None,
+    confirm: bool = False,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    """Update an existing traffic matching list.
+
+    Args:
+        site_id: Site identifier
+        list_id: Traffic matching list ID
+        settings: Application settings
+        list_type: New list type
+        name: New list name
+        items: New list items
+        confirm: Confirmation flag (must be True to execute)
+        dry_run: If True, validate but don't update
+
+    Returns:
+        Updated list dictionary or dry-run result
+
+    Raises:
+        ConfirmationRequiredError: If confirm is not True
+        ResourceNotFoundError: If list not found
+    """
+    site_id = validate_site_id(site_id)
+    validate_confirmation(confirm, "traffic matching list operation")
+    logger = get_logger(__name__, settings.log_level)
+
+    # Validate list type if provided
+    if list_type is not None:
+        valid_types = ["PORTS", "IPV4_ADDRESSES", "IPV6_ADDRESSES"]
+        if list_type not in valid_types:
+            raise ValidationError(f"Invalid list type '{list_type}'. Must be one of: {valid_types}")
+
+    # Validate items if provided
+    if items is not None and len(items) == 0:
+        raise ValidationError("Items list cannot be empty")
+
+    parameters = {
+        "site_id": site_id,
+        "list_id": list_id,
+        "type": list_type,
+        "name": name,
+        "items_count": len(items) if items else None,
+    }
+
+    if dry_run:
+        logger.info(f"DRY RUN: Would update traffic matching list '{list_id}' in site '{site_id}'")
+        log_audit(
+            operation="update_traffic_matching_list",
+            parameters=parameters,
+            result="dry_run",
+            site_id=site_id,
+            dry_run=True,
+        )
+        return {"dry_run": True, "would_update": parameters}
+
+    try:
+        async with UniFiClient(settings) as client:
+            await client.authenticate()
+
+            # Get existing list
+            response = await client.get(
+                f"/integration/v1/sites/{site_id}/traffic-matching-lists/{list_id}"
+            )
+            existing_list = response.get("data", response)
+
+            if not existing_list:
+                raise ResourceNotFoundError("traffic_matching_list", list_id)
+
+            # Build update data
+            update_data = existing_list.copy()
+
+            if list_type is not None:
+                update_data["type"] = list_type
+            if name is not None:
+                update_data["name"] = name
+            if items is not None:
+                update_data["items"] = items
+
+            response = await client.put(
+                f"/integration/v1/sites/{site_id}/traffic-matching-lists/{list_id}",
+                json_data=update_data,
+            )
+            updated_list: dict[str, Any] = response.get("data", response)
+
+            logger.info(f"Updated traffic matching list '{list_id}' in site '{site_id}'")
+            log_audit(
+                operation="update_traffic_matching_list",
+                parameters=parameters,
+                result="success",
+                site_id=site_id,
+            )
+
+            return updated_list
+
+    except Exception as e:
+        logger.error(f"Failed to update traffic matching list '{list_id}': {e}")
+        log_audit(
+            operation="update_traffic_matching_list",
+            parameters=parameters,
+            result="failed",
+            site_id=site_id,
+        )
+        raise
+
+
+async def delete_traffic_matching_list(
+    site_id: str,
+    list_id: str,
+    settings: Settings,
+    confirm: bool = False,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    """Delete a traffic matching list.
+
+    Args:
+        site_id: Site identifier
+        list_id: Traffic matching list ID
+        settings: Application settings
+        confirm: Confirmation flag (must be True to execute)
+        dry_run: If True, validate but don't delete
+
+    Returns:
+        Deletion result dictionary
+
+    Raises:
+        ConfirmationRequiredError: If confirm is not True
+        ResourceNotFoundError: If list not found
+    """
+    site_id = validate_site_id(site_id)
+    validate_confirmation(confirm, "traffic matching list operation")
+    logger = get_logger(__name__, settings.log_level)
+
+    parameters = {"site_id": site_id, "list_id": list_id}
+
+    if dry_run:
+        logger.info(
+            f"DRY RUN: Would delete traffic matching list '{list_id}' from site '{site_id}'"
+        )
+        log_audit(
+            operation="delete_traffic_matching_list",
+            parameters=parameters,
+            result="dry_run",
+            site_id=site_id,
+            dry_run=True,
+        )
+        return {"dry_run": True, "would_delete": list_id}
+
+    try:
+        async with UniFiClient(settings) as client:
+            await client.authenticate()
+
+            # Verify list exists before deleting
+            try:
+                await client.get(
+                    f"/integration/v1/sites/{site_id}/traffic-matching-lists/{list_id}"
+                )
+            except Exception as err:
+                raise ResourceNotFoundError("traffic_matching_list", list_id) from err
+
+            await client.delete(f"/integration/v1/sites/{site_id}/traffic-matching-lists/{list_id}")
+
+            logger.info(f"Deleted traffic matching list '{list_id}' from site '{site_id}'")
+            log_audit(
+                operation="delete_traffic_matching_list",
+                parameters=parameters,
+                result="success",
+                site_id=site_id,
+            )
+
+            return {"success": True, "deleted_list_id": list_id}
+
+    except Exception as e:
+        logger.error(f"Failed to delete traffic matching list '{list_id}': {e}")
+        log_audit(
+            operation="delete_traffic_matching_list",
+            parameters=parameters,
+            result="failed",
+            site_id=site_id,
+        )
+        raise

src/tools/vouchers.py

@@ -0,0 +1,249 @@
+"""Hotspot voucher management tools."""
+
+from typing import Any
+
+from ..api.client import UniFiClient
+from ..config import Settings
+from ..models import Voucher
+from ..utils import audit_action, get_logger, validate_confirmation
+
+logger = get_logger(__name__)
+
+
+async def list_vouchers(
+    site_id: str,
+    settings: Settings,
+    limit: int | None = None,
+    offset: int | None = None,
+    filter_expr: str | None = None,
+) -> list[dict]:
+    """List all hotspot vouchers for a site.
+
+    Args:
+        site_id: Site identifier
+        settings: Application settings
+        limit: Maximum number of results
+        offset: Starting position
+        filter_expr: Filter expression
+
+    Returns:
+        List of vouchers
+    """
+    async with UniFiClient(settings) as client:
+        logger.info(f"Listing vouchers for site {site_id}")
+
+        if not client.is_authenticated:
+            await client.authenticate()
+
+        params: dict[str, Any] = {}
+        if limit is not None:
+            params["limit"] = limit
+        if offset is not None:
+            params["offset"] = offset
+        if filter_expr:
+            params["filter"] = filter_expr
+
+        response = await client.get(f"/integration/v1/sites/{site_id}/vouchers", params=params)
+        data = response.get("data", [])
+
+        return [Voucher(**voucher).model_dump() for voucher in data]
+
+
+async def get_voucher(site_id: str, voucher_id: str, settings: Settings) -> dict:
+    """Get details for a specific voucher.
+
+    Args:
+        site_id: Site identifier
+        voucher_id: Voucher identifier
+        settings: Application settings
+
+    Returns:
+        Voucher details
+    """
+    async with UniFiClient(settings) as client:
+        logger.info(f"Getting voucher {voucher_id} for site {site_id}")
+
+        if not client.is_authenticated:
+            await client.authenticate()
+
+        response = await client.get(f"/integration/v1/sites/{site_id}/vouchers/{voucher_id}")
+        data = response.get("data", response)
+
+        return Voucher(**data).model_dump()  # type: ignore[no-any-return]
+
+
+async def create_vouchers(
+    site_id: str,
+    count: int,
+    duration: int,
+    settings: Settings,
+    upload_limit_kbps: int | None = None,
+    download_limit_kbps: int | None = None,
+    upload_quota_mb: int | None = None,
+    download_quota_mb: int | None = None,
+    note: str | None = None,
+    confirm: bool = False,
+    dry_run: bool = False,
+) -> dict:
+    """Create new hotspot vouchers.
+
+    Args:
+        site_id: Site identifier
+        count: Number of vouchers to create
+        duration: Duration in seconds
+        settings: Application settings
+        upload_limit_kbps: Upload speed limit in kbps
+        download_limit_kbps: Download speed limit in kbps
+        upload_quota_mb: Upload quota in MB
+        download_quota_mb: Download quota in MB
+        note: Admin notes
+        confirm: Confirmation flag (required)
+        dry_run: If True, validate but don't execute
+
+    Returns:
+        Created voucher codes
+    """
+    validate_confirmation(confirm, "create vouchers")
+
+    async with UniFiClient(settings) as client:
+        logger.info(f"Creating {count} vouchers for site {site_id}")
+
+        if not client.is_authenticated:
+            await client.authenticate()
+
+        # Build request payload
+        payload: dict[str, Any] = {
+            "count": count,
+            "duration": duration,
+        }
+
+        if upload_limit_kbps is not None:
+            payload["uploadLimit"] = upload_limit_kbps
+        if download_limit_kbps is not None:
+            payload["downloadLimit"] = download_limit_kbps
+        if upload_quota_mb is not None:
+            payload["uploadQuota"] = upload_quota_mb
+        if download_quota_mb is not None:
+            payload["downloadQuota"] = download_quota_mb
+        if note:
+            payload["note"] = note
+
+        if dry_run:
+            logger.info(f"[DRY RUN] Would create vouchers with payload: {payload}")
+            return {"dry_run": True, "payload": payload}
+
+        response = await client.post(f"/integration/v1/sites/{site_id}/vouchers", json_data=payload)
+        data = response.get("data", response)
+
+        # Audit the action
+        await audit_action(
+            settings,
+            action_type="create_vouchers",
+            resource_type="voucher",
+            resource_id="bulk",
+            site_id=site_id,
+            details={"count": count, "duration": duration},
+        )
+
+        return {
+            "success": True,
+            "count": count,
+            "vouchers": data if isinstance(data, list) else [data],
+        }
+
+
+async def delete_voucher(
+    site_id: str,
+    voucher_id: str,
+    settings: Settings,
+    confirm: bool = False,
+    dry_run: bool = False,
+) -> dict:
+    """Delete a specific voucher.
+
+    Args:
+        site_id: Site identifier
+        voucher_id: Voucher identifier
+        settings: Application settings
+        confirm: Confirmation flag (required)
+        dry_run: If True, validate but don't execute
+
+    Returns:
+        Deletion status
+    """
+    validate_confirmation(confirm, "delete voucher")
+
+    async with UniFiClient(settings) as client:
+        logger.info(f"Deleting voucher {voucher_id} for site {site_id}")
+
+        if not client.is_authenticated:
+            await client.authenticate()
+
+        if dry_run:
+            logger.info(f"[DRY RUN] Would delete voucher {voucher_id}")
+            return {"dry_run": True, "voucher_id": voucher_id}
+
+        await client.delete(f"/integration/v1/sites/{site_id}/vouchers/{voucher_id}")
+
+        # Audit the action
+        await audit_action(
+            settings,
+            action_type="delete_voucher",
+            resource_type="voucher",
+            resource_id=voucher_id,
+            site_id=site_id,
+            details={},
+        )
+
+        return {"success": True, "message": f"Voucher {voucher_id} deleted successfully"}
+
+
+async def bulk_delete_vouchers(
+    site_id: str,
+    filter_expr: str,
+    settings: Settings,
+    confirm: bool = False,
+    dry_run: bool = False,
+) -> dict:
+    """Bulk delete vouchers using a filter expression.
+
+    Args:
+        site_id: Site identifier
+        filter_expr: Filter expression to select vouchers
+        settings: Application settings
+        confirm: Confirmation flag (required)
+        dry_run: If True, validate but don't execute
+
+    Returns:
+        Deletion status
+    """
+    validate_confirmation(confirm, "bulk delete vouchers")
+
+    async with UniFiClient(settings) as client:
+        logger.info(f"Bulk deleting vouchers for site {site_id} with filter: {filter_expr}")
+
+        if not client.is_authenticated:
+            await client.authenticate()
+
+        if dry_run:
+            logger.info(f"[DRY RUN] Would bulk delete vouchers with filter: {filter_expr}")
+            return {"dry_run": True, "filter": filter_expr}
+
+        params = {"filter": filter_expr}
+        response = await client.delete(f"/integration/v1/sites/{site_id}/vouchers", params=params)
+
+        # Audit the action
+        await audit_action(
+            settings,
+            action_type="bulk_delete_vouchers",
+            resource_type="voucher",
+            resource_id="bulk",
+            site_id=site_id,
+            details={"filter": filter_expr},
+        )
+
+        return {
+            "success": True,
+            "message": "Vouchers deleted successfully",
+            "deleted_count": response.get("data", {}).get("count", 0),
+        }

src/tools/vpn.py

@@ -0,0 +1,76 @@
+"""VPN management MCP tools."""
+
+from typing import Any
+
+from ..api import UniFiClient
+from ..config import Settings
+from ..models.vpn import VPNServer, VPNTunnel
+from ..utils import get_logger, validate_limit_offset, validate_site_id
+
+
+async def list_vpn_tunnels(
+    site_id: str,
+    settings: Settings,
+    limit: int | None = None,
+    offset: int | None = None,
+) -> list[dict[str, Any]]:
+    """List all site-to-site VPN tunnels in a site (read-only).
+
+    Args:
+        site_id: Site identifier
+        settings: Application settings
+        limit: Maximum number of tunnels to return
+        offset: Number of tunnels to skip
+
+    Returns:
+        List of VPN tunnel dictionaries
+    """
+    site_id = validate_site_id(site_id)
+    limit, offset = validate_limit_offset(limit, offset)
+    logger = get_logger(__name__, settings.log_level)
+
+    async with UniFiClient(settings) as client:
+        await client.authenticate()
+
+        response = await client.get(f"/integration/v1/sites/{site_id}/vpn/site-to-site-tunnels")
+        tunnels_data: list[dict[str, Any]] = response.get("data", [])
+
+        # Apply pagination
+        paginated = tunnels_data[offset : offset + limit]
+
+        logger.info(f"Retrieved {len(paginated)} VPN tunnels for site '{site_id}'")
+        return [VPNTunnel(**tunnel).model_dump() for tunnel in paginated]
+
+
+async def list_vpn_servers(
+    site_id: str,
+    settings: Settings,
+    limit: int | None = None,
+    offset: int | None = None,
+) -> list[dict[str, Any]]:
+    """List all VPN servers in a site (read-only).
+
+    Args:
+        site_id: Site identifier
+        settings: Application settings
+        limit: Maximum number of servers to return
+        offset: Number of servers to skip
+
+    Returns:
+        List of VPN server dictionaries
+    """
+    site_id = validate_site_id(site_id)
+    limit, offset = validate_limit_offset(limit, offset)
+    logger = get_logger(__name__, settings.log_level)
+
+    async with UniFiClient(settings) as client:
+        await client.authenticate()
+
+        response = await client.get(f"/integration/v1/sites/{site_id}/vpn/servers")
+        servers_data: list[dict[str, Any]] = response.get("data", [])
+
+        # Apply pagination
+        paginated = servers_data[offset : offset + limit]
+
+        logger.info(f"Retrieved {len(paginated)} VPN servers for site '{site_id}'")
+        return [VPNServer(**server).model_dump() for server in paginated]