unifi-network-mcp 0.2.0__tar.gz → 0.3.0__tar.gz

{unifi_network_mcp-0.2.0 → unifi_network_mcp-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unifi-network-mcp
-Version: 0.2.0
+Version: 0.3.0
 Summary: Unifi Network MCP Server
 License-File: LICENSE
 Requires-Python: >=3.13
@@ -62,6 +62,7 @@ A self-hosted [Model Context Protocol](https://github.com/modelcontextprotocol)
 
 * Full catalog of UniFi controller operations – firewall, traffic-routes, port-forwards, QoS, VPN, WLANs, stats, devices, clients **and more**.
 * All mutating tools require `confirm=true` so nothing can change your network by accident.
+* **Workflow automation friendly** – set `UNIFI_AUTO_CONFIRM=true` to skip confirmation prompts (ideal for n8n, Make, Zapier).
 * Works over **stdio** (FastMCP). Optional SSE HTTP endpoint can be enabled via config.
 * **Code execution mode** with tool index, async operations, and TypeScript examples.
 * One-liner launch via the console-script **`unifi-network-mcp`**.
@@ -520,6 +521,7 @@ The server merges settings from **environment variables**, an optional `.env` fi
 | `UNIFI_VERIFY_SSL` | Set to `false` if using self-signed certs |
 | `UNIFI_CONTROLLER_TYPE` | Controller API path type: `auto` (detect), `proxy` (UniFi OS), `direct` (standalone). Default `auto` |
 | `UNIFI_MCP_HTTP_ENABLED` | Set `true` to enable optional HTTP SSE server (default `false`) |
+| `UNIFI_AUTO_CONFIRM` | Set `true` to auto-confirm all mutating operations (skips preview step). Ideal for workflow automation (n8n, Make, Zapier). Default `false` |
 
 ### Controller Type Detection
 

{unifi_network_mcp-0.2.0 → unifi_network_mcp-0.3.0}/README.md

@@ -46,6 +46,7 @@ A self-hosted [Model Context Protocol](https://github.com/modelcontextprotocol)
 
 * Full catalog of UniFi controller operations – firewall, traffic-routes, port-forwards, QoS, VPN, WLANs, stats, devices, clients **and more**.
 * All mutating tools require `confirm=true` so nothing can change your network by accident.
+* **Workflow automation friendly** – set `UNIFI_AUTO_CONFIRM=true` to skip confirmation prompts (ideal for n8n, Make, Zapier).
 * Works over **stdio** (FastMCP). Optional SSE HTTP endpoint can be enabled via config.
 * **Code execution mode** with tool index, async operations, and TypeScript examples.
 * One-liner launch via the console-script **`unifi-network-mcp`**.
@@ -504,6 +505,7 @@ The server merges settings from **environment variables**, an optional `.env` fi
 | `UNIFI_VERIFY_SSL` | Set to `false` if using self-signed certs |
 | `UNIFI_CONTROLLER_TYPE` | Controller API path type: `auto` (detect), `proxy` (UniFi OS), `direct` (standalone). Default `auto` |
 | `UNIFI_MCP_HTTP_ENABLED` | Set `true` to enable optional HTTP SSE server (default `false`) |
+| `UNIFI_AUTO_CONFIRM` | Set `true` to auto-confirm all mutating operations (skips preview step). Ideal for workflow automation (n8n, Make, Zapier). Default `false` |
 
 ### Controller Type Detection
 

{unifi_network_mcp-0.2.0 → unifi_network_mcp-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unifi-network-mcp"
-version = "0.2.0"
+version = "0.3.0"
 description = "Unifi Network MCP Server"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -58,3 +58,15 @@ dev-dependencies = [
 [project.scripts]
 # CLI entrypoint that launches the UniFi Network MCP server
 unifi-network-mcp = "src.main:main"
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+ignore = [
+    "E501",  # Line too long - handled by line-length setting above
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["src"]

{unifi_network_mcp-0.2.0 → unifi_network_mcp-0.3.0}/src/bootstrap.py

@@ -12,13 +12,13 @@ Importing it early guarantees deterministic side‑effects (env + logging) and
 exposes a `load_config()` helper that the rest of the codebase can share.
 """
 
-from dataclasses import dataclass
+import importlib.resources
 import logging
 import os
 import sys
+from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
-import importlib.resources
 
 from dotenv import load_dotenv
 from omegaconf import OmegaConf
@@ -118,32 +118,20 @@ def load_config(path_override: str | Path | None = None) -> OmegaConf:
         relative_path = Path("config/config.yaml")
         if relative_path.exists() and relative_path.is_file():
             resolved_path = relative_path
-            logger.info(
-                "Using configuration file from relative path: %s", relative_path
-            )
+            logger.info("Using configuration file from relative path: %s", relative_path)
         else:
             # 3. Use bundled default config
             try:
                 # Use importlib.resources to safely access package data
-                config_file_ref = importlib.resources.files("src.config").joinpath(
-                    "config.yaml"
-                )
+                config_file_ref = importlib.resources.files("src.config").joinpath("config.yaml")
                 if config_file_ref.is_file():
-                    resolved_path = Path(
-                        str(config_file_ref)
-                    )  # Convert Traversable to Path
-                    logger.info(
-                        "Using bundled default configuration: %s", resolved_path
-                    )
+                    resolved_path = Path(str(config_file_ref))  # Convert Traversable to Path
+                    logger.info("Using bundled default configuration: %s", resolved_path)
                 else:
-                    logger.error(
-                        "Bundled default configuration file could not be accessed (not a file)."
-                    )
+                    logger.error("Bundled default configuration file could not be accessed (not a file).")
                     raise SystemExit(3)  # Exit if bundled config isn't a file
             except (ModuleNotFoundError, FileNotFoundError, Exception) as e:
-                logger.error(
-                    "Could not find or access bundled default configuration: %s", e
-                )
+                logger.error("Could not find or access bundled default configuration: %s", e)
                 raise SystemExit(3)  # Exit if bundled config cannot be loaded
 
     if resolved_path is None:

{unifi_network_mcp-0.2.0 → unifi_network_mcp-0.3.0}/src/config/config.yaml

@@ -71,4 +71,20 @@ permissions:
 
   vpn_servers:
     create: false
-    update: true
+    update: true
+
+  events:
+    create: false  # Events are read-only
+    update: true   # Allow archiving alarms
+
+  vouchers:
+    create: true   # Allow creating guest vouchers
+    update: true   # Allow revoking vouchers
+
+  usergroups:
+    create: true   # Allow creating bandwidth profiles
+    update: true   # Allow modifying bandwidth limits
+
+  routes:
+    create: false  # Static routes can disrupt connectivity
+    update: false  # Modifying routes requires careful planning

{unifi_network_mcp-0.2.0 → unifi_network_mcp-0.3.0}/src/jobs.py

@@ -78,9 +78,7 @@ class JobStore:
                         self._jobs[job_id]["status"] = "error"
                         self._jobs[job_id]["error"] = str(e)
                         self._jobs[job_id]["completed"] = time.time()
-                logger.error(
-                    f"Background job {job_id} failed with error: {e}", exc_info=True
-                )
+                logger.error(f"Background job {job_id} failed with error: {e}", exc_info=True)
 
         # Launch the runner as a background task
         asyncio.create_task(_runner())

{unifi_network_mcp-0.2.0 → unifi_network_mcp-0.3.0}/src/main.py

@@ -9,29 +9,28 @@ Responsibilities:
 
 import asyncio
 import logging
-import traceback
-import sys  # Removed uvicorn import
 import os
+import sys  # Removed uvicorn import
+import traceback
 
 from src.bootstrap import (
-    logger,
     UNIFI_TOOL_REGISTRATION_MODE,
+    logger,
 )  # ensures logging/env setup early
+from src.jobs import get_job_status, start_async_tool
 
 # Shared singletons
 from src.runtime import (
-    server,
     config,
     connection_manager,
+    server,
 )
-
-from src.utils.tool_loader import auto_load_tools
-from src.utils.lazy_tool_loader import setup_lazy_loading
+from src.tool_index import register_tool, tool_index_handler
 from src.utils.diagnostics import diagnostics_enabled, wrap_tool
-from src.utils.permissions import parse_permission  # noqa: E402
+from src.utils.lazy_tool_loader import setup_lazy_loading
 from src.utils.meta_tools import register_meta_tools
-from src.tool_index import register_tool, tool_index_handler
-from src.jobs import start_async_tool, get_job_status
+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
 
@@ -39,11 +38,7 @@ _original_tool_decorator = server.tool  # keep reference to wrap later
 def permissioned_tool(*d_args, **d_kwargs):  # acts like @server.tool
     """Decorator that only registers the tool if permission allows."""
 
-    tool_name = (
-        d_kwargs.get("name")
-        if d_kwargs.get("name")
-        else (d_args[0] if d_args else None)
-    )
+    tool_name = d_kwargs.get("name") if d_kwargs.get("name") else (d_args[0] if d_args else None)
 
     category = d_kwargs.pop("permission_category", None)
     action = d_kwargs.pop("permission_action", None)
@@ -141,9 +136,7 @@ def permissioned_tool(*d_args, **d_kwargs):  # acts like @server.tool
         if allowed:
             # Permission granted - register with MCP server
             wrapped = (
-                wrap_tool(func, tool_name or getattr(func, "__name__", "<tool>"))
-                if diagnostics_enabled()
-                else func
+                wrap_tool(func, tool_name or getattr(func, "__name__", "<tool>")) if diagnostics_enabled() else func
             )
             return _original_tool_decorator(*d_args, **d_kwargs)(wrapped)
 
@@ -168,9 +161,7 @@ try:
 
     logger.info(f"MCP Python SDK version: {getattr(mcp, '__version__', 'unknown')}")
     logger.info(f"Server methods: {dir(server)}")
-    logger.info(
-        f"Server tool methods: {[m for m in dir(server) if 'tool' in m.lower()]}"
-    )
+    logger.info(f"Server tool methods: {[m for m in dir(server) if 'tool' in m.lower()]}")
 except Exception as e:
     logger.error(f"Error inspecting server: {e}")
 
@@ -194,9 +185,7 @@ async def main_async():
     try:
         from src.bootstrap import logger as bootstrap_logger_async
 
-        bootstrap_logger_async.critical(
-            "ASYNCHRONOUS main_async() FUNCTION ENTERED - TEST MESSAGE"
-        )
+        bootstrap_logger_async.critical("ASYNCHRONOUS main_async() FUNCTION ENTERED - TEST MESSAGE")
     except Exception as e:
         print(f"Logging in main_async() failed: {e}", file=sys.stderr)  # Fallback
     # ---- END VERY EARLY ASYNC LOG TEST ----
@@ -220,9 +209,7 @@ async def main_async():
                     context["exception"].__traceback__,
                 )
             )
-            logger.error(
-                f"Original traceback for global asyncio exception:\n{orig_traceback}"
-            )
+            logger.error(f"Original traceback for global asyncio exception:\n{orig_traceback}")
 
     loop.set_exception_handler(handle_asyncio_exception)
     logger.info("Global asyncio exception handler set.")
@@ -232,17 +219,13 @@ async def main_async():
     log_level = config.server.get("log_level", "INFO").upper()
     # Ensure logging is configured (might be redundant if already set by bootstrap)
     # but this ensures the level is applied if changed post-bootstrap.
-    logging.basicConfig(
-        level=getattr(logging, log_level, logging.INFO), force=True
-    )  # Use default format
+    logging.basicConfig(level=getattr(logging, log_level, logging.INFO), force=True)  # Use default format
     logger.info(f"Log level set to {log_level} in main_async.")
 
     # Initialize the global Unifi connection
     logger.info("Initializing global Unifi connection from main_async...")
     if not await connection_manager.initialize():
-        logger.error(
-            "Failed to connect to Unifi Controller from main_async. Tool functionality may be impaired."
-        )
+        logger.error("Failed to connect to Unifi Controller from main_async. Tool functionality may be impaired.")
     else:
         logger.info("Global Unifi connection initialized successfully from main_async.")
 
@@ -276,9 +259,7 @@ async def main_async():
         # They'll be registered on first use
         from src.utils.lazy_tool_loader import TOOL_MODULE_MAP
 
-        logger.info(
-            f"   Lazy loader ready - {len(TOOL_MODULE_MAP)} tools available on-demand"
-        )
+        logger.info(f"   Lazy loader ready - {len(TOOL_MODULE_MAP)} tools available on-demand")
     else:  # eager (default)
         logger.info("📚 Tool registration mode: eager")
         logger.info("   All 64+ UniFi tools registered immediately")
@@ -324,9 +305,7 @@ async def main_async():
                 server.settings.host = host
                 server.settings.port = port
                 await server.run_sse_async()
-                logger.info(
-                    "HTTP SSE started via run_sse_async() using server.settings host/port."
-                )
+                logger.info("HTTP SSE started via run_sse_async() using server.settings host/port.")
             except Exception as http_e:
                 logger.error(f"HTTP SSE server failed to start: {http_e}")
                 logger.error(traceback.format_exc())
@@ -353,17 +332,13 @@ def main():
         print(f"Logging in main() failed: {e}", file=sys.stderr)  # Fallback
     # ---- END VERY EARLY LOG TEST ----
 
-    logger.debug(
-        "Starting main()"
-    )  # This uses the logger from bootstrap via global scope
+    logger.debug("Starting main()")  # This uses the logger from bootstrap via global scope
     try:
         asyncio.run(main_async())
     except KeyboardInterrupt:
         logger.info("Server stopped by user (KeyboardInterrupt).")
     except Exception as e:
-        logger.exception(
-            "Unhandled exception during server run (from asyncio.run): %s", e
-        )
+        logger.exception("Unhandled exception during server run (from asyncio.run): %s", e)
     finally:
         logger.info("Server process exiting.")
 

{unifi_network_mcp-0.2.0 → unifi_network_mcp-0.3.0}/src/managers/client_manager.py

@@ -3,6 +3,7 @@ from typing import List, Optional
 
 from aiounifi.models.api import ApiRequest
 from aiounifi.models.client import Client
+
 from .connection_manager import ConnectionManager
 
 logger = logging.getLogger("unifi-network-mcp")
@@ -23,10 +24,7 @@ class ClientManager:
 
     async def get_clients(self) -> List[Client]:
         """Get list of currently online clients for the current site."""
-        if (
-            not await self._connection.ensure_connected()
-            or not self._connection.controller
-        ):
+        if not await self._connection.ensure_connected() or not self._connection.controller:
             return []
 
         cache_key = f"{CACHE_PREFIX_CLIENTS}_online_{self._connection.site}"
@@ -45,9 +43,7 @@ class ClientManager:
             #   Therefore for "online" we fallback to GET /stat/sta.
             if not clients:
                 try:
-                    raw_clients = await self._connection.request(
-                        ApiRequest(method="get", path="/stat/sta")
-                    )
+                    raw_clients = await self._connection.request(ApiRequest(method="get", path="/stat/sta"))
                     if isinstance(raw_clients, list) and raw_clients:
                         # Cache raw dicts; tool layer handles dict or Client
                         self._connection._update_cache(cache_key, raw_clients)
@@ -62,10 +58,7 @@ class ClientManager:
 
     async def get_all_clients(self) -> List[Client]:
         """Get list of all clients (including offline/historical) for the current site."""
-        if (
-            not await self._connection.ensure_connected()
-            or not self._connection.controller
-        ):
+        if not await self._connection.ensure_connected() or not self._connection.controller:
             return []
 
         cache_key = f"{CACHE_PREFIX_CLIENTS}_all_{self._connection.site}"
@@ -75,9 +68,7 @@ class ClientManager:
 
         try:
             await self._connection.controller.clients_all.update()
-            all_clients: List[Client] = list(
-                self._connection.controller.clients_all.values()
-            )
+            all_clients: List[Client] = list(self._connection.controller.clients_all.values())
             # Fallback rationale:
             # - When the clients_all collection is empty, query the canonical
             #   UniFi endpoint for all/historical client records.
@@ -86,9 +77,7 @@ class ClientManager:
             #   connected. This complements GET /stat/sta used for online-only.
             if not all_clients:
                 try:
-                    raw_all = await self._connection.request(
-                        ApiRequest(method="get", path="/rest/user")
-                    )
+                    raw_all = await self._connection.request(ApiRequest(method="get", path="/rest/user"))
                     if isinstance(raw_all, list) and raw_all:
                         self._connection._update_cache(cache_key, raw_all)
                         return raw_all  # type: ignore[return-value]
@@ -103,13 +92,9 @@ class ClientManager:
     async def get_client_details(self, client_mac: str) -> Optional[Client]:
         """Get detailed information for a specific client by MAC address."""
         all_clients = await self.get_all_clients()
-        client: Optional[Client] = next(
-            (c for c in all_clients if c.mac == client_mac), None
-        )
+        client: Optional[Client] = next((c for c in all_clients if c.mac == client_mac), None)
         if not client:
-            logger.debug(
-                f"Client details for MAC {client_mac} not found in clients_all list."
-            )
+            logger.debug(f"Client details for MAC {client_mac} not found in clients_all list.")
         return client
 
     async def block_client(self, client_mac: str) -> bool:
@@ -119,14 +104,12 @@ class ClientManager:
             api_request = ApiRequest(
                 method="post",
                 path="/cmd/stamgr",
-                json={"mac": client_mac, "cmd": "block-sta"},
+                data={"mac": client_mac, "cmd": "block-sta"},
             )
             # Call the updated request method
             await self._connection.request(api_request)
             logger.info(f"Block command sent for client {client_mac}")
-            self._connection._invalidate_cache(
-                f"{CACHE_PREFIX_CLIENTS}"
-            )  # Invalidate all client caches
+            self._connection._invalidate_cache(f"{CACHE_PREFIX_CLIENTS}")  # Invalidate all client caches
             return True
         except Exception as e:
             logger.error(f"Error blocking client {client_mac}: {e}")
@@ -139,7 +122,7 @@ class ClientManager:
             api_request = ApiRequest(
                 method="post",
                 path="/cmd/stamgr",
-                json={"mac": client_mac, "cmd": "unblock-sta"},
+                data={"mac": client_mac, "cmd": "unblock-sta"},
             )
             # Call the updated request method
             await self._connection.request(api_request)
@@ -155,15 +138,11 @@ class ClientManager:
         try:
             client = await self.get_client_details(client_mac)
             if not client or "_id" not in client.raw:
-                logger.error(
-                    f"Cannot rename client {client_mac}: Not found or missing ID."
-                )
+                logger.error(f"Cannot rename client {client_mac}: Not found or missing ID.")
                 return False
             client_id = client.raw["_id"]
 
-            api_request = ApiRequest(
-                method="put", path=f"/upd/user/{client_id}", json={"name": name}
-            )
+            api_request = ApiRequest(method="put", path=f"/upd/user/{client_id}", data={"name": name})
             await self._connection.request(api_request)
             logger.info(f"Rename command sent for client {client_mac} to '{name}'")
             self._connection._invalidate_cache(f"{CACHE_PREFIX_CLIENTS}")
@@ -178,7 +157,7 @@ class ClientManager:
             api_request = ApiRequest(
                 method="post",
                 path="/cmd/stamgr",
-                json={"mac": client_mac, "cmd": "kick-sta"},
+                data={"mac": client_mac, "cmd": "kick-sta"},
             )
             await self._connection.request(api_request)
             logger.info(f"Force reconnect (kick) command sent for client {client_mac}")
@@ -213,12 +192,10 @@ class ClientManager:
                 payload["bytes"] = bytes_quota
 
             # Construct ApiRequest
-            api_request = ApiRequest(method="post", path="/cmd/stamgr", json=payload)
+            api_request = ApiRequest(method="post", path="/cmd/stamgr", data=payload)
             # Call the updated request method
             await self._connection.request(api_request)
-            logger.info(
-                f"Authorize command sent for guest {client_mac} for {minutes} minutes"
-            )
+            logger.info(f"Authorize command sent for guest {client_mac} for {minutes} minutes")
             self._connection._invalidate_cache(f"{CACHE_PREFIX_CLIENTS}")
             return True
         except Exception as e:
@@ -231,7 +208,7 @@ class ClientManager:
             api_request = ApiRequest(
                 method="post",
                 path="/cmd/stamgr",
-                json={"mac": client_mac, "cmd": "unauthorize-guest"},
+                data={"mac": client_mac, "cmd": "unauthorize-guest"},
             )
             await self._connection.request(api_request)
             logger.info(f"Unauthorize command sent for guest {client_mac}")
@@ -240,3 +217,98 @@ class ClientManager:
         except Exception as e:
             logger.error(f"Error unauthorizing guest {client_mac}: {e}")
             return False
+
+    async def set_client_ip_settings(
+        self,
+        client_mac: str,
+        use_fixedip: Optional[bool] = None,
+        fixed_ip: Optional[str] = None,
+        local_dns_record_enabled: Optional[bool] = None,
+        local_dns_record: Optional[str] = None,
+    ) -> bool:
+        """Set fixed IP and/or local DNS record for a client.
+
+        Uses the UniFi REST API endpoint PUT /rest/user/{client_id}.
+        Local DNS records require UniFi Network 7.2+.
+
+        Args:
+            client_mac: MAC address of the client to update.
+            use_fixedip: Enable (True) or disable (False) fixed IP.
+            fixed_ip: The fixed IP address to assign (required if use_fixedip=True).
+            local_dns_record_enabled: Enable (True) or disable (False) local DNS.
+            local_dns_record: The DNS hostname to assign (e.g., "mydevice.local").
+
+        Returns:
+            True if the update was successful, False otherwise.
+        """
+        try:
+            # Get client to find their internal _id
+            client = await self.get_client_details(client_mac)
+            if not client:
+                logger.error(f"Cannot set IP settings for {client_mac}: Client not found")
+                return False
+
+            client_raw = client.raw if hasattr(client, "raw") else client
+            if "_id" not in client_raw:
+                logger.error(f"Cannot set IP settings for {client_mac}: Missing _id")
+                return False
+
+            client_id = client_raw["_id"]
+
+            # If client is not "noted" (known), mark it first to enable IP config
+            if not client_raw.get("noted"):
+                logger.info(f"Client {client_mac} not noted, marking as known first")
+                note_payload = {"noted": True}
+                if not client_raw.get("name") and client_raw.get("hostname"):
+                    note_payload["name"] = client_raw["hostname"]
+                try:
+                    note_request = ApiRequest(
+                        method="put",
+                        path=f"/rest/user/{client_id}",
+                        data=note_payload,
+                    )
+                    await self._connection.request(note_request)
+                except Exception as note_err:
+                    logger.warning(f"Could not mark client as noted: {note_err}")
+
+            # Build payload with only explicitly provided fields
+            payload: dict = {}
+
+            if use_fixedip is not None:
+                payload["use_fixedip"] = use_fixedip
+                if use_fixedip and fixed_ip:
+                    payload["fixed_ip"] = fixed_ip
+                elif not use_fixedip:
+                    payload["fixed_ip"] = ""
+            elif fixed_ip is not None:
+                # If only fixed_ip provided, assume enabling
+                payload["use_fixedip"] = True
+                payload["fixed_ip"] = fixed_ip
+
+            if local_dns_record_enabled is not None:
+                payload["local_dns_record_enabled"] = local_dns_record_enabled
+                if local_dns_record_enabled and local_dns_record:
+                    payload["local_dns_record"] = local_dns_record
+                elif not local_dns_record_enabled:
+                    payload["local_dns_record"] = ""
+            elif local_dns_record is not None:
+                # If only local_dns_record provided, assume enabling
+                payload["local_dns_record_enabled"] = True
+                payload["local_dns_record"] = local_dns_record
+
+            if not payload:
+                logger.warning(f"No IP settings provided for {client_mac}")
+                return False
+
+            api_request = ApiRequest(
+                method="put",
+                path=f"/rest/user/{client_id}",
+                data=payload,
+            )
+            await self._connection.request(api_request)
+            logger.info(f"IP settings updated for client {client_mac}: {payload}")
+            self._connection._invalidate_cache(f"{CACHE_PREFIX_CLIENTS}")
+            return True
+        except Exception as e:
+            logger.error(f"Error setting IP settings for {client_mac}: {e}")
+            return False