unifi-network-mcp 0.4.1__tar.gz → 0.5.0__tar.gz

{unifi_network_mcp-0.4.1 → unifi_network_mcp-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unifi-network-mcp
-Version: 0.4.1
+Version: 0.5.0
 Summary: Unifi Network MCP Server
 License-File: LICENSE
 Requires-Python: >=3.13

{unifi_network_mcp-0.4.1 → unifi_network_mcp-0.5.0}/src/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.4.1'
-__version_tuple__ = version_tuple = (0, 4, 1)
+__version__ = version = '0.5.0'
+__version_tuple__ = version_tuple = (0, 5, 0)
 
 __commit_id__ = commit_id = None

{unifi_network_mcp-0.4.1 → unifi_network_mcp-0.5.0}/src/config/config.yaml

@@ -51,6 +51,7 @@ server:
 
   http:
     enabled: ${oc.env:UNIFI_MCP_HTTP_ENABLED,false}
+    force: ${oc.env:UNIFI_MCP_HTTP_FORCE,false}
   diagnostics:
     enabled: ${oc.env:UNIFI_MCP_DIAGNOSTICS,false}
     log_tool_args: ${oc.env:UNIFI_MCP_DIAG_LOG_TOOL_ARGS,true}
@@ -117,4 +118,8 @@ permissions:
 
   routes:
     create: false  # Static routes can disrupt connectivity
-    update: false  # Modifying routes requires careful planning
+    update: false  # Modifying routes requires careful planning
+
+  snmp:
+    create: false  # Not applicable
+    update: true   # Allow enabling/disabling SNMP and changing community

{unifi_network_mcp-0.4.1 → unifi_network_mcp-0.5.0}/src/main.py

@@ -10,9 +10,11 @@ Responsibilities:
 import asyncio
 import logging
 import os
-import sys  # Removed uvicorn import
+import sys
 import traceback
 
+import uvicorn.config
+
 from src.bootstrap import (
     UNIFI_TOOL_REGISTRATION_MODE,
     logger,
@@ -26,13 +28,15 @@ from src.runtime import (
     server,
 )
 from src.tool_index import register_tool, tool_index_handler
+from src.utils.config_helpers import parse_config_bool
 from src.utils.diagnostics import diagnostics_enabled, wrap_tool
 from src.utils.lazy_tool_loader import setup_lazy_loading
 from src.utils.meta_tools import register_load_tools, register_meta_tools
 from src.utils.permissions import parse_permission  # noqa: E402
 from src.utils.tool_loader import auto_load_tools
 
-_original_tool_decorator = server.tool  # keep reference to wrap later
+# Use the original FastMCP tool decorator (saved in runtime.py before wrapping)
+_original_tool_decorator = getattr(server, "_original_tool", server.tool)
 
 
 def permissioned_tool(*d_args, **d_kwargs):  # acts like @server.tool
@@ -310,17 +314,16 @@ async def main_async():
     host = config.server.get("host", "0.0.0.0")
     port = int(config.server.get("port", 3000))
     http_cfg = config.server.get("http", {})
-    http_enabled_raw = http_cfg.get("enabled", False)
-    if isinstance(http_enabled_raw, str):
-        http_enabled = http_enabled_raw.strip().lower() in {"1", "true", "yes", "on"}
-    else:
-        http_enabled = bool(http_enabled_raw)
+    http_enabled = parse_config_bool(http_cfg.get("enabled", False))
 
-    # Only the main container process (PID 1) should bind the HTTP SSE port.
+    # Only the main container process (PID 1) should bind the HTTP SSE port,
+    # unless http.force=true is set in config (for local development/testing).
+    force_http = parse_config_bool(http_cfg.get("force", False))
     is_main_container_process = os.getpid() == 1
-    if http_enabled and not is_main_container_process:
+    if http_enabled and not is_main_container_process and not force_http:
         logger.info(
-            "HTTP SSE enabled in config but skipped in exec session (PID %s != 1)",
+            "HTTP SSE enabled in config but skipped in exec session (PID %s != 1). "
+            "Set UNIFI_MCP_HTTP_FORCE=true to override.",
             os.getpid(),
         )
         http_enabled = False
@@ -338,9 +341,9 @@ async def main_async():
                 server.settings.host = host
                 server.settings.port = port
 
-                # Disable uvicorn access logging to prevent stdout conflicts
-                # when running alongside stdio transport
-                logging.getLogger("uvicorn.access").disabled = True
+                # Redirect uvicorn access logs to stderr to prevent stdout conflicts
+                # when running alongside stdio transport (stdout is used for JSON-RPC)
+                uvicorn.config.LOGGING_CONFIG["handlers"]["access"]["stream"] = "ext://sys.stderr"
 
                 await server.run_sse_async()
                 logger.info("HTTP SSE started via run_sse_async() using server.settings host/port.")

{unifi_network_mcp-0.4.1 → unifi_network_mcp-0.5.0}/src/runtime.py

@@ -12,6 +12,10 @@ Downstream code (tool modules, tests, etc.) should import these via::
 
 Lazy factories (`get_*`) are provided so unit tests can substitute fakes by
 monkey‑patching before the first call.
+
+IMPORTANT: The server's `tool` decorator is wrapped here (not in main.py) to
+ensure that tool modules can be imported directly (for testing, etc.) without
+errors from unrecognized decorator kwargs like `permission_category`.
 """
 
 import os
@@ -49,6 +53,25 @@ def get_config():
     return load_config()
 
 
+def _create_permissioned_tool_wrapper(original_tool_decorator):
+    """Wrap the FastMCP tool decorator to handle permission kwargs.
+
+    This wrapper strips `permission_category` and `permission_action` kwargs
+    before passing to the original FastMCP decorator. This allows tool modules
+    to be imported directly (for testing, etc.) without errors.
+
+    The actual permission checking is done in main.py's permissioned_tool,
+    which replaces this wrapper at startup. This wrapper just ensures imports
+    don't fail when tools have permission kwargs.
+    """
+    def wrapper(*args, **kwargs):
+        # Strip permission-related kwargs that FastMCP doesn't understand
+        kwargs.pop("permission_category", None)
+        kwargs.pop("permission_action", None)
+        return original_tool_decorator(*args, **kwargs)
+    return wrapper
+
+
 @lru_cache
 def get_server() -> FastMCP:
     """Create the FastMCP server instance exactly once."""
@@ -62,12 +85,20 @@ def get_server() -> FastMCP:
 
     logger.debug(f"Configuring FastMCP with allowed_hosts: {allowed_hosts}")
 
-    return FastMCP(
+    server = FastMCP(
         name="unifi-network-mcp",
         debug=True,
         transport_security=transport_security,
     )
 
+    # Wrap the tool decorator to handle permission kwargs gracefully.
+    # This ensures tool modules can be imported directly without errors.
+    # main.py will replace this with the full permissioned_tool implementation.
+    server._original_tool = server.tool
+    server.tool = _create_permissioned_tool_wrapper(server.tool)
+
+    return server
+
 
 # ---------------------------------------------------------------------------
 # Manager factories ---------------------------------------------------------

{unifi_network_mcp-0.4.1 → unifi_network_mcp-0.5.0}/src/tools/clients.py

@@ -485,10 +485,10 @@ Either setting can be enabled/disabled independently.""",
 )
 async def set_client_ip_settings(
     mac_address: str,
-    use_fixedip: Optional[bool] = None,
-    fixed_ip: Optional[str] = None,
-    local_dns_record_enabled: Optional[bool] = None,
-    local_dns_record: Optional[str] = None,
+    use_fixedip: bool | None = None,
+    fixed_ip: str | None = None,
+    local_dns_record_enabled: bool | None = None,
+    local_dns_record: str | None = None,
     confirm: bool = False,
 ) -> Dict[str, Any]:
     """Set fixed IP and/or local DNS record for a client."""

unifi_network_mcp-0.5.0/src/tools/system.py

@@ -0,0 +1,168 @@
+"""
+Unifi Network MCP system tools.
+
+This module provides MCP tools to interact with a Unifi Network Controller's system functions.
+"""
+
+import logging
+from typing import Any, Dict, Optional
+
+from src.runtime import config, server, system_manager
+from src.utils.confirmation import should_auto_confirm, update_preview
+from src.utils.permissions import parse_permission
+
+logger = logging.getLogger(__name__)
+
+# Explicitly retrieve and log the server instance to confirm it's being used
+logger.info(f"System tools module loaded, server instance: {server}")
+
+
+@server.tool(
+    name="unifi_get_system_info",
+    description="Get general system information from the Unifi Network controller (version, uptime, etc).",
+)
+async def get_system_info() -> Dict[str, Any]:
+    """Implementation for getting system info."""
+    logger.info("unifi_get_system_info tool called")
+    try:
+        info = await system_manager.get_system_info()
+        return {
+            "success": True,
+            "site": system_manager._connection.site,
+            "system_info": info,
+        }
+    except Exception as e:
+        logger.error(f"Error getting system info: {e}", exc_info=True)
+        return {"success": False, "error": str(e)}
+
+
+@server.tool(
+    name="unifi_get_network_health",
+    description="Get the current network health summary (WAN status, device counts).",
+)
+async def get_network_health() -> Dict[str, Any]:
+    """Implementation for getting network health."""
+    logger.info("unifi_get_network_health tool called")
+    try:
+        health = await system_manager.get_network_health()
+        return {
+            "success": True,
+            "site": system_manager._connection.site,
+            "health_summary": health,
+        }
+    except Exception as e:
+        logger.error(f"Error getting network health: {e}", exc_info=True)
+        return {"success": False, "error": str(e)}
+
+
+@server.tool(
+    name="unifi_get_site_settings",
+    description="Get current site settings (e.g., country code, timezone, connectivity monitoring).",
+)
+async def get_site_settings() -> Dict[str, Any]:
+    """Implementation for getting site settings."""
+    logger.info("unifi_get_site_settings tool called")
+    try:
+        settings = await system_manager.get_site_settings()
+        return {
+            "success": True,
+            "site": system_manager._connection.site,
+            "site_settings": settings,
+        }
+    except Exception as e:
+        logger.error(f"Error getting site settings: {e}", exc_info=True)
+        return {"success": False, "error": str(e)}
+
+
+@server.tool(
+    name="unifi_get_snmp_settings",
+    description="Get current SNMP settings for the site (enabled state, community string).",
+)
+async def get_snmp_settings() -> Dict[str, Any]:
+    """Implementation for getting SNMP settings."""
+    logger.info("unifi_get_snmp_settings tool called")
+    try:
+        settings_list = await system_manager.get_settings("snmp")
+        snmp_settings = settings_list[0] if settings_list else {}
+        return {
+            "success": True,
+            "site": system_manager._connection.site,
+            "snmp_settings": {
+                "enabled": snmp_settings.get("enabled", False),
+                "community": snmp_settings.get("community", ""),
+            },
+        }
+    except Exception as e:
+        logger.error(f"Error getting SNMP settings: {e}", exc_info=True)
+        return {"success": False, "error": str(e)}
+
+
+@server.tool(
+    name="unifi_update_snmp_settings",
+    description="Update SNMP settings for the site (enable/disable, set community string). Requires confirm=true to apply changes.",
+)
+async def update_snmp_settings(
+    enabled: bool,
+    community: Optional[str] = None,
+    confirm: bool = False,
+) -> Dict[str, Any]:
+    """Implementation for updating SNMP settings.
+
+    Args:
+        enabled: Whether SNMP should be enabled on the site.
+        community: SNMP community string (optional, keeps current value if not provided).
+        confirm: Must be true to apply changes. When false, returns a preview of proposed changes.
+    """
+    logger.info(f"unifi_update_snmp_settings tool called (enabled={enabled}, confirm={confirm})")
+
+    if not parse_permission(config.permissions, "snmp", "update"):
+        logger.warning("Permission denied for updating SNMP settings.")
+        return {"success": False, "error": "Permission denied to update SNMP settings."}
+
+    try:
+        settings_list = await system_manager.get_settings("snmp")
+        current = settings_list[0] if settings_list else {}
+
+        updates: Dict[str, Any] = {"enabled": enabled}
+        if community is not None:
+            updates["community"] = community
+
+        if not confirm and not should_auto_confirm():
+            return update_preview(
+                resource_type="snmp_settings",
+                resource_id=current.get("_id", "snmp"),
+                resource_name="SNMP Settings",
+                current_state={
+                    "enabled": current.get("enabled", False),
+                    "community": current.get("community", ""),
+                },
+                updates=updates,
+            )
+
+        payload: Dict[str, Any] = {"enabled": enabled}
+        if community is not None:
+            payload["community"] = community
+
+        success = await system_manager.update_settings("snmp", payload)
+        if success:
+            refreshed = await system_manager.get_settings("snmp")
+            new_settings = refreshed[0] if refreshed else payload
+            return {
+                "success": True,
+                "site": system_manager._connection.site,
+                "snmp_settings": {
+                    "enabled": new_settings.get("enabled", enabled),
+                    "community": new_settings.get("community", community or ""),
+                },
+            }
+        return {"success": False, "error": "Failed to update SNMP settings."}
+    except Exception as e:
+        logger.error(f"Error updating SNMP settings: {e}", exc_info=True)
+        return {"success": False, "error": str(e)}
+
+
+# Print confirmation that all tools have been registered
+logger.info(
+    "System tools registered: unifi_get_system_info, unifi_get_network_health, "
+    "unifi_get_site_settings, unifi_get_snmp_settings, unifi_update_snmp_settings"
+)

{unifi_network_mcp-0.4.1 → unifi_network_mcp-0.5.0}/src/tools_manifest.json

@@ -1,6 +1,91 @@
 {
-  "count": 81,
+  "count": 83,
   "generated_by": "scripts/generate_tool_manifest.py",
+  "module_map": {
+    "unifi_adopt_device": "src.tools.devices",
+    "unifi_archive_alarm": "src.tools.events",
+    "unifi_archive_all_alarms": "src.tools.events",
+    "unifi_authorize_guest": "src.tools.clients",
+    "unifi_block_client": "src.tools.clients",
+    "unifi_create_firewall_policy": "src.tools.firewall",
+    "unifi_create_network": "src.tools.network",
+    "unifi_create_port_forward": "src.tools.port_forwards",
+    "unifi_create_qos_rule": "src.tools.qos",
+    "unifi_create_route": "src.tools.routing",
+    "unifi_create_simple_firewall_policy": "src.tools.firewall",
+    "unifi_create_simple_port_forward": "src.tools.port_forwards",
+    "unifi_create_simple_qos_rule": "src.tools.qos",
+    "unifi_create_usergroup": "src.tools.usergroups",
+    "unifi_create_voucher": "src.tools.hotspot",
+    "unifi_create_wlan": "src.tools.network",
+    "unifi_force_reconnect_client": "src.tools.clients",
+    "unifi_get_alerts": "src.tools.stats",
+    "unifi_get_client_details": "src.tools.clients",
+    "unifi_get_client_stats": "src.tools.stats",
+    "unifi_get_device_details": "src.tools.devices",
+    "unifi_get_device_stats": "src.tools.stats",
+    "unifi_get_dpi_stats": "src.tools.stats",
+    "unifi_get_event_types": "src.tools.events",
+    "unifi_get_firewall_policy_details": "src.tools.firewall",
+    "unifi_get_network_details": "src.tools.network",
+    "unifi_get_network_health": "src.tools.system",
+    "unifi_get_network_stats": "src.tools.stats",
+    "unifi_get_port_forward": "src.tools.port_forwards",
+    "unifi_get_qos_rule_details": "src.tools.qos",
+    "unifi_get_route_details": "src.tools.routing",
+    "unifi_get_site_settings": "src.tools.config",
+    "unifi_get_snmp_settings": "src.tools.system",
+    "unifi_get_system_info": "src.tools.system",
+    "unifi_get_top_clients": "src.tools.stats",
+    "unifi_get_traffic_route_details": "src.tools.traffic_routes",
+    "unifi_get_usergroup_details": "src.tools.usergroups",
+    "unifi_get_voucher_details": "src.tools.hotspot",
+    "unifi_get_vpn_client_details": "src.tools.vpn",
+    "unifi_get_vpn_server_details": "src.tools.vpn",
+    "unifi_get_wlan_details": "src.tools.network",
+    "unifi_list_active_routes": "src.tools.routing",
+    "unifi_list_alarms": "src.tools.events",
+    "unifi_list_blocked_clients": "src.tools.clients",
+    "unifi_list_clients": "src.tools.clients",
+    "unifi_list_devices": "src.tools.devices",
+    "unifi_list_events": "src.tools.events",
+    "unifi_list_firewall_policies": "src.tools.firewall",
+    "unifi_list_firewall_zones": "src.tools.firewall",
+    "unifi_list_ip_groups": "src.tools.firewall",
+    "unifi_list_networks": "src.tools.network",
+    "unifi_list_port_forwards": "src.tools.port_forwards",
+    "unifi_list_qos_rules": "src.tools.qos",
+    "unifi_list_routes": "src.tools.routing",
+    "unifi_list_traffic_routes": "src.tools.traffic_routes",
+    "unifi_list_usergroups": "src.tools.usergroups",
+    "unifi_list_vouchers": "src.tools.hotspot",
+    "unifi_list_vpn_clients": "src.tools.vpn",
+    "unifi_list_vpn_servers": "src.tools.vpn",
+    "unifi_list_wlans": "src.tools.network",
+    "unifi_reboot_device": "src.tools.devices",
+    "unifi_rename_client": "src.tools.clients",
+    "unifi_rename_device": "src.tools.devices",
+    "unifi_revoke_voucher": "src.tools.hotspot",
+    "unifi_set_client_ip_settings": "src.tools.clients",
+    "unifi_toggle_firewall_policy": "src.tools.firewall",
+    "unifi_toggle_port_forward": "src.tools.port_forwards",
+    "unifi_toggle_qos_rule_enabled": "src.tools.qos",
+    "unifi_toggle_traffic_route": "src.tools.traffic_routes",
+    "unifi_unauthorize_guest": "src.tools.clients",
+    "unifi_unblock_client": "src.tools.clients",
+    "unifi_update_firewall_policy": "src.tools.firewall",
+    "unifi_update_network": "src.tools.network",
+    "unifi_update_port_forward": "src.tools.port_forwards",
+    "unifi_update_qos_rule": "src.tools.qos",
+    "unifi_update_route": "src.tools.routing",
+    "unifi_update_snmp_settings": "src.tools.system",
+    "unifi_update_traffic_route": "src.tools.traffic_routes",
+    "unifi_update_usergroup": "src.tools.usergroups",
+    "unifi_update_vpn_client_state": "src.tools.vpn",
+    "unifi_update_vpn_server_state": "src.tools.vpn",
+    "unifi_update_wlan": "src.tools.network",
+    "unifi_upgrade_device": "src.tools.devices"
+  },
   "note": "Auto-generated with full schemas from tool decorators. Do not edit manually.",
   "tools": [
     {
@@ -611,6 +696,16 @@
         }
       }
     },
+    {
+      "description": "Get current SNMP settings for the site (enabled state, community string).",
+      "name": "unifi_get_snmp_settings",
+      "schema": {
+        "input": {
+          "properties": {},
+          "type": "object"
+        }
+      }
+    },
     {
       "description": "Get general system information from the Unifi Network controller (version, uptime, etc).",
       "name": "unifi_get_system_info",
@@ -1345,6 +1440,29 @@
         }
       }
     },
+    {
+      "description": "Update SNMP settings for the site (enable/disable, set community string). Requires confirm=true to apply changes.",
+      "name": "unifi_update_snmp_settings",
+      "schema": {
+        "input": {
+          "properties": {
+            "community": {
+              "type": "string"
+            },
+            "confirm": {
+              "type": "boolean"
+            },
+            "enabled": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "enabled"
+          ],
+          "type": "object"
+        }
+      }
+    },
     {
       "description": "Update a traffic route's settings.\n\nCan update:\n- enabled: Enable or disable the traffic route\n- kill_switch_enabled: Enable/disable the kill switch (blocks traffic if VPN is down)\n\nAt least one parameter must be provided.",
       "name": "unifi_update_traffic_route",

unifi_network_mcp-0.5.0/src/utils/config_helpers.py

@@ -0,0 +1,38 @@
+"""Configuration parsing utilities.
+
+This module provides helpers for parsing configuration values that may come
+from OmegaConf-resolved environment variables (which can be strings like
+"true"/"false") or direct boolean values.
+"""
+
+from typing import Any
+
+
+def parse_config_bool(value: Any, default: bool = False) -> bool:
+    """Parse a config value as boolean, handling string values from env vars.
+
+    OmegaConf resolves ${oc.env:VAR,default} to strings when the env var is set,
+    so "true"/"false" strings need to be parsed explicitly.
+
+    Args:
+        value: The config value to parse (string, bool, or None)
+        default: Default value if value is None
+
+    Returns:
+        Boolean interpretation of the value
+
+    Examples:
+        >>> parse_config_bool("true")
+        True
+        >>> parse_config_bool("false")
+        False
+        >>> parse_config_bool(True)
+        True
+        >>> parse_config_bool(None, default=True)
+        True
+    """
+    if value is None:
+        return default
+    if isinstance(value, str):
+        return value.strip().lower() in {"1", "true", "yes", "on"}
+    return bool(value)

unifi_network_mcp-0.5.0/src/utils/lazy_tool_loader.py

@@ -0,0 +1,214 @@
+"""Lazy tool loader for on-demand tool registration.
+
+This module implements true lazy loading of tools, registering them only
+when first called by an LLM. This dramatically reduces initial context usage.
+"""
+
+import importlib
+import json
+import logging
+import re
+from functools import wraps
+from pathlib import Path
+from typing import Any, Callable, Dict, Set
+
+logger = logging.getLogger("unifi-network-mcp")
+
+
+def _load_module_map_from_manifest() -> Dict[str, str]:
+    """Load tool-to-module mapping from the manifest file.
+
+    The manifest is auto-generated by scripts/generate_tool_manifest.py and
+    includes a module_map that stays in sync with the actual tools.
+
+    Returns:
+        Dictionary mapping tool names to their module paths, or empty dict if unavailable
+    """
+    # Try relative to this file first
+    manifest_path = Path(__file__).parent.parent / "tools_manifest.json"
+
+    if not manifest_path.exists():
+        # Try relative to cwd
+        manifest_path = Path("src/tools_manifest.json")
+
+    if not manifest_path.exists():
+        logger.warning("Tools manifest not found for fallback loading")
+        return {}
+
+    try:
+        with open(manifest_path) as f:
+            manifest = json.load(f)
+        module_map = manifest.get("module_map", {})
+        logger.info(f"Loaded module map from manifest with {len(module_map)} tools")
+        return module_map
+    except Exception as e:
+        logger.warning(f"Failed to load module map from manifest: {e}")
+        return {}
+
+
+def _build_tool_module_map() -> Dict[str, str]:
+    """Build tool-to-module mapping by scanning tool files.
+
+    This dynamically discovers all tools and their modules, eliminating the need
+    for a manually-maintained static mapping that can get out of sync.
+
+    Falls back to loading from tools_manifest.json if the tools directory
+    is not found (e.g., in unusual deployment scenarios).
+    """
+    tool_map: Dict[str, str] = {}
+
+    # Find the tools directory
+    # Try relative to this file first, then fall back to cwd
+    this_dir = Path(__file__).parent
+    tools_dir = this_dir.parent / "tools"
+
+    if not tools_dir.exists():
+        tools_dir = Path("src/tools")
+
+    if not tools_dir.exists():
+        logger.warning("Tools directory not found, falling back to manifest")
+        return _load_module_map_from_manifest()
+
+    # Scan each .py file in tools directory
+    for tool_file in tools_dir.glob("*.py"):
+        if tool_file.name.startswith("_"):
+            continue
+
+        module_name = f"src.tools.{tool_file.stem}"
+
+        try:
+            # Read file and look for @server.tool or @permissioned_tool decorators
+            content = tool_file.read_text()
+
+            # Find tool names using simple pattern matching
+            # Looking for: name="unifi_xxx" or name='unifi_xxx'
+            # Note: pattern uses literal 'unifi_' prefix, not a character class
+            pattern = r'name\s*=\s*["\'](unifi_[a-z_]+)["\']'
+            matches = re.findall(pattern, content)
+
+            for tool_name in matches:
+                if tool_name.startswith("unifi_"):
+                    tool_map[tool_name] = module_name
+
+        except Exception as e:
+            logger.debug(f"Error scanning {tool_file}: {e}")
+
+    logger.debug(f"Built dynamic tool map with {len(tool_map)} tools")
+    return tool_map
+
+
+# Build the tool map dynamically at module load time
+# Falls back to manifest if dynamic discovery fails
+TOOL_MODULE_MAP: Dict[str, str] = _build_tool_module_map()
+
+
+class LazyToolLoader:
+    """Manages lazy/on-demand tool loading."""
+
+    def __init__(self, server, tool_decorator: Callable):
+        """Initialize the lazy tool loader.
+
+        Args:
+            server: FastMCP server instance
+            tool_decorator: The decorator function to register tools
+        """
+        self.server = server
+        self.tool_decorator = tool_decorator
+        self.loaded_modules: Set[str] = set()
+        self.loaded_tools: Set[str] = set()
+        self._loading = False
+
+        logger.info("Lazy tool loader initialized")
+
+    def is_loaded(self, tool_name: str) -> bool:
+        """Check if a tool is already loaded."""
+        return tool_name in self.loaded_tools
+
+    async def load_tool(self, tool_name: str) -> bool:
+        """Load a tool on-demand.
+
+        Args:
+            tool_name: Name of the tool to load
+
+        Returns:
+            True if tool was loaded successfully, False otherwise
+        """
+        # Avoid recursive loading
+        if self._loading:
+            return False
+
+        if self.is_loaded(tool_name):
+            logger.debug(f"Tool '{tool_name}' already loaded")
+            return True
+
+        module_path = TOOL_MODULE_MAP.get(tool_name)
+        if not module_path:
+            logger.warning(f"No module mapping found for tool '{tool_name}'")
+            return False
+
+        try:
+            self._loading = True
+            logger.info(f"🔄 Lazy-loading tool '{tool_name}' from '{module_path}'")
+
+            # Import the module (this will trigger @server.tool decorators)
+            if module_path not in self.loaded_modules:
+                importlib.import_module(module_path)
+                self.loaded_modules.add(module_path)
+
+            # Mark tool as loaded
+            self.loaded_tools.add(tool_name)
+
+            logger.info(f"✅ Tool '{tool_name}' loaded successfully")
+            return True
+
+        except Exception as e:
+            logger.error(f"Failed to load tool '{tool_name}': {e}", exc_info=True)
+            return False
+        finally:
+            self._loading = False
+
+    async def intercept_call_tool(self, original_call_tool: Callable, name: str, arguments: dict) -> Any:
+        """Intercept tool calls to load tools on-demand.
+
+        Args:
+            original_call_tool: Original call_tool method
+            name: Tool name
+            arguments: Tool arguments
+
+        Returns:
+            Result from the tool execution
+        """
+        # Try to load the tool if not already loaded
+        if not self.is_loaded(name) and name in TOOL_MODULE_MAP:
+            loaded = await self.load_tool(name)
+            if not loaded:
+                raise ValueError(f"Failed to load tool '{name}'")
+
+        # Call the original method
+        return await original_call_tool(name, arguments)
+
+
+def setup_lazy_loading(server, tool_decorator: Callable) -> LazyToolLoader:
+    """Setup lazy tool loading by intercepting call_tool.
+
+    Args:
+        server: FastMCP server instance
+        tool_decorator: The decorator function to register tools
+
+    Returns:
+        LazyToolLoader instance
+    """
+    loader = LazyToolLoader(server, tool_decorator)
+
+    # Intercept call_tool to load tools on-demand
+    original_call_tool = server.call_tool
+
+    @wraps(original_call_tool)
+    async def lazy_call_tool(name: str, arguments: dict):
+        return await loader.intercept_call_tool(original_call_tool, name, arguments)
+
+    server.call_tool = lazy_call_tool
+
+    logger.info("✨ Lazy tool loading enabled - tools will be loaded on first use")
+
+    return loader

{unifi_network_mcp-0.4.1 → unifi_network_mcp-0.5.0}/src/utils/permissions.py

@@ -35,6 +35,7 @@ CATEGORY_MAP = {
     "voucher": "vouchers",
     "usergroup": "usergroups",
     "route": "routes",
+    "snmp": "snmp",
 }
 
 DEFAULT_PERMISSIONS_KEY = "default"

unifi_network_mcp-0.4.1/src/tools/system.py

@@ -1,76 +0,0 @@
-"""
-Unifi Network MCP system tools.
-
-This module provides MCP tools to interact with a Unifi Network Controller's system functions.
-"""
-
-import logging
-from typing import Any, Dict
-
-from src.runtime import server, system_manager
-
-logger = logging.getLogger(__name__)
-
-# Explicitly retrieve and log the server instance to confirm it's being used
-logger.info(f"System tools module loaded, server instance: {server}")
-
-
-@server.tool(
-    name="unifi_get_system_info",
-    description="Get general system information from the Unifi Network controller (version, uptime, etc).",
-)
-async def get_system_info() -> Dict[str, Any]:
-    """Implementation for getting system info."""
-    logger.info("unifi_get_system_info tool called")
-    try:
-        info = await system_manager.get_system_info()
-        return {
-            "success": True,
-            "site": system_manager._connection.site,
-            "system_info": info,
-        }
-    except Exception as e:
-        logger.error(f"Error getting system info: {e}", exc_info=True)
-        return {"success": False, "error": str(e)}
-
-
-@server.tool(
-    name="unifi_get_network_health",
-    description="Get the current network health summary (WAN status, device counts).",
-)
-async def get_network_health() -> Dict[str, Any]:
-    """Implementation for getting network health."""
-    logger.info("unifi_get_network_health tool called")
-    try:
-        health = await system_manager.get_network_health()
-        return {
-            "success": True,
-            "site": system_manager._connection.site,
-            "health_summary": health,
-        }
-    except Exception as e:
-        logger.error(f"Error getting network health: {e}", exc_info=True)
-        return {"success": False, "error": str(e)}
-
-
-@server.tool(
-    name="unifi_get_site_settings",
-    description="Get current site settings (e.g., country code, timezone, connectivity monitoring).",
-)
-async def get_site_settings() -> Dict[str, Any]:
-    """Implementation for getting site settings."""
-    logger.info("unifi_get_site_settings tool called")
-    try:
-        settings = await system_manager.get_site_settings()
-        return {
-            "success": True,
-            "site": system_manager._connection.site,
-            "site_settings": settings,
-        }
-    except Exception as e:
-        logger.error(f"Error getting site settings: {e}", exc_info=True)
-        return {"success": False, "error": str(e)}
-
-
-# Print confirmation that all tools have been registered
-logger.info("System tools registered: unifi_get_system_info, unifi_get_network_health, unifi_get_site_settings")

unifi_network_mcp-0.4.1/src/utils/lazy_tool_loader.py

@@ -1,300 +0,0 @@
-"""Lazy tool loader for on-demand tool registration.
-
-This module implements true lazy loading of tools, registering them only
-when first called by an LLM. This dramatically reduces initial context usage.
-"""
-
-import importlib
-import logging
-from functools import wraps
-from pathlib import Path
-from typing import Any, Callable, Dict, Set
-
-logger = logging.getLogger("unifi-network-mcp")
-
-
-def _build_tool_module_map() -> Dict[str, str]:
-    """Build tool-to-module mapping by scanning tool files.
-
-    This dynamically discovers all tools and their modules, eliminating the need
-    for a manually-maintained static mapping that can get out of sync.
-    """
-    tool_map: Dict[str, str] = {}
-
-    # Find the tools directory
-    # Try relative to this file first, then fall back to cwd
-    this_dir = Path(__file__).parent
-    tools_dir = this_dir.parent / "tools"
-
-    if not tools_dir.exists():
-        tools_dir = Path("src/tools")
-
-    if not tools_dir.exists():
-        logger.warning("Tools directory not found, falling back to static map")
-        return _STATIC_TOOL_MODULE_MAP
-
-    # Scan each .py file in tools directory
-    for tool_file in tools_dir.glob("*.py"):
-        if tool_file.name.startswith("_"):
-            continue
-
-        module_name = f"src.tools.{tool_file.stem}"
-
-        try:
-            # Read file and look for @server.tool or @permissioned_tool decorators
-            content = tool_file.read_text()
-
-            # Find tool names using simple pattern matching
-            # Looking for: name="unifi_xxx" or name='unifi_xxx'
-            import re
-
-            pattern = r'name\s*=\s*["\']([unifi_][a-z_]+)["\']'
-            matches = re.findall(pattern, content)
-
-            for tool_name in matches:
-                if tool_name.startswith("unifi_"):
-                    tool_map[tool_name] = module_name
-
-        except Exception as e:
-            logger.debug(f"Error scanning {tool_file}: {e}")
-
-    logger.debug(f"Built dynamic tool map with {len(tool_map)} tools")
-    return tool_map
-
-
-# Static fallback map (used if dynamic discovery fails)
-_STATIC_TOOL_MODULE_MAP: Dict[str, str] = {
-    # Client tools
-    "unifi_list_clients": "src.tools.clients",
-    "unifi_get_client_details": "src.tools.clients",
-    "unifi_list_blocked_clients": "src.tools.clients",
-    "unifi_block_client": "src.tools.clients",
-    "unifi_unblock_client": "src.tools.clients",
-    "unifi_rename_client": "src.tools.clients",
-    "unifi_force_reconnect_client": "src.tools.clients",
-    "unifi_authorize_guest": "src.tools.clients",
-    "unifi_unauthorize_guest": "src.tools.clients",
-    "unifi_set_client_ip_settings": "src.tools.clients",
-    # Device tools
-    "unifi_list_devices": "src.tools.devices",
-    "unifi_get_device_details": "src.tools.devices",
-    "unifi_reboot_device": "src.tools.devices",
-    "unifi_locate_device": "src.tools.devices",
-    "unifi_adopt_device": "src.tools.devices",
-    "unifi_upgrade_device": "src.tools.devices",
-    "unifi_set_device_name": "src.tools.devices",
-    "unifi_power_cycle_port": "src.tools.devices",
-    "unifi_set_port_profile": "src.tools.devices",
-    # Network tools
-    "unifi_list_networks": "src.tools.networks",
-    "unifi_get_network_details": "src.tools.networks",
-    "unifi_create_network": "src.tools.networks",
-    "unifi_update_network": "src.tools.networks",
-    "unifi_delete_network": "src.tools.networks",
-    # Firewall tools
-    "unifi_list_firewall_rules": "src.tools.firewall",
-    "unifi_get_firewall_rule": "src.tools.firewall",
-    "unifi_create_firewall_rule": "src.tools.firewall",
-    "unifi_update_firewall_rule": "src.tools.firewall",
-    "unifi_delete_firewall_rule": "src.tools.firewall",
-    "unifi_enable_firewall_rule": "src.tools.firewall",
-    "unifi_disable_firewall_rule": "src.tools.firewall",
-    "unifi_list_firewall_groups": "src.tools.firewall",
-    "unifi_create_firewall_group": "src.tools.firewall",
-    "unifi_update_firewall_group": "src.tools.firewall",
-    "unifi_delete_firewall_group": "src.tools.firewall",
-    # VPN tools
-    "unifi_list_vpn_servers": "src.tools.vpn",
-    "unifi_get_vpn_server_details": "src.tools.vpn",
-    "unifi_update_vpn_server_state": "src.tools.vpn",
-    "unifi_list_vpn_clients": "src.tools.vpn",
-    "unifi_get_vpn_client_details": "src.tools.vpn",
-    "unifi_update_vpn_client_state": "src.tools.vpn",
-    # QoS tools
-    "unifi_list_qos_rules": "src.tools.qos",
-    "unifi_get_qos_rule_details": "src.tools.qos",
-    "unifi_create_qos_rule": "src.tools.qos",
-    "unifi_create_simple_qos_rule": "src.tools.qos",
-    "unifi_update_qos_rule": "src.tools.qos",
-    "unifi_delete_qos_rule": "src.tools.qos",
-    "unifi_toggle_qos_rule_enabled": "src.tools.qos",
-    # Statistics tools
-    "unifi_get_client_stats": "src.tools.stats",
-    "unifi_get_device_stats": "src.tools.stats",
-    "unifi_get_network_stats": "src.tools.stats",
-    "unifi_get_wireless_stats": "src.tools.stats",
-    "unifi_get_system_stats": "src.tools.stats",
-    "unifi_get_top_clients": "src.tools.stats",
-    "unifi_get_dpi_stats": "src.tools.stats",
-    "unifi_get_alerts": "src.tools.stats",
-    # System tools
-    "unifi_get_system_info": "src.tools.system",
-    "unifi_get_network_health": "src.tools.system",
-    "unifi_get_site_settings": "src.tools.system",
-    # Event tools
-    "unifi_list_events": "src.tools.events",
-    "unifi_list_alarms": "src.tools.events",
-    "unifi_get_event_types": "src.tools.events",
-    "unifi_archive_alarm": "src.tools.events",
-    "unifi_archive_all_alarms": "src.tools.events",
-    # Hotspot/Voucher tools
-    "unifi_list_vouchers": "src.tools.hotspot",
-    "unifi_get_voucher_details": "src.tools.hotspot",
-    "unifi_create_voucher": "src.tools.hotspot",
-    "unifi_revoke_voucher": "src.tools.hotspot",
-    # User group tools
-    "unifi_list_usergroups": "src.tools.usergroups",
-    "unifi_get_usergroup_details": "src.tools.usergroups",
-    "unifi_create_usergroup": "src.tools.usergroups",
-    "unifi_update_usergroup": "src.tools.usergroups",
-    # Static Routing tools (V1 API)
-    "unifi_list_routes": "src.tools.routing",
-    "unifi_list_active_routes": "src.tools.routing",
-    "unifi_get_route_details": "src.tools.routing",
-    "unifi_create_route": "src.tools.routing",
-    "unifi_update_route": "src.tools.routing",
-    # Traffic Route tools (V2 API - policy-based routing)
-    "unifi_list_traffic_routes": "src.tools.traffic_routes",
-    "unifi_get_traffic_route_details": "src.tools.traffic_routes",
-    "unifi_update_traffic_route": "src.tools.traffic_routes",
-    "unifi_toggle_traffic_route": "src.tools.traffic_routes",
-    # Port Forward tools
-    "unifi_list_port_forwards": "src.tools.port_forwards",
-    "unifi_get_port_forward": "src.tools.port_forwards",
-    "unifi_create_port_forward": "src.tools.port_forwards",
-    "unifi_create_simple_port_forward": "src.tools.port_forwards",
-    "unifi_update_port_forward": "src.tools.port_forwards",
-    "unifi_toggle_port_forward": "src.tools.port_forwards",
-    # Firewall Policy tools (zone-based)
-    "unifi_list_firewall_policies": "src.tools.firewall",
-    "unifi_list_firewall_zones": "src.tools.firewall",
-    "unifi_list_ip_groups": "src.tools.firewall",
-    "unifi_get_firewall_policy_details": "src.tools.firewall",
-    "unifi_create_firewall_policy": "src.tools.firewall",
-    "unifi_create_simple_firewall_policy": "src.tools.firewall",
-    "unifi_update_firewall_policy": "src.tools.firewall",
-    "unifi_toggle_firewall_policy": "src.tools.firewall",
-    # WLAN tools
-    "unifi_list_wlans": "src.tools.network",
-    "unifi_get_wlan_details": "src.tools.network",
-    "unifi_create_wlan": "src.tools.network",
-    "unifi_update_wlan": "src.tools.network",
-    # Device tools (additional)
-    "unifi_rename_device": "src.tools.devices",
-}
-
-# Build the tool map dynamically at module load time
-# Falls back to static map if dynamic discovery fails
-TOOL_MODULE_MAP: Dict[str, str] = _build_tool_module_map()
-
-
-class LazyToolLoader:
-    """Manages lazy/on-demand tool loading."""
-
-    def __init__(self, server, tool_decorator: Callable):
-        """Initialize the lazy tool loader.
-
-        Args:
-            server: FastMCP server instance
-            tool_decorator: The decorator function to register tools
-        """
-        self.server = server
-        self.tool_decorator = tool_decorator
-        self.loaded_modules: Set[str] = set()
-        self.loaded_tools: Set[str] = set()
-        self._loading = False
-
-        logger.info("Lazy tool loader initialized")
-
-    def is_loaded(self, tool_name: str) -> bool:
-        """Check if a tool is already loaded."""
-        return tool_name in self.loaded_tools
-
-    async def load_tool(self, tool_name: str) -> bool:
-        """Load a tool on-demand.
-
-        Args:
-            tool_name: Name of the tool to load
-
-        Returns:
-            True if tool was loaded successfully, False otherwise
-        """
-        # Avoid recursive loading
-        if self._loading:
-            return False
-
-        if self.is_loaded(tool_name):
-            logger.debug(f"Tool '{tool_name}' already loaded")
-            return True
-
-        module_path = TOOL_MODULE_MAP.get(tool_name)
-        if not module_path:
-            logger.warning(f"No module mapping found for tool '{tool_name}'")
-            return False
-
-        try:
-            self._loading = True
-            logger.info(f"🔄 Lazy-loading tool '{tool_name}' from '{module_path}'")
-
-            # Import the module (this will trigger @server.tool decorators)
-            if module_path not in self.loaded_modules:
-                importlib.import_module(module_path)
-                self.loaded_modules.add(module_path)
-
-            # Mark tool as loaded
-            self.loaded_tools.add(tool_name)
-
-            logger.info(f"✅ Tool '{tool_name}' loaded successfully")
-            return True
-
-        except Exception as e:
-            logger.error(f"Failed to load tool '{tool_name}': {e}", exc_info=True)
-            return False
-        finally:
-            self._loading = False
-
-    async def intercept_call_tool(self, original_call_tool: Callable, name: str, arguments: dict) -> Any:
-        """Intercept tool calls to load tools on-demand.
-
-        Args:
-            original_call_tool: Original call_tool method
-            name: Tool name
-            arguments: Tool arguments
-
-        Returns:
-            Result from the tool execution
-        """
-        # Try to load the tool if not already loaded
-        if not self.is_loaded(name) and name in TOOL_MODULE_MAP:
-            loaded = await self.load_tool(name)
-            if not loaded:
-                raise ValueError(f"Failed to load tool '{name}'")
-
-        # Call the original method
-        return await original_call_tool(name, arguments)
-
-
-def setup_lazy_loading(server, tool_decorator: Callable) -> LazyToolLoader:
-    """Setup lazy tool loading by intercepting call_tool.
-
-    Args:
-        server: FastMCP server instance
-        tool_decorator: The decorator function to register tools
-
-    Returns:
-        LazyToolLoader instance
-    """
-    loader = LazyToolLoader(server, tool_decorator)
-
-    # Intercept call_tool to load tools on-demand
-    original_call_tool = server.call_tool
-
-    @wraps(original_call_tool)
-    async def lazy_call_tool(name: str, arguments: dict):
-        return await loader.intercept_call_tool(original_call_tool, name, arguments)
-
-    server.call_tool = lazy_call_tool
-
-    logger.info("✨ Lazy tool loading enabled - tools will be loaded on first use")
-
-    return loader