suprema-biostar-mcp 1.0.1__py3-none-any.whl

biostar_x_mcp_server/handlers/access_handler.py

@@ -0,0 +1,2162 @@
+import logging
+import json
+import asyncio
+from typing import Sequence, Dict, Any, List, Optional, Tuple, Set
+from mcp.types import TextContent
+import httpx
+from .base_handler import BaseHandler
+
+logger = logging.getLogger(__name__)
+
+
+class AccessHandler(BaseHandler):
+    """Handle access control operations."""
+
+    # ----------------------------------------------------------------------
+    # Access Group methods
+    # ----------------------------------------------------------------------
+    async def get_access_groups(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Get list of access groups."""
+        try:
+            self.check_auth()
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.get(
+                    f"{self.session.config.biostar_url}/api/access_groups",
+                    headers=headers
+                )
+            if response.status_code != 200:
+                return self.error_response(f"API call failed: {response.status_code} - {response.text}")
+            data = response.json()
+            groups = data.get("AccessGroupCollection", {}).get("rows", []) or []
+            return self.success_response({
+                "message": f"Found {len(groups)} access groups",
+                "total": len(groups),
+                "groups": [self.format_access_group_info(group) for group in groups]
+            })
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def get_access_group(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Get specific access group details."""
+        try:
+            self.check_auth()
+            group_id = args["group_id"]
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.get(
+                    f"{self.session.config.biostar_url}/api/access_groups/{group_id}",
+                    headers=headers
+                )
+            if response.status_code != 200:
+                return self.error_response(f"API call failed: {response.status_code} - {response.text}")
+            data = response.json()
+            group = data.get("AccessGroup", {}) or {}
+            return self.success_response({
+                "group": self.format_access_group_info(group)
+            })
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def create_access_group(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Create a new access group.
+
+        API spec alignment:
+        - POST /api/access_groups (NO trailing slash)
+        - Body:
+          {
+            "AccessGroup": {
+              "name": "str",                        # required
+              "description": "str",                 # optional
+              "users": [ {"user_id": "1"}, ... ],   # optional
+              "user_groups": [ {"id": 1106, "name": "ACE Group"}, ... ], # optional
+              "access_levels": [ {"id": "2"}, ... ] # optional
+            }
+          }
+
+        Business rules:
+        - Floor levels are ignored with a warning.
+        - User groups:
+          * If 'user_group_ids' are provided → validate against GET /api/user_groups (flattened).
+          * Else if 'user_group_search_text' is provided → 3-case:
+              (0) no match → return full list with needs_selection=true
+              (1) single   → proceed with that group
+              (>=2) multi  → return candidates with needs_selection=true
+          * If neither is provided → do not include user_groups.
+        - Do NOT auto-select anything else.
+        """
+        try:
+            self.check_auth()
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            name: str = args["name"]
+            description: str = (args.get("description") or "").strip()
+
+            # Optional inputs
+            raw_user_ids = args.get("user_ids") or []
+            
+            #  CRITICAL: Ensure access_level_ids is always a list
+            raw_access_level_ids_input = args.get("access_level_ids")
+            if raw_access_level_ids_input is None:
+                raw_access_level_ids = []
+            elif isinstance(raw_access_level_ids_input, list):
+                raw_access_level_ids = raw_access_level_ids_input
+            else:
+                # Single value (int or string) → convert to list
+                raw_access_level_ids = [raw_access_level_ids_input]
+
+            # User group inputs (NEW)
+            #  CRITICAL: Ensure user_group_ids is always a list
+            raw_user_group_ids_input = args.get("user_group_ids")
+            if raw_user_group_ids_input is None:
+                raw_user_group_ids = []
+            elif isinstance(raw_user_group_ids_input, list):
+                raw_user_group_ids = raw_user_group_ids_input
+            else:
+                # Single value (int or string) → convert to list
+                raw_user_group_ids = [raw_user_group_ids_input]
+            
+            user_group_search_text = (args.get("user_group_search_text") or args.get("user_group_name") or "").strip()
+
+            # Disallowed inputs (ignored with warning)
+            ignored_fields: List[str] = []
+            for forbidden in ["floor_levels", "parent_id"]:
+                if forbidden in args and args[forbidden]:
+                    ignored_fields.append(forbidden)
+
+            # Build payload
+            ag_body: Dict[str, Any] = {"name": name, "description": description}
+
+            if raw_user_ids:
+                ag_body["users"] = [{"user_id": str(uid)} for uid in raw_user_ids if str(uid).strip()]
+
+            if raw_access_level_ids:
+                #  CRITICAL: Access levels MUST include both 'id' and 'name'
+                # First, fetch all access levels to get the name mapping
+                async with httpx.AsyncClient(verify=False) as client:
+                    al_resp = await client.get(
+                        f"{self.session.config.biostar_url}/api/access_levels?limit=9999&order_by=id:false",
+                        headers=headers
+                    )
+                
+                al_id_to_name = {}
+                if al_resp.status_code == 200:
+                    al_data = al_resp.json() or {}
+                    al_rows = al_data.get("AccessLevelCollection", {}).get("rows", []) or []
+                    for al in al_rows:
+                        al_id = al.get("id")
+                        if al_id is not None:
+                            al_id_to_name[str(al_id)] = al.get("name", "")
+                    logger.info(f" Loaded {len(al_id_to_name)} Access Levels for validation: {list(al_id_to_name.keys())}")
+                else:
+                    logger.error(f" Failed to load Access Levels: {al_resp.status_code} - {al_resp.text[:200]}")
+                
+                # Validate and build access_levels with both id and name
+                logger.info(f" Validating access_level_ids: {raw_access_level_ids}")
+                access_levels_payload = []
+                invalid_al_ids = []
+                for alid in raw_access_level_ids:
+                    alid_str = str(alid).strip()
+                    if not alid_str:
+                        continue
+                    if alid_str not in al_id_to_name:
+                        invalid_al_ids.append(alid)
+                    else:
+                        access_levels_payload.append({
+                            "id": alid_str,
+                            "name": al_id_to_name[alid_str]
+                        })
+                
+                if invalid_al_ids:
+                    logger.error(f" Access Level validation failed! Invalid IDs: {invalid_al_ids}, Available: {list(al_id_to_name.keys())}")
+                    return self.error_response(
+                        "Invalid access_level_ids provided.",
+                        {
+                            "status": "access_level_validation_failed",
+                            "invalid_access_level_ids": invalid_al_ids,
+                            "available_access_levels": [{"id": al_id, "name": al_name} for al_id, al_name in al_id_to_name.items()]
+                        }
+                    )
+                
+                ag_body["access_levels"] = access_levels_payload
+
+            # Resolve user_groups
+            user_groups_payload: List[Dict[str, Any]] = []
+            if raw_user_group_ids:
+                ug_all = await self._list_all_user_groups(headers)
+                id_to_name = {
+                    str(int(str(g["id"]).strip())): (g.get("name") or "")
+                    for g in ug_all if g.get("id") is not None
+                }
+                invalid_ids: List[Any] = []
+                for gid in raw_user_group_ids:
+                    try:
+                        key = str(int(str(gid).strip()))
+                        if key in id_to_name:
+                            user_groups_payload.append({"id": int(key), "name": id_to_name[key]})
+                        else:
+                            invalid_ids.append(int(key))
+                    except Exception:
+                        invalid_ids.append(gid)
+
+                if invalid_ids:
+                    return self.error_response(
+                        "Invalid user_group_ids provided.",
+                        {
+                            "status": "user_group_validation_failed",
+                            "invalid_user_group_ids": invalid_ids,
+                            "available_user_groups": [
+                                {"id": int(str(g["id"]).strip()), "name": g.get("name")}
+                                for g in ug_all if g.get("id") is not None
+                            ]
+                        }
+                    )
+
+            elif user_group_search_text:
+                ug_all = await self._list_all_user_groups(headers)
+                if not ug_all:
+                    return self.error_response(
+                        "Failed to list user groups (empty or API error).",
+                        {"status": "user_group_list_failed"}
+                    )
+
+                matches = self._filter_user_groups_by_name(ug_all, user_group_search_text)
+
+                if len(matches) == 0:
+                    return self.success_response({
+                        "message": "No user group matched the query. Here is the full user group list. Please pick one.",
+                        "status": "user_group_not_found",
+                        "needs_selection": True,
+                        "user_groups": [
+                            {"id": int(str(g["id"]).strip()), "name": g.get("name")}
+                            for g in ug_all if g.get("id") is not None
+                        ]
+                    })
+
+                if len(matches) > 1:
+                    return self.success_response({
+                        "message": "Multiple user groups matched. Please pick one or more.",
+                        "status": "ambiguous_user_group",
+                        "needs_selection": True,
+                        "candidates": [
+                            {"id": int(str(g["id"]).strip()), "name": g.get("name")}
+                            for g in matches if g.get("id") is not None
+                        ]
+                    })
+
+                # exactly one match
+                mg = matches[0]
+                if mg.get("id") is not None:
+                    user_groups_payload.append({"id": int(str(mg["id"]).strip()), "name": mg.get("name")})
+
+            if user_groups_payload:
+                ag_body["user_groups"] = user_groups_payload
+
+            #  NEW: Add sync_hint for user_groups and access_levels
+            sync_hint = {}
+            if raw_access_level_ids:
+                sync_hint["new_access_levels"] = [str(al_id) for al_id in raw_access_level_ids]
+            if user_groups_payload:
+                sync_hint["new_user_groups"] = [str(ug["id"]) for ug in user_groups_payload]
+            
+            if sync_hint:
+                ag_body["sync_hint"] = sync_hint
+
+            payload = {"AccessGroup": ag_body}
+
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.post(
+                    f"{self.session.config.biostar_url}/api/access_groups",
+                    headers=headers,
+                    json=payload
+                )
+
+            if response.status_code not in (200, 201):
+                return self.error_response(
+                    f"API call failed: {response.status_code} - {response.text}",
+                    {"request_body": payload}
+                )
+
+            rj = {}
+            try:
+                rj = response.json() or {}
+            except Exception:
+                pass
+
+            ag_obj = rj.get("AccessGroup", {}) or {}
+            group_id = ag_obj.get("id") or rj.get("id")
+            group_name = ag_obj.get("name") or name
+            device_resp = rj.get("DeviceResponse")
+
+            out = {
+                "message": f"Access group '{group_name}' created successfully",
+                "group_id": group_id,
+                "group_name": group_name,
+                "ignored_fields": ignored_fields
+            }
+            if raw_user_ids:
+                out["users_added"] = len(raw_user_ids)
+            if raw_access_level_ids:
+                out["access_levels_attached"] = [str(x) for x in raw_access_level_ids]
+            if user_groups_payload:
+                out["user_groups_attached"] = [{"id": ug["id"], "name": ug["name"]} for ug in user_groups_payload]
+            if device_resp is not None:
+                out["device_response"] = device_resp
+
+            return self.success_response(out)
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def _list_all_user_groups(self, headers: Dict[str, str]) -> List[Dict[str, Any]]:
+        """
+        GET /api/user_groups and return a flattened list of groups.
+        - Includes top-level rows and each row's 'user_groups' children.
+        - Ensures children are included even if not present as separate rows.
+        - Best-effort depth: parent's depth + 1 if available; otherwise None.
+        - IDs are normalized to int when possible.
+        """
+        try:
+            async with httpx.AsyncClient(verify=False) as client:
+                r = await client.get(f"{self.session.config.biostar_url}/api/user_groups", headers=headers)
+            if r.status_code != 200:
+                logger.error("List user_groups failed: %s %s", r.status_code, r.text)
+                return []
+
+            data = r.json() or {}
+            rows = data.get("UserGroupCollection", {}).get("rows", []) or []
+
+            flat: Dict[str, Dict[str, Any]] = {}
+
+            def add(g: Dict[str, Any], depth_hint: Optional[int] = None):
+                gid = g.get("id")
+                if gid is None:
+                    return
+                try:
+                    gid_int = int(str(gid).strip())
+                except Exception:
+                    return
+                name = g.get("name") or ""
+                if depth_hint is not None:
+                    depth_val = depth_hint
+                else:
+                    try:
+                        depth_val = int(str(g.get("depth")).strip()) if g.get("depth") is not None else None
+                    except Exception:
+                        depth_val = None
+                key = str(gid_int)
+                if key not in flat:
+                    flat[key] = {"id": gid_int, "name": name, "depth": depth_val}
+
+            # Top-level rows
+            for g in rows:
+                add(g)
+
+            # Children inside each row
+            for g in rows:
+                try:
+                    base_depth = int(str(g.get("depth")).strip()) if g.get("depth") is not None else 0
+                except Exception:
+                    base_depth = 0
+                for ch in (g.get("user_groups") or []):
+                    add(ch, depth_hint=base_depth + 1)
+
+            return list(flat.values())
+
+        except Exception as e:
+            logger.exception("list_all_user_groups error: %s", e)
+            return []
+
+    def _filter_user_groups_by_name(self, rows: List[Dict[str, Any]], query: str) -> List[Dict[str, Any]]:
+        """Case-insensitive substring match with whitespace normalization."""
+        q = " ".join((query or "").lower().split())
+        out: List[Dict[str, Any]] = []
+        for g in rows:
+            name = str(g.get("name") or "")
+            norm = " ".join(name.lower().split())
+            if q in norm:
+                out.append(g)
+        return out
+
+    async def update_access_group(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Update an existing access group (PUT /api/access_groups/{id}).
+
+        Behavior:
+        - User groups: supports both replacement and delta operations.
+          * Replacement:
+              - If "user_group_ids" key is PRESENT (even if empty) → replace with that exact list.
+                (Empty list explicitly clears all user groups.)
+              - Optional helper: "user_group_search_text" (single-match → replacement),
+                for backward compatibility. Prefer explicit ids or delta fields below.
+          * Delta:
+              - add_user_group_ids / add_user_group_search_text
+              - remove_user_group_ids / remove_user_group_search_text
+              Each search_text uses 3-case logic (0/1/>=2) like create():
+                0 → return full list with needs_selection=true
+                1 → apply add/remove
+                >=2 → return candidates with needs_selection=true
+        - Users:
+          * If user_ids is provided → replace full 'users'
+          * Else apply delta with new_users / delete_users (and include those arrays in payload)
+        - Access levels:
+          * access_level_ids → replace full 'access_levels'
+        - Floor levels: ignored with warning.
+        - Only provided fields are included in PUT body; others are preserved server-side.
+        """
+        try:
+            self.check_auth()
+            group_id = int(args["group_id"])
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            # --- Read current group for safe deltas ---
+            async with httpx.AsyncClient(verify=False) as client:
+                get_resp = await client.get(
+                    f"{self.session.config.biostar_url}/api/access_groups/{group_id}",
+                    headers=headers
+                )
+            if get_resp.status_code != 200:
+                return self.error_response(f"Failed to get access group: {get_resp.status_code} - {get_resp.text}")
+            current = (get_resp.json() or {}).get("AccessGroup", {}) or {}
+
+            # --- Current snapshots ---
+            cur_users_field = current.get("users") or []
+            cur_user_ids: Set[str] = set()
+            for u in (cur_users_field if isinstance(cur_users_field, list) else []):
+                uid = u.get("user_id") if isinstance(u, dict) else None
+                if uid is not None:
+                    cur_user_ids.add(str(uid))
+
+            cur_ug_field = current.get("user_groups") or []
+            cur_ug_ids: Set[int] = set()
+            cur_ug_name_by_id: Dict[int, str] = {}
+            for g in (cur_ug_field if isinstance(cur_ug_field, list) else []):
+                try:
+                    gi = int(str(g.get("id")))
+                    cur_ug_ids.add(gi)
+                    cur_ug_name_by_id[gi] = g.get("name") or ""
+                except Exception:
+                    continue
+
+            # --- Inputs ---
+            name_in = args.get("name")
+            desc_in = args.get("description")
+
+            raw_user_ids = args.get("user_ids") or []
+            new_users_raw = args.get("new_users") or []
+            del_users_raw = args.get("delete_users") or []
+
+            #  CRITICAL: Ensure access_level_ids is always a list
+            raw_access_level_ids_input = args.get("access_level_ids")
+            if raw_access_level_ids_input is None:
+                raw_access_level_ids = []
+            elif isinstance(raw_access_level_ids_input, list):
+                raw_access_level_ids = raw_access_level_ids_input
+            else:
+                # Single value (int or string) → convert to list
+                raw_access_level_ids = [raw_access_level_ids_input]
+
+            # Replacement (presence-based)
+            has_user_group_ids_key = "user_group_ids" in args
+            
+            #  CRITICAL: Ensure user_group_ids is always a list
+            raw_user_group_ids_input = args.get("user_group_ids")
+            if raw_user_group_ids_input is None:
+                raw_user_group_ids = []
+            elif isinstance(raw_user_group_ids_input, list):
+                raw_user_group_ids = raw_user_group_ids_input
+            else:
+                # Single value (int or string) → convert to list
+                raw_user_group_ids = [raw_user_group_ids_input]
+            
+            # Legacy single-search (replacement)
+            replacement_search_text = (args.get("user_group_search_text") or args.get("user_group_name") or "").strip()
+
+            # Delta operations
+            #  CRITICAL: Ensure add/remove user_group_ids are always lists
+            add_ug_ids_raw_input = args.get("add_user_group_ids")
+            if add_ug_ids_raw_input is None:
+                add_ug_ids_raw = []
+            elif isinstance(add_ug_ids_raw_input, list):
+                add_ug_ids_raw = add_ug_ids_raw_input
+            else:
+                add_ug_ids_raw = [add_ug_ids_raw_input]
+            
+            remove_ug_ids_raw_input = args.get("remove_user_group_ids")
+            if remove_ug_ids_raw_input is None:
+                remove_ug_ids_raw = []
+            elif isinstance(remove_ug_ids_raw_input, list):
+                remove_ug_ids_raw = remove_ug_ids_raw_input
+            else:
+                remove_ug_ids_raw = [remove_ug_ids_raw_input]
+            add_ug_search_text = (args.get("add_user_group_search_text") or "").strip()
+            remove_ug_search_text = (args.get("remove_user_group_search_text") or "").strip()
+
+            # Ignored fields parity with create()
+            ignored_fields: List[str] = []
+            for forbidden in ["floor_levels", "parent_id"]:
+                if forbidden in args and args[forbidden]:
+                    ignored_fields.append(forbidden)
+
+            # --- Helpers ---
+            def _norm_int_list(raw) -> List[int]:
+                out, seen = [], set()
+                for x in (raw or []):
+                    try:
+                        v = int(str(x).strip())
+                        if v not in seen:
+                            seen.add(v); out.append(v)
+                    except Exception:
+                        continue
+                return out
+
+            def _norm_user_ids(raw) -> List[str]:
+                out, seen = [], set()
+                for x in (raw or []):
+                    s = str(x).strip()
+                    if not s:
+                        continue
+                    try:
+                        v = str(int(s))
+                    except Exception:
+                        v = s
+                    if v not in seen:
+                        seen.add(v); out.append(v)
+                return out
+
+            # --- Build update object incrementally ---
+            update_obj: Dict[str, Any] = {}
+            if name_in is not None:
+                update_obj["name"] = name_in
+            if desc_in is not None:
+                update_obj["description"] = desc_in
+
+            # Access levels (replacement)
+            if raw_access_level_ids:
+                #  CRITICAL: Access levels MUST include both 'id' and 'name'
+                # First, fetch all access levels to get the name mapping
+                async with httpx.AsyncClient(verify=False) as client:
+                    al_resp = await client.get(
+                        f"{self.session.config.biostar_url}/api/access_levels?limit=9999&order_by=id:false",
+                        headers=headers
+                    )
+                
+                al_id_to_name = {}
+                if al_resp.status_code == 200:
+                    al_data = al_resp.json() or {}
+                    al_rows = al_data.get("AccessLevelCollection", {}).get("rows", []) or []
+                    for al in al_rows:
+                        al_id = al.get("id")
+                        if al_id is not None:
+                            al_id_to_name[str(al_id)] = al.get("name", "")
+                    logger.info(f" Loaded {len(al_id_to_name)} Access Levels for validation: {list(al_id_to_name.keys())}")
+                else:
+                    logger.error(f" Failed to load Access Levels: {al_resp.status_code} - {al_resp.text[:200]}")
+                
+                # Validate and build access_levels with both id and name
+                logger.info(f" Validating access_level_ids: {raw_access_level_ids}")
+                access_levels_payload = []
+                invalid_al_ids = []
+                for alid in raw_access_level_ids:
+                    alid_str = str(alid).strip()
+                    if not alid_str:
+                        continue
+                    if alid_str not in al_id_to_name:
+                        invalid_al_ids.append(alid)
+                    else:
+                        access_levels_payload.append({
+                            "id": alid_str,
+                            "name": al_id_to_name[alid_str]
+                        })
+                
+                if invalid_al_ids:
+                    logger.error(f" Access Level validation failed! Invalid IDs: {invalid_al_ids}, Available: {list(al_id_to_name.keys())}")
+                    return self.error_response(
+                        "Invalid access_level_ids provided.",
+                        {
+                            "status": "access_level_validation_failed",
+                            "invalid_access_level_ids": invalid_al_ids,
+                            "available_access_levels": [{"id": al_id, "name": al_name} for al_id, al_name in al_id_to_name.items()]
+                        }
+                    )
+                
+                update_obj["access_levels"] = access_levels_payload
+
+            # ------------------------------
+            # USER GROUPS: replacement / delta
+            # ------------------------------
+            ug_all_cache: Optional[List[Dict[str, Any]]] = None
+            ug_final_ids: Optional[Set[int]] = None
+            ug_msg_parts: List[str] = []
+
+            async def _load_ug_all() -> List[Dict[str, Any]]:
+                nonlocal ug_all_cache
+                if ug_all_cache is None:
+                    ug_all_cache = await self._list_all_user_groups(headers)
+                return ug_all_cache
+
+            def _id_to_name_map(rows: List[Dict[str, Any]]) -> Dict[int, str]:
+                m: Dict[int, str] = {}
+                for g in rows:
+                    gid = g.get("id")
+                    if gid is None:
+                        continue
+                    try:
+                        gi = int(str(gid))
+                        m[gi] = g.get("name") or ""
+                    except Exception:
+                        continue
+                return m
+
+            # Replacement via explicit ids (key presence matters)
+            if has_user_group_ids_key:
+                ids = _norm_int_list(raw_user_group_ids)  # may be empty
+                if ids:
+                    ug_all = await _load_ug_all()
+                    id2name = _id_to_name_map(ug_all)
+                    invalid = [i for i in ids if i not in id2name]
+                    if invalid:
+                        return self.error_response(
+                            "Invalid user_group_ids provided.",
+                            {
+                                "status": "user_group_validation_failed",
+                                "invalid_user_group_ids": invalid,
+                                "available_user_groups": [{"id": i, "name": n} for i, n in id2name.items()]
+                            }
+                        )
+                    ug_final_ids = set(ids)
+                else:
+                    # explicit clear
+                    ug_final_ids = set()
+                ug_msg_parts.append("user groups replaced")
+
+            # Replacement via single search (legacy/compat)
+            elif replacement_search_text:
+                ug_all = await _load_ug_all()
+                matches = self._filter_user_groups_by_name(ug_all, replacement_search_text)
+
+                if len(matches) == 0:
+                    return self.success_response({
+                        "message": "No user group matched the query. Here is the full user group list. Please pick one.",
+                        "status": "user_group_not_found",
+                        "needs_selection": True,
+                        "user_groups": [
+                            {"id": int(str(g["id"]).strip()), "name": g.get("name")}
+                            for g in ug_all if g.get("id") is not None
+                        ]
+                    })
+                if len(matches) > 1:
+                    return self.success_response({
+                        "message": "Multiple user groups matched. Please pick one or more.",
+                        "status": "ambiguous_user_group",
+                        "needs_selection": True,
+                        "candidates": [
+                            {"id": int(str(g["id"]).strip()), "name": g.get("name")}
+                            for g in matches if g.get("id") is not None
+                        ]
+                    })
+
+                mg = matches[0]
+                if mg.get("id") is not None:
+                    ug_final_ids = {int(str(mg["id"]).strip())}
+                    ug_msg_parts.append("user groups replaced (single-match)")
+
+            # Delta operations (apply on top of current)
+            if (add_ug_ids_raw or remove_ug_ids_raw or add_ug_search_text or remove_ug_search_text):
+                # start from:
+                base_ids = set(cur_ug_ids) if ug_final_ids is None else set(ug_final_ids)
+
+                ug_all = await _load_ug_all()
+                id2name = _id_to_name_map(ug_all)
+
+                # add by ids
+                add_ids = _norm_int_list(add_ug_ids_raw)
+                invalid_add = [i for i in add_ids if i not in id2name]
+                if invalid_add:
+                    return self.error_response(
+                        "Invalid add_user_group_ids provided.",
+                        {
+                            "status": "user_group_validation_failed",
+                            "invalid_user_group_ids": invalid_add,
+                            "available_user_groups": [{"id": i, "name": n} for i, n in id2name.items()]
+                        }
+                    )
+                for i in add_ids:
+                    base_ids.add(i)
+
+                # add by search
+                if add_ug_search_text:
+                    matches = self._filter_user_groups_by_name(ug_all, add_ug_search_text)
+                    if len(matches) == 0:
+                        return self.success_response({
+                            "message": "No user group matched the add query. Here is the full user group list. Please pick one.",
+                            "status": "user_group_not_found_for_add",
+                            "needs_selection": True,
+                            "user_groups": [{"id": int(str(g["id"]).strip()), "name": g.get("name")} for g in ug_all if g.get("id") is not None]
+                        })
+                    if len(matches) > 1:
+                        return self.success_response({
+                            "message": "Multiple user groups matched for add. Please pick one or more.",
+                            "status": "ambiguous_user_group_for_add",
+                            "needs_selection": True,
+                            "candidates": [{"id": int(str(g["id"]).strip()), "name": g.get("name")} for g in matches if g.get("id") is not None]
+                        })
+                    mi = int(str(matches[0]["id"]).strip())
+                    base_ids.add(mi)
+
+                # remove by ids
+                rem_ids = _norm_int_list(remove_ug_ids_raw)
+                # (no strict invalid check for remove; silently ignore unknown)
+                for i in rem_ids:
+                    if i in base_ids:
+                        base_ids.remove(i)
+
+                # remove by search
+                if remove_ug_search_text:
+                    matches = self._filter_user_groups_by_name(ug_all, remove_ug_search_text)
+                    if len(matches) == 0:
+                        return self.success_response({
+                            "message": "No user group matched the remove query. Here is the full user group list. Please pick one.",
+                            "status": "user_group_not_found_for_remove",
+                            "needs_selection": True,
+                            "user_groups": [{"id": int(str(g["id"]).strip()), "name": g.get("name")} for g in ug_all if g.get("id") is not None]
+                        })
+                    if len(matches) > 1:
+                        return self.success_response({
+                            "message": "Multiple user groups matched for remove. Please pick one or more.",
+                            "status": "ambiguous_user_group_for_remove",
+                            "needs_selection": True,
+                            "candidates": [{"id": int(str(g["id"]).strip()), "name": g.get("name")} for g in matches if g.get("id") is not None]
+                        })
+                    mi = int(str(matches[0]["id"]).strip())
+                    if mi in base_ids:
+                        base_ids.remove(mi)
+
+                ug_final_ids = base_ids
+                ug_msg_parts.append("user groups delta applied")
+
+            # If we computed a final set, include in payload (replacement semantics)
+            if ug_final_ids is not None:
+                # resolve names (for nice payload)
+                ug_all = await _load_ug_all()
+                id2name = _id_to_name_map(ug_all)
+                update_obj["user_groups"] = [{"id": i, "name": id2name.get(i, cur_ug_name_by_id.get(i, ""))} for i in sorted(list(ug_final_ids))]
+
+            # ------------------------------
+            # USERS: replacement / delta
+            # ------------------------------
+            final_users_set: Optional[Set[str]] = None
+            new_users_norm = _norm_user_ids(new_users_raw)
+            del_users_norm = set(_norm_user_ids(del_users_raw))
+
+            if raw_user_ids:
+                final_users_set = set(_norm_user_ids(raw_user_ids))
+                update_obj["users"] = [{"user_id": uid} for uid in sorted(final_users_set, key=lambda s: int(s))]
+            elif new_users_norm or del_users_norm:
+                final_users_set = set(cur_user_ids)
+                for uid in new_users_norm:
+                    final_users_set.add(uid)
+                if del_users_norm:
+                    final_users_set = {uid for uid in final_users_set if uid not in del_users_norm}
+                update_obj["users"] = [{"user_id": uid} for uid in sorted(final_users_set, key=lambda s: int(s))]
+                if new_users_norm:
+                    update_obj["new_users"] = [{"user_id": uid} for uid in new_users_norm]
+                if del_users_norm:
+                    update_obj["delete_users"] = [{"user_id": uid} for uid in sorted(list(del_users_norm), key=lambda s: int(s))]
+
+            # --- Short-circuit if nothing to update ---
+            if not update_obj:
+                return self.success_response({
+                    "message": f"Access group {group_id}: no changes applied",
+                    "ignored_fields": ignored_fields
+                })
+
+            #  NEW: Add sync_hint for newly added user_groups and access_levels
+            sync_hint = {}
+            
+            # Track new access levels (if any)
+            if raw_access_level_ids:
+                cur_al_field = current.get("access_levels") or []
+                cur_al_ids = {str(al.get("id")) for al in (cur_al_field if isinstance(cur_al_field, list) else []) if al.get("id") is not None}
+                new_al_ids = [str(al_id) for al_id in raw_access_level_ids if str(al_id) not in cur_al_ids]
+                if new_al_ids:
+                    sync_hint["new_access_levels"] = new_al_ids
+            
+            # Track new user groups (if any)
+            if ug_final_ids is not None:
+                new_ug_ids = [str(ug_id) for ug_id in ug_final_ids if ug_id not in cur_ug_ids]
+                if new_ug_ids:
+                    sync_hint["new_user_groups"] = new_ug_ids
+            
+            if sync_hint:
+                update_obj["sync_hint"] = sync_hint
+
+            payload = {"AccessGroup": update_obj}
+
+            # --- PUT ---
+            async with httpx.AsyncClient(verify=False) as client:
+                put_resp = await client.put(
+                    f"{self.session.config.biostar_url}/api/access_groups/{group_id}",
+                    headers=headers,
+                    json=payload
+                )
+
+            if put_resp.status_code != 200:
+                return self.error_response(
+                    f"API call failed: {put_resp.status_code} - {put_resp.text}",
+                    {"request_body": payload}
+                )
+
+            rj = {}
+            try:
+                rj = put_resp.json() or {}
+            except Exception:
+                pass
+
+            # --- Summary ---
+            msg_parts = []
+            if name_in is not None or desc_in is not None:
+                msg_parts.append("group fields updated")
+            if "users" in update_obj:
+                msg_parts.append(f"users set = {len(update_obj['users'])}")
+            if "new_users" in update_obj or "delete_users" in update_obj:
+                add_n = len(update_obj.get("new_users", []))
+                del_n = len(update_obj.get("delete_users", []))
+                msg_parts.append(f"user delta (+{add_n}/-{del_n})")
+            if "access_levels" in update_obj:
+                msg_parts.append(f"access levels set = {len(update_obj['access_levels'])}")
+            if "user_groups" in update_obj:
+                msg_parts.append(f"user groups set = {len(update_obj['user_groups'])}")
+            if not msg_parts:
+                msg_parts.append("updated")
+
+            out = {
+                "message": f"Access group {group_id}: " + ", ".join(msg_parts + ug_msg_parts),
+                "ignored_fields": ignored_fields,
+                "request_body": payload
+            }
+            device_resp = rj.get("DeviceResponse")
+            if device_resp is not None:
+                out["device_response"] = device_resp
+
+            return self.success_response(out)
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+
+    async def delete_access_group(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Delete an access group."""
+        try:
+            self.check_auth()
+
+            group_id = args["group_id"]
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.delete(
+                    f"{self.session.config.biostar_url}/api/access_groups/{group_id}",
+                    headers=headers
+                )
+
+            if response.status_code not in [200, 204]:
+                return self.error_response(f"API call failed: {response.status_code} - {response.text}")
+
+            return self.success_response({
+                "message": f"Access group {group_id} deleted successfully"
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    # ----------------------------------------------------------------------
+    # Access Level methods
+    # ----------------------------------------------------------------------
+    async def get_access_levels(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Get list of access levels (supports View All params)."""
+        try:
+            self.check_auth()
+
+            limit = int(args.get("limit", 50)) if isinstance(args, dict) else 50
+            offset = int(args.get("offset", 0)) if isinstance(args, dict) else 0
+            order_by = args.get("order_by", "id:false") if isinstance(args, dict) else "id:false"
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            params = {"limit": limit, "offset": offset, "order_by": order_by}
+
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.get(
+                    f"{self.session.config.biostar_url}/api/access_levels",
+                    headers=headers,
+                    params=params
+                )
+
+            if response.status_code != 200:
+                return self.error_response(f"API call failed: {response.status_code} - {response.text}")
+
+            data = response.json() or {}
+            levels = data.get("AccessLevelCollection", {}).get("rows", []) or data.get("rows", []) or []
+
+            return self.success_response({
+                "message": f"Found {len(levels)} access levels",
+                "total": len(levels),
+                "levels": [self.format_access_level_info(level) for level in levels]
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def get_access_level(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Get specific access level details."""
+        try:
+            self.check_auth()
+
+            level_id = args["level_id"]
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.get(
+                    f"{self.session.config.biostar_url}/api/access_levels/{level_id}",
+                    headers=headers
+                )
+
+            if response.status_code != 200:
+                return self.error_response(f"API call failed: {response.status_code} - {response.text}")
+
+            data = response.json()
+            level = data.get("AccessLevel", {})
+
+            return self.success_response({
+                "level": self.format_access_level_info(level)
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def create_access_level(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Create an Access Level with strict door validation and enforced 'Always' schedule.
+        🆕 Supports simple mode (door_ids/door_names) and advanced mode (access_level_items).
+        """
+        try:
+            self.check_auth()
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            confirm: bool = bool(args.get("confirm", True))  # ← 기본값 True로 변경 (자동 생성)
+            name: str = str(args.get("name", "")).strip()
+            if not name:
+                return self.error_response(
+                    " 'name' parameter is required and cannot be empty.",
+                    {"hint": "Provide a unique name for the Access Level"}
+                )
+            description: str = (args.get("description") or "").strip()
+            
+            logger.info(f" Creating Access Level: name='{name}', description='{description}'")
+            
+            # 🆕 Simple mode: door_ids or door_names
+            #  CRITICAL: Normalize to list and parse JSON strings
+            door_ids_input = args.get("door_ids") or []
+            door_ids_simple: List[int] = []
+            
+            if isinstance(door_ids_input, list):
+                for item in door_ids_input:
+                    if isinstance(item, int):
+                        door_ids_simple.append(item)
+                    elif isinstance(item, str):
+                        # Try to parse as JSON array first
+                        try:
+                            parsed = json.loads(item)
+                            if isinstance(parsed, list):
+                                door_ids_simple.extend([int(x) for x in parsed if x])
+                            else:
+                                door_ids_simple.append(int(parsed))
+                        except (json.JSONDecodeError, ValueError):
+                            # Try direct int conversion
+                            try:
+                                door_ids_simple.append(int(item))
+                            except ValueError:
+                                logger.warning(f" Could not convert door_id to int: {item}")
+            elif isinstance(door_ids_input, int):
+                door_ids_simple.append(door_ids_input)
+            elif isinstance(door_ids_input, str):
+                try:
+                    parsed = json.loads(door_ids_input)
+                    if isinstance(parsed, list):
+                        door_ids_simple.extend([int(x) for x in parsed if x])
+                    else:
+                        door_ids_simple.append(int(parsed))
+                except (json.JSONDecodeError, ValueError):
+                    try:
+                        door_ids_simple.append(int(door_ids_input))
+                    except ValueError:
+                        pass
+            
+            door_names_input = args.get("door_names") or []
+            door_names_simple: List[str] = []
+            
+            if isinstance(door_names_input, list):
+                for item in door_names_input:
+                    if isinstance(item, str):
+                        # Try to parse as JSON array first
+                        try:
+                            parsed = json.loads(item)
+                            if isinstance(parsed, list):
+                                door_names_simple.extend([str(x) for x in parsed if x])
+                            else:
+                                door_names_simple.append(str(parsed))
+                        except json.JSONDecodeError:
+                            # Not JSON, use as-is
+                            door_names_simple.append(item)
+            elif isinstance(door_names_input, str):
+                try:
+                    parsed = json.loads(door_names_input)
+                    if isinstance(parsed, list):
+                        door_names_simple.extend([str(x) for x in parsed if x])
+                    else:
+                        door_names_simple.append(str(parsed))
+                except json.JSONDecodeError:
+                    door_names_simple.append(door_names_input)
+            
+            logger.info(f" Normalized: door_ids={door_ids_simple}, door_names={door_names_simple}")
+            
+            raw_items: List[Dict[str, Any]] = args.get("access_level_items") or []
+            
+            # 🆕 Convert simple mode to access_level_items format
+            if door_ids_simple or door_names_simple:
+                logger.info(f"🆕 Simple mode detected: door_ids={door_ids_simple}, door_names={door_names_simple}")
+                
+                # Fetch all doors to resolve names
+                all_doors = await self._get_all_doors(headers)
+                door_name_to_id = {str(d.get("name", "")).strip().lower(): int(d["id"]) for d in all_doors if d.get("id")}
+                
+                logger.info(f" Available doors for lookup: {list(door_name_to_id.keys())}")
+                
+                # Resolve door_names to IDs
+                resolved_ids = list(door_ids_simple)  # Start with explicit IDs
+                not_found_names = []
+                
+                for name in door_names_simple:
+                    name_lower = name.strip().lower()
+                    logger.info(f" Looking for door: '{name}' (normalized: '{name_lower}')")
+                    
+                    if name_lower in door_name_to_id:
+                        door_id = door_name_to_id[name_lower]
+                        resolved_ids.append(door_id)
+                        logger.info(f"   Found: ID {door_id}")
+                    else:
+                        not_found_names.append(name)
+                        logger.error(f"   Not found: '{name}' (looking for '{name_lower}')")
+                
+                if not_found_names:
+                    door_list_formatted = "\n".join([f"  - {d['name']} (ID: {d['id']})" for d in all_doors])
+                    logger.error(f" Door name lookup FAILED for: {not_found_names}")
+                    logger.error(f" Available doors:\n{door_list_formatted}")
+                    
+                    # Format not found names outside f-string (f-string cannot include backslash)
+                    not_found_str = ", ".join([f"'{n}'" for n in not_found_names])
+                    
+                    return self.error_response(
+                        f" Door name(s) not found: {not_found_str}\n\n"
+                        f" Available doors ({len(all_doors)} total):\n{door_list_formatted}\n\n"
+                        f" Tip: Door names are case-insensitive. Use exact names from the list above.",
+                        {
+                            "status": "door_not_found",
+                            "not_found": not_found_names,
+                            "available_doors": all_doors,
+                            "hint": "Use exact door names or door IDs instead"
+                        }
+                    )
+                
+                if not resolved_ids:
+                    return self.error_response(
+                        " No valid doors specified in door_ids or door_names.",
+                        {"available_doors": all_doors}
+                    )
+                
+                # Convert to access_level_items format
+                raw_items = [{"doors": [{"id": did} for did in resolved_ids]}]
+                logger.info(f" Converted to access_level_items: {len(resolved_ids)} doors")
+
+            # 1) FIRST: Reject empty items BEFORE duplicate check - PROVIDE CLEAR RETRY EXAMPLE
+            if not isinstance(raw_items, list) or len(raw_items) == 0:
+                all_doors = await self._get_all_doors(headers)
+                
+                logger.warning(f" create-access-level called without doors for '{name}'. Available: {len(all_doors)} doors")
+                
+                # Build concrete retry example using SIMPLE MODE
+                door_ids_example = ", ".join([str(d["id"]) for d in all_doors[:3]])
+                door_names_example = ", ".join([f'"{d["name"]}"' for d in all_doors[:3]])
+                
+                retry_example_simple = (
+                    f'🆕 SIMPLE MODE (Recommended):\n'
+                    f'create-access-level(\n'
+                    f'  name="{name}",\n'
+                    f'  door_ids=[{door_ids_example}],  # Use door IDs\n'
+                    f'  confirm=true\n'
+                    f')\n\n'
+                    f'OR:\n'
+                    f'create-access-level(\n'
+                    f'  name="{name}",\n'
+                    f'  door_names=[{door_names_example}],  # Use door names\n'
+                    f'  confirm=true\n'
+                    f')'
+                )
+                
+                return self.error_response(
+                    f" Door selection required! You MUST provide doors in one of these ways:\n"
+                    f"  1. door_ids=[...] - List of door IDs\n"
+                    f"  2. door_names=[...] - List of door names\n"
+                    f"  3. access_level_items=[{{...}}] - Advanced structure\n\n"
+                    f" Available doors ({len(all_doors)} total):\n" +
+                    "\n".join([f"  - ID {d['id']}: {d['name']}" for d in all_doors]) +
+                    f"\n\n RETRY NOW with this format:\n{retry_example_simple}",
+                    {
+                        "status": "door_selection_required",
+                        "available_doors": all_doors,
+                        "retry_example": retry_example_simple,
+                        "hint": f"Use door_ids or door_names parameter for simple access levels!"
+                    }
+                )
+
+            # 2) Duplicate name check with SIMPLE AUTO-DELETE
+            logger.info(f" Checking if Access Level '{name}' already exists...")
+            existing = await self._find_access_level_by_name(headers, name)
+            auto_update_on_exist = bool(args.get("auto_update_on_exist", True))  # 🆕 기본값 True로 자동 업데이트
+            
+            if existing:
+                existing_id = existing.get("id")
+                logger.warning(f" Access Level '{name}' already exists (ID: {existing_id}).")
+                logger.info(f"   Existing doors: {existing.get('access_levels', [])}")
+                
+                if auto_update_on_exist:
+                    logger.info(f" Auto-update enabled. Deleting existing Access Level '{name}' (ID: {existing_id}) and recreating...")
+                    
+                    # 🆕 간단하게: 무조건 삭제 후 재생성
+                    delete_success = False
+                    try:
+                        async with httpx.AsyncClient(verify=False, timeout=10) as client:
+                            del_resp = await client.delete(
+                                f"{self.session.config.biostar_url}/api/access_levels/{existing_id}",
+                                headers=headers
+                            )
+                        if del_resp.status_code in (200, 204):
+                            logger.info(f"  Successfully deleted existing Access Level '{name}' (ID: {existing_id})")
+                            delete_success = True
+                        else:
+                            logger.error(f" Delete FAILED with {del_resp.status_code}: {del_resp.text[:500]}")
+                    except Exception as e:
+                        logger.error(f" Exception during delete of Access Level '{name}': {e}")
+                    
+                    if delete_success:
+                        logger.info(f" Proceeding to create new Access Level '{name}'...")
+                    else:
+                        logger.warning(f" Delete failed, but proceeding to create anyway (may fail with duplicate name error)...")
+                    
+                    # 반드시 계속 진행!
+                else:
+                    logger.error(f" Auto-update disabled. Skipping creation. (This should not happen with default settings!)")
+                    return self.success_response({
+                        "message": f" Access Level '{name}' already exists. Set auto_update_on_exist=true to update automatically.",
+                        "exists": True,
+                        "existing": self.format_access_level_info(existing),
+                        "note": "Use update-access-level tool or set auto_update_on_exist=true"
+                    })
+            else:
+                logger.info(f" Access Level '{name}' does not exist. Proceeding with creation...")
+
+            # 3) Normalize items (doors only)
+            logger.info(f" Step 3: Normalizing items...")
+            logger.info(f"   Input raw_items: {raw_items}")
+            normalized_items, normalization_report = self._normalize_al_items_doors_only(raw_items)
+            logger.info(f"   Normalized items count: {len(normalized_items)}")
+            logger.info(f"   Normalization report: {normalization_report}")
+
+            # 4) Validate presence of doors in each item - PROVIDE CLEAR RETRY EXAMPLE
+            logger.info(f" Step 4: Validating door presence...")
+            items_missing_doors: List[int] = [i for i, it in enumerate(normalized_items) if not it.get("doors")]
+            logger.info(f"   Items missing doors: {items_missing_doors}")
+            if items_missing_doors:
+                all_doors = await self._get_all_doors(headers)
+                
+                # Build concrete retry example
+                door_list_str = ", ".join([f'{{"id": {d["id"]}, "name": "{d["name"]}"}}' for d in all_doors[:3]])
+                retry_example = (
+                    f'create-access-level(\n'
+                    f'  name="{name}",\n'
+                    f'  access_level_items=[{{\n'
+                    f'    "doors": [{door_list_str}],\n'
+                    f'    "schedule_id": {{"id": "1", "name": "Always"}}\n'
+                    f'  }}],\n'
+                    f'  confirm=true\n'
+                    f')'
+                )
+                
+                return self.error_response(
+                    f" Each access_level_item must include doors!\n\n"
+                    f" Available doors ({len(all_doors)} total):\n" +
+                    "\n".join([f"  - ID {d['id']}: {d['name']}" for d in all_doors]) +
+                    f"\n\n RETRY NOW with this format:\n{retry_example}",
+                    {
+                        "status": "door_selection_required",
+                        "items_missing_doors": items_missing_doors,
+                        "available_doors": self._format_door_options(all_doors),
+                        "prompt": f"Select doors for each item to create Access Level '{name}'.",
+                        "hint": "Each item requires at least one door id."
+                    }
+                )
+
+            # 5) Validate doors exist
+            logger.info(f" Step 5: Validating doors...")
+            all_doors = await self._get_all_doors(headers)
+            logger.info(f"   Retrieved {len(all_doors)} doors from API")
+            known_door_ids: Set[int] = {int(d["id"]) for d in all_doors if d.get("id") is not None}
+            logger.info(f"   Known door IDs: {sorted(list(known_door_ids))}")
+
+            provided_door_ids: Set[int] = set(self._collect_door_ids_from_items(normalized_items))
+            logger.info(f"   Provided door IDs: {sorted(list(provided_door_ids))}")
+            invalid_door_ids: List[int] = sorted([d for d in provided_door_ids if d not in known_door_ids])
+            if invalid_door_ids:
+                # Build concrete retry example with VALID doors
+                door_list_str = ", ".join([f'{{"id": {d["id"]}, "name": "{d["name"]}"}}' for d in all_doors[:3]])
+                retry_example = (
+                    f'create-access-level(\n'
+                    f'  name="{name}",\n'
+                    f'  access_level_items=[{{\n'
+                    f'    "doors": [{door_list_str}],\n'
+                    f'    "schedule_id": {{"id": "1", "name": "Always"}}\n'
+                    f'  }}],\n'
+                    f'  confirm=true\n'
+                    f')'
+                )
+                
+                return self.error_response(
+                    f" Invalid door IDs: {invalid_door_ids}\n\n"
+                    f" Valid doors ({len(all_doors)} total):\n" +
+                    "\n".join([f"  - ID {d['id']}: {d['name']}" for d in all_doors]) +
+                    f"\n\n RETRY NOW with valid door IDs:\n{retry_example}",
+                    {
+                        "status": "door_selection_required",
+                        "invalid_door_ids": invalid_door_ids,
+                        "available_doors": all_doors,  # ← Simple list: [{"id": 125, "name": "Main Entrance"}, ...]
+                        "retry_example": retry_example,
+                        "hint": f"Use only valid door IDs from available_doors list!"
+                    }
+                )
+
+            # 6) Ensure 'Always' schedule id
+            logger.info(f" Step 6: Getting 'Always' schedule ID...")
+            always_id_str = await self._get_or_create_always_schedule_id(headers)
+            logger.info(f"   Schedule ID: {always_id_str}")
+            if not always_id_str:
+                logger.error(f" Failed to get Always schedule ID!")
+                return self.error_response(
+                    "Failed to resolve 'Always' schedule id.",
+                    {"status": "schedule_resolution_failed"}
+                )
+
+            # 7) Build door name mapping
+            logger.info(f" Step 7: Building door name mapping...")
+            door_name_map: Dict[int, str] = {int(d["id"]): d.get("name", "") for d in all_doors if d.get("id") is not None}
+            logger.info(f"   Mapped {len(door_name_map)} doors")
+
+            # 8) Build items with enforced 'Always' schedule and door names
+            logger.info(f" Step 8: Building pruned items...")
+            pruned_items: List[Dict[str, Any]] = []
+            for it in normalized_items:
+                valid_doors_with_names = []
+                for d in it.get("doors", []):
+                    door_id = int(d.get("id"))
+                    if door_id in known_door_ids:
+                        valid_doors_with_names.append({
+                            "id": door_id,
+                            "name": door_name_map.get(door_id, "")
+                        })
+                if not valid_doors_with_names:
+                    continue
+                pruned_items.append({
+                    "doors": valid_doors_with_names,
+                    "schedule_id": {"id": str(always_id_str), "name": "Always"}
+                })
+
+            logger.info(f"   Final pruned_items count: {len(pruned_items)}")
+            
+            if not pruned_items:
+                logger.error(f" No valid doors in pruned_items!")
+                return self.error_response(
+                    "No valid doors to create an Access Level.",
+                    {
+                        "status": "door_selection_required",
+                        "available_doors": self._format_door_options(all_doors)
+                    }
+                )
+
+            # 9) Build request payload
+            logger.info(f" Step 9: Building payload...")
+            payload = self._build_al_payload(
+                name=name,
+                description=description,
+                items=pruned_items
+            )
+            logger.info(f"   Payload built: {json.dumps(payload, indent=2)[:500]}...")
+
+            # 10) Preview
+            logger.info(f" Step 10: Checking confirm flag... (confirm={confirm})")
+            if not confirm:
+                return self.success_response({
+                    "message": "Preview the Access Level creation plan with 'Always' schedule applied.",
+                    "needs_confirmation": True,
+                    "preview": {
+                        "request_body": payload,
+                        "normalized_items": normalization_report
+                    }
+                })
+
+            # 11) Confirmed creation with RETRY logic
+            logger.info(f" Step 11: Starting POST request with retry logic...")
+            door_count = sum(len(item.get("doors", [])) for item in pruned_items)
+            logger.info(f"   Total door count: {door_count}")
+            max_retries = 3
+            retry_delay = 1  # seconds
+            
+            logger.info(f" READY TO POST! Starting retry loop...")
+            for attempt in range(1, max_retries + 1):
+                logger.info(f" Creating Access Level '{name}' with {door_count} doors... (Attempt {attempt}/{max_retries})")
+                logger.debug(f" Request payload: {json.dumps(payload, indent=2)}")
+                
+                try:
+                    async with httpx.AsyncClient(verify=False, timeout=30) as client:
+                        resp = await client.post(
+                            f"{self.session.config.biostar_url}/api/access_levels",
+                            headers=headers,
+                            json=payload
+                        )
+                    
+                    logger.info(f" Response: {resp.status_code} - {resp.text[:500]}")
+                    
+                    if resp.status_code in (200, 201):
+                        # 성공!
+                        break
+                    
+                    # 실패 - 재시도 가능한지 확인
+                    logger.warning(f" Attempt {attempt} failed: {resp.status_code}")
+                    
+                    if attempt < max_retries:
+                        logger.info(f" Retrying in {retry_delay} seconds...")
+                        await asyncio.sleep(retry_delay)
+                        retry_delay *= 2  # Exponential backoff
+                    else:
+                        # 최종 실패
+                        logger.error(f" Access Level creation FAILED after {max_retries} attempts")
+                        logger.error(f"   Final error: {resp.status_code} - {resp.text}")
+                        logger.error(f"   Request body: {json.dumps(payload, indent=2)}")
+                        return self.error_response(
+                            f" API call failed after {max_retries} attempts: {resp.status_code}\n"
+                            f"Error: {resp.text[:500]}\n\n"
+                            f"Troubleshooting:\n"
+                            f"  1. Check door IDs are valid: {[d['id'] for item in pruned_items for d in item.get('doors', [])]}\n"
+                            f"  2. Verify 'Always' schedule exists\n"
+                            f"  3. Confirm user has permission to create access levels\n"
+                            f"  4. Check BioStar server logs for more details",
+                            {
+                                "status_code": resp.status_code,
+                                "error": resp.text,
+                                "request_body": payload,
+                                "attempts": max_retries
+                            }
+                        )
+                
+                except asyncio.TimeoutError:
+                    logger.error(f" Timeout on attempt {attempt}")
+                    if attempt < max_retries:
+                        logger.info(f" Retrying in {retry_delay} seconds...")
+                        await asyncio.sleep(retry_delay)
+                        retry_delay *= 2
+                    else:
+                        return self.error_response(
+                            f" Timeout after {max_retries} attempts. BioStar server may be slow or unresponsive.",
+                            {"attempts": max_retries, "error": "timeout"}
+                        )
+                
+                except Exception as e:
+                    logger.error(f" Unexpected error on attempt {attempt}: {e}")
+                    if attempt < max_retries:
+                        logger.info(f" Retrying in {retry_delay} seconds...")
+                        await asyncio.sleep(retry_delay)
+                        retry_delay *= 2
+                    else:
+                        return self.error_response(
+                            f" Unexpected error after {max_retries} attempts: {str(e)}",
+                            {"attempts": max_retries, "error": str(e)}
+                        )
+
+            rj: Dict[str, Any] = {}
+            try:
+                rj = resp.json()
+            except Exception as e:
+                logger.warning(f" Failed to parse JSON response: {e}")
+                rj = {}
+
+            al_id = (
+                rj.get("AccessLevel", {}).get("id")
+                or rj.get("id")
+                or rj.get("AccessLevel", {}).get("access_level_id")
+            )
+
+            logger.info(f" Access Level '{name}' created successfully!")
+            logger.info(f"   ID: {al_id}")
+            logger.info(f"   Doors: {door_count}")
+            logger.info(f"   Schedule: Always")
+
+            return self.success_response({
+                "message": f" Access Level '{name}' created successfully!",
+                "access_level_id": al_id,
+                "door_count": door_count,
+                "schedule": "Always",
+                "details": {
+                    "name": name,
+                    "description": description,
+                    "doors": [d["name"] for item in pruned_items for d in item.get("doors", [])]
+                }
+            })
+
+        except Exception as e:
+            logger.error(f" EXCEPTION in create_access_level: {type(e).__name__}: {e}")
+            logger.exception("Full traceback:")
+            return await self.handle_api_error(e)
+
+    async def _get_or_create_always_schedule_id(self, headers: Dict[str, str]) -> Optional[str]:
+        """
+        Resolve 'Always' schedule id from /api/schedules.
+        If not found, create a weekly 'Always' schedule (0..6 each with [0,1440]) and return its id.
+        """
+        # 1) Try to find existing
+        try:
+            async with httpx.AsyncClient(verify=False) as client:
+                resp = await client.get(f"{self.session.config.biostar_url}/api/schedules", headers=headers)
+            if resp.status_code == 200:
+                data = resp.json() or {}
+                rows = data.get("ScheduleCollection", {}).get("rows") or data.get("rows") or []
+                for s in rows:
+                    nm = (s.get("name") or s.get("Schedule", {}).get("name") or "").strip().lower()
+                    sid = s.get("id") or s.get("Schedule", {}).get("id")
+                    if nm == "always" and sid is not None:
+                        return str(sid)
+        except Exception:
+            pass
+
+        # 2) Create if missing
+        try:
+            daily_schedules = [{"day_index": i, "time_segments": [{"start_time": 0, "end_time": 1440}]} for i in range(0, 7)]
+            payload = {
+                "Schedule": {
+                    "name": "Always",
+                    "description": "Auto-created by MCP for Access Level creation",
+                    "daily_schedules": daily_schedules,
+                    "holiday_schedules": [],
+                    "days_of_iteration": 7,
+                    "use_daily_iteration": False
+                }
+            }
+            async with httpx.AsyncClient(verify=False) as client:
+                c_resp = await client.post(f"{self.session.config.biostar_url}/api/schedules", headers=headers, json=payload)
+            if c_resp.status_code in (200, 201):
+                try:
+                    rj = c_resp.json() or {}
+                    sid = rj.get("Schedule", {}).get("id") or rj.get("id")
+                    if sid is not None:
+                        return str(sid)
+                except Exception:
+                    return None
+            else:
+                logger.error("Failed to create 'Always' schedule: %s %s", c_resp.status_code, c_resp.text)
+                return None
+        except Exception:
+            return None
+
+    async def _get_all_doors(self, headers: Dict[str, str]) -> List[Dict[str, Any]]:
+        """Fetch all doors (GET /api/doors)."""
+        try:
+            async with httpx.AsyncClient(verify=False) as client:
+                resp = await client.get(f"{self.session.config.biostar_url}/api/doors", headers=headers)
+            if resp.status_code != 200:
+                return []
+            data = resp.json() or {}
+            rows = data.get("DoorCollection", {}).get("rows") or data.get("rows") or []
+            out = []
+            for d in rows:
+                out.append({
+                    "id": d.get("id") or d.get("door_id") or d.get("Door", {}).get("id"),
+                    "name": d.get("name") or d.get("Door", {}).get("name") or ""
+                })
+            return out
+        except Exception:
+            return []
+
+    async def _view_all_access_levels(self, headers: Dict[str, str], limit: int = 50, offset: int = 0, order_by: str = "id:false") -> List[Dict[str, Any]]:
+        """
+        View all Access Levels using official query params:
+        GET /api/access_levels?limit={limit}&offset={offset}&order_by={order_by}
+        """
+        try:
+            params = {"limit": limit, "offset": offset, "order_by": order_by}
+            async with httpx.AsyncClient(verify=False) as client:
+                resp = await client.get(
+                    f"{self.session.config.biostar_url}/api/access_levels",
+                    headers=headers,
+                    params=params
+                )
+            if resp.status_code != 200:
+                return []
+            data = resp.json() or {}
+            rows = data.get("AccessLevelCollection", {}).get("rows", []) or data.get("rows", []) or []
+            return rows
+        except Exception:
+            return []
+
+    def _collect_door_ids_from_items(self, items: List[Dict[str, Any]]) -> List[int]:
+        """Collect distinct door ids from items that have 'doors': [{'id': int}, ...]."""
+        acc: List[int] = []
+        seen: Set[int] = set()
+        for it in items:
+            for d in it.get("doors", []):
+                try:
+                    val = int(d.get("id"))
+                    if val not in seen:
+                        seen.add(val)
+                        acc.append(val)
+                except Exception:
+                    continue
+        return acc
+
+    def _format_door_options(self, doors: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """Format door options for client prompts."""
+        return [{"id": d.get("id"), "name": d.get("name")} for d in doors if d.get("id") is not None]
+
+    async def _find_access_level_by_name(self, headers: Dict[str, str], name: str) -> Optional[Dict[str, Any]]:
+        """Find Access Level by case-insensitive name (list-all fallback)."""
+        try:
+            async with httpx.AsyncClient(verify=False) as client:
+                resp = await client.get(f"{self.session.config.biostar_url}/api/access_levels", headers=headers)
+            if resp.status_code != 200:
+                return None
+            data = resp.json() or {}
+            rows = data.get("AccessLevelCollection", {}).get("rows", []) or data.get("rows", []) or []
+            target = name.strip().lower()
+            for r in rows:
+                if str(r.get("name", "")).strip().lower() == target:
+                    return r
+            return None
+        except Exception:
+            return None
+
+    async def _search_access_levels(self, headers: Dict[str, str], search_text: str) -> List[Dict[str, Any]]:
+        """
+        Search Access Levels by name/description substring using:
+        GET /api/access_levels?search_text=...
+        Returns the 'rows' list.
+        """
+        try:
+            async with httpx.AsyncClient(verify=False) as client:
+                resp = await client.get(
+                    f"{self.session.config.biostar_url}/api/access_levels",
+                    headers=headers,
+                    params={"search_text": search_text}
+                )
+            if resp.status_code != 200:
+                return []
+            data = resp.json() or {}
+            rows = data.get("AccessLevelCollection", {}).get("rows", []) or []
+            return rows
+        except Exception:
+            return []
+
+    def _normalize_al_items_doors_only(self, items: List[Dict[str, Any]]) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
+        """
+        Normalize only doors for access_level_items:
+        - doors: cast to int, drop invalid, de-duplicate while preserving order.
+        - schedule_id from input is ignored (will be replaced with 'Always').
+        """
+        normalized: List[Dict[str, Any]] = []
+        report: List[Dict[str, Any]] = []
+
+        for idx, raw in enumerate(items):
+            doors_raw = raw.get("doors") or []
+
+            tmp: List[int] = []
+            for d in doors_raw:
+                try:
+                    # Handle dict format: {'id': 267} or {'id': 267, 'name': '...'}
+                    if isinstance(d, dict):
+                        door_id = d.get("id")
+                        if door_id is not None:
+                            tmp.append(int(door_id))
+                    # Handle direct int or string format
+                    elif isinstance(d, (int, str)):
+                        tmp.append(int(d))
+                except Exception:
+                    continue
+            seen = set()
+            dedup = []
+            for di in tmp:
+                if di not in seen:
+                    seen.add(di)
+                    dedup.append(di)
+            doors_final = dedup  # keep original order
+
+            item_payload: Dict[str, Any] = {}
+            if doors_final:
+                item_payload["doors"] = [{"id": d} for d in doors_final]
+
+            normalized.append(item_payload)
+
+            report.append({
+                "index": idx,
+                "input": {"doors": doors_raw},
+                "normalized": {"doors": doors_final}
+            })
+        return normalized, report
+
+    def _build_al_payload(self, name: str, description: str, items: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """Build payload for POST /api/access_levels."""
+        body: Dict[str, Any] = {"AccessLevel": {"name": name, "description": description}}
+        if items:
+            body["AccessLevel"]["access_level_items"] = items
+        return body
+
+    async def update_access_level(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Update an existing Access Level with enforced 'Always' schedule.
+
+        HARD GUARD: This method will NEVER create a new access level when the target does not exist.
+        If target cannot be resolved, it returns status="target_not_found", includes available levels,
+        and sets do_not_autocreate=True to instruct the caller not to escalate into creation.
+        """
+        try:
+            self.check_auth()
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            dry_run = bool(args.get("dry_run", False))
+            level_id = args.get("level_id")
+            level_name = (args.get("level_name") or "").strip()
+            search_text = (args.get("search_text") or level_name).strip()
+
+            async def not_found_response(msg: str) -> Sequence[TextContent]:
+                # View All AL per official query (limit/offset/order_by)
+                available = await self._view_all_access_levels(headers, limit=50, offset=0, order_by="id:false")
+                return self.error_response(
+                    msg,
+                    {
+                        "status": "target_not_found",
+                        "do_not_autocreate": True,
+                        "available_levels": [
+                            {"id": r.get("id"), "name": r.get("name"), "description": r.get("description")}
+                            for r in (available or [])
+                        ],
+                        "example_get_url": f"{self.session.config.biostar_url}/api/access_levels?limit=50&offset=0&order_by=id:false",
+                        "example_curl": "curl --location 'https://127.0.0.1/api/access_levels?limit=50&offset=0&order_by=id:false'",
+                        "next_step": "Pick an existing access level by id, or explicitly ask to create a new one."
+                    }
+                )
+
+            # -------- existence check (branch on 'exists?' vs 'not exists?') --------
+            if not level_id:
+                if not search_text:
+                    return await not_found_response(
+                        "No target specified or target not found. The requested access level does not exist."
+                    )
+
+                candidates = await self._search_access_levels(headers, search_text)
+
+                if level_name:
+                    exact = [r for r in candidates if (str(r.get("name") or "").strip() == level_name)]
+                    if len(exact) == 1:
+                        level_id = int(exact[0]["id"])
+                    elif len(exact) == 0:
+                        return await not_found_response(
+                            f"No exact match for level_name='{level_name}'. The requested access level does not exist."
+                        )
+                    else:
+                        return self.error_response(
+                            f"Multiple access levels found with name '{level_name}'. Please provide level_id.",
+                            {"status": "ambiguous_target", "matches": [{"id": m.get("id"), "name": m.get("name")} for m in exact]}
+                        )
+                else:
+                    if len(candidates) == 1:
+                        level_id = int(candidates[0]["id"])
+                    elif len(candidates) == 0:
+                        return await not_found_response(
+                            f"No access levels match search_text='{search_text}'. The requested access level does not exist."
+                        )
+                    else:
+                        return self.error_response(
+                            f"Multiple candidates for search_text='{search_text}'. Provide level_name (exact) or level_id.",
+                            {"status": "ambiguous_target", "candidates": [{"id": c.get("id"), "name": c.get("name")} for c in candidates]}
+                        )
+
+            level_id = int(level_id)
+
+            # Get current AL by id; if not found → hard stop (no create)
+            async with httpx.AsyncClient(verify=False) as client:
+                get_resp = await client.get(
+                    f"{self.session.config.biostar_url}/api/access_levels/{level_id}",
+                    headers=headers
+                )
+            if get_resp.status_code != 200:
+                return await not_found_response(
+                    f"Access Level id='{level_id}' not found. The requested access level does not exist."
+                )
+            cur = (get_resp.json() or {}).get("AccessLevel", {}) or {}
+
+            # ---------------- normal update path (exists) ----------------
+            current_name = cur.get("name", "")
+            current_desc = cur.get("description", "")
+            items = cur.get("access_level_items", []) or []
+
+            # Flatten current doors
+            current_doors_list: List[int] = []
+            seen_doors: Set[int] = set()
+            first_item_id: Optional[str] = None
+            if items:
+                first_item = items[0] or {}
+                fi = first_item.get("id")
+                if fi is not None:
+                    first_item_id = str(fi)
+                for it in items:
+                    for d in (it.get("doors") or []):
+                        try:
+                            di = int(str(d.get("id")))
+                            if di not in seen_doors:
+                                seen_doors.add(di)
+                                current_doors_list.append(di)
+                        except Exception:
+                            continue
+
+            # Desired fields
+            new_name = args.get("name", current_name)
+            new_desc = args.get("description", current_desc)
+
+            set_doors_raw = args.get("set_doors")
+            add_doors_raw = args.get("add_doors")
+            remove_doors_raw = args.get("remove_doors")
+
+            def normalize_ids(raw) -> List[int]:
+                if not raw:
+                    return []
+                out, seen = [], set()
+                for x in raw:
+                    try:
+                        v = int(str(x).strip())
+                        if v not in seen:
+                            seen.add(v); out.append(v)
+                    except Exception:
+                        continue
+                return out
+
+            if set_doors_raw is not None:
+                final_doors = normalize_ids(set_doors_raw)
+                add_list, rem_list = [], [d for d in current_doors_list if d not in final_doors]
+            else:
+                final_doors = list(current_doors_list)
+                add_list = normalize_ids(add_doors_raw)
+                rem_list = normalize_ids(remove_doors_raw)
+                for d in add_list:
+                    if d not in final_doors:
+                        final_doors.append(d)
+                if rem_list:
+                    final_doors = [d for d in final_doors if d not in set(rem_list)]
+
+            # Door id validation (only if door op was requested)
+            door_op_requested = (set_doors_raw is not None) or bool(add_list) or bool(rem_list)
+            all_doors = await self._get_all_doors(headers)
+            known_ids: Set[int] = {int(d["id"]) for d in all_doors if d.get("id") is not None}
+
+            invalid_set = [d for d in (normalize_ids(set_doors_raw) if set_doors_raw is not None else []) if d not in known_ids]
+            invalid_add = [d for d in add_list if d not in known_ids]
+            invalid_remove = [d for d in rem_list if d not in known_ids]
+
+            if invalid_set or invalid_add:
+                return self.error_response(
+                    "Invalid door id(s) provided.",
+                    {
+                        "status": "door_validation_failed",
+                        "invalid_set_doors": invalid_set,
+                        "invalid_add_doors": invalid_add,
+                        "invalid_remove_doors": invalid_remove,
+                        "available_doors": self._format_door_options(all_doors)
+                    }
+                )
+
+            # Ensure 'Always' schedule
+            always_id = await self._get_or_create_always_schedule_id(headers)
+            if not always_id:
+                return self.error_response("Failed to resolve 'Always' schedule id.", {"status": "schedule_resolution_failed"})
+
+            # Build PUT payload (collapse into single item)
+            item_obj: Dict[str, Any] = {
+                "doors": [{"id": str(d)} for d in final_doors],
+                "schedule_id": {"id": str(always_id)}
+            }
+            if first_item_id is not None:
+                item_obj["id"] = str(first_item_id)
+
+            payload = {
+                "AccessLevel": {
+                    "name": new_name,
+                    "description": new_desc,
+                    "access_level_items": [item_obj]
+                }
+            }
+
+            # Diffs
+            door_diff = {
+                "before": current_doors_list,
+                "after": final_doors,
+                "added": [d for d in final_doors if d not in current_doors_list],
+                "removed": [d for d in current_doors_list if d not in final_doors],
+                "ignored_remove": [d for d in (normalize_ids(remove_doors_raw) if remove_doors_raw else []) if d not in current_doors_list]
+            }
+            field_changes = {
+                "name_changed": (new_name != current_name),
+                "description_changed": (new_desc != current_desc),
+                "doors_changed": (current_doors_list != final_doors)
+            }
+
+            if dry_run:
+                return self.success_response({
+                    "message": "Dry run: would update Access Level with enforced 'Always' schedule.",
+                    "level_id": level_id,
+                    "request_body": payload,
+                    "door_diff": door_diff,
+                    "field_changes": field_changes
+                })
+
+            # PUT update
+            async with httpx.AsyncClient(verify=False) as client:
+                put_resp = await client.put(
+                    f"{self.session.config.biostar_url}/api/access_levels/{level_id}",
+                    headers=headers,
+                    json=payload
+                )
+            if put_resp.status_code != 200:
+                return self.error_response(
+                    f"API call failed: {put_resp.status_code} - {put_resp.text}",
+                    {"request_body": payload, "door_diff": door_diff}
+                )
+
+            rj = {}
+            try:
+                rj = put_resp.json() or {}
+            except Exception:
+                pass
+
+            device_resp = rj.get("DeviceResponse")
+            msg_parts = []
+            if field_changes["name_changed"]:
+                msg_parts.append("name updated")
+            if field_changes["description_changed"]:
+                msg_parts.append("description updated")
+            if field_changes["doors_changed"]:
+                msg_parts.append(f"doors updated (+{len(door_diff['added'])}/-{len(door_diff['removed'])})")
+            if not msg_parts:
+                msg_parts.append("no effective changes")
+
+            out = {
+                "message": f"Access level {level_id}: " + ", ".join(msg_parts),
+                "request_body": payload,
+                "door_diff": door_diff
+            }
+            if device_resp is not None:
+                out["device_response"] = device_resp
+
+            return self.success_response(out)
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def delete_access_level(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Delete an access level."""
+        try:
+            self.check_auth()
+
+            level_id = args["level_id"]
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.delete(
+                    f"{self.session.config.biostar_url}/api/access_levels/{level_id}",
+                    headers=headers
+                )
+
+            if response.status_code not in [200, 204]:
+                return self.error_response(f"API call failed: {response.status_code} - {response.text}")
+
+            return self.success_response({
+                "message": f"Access level {level_id} deleted successfully"
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    # ----------------------------------------------------------------------
+    # Access Level <-> Access Group linking (ADD/REMOVE)
+    # ----------------------------------------------------------------------
+    async def _get_access_group_detail(self, headers: Dict[str, str], group_id: int) -> Optional[Dict[str, Any]]:
+        """GET /api/access_groups/{id} and return the 'AccessGroup' object or None."""
+        async with httpx.AsyncClient(verify=False) as client:
+            r = await client.get(f"{self.session.config.biostar_url}/api/access_groups/{group_id}", headers=headers)
+        if r.status_code != 200:
+            return None
+        return (r.json() or {}).get("AccessGroup") or {}
+
+    async def _list_all_access_levels(self, headers: Dict[str, str]) -> List[Dict[str, Any]]:
+        """List all access levels using GET /api/access_levels with limit=0."""
+        try:
+            async with httpx.AsyncClient(verify=False) as client:
+                r = await client.get(
+                    f"{self.session.config.biostar_url}/api/access_levels",
+                    headers=headers,
+                    params={"limit": 0, "offset": 0, "order_by": "id:false"}
+                )
+            if r.status_code != 200:
+                return []
+            data = r.json() or {}
+            return data.get("AccessLevelCollection", {}).get("rows", []) or data.get("rows", []) or []
+        except Exception:
+            return []
+
+    def _norm_ids_str(self, raw: Any) -> List[str]:
+        """Normalize single or multiple numeric ids to a list of unique strings."""
+        if raw is None:
+            return []
+        out, seen = [], set()
+        if not isinstance(raw, (list, tuple, set)):
+            raw = [raw]
+        for x in raw:
+            try:
+                v = str(int(str(x).strip()))
+                if v not in seen:
+                    seen.add(v)
+                    out.append(v)
+            except Exception:
+                continue
+        return out
+
+    async def _add_or_remove_access_levels(self, *, op: str, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Add or remove access level ids from an access group while preserving other fields.
+
+        Steps:
+        1) Resolve group and read current 'access_levels'
+        2) Normalize requested ids (single or multiple)
+        3) Validate existence against full list of access levels
+        4) Compute union/difference
+        5) PUT /api/access_groups/{id} with only {"AccessGroup":{"access_levels":[...]}}
+        """
+        self.check_auth()
+        headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+        # Resolve group
+        try:
+            access_group_id = int(args["access_group_id"])
+        except Exception:
+            return self.error_response("access_group_id must be an integer")
+
+        group = await self._get_access_group_detail(headers, access_group_id)
+        if not group:
+            return self.error_response(
+                f"Access group {access_group_id} not found.",
+                {"status": "group_not_found", "group_id": access_group_id}
+            )
+
+        # Current access levels in the group
+        cur_levels = group.get("access_levels") or []
+        cur_ids: Set[str] = {str(x.get("id")) for x in cur_levels if isinstance(x, dict) and x.get("id") is not None}
+
+        # Requested ids (single or multiple)
+        req_ids = []
+        if "access_level_ids" in args:
+            req_ids = self._norm_ids_str(args.get("access_level_ids"))
+        elif "access_level_id" in args:
+            req_ids = self._norm_ids_str(args.get("access_level_id"))
+        else:
+            return self.error_response(
+                "Provide 'access_level_id' or 'access_level_ids'.",
+                {"status": "missing_access_level_ids"}
+            )
+
+        if not req_ids:
+            return self.error_response("No valid access level ids provided.", {"status": "empty_access_level_ids"})
+
+        # Validate existence
+        all_levels = await self._list_all_access_levels(headers)
+        all_id_set: Set[str] = {str(lv.get("id")) for lv in all_levels if lv.get("id") is not None}
+        unknown = [x for x in req_ids if x not in all_id_set]
+        if unknown:
+            return self.error_response(
+                "Requested access level(s) not found.",
+                {
+                    "status": "access_level_not_found",
+                    "unknown_ids": unknown,
+                    "available_levels": [
+                        {"id": str(lv.get("id")), "name": lv.get("name"), "description": lv.get("description")}
+                        for lv in all_levels
+                    ]
+                }
+            )
+
+        # Compute before/after
+        before = sorted(cur_ids, key=lambda s: int(s))
+        if op == "add":
+            final_ids = set(cur_ids)
+            for i in req_ids:
+                final_ids.add(i)
+            changed_added = [i for i in req_ids if i not in cur_ids]
+            changed_removed: List[str] = []
+        elif op == "remove":
+            final_ids = {i for i in cur_ids if i not in set(req_ids)}
+            changed_added = []
+            changed_removed = [i for i in req_ids if i in cur_ids]
+        else:
+            return self.error_response("op must be 'add' or 'remove'")
+
+        after = sorted(final_ids, key=lambda s: int(s))
+        if before == after:
+            msg = "No changes applied: "
+            if op == "add":
+                msg += "all requested access levels are already assigned."
+            else:
+                msg += "none of the requested access levels were assigned to the group."
+            return self.success_response({
+                "message": msg,
+                "group_id": access_group_id,
+                "requested": req_ids,
+                "current_access_levels": before
+            })
+
+        # PUT only the 'access_levels' field to preserve others
+        payload = {"AccessGroup": {"access_levels": [{"id": i} for i in after]}}
+        async with httpx.AsyncClient(verify=False) as client:
+            put_resp = await client.put(
+                f"{self.session.config.biostar_url}/api/access_groups/{access_group_id}",
+                headers=headers,
+                json=payload
+            )
+
+        if put_resp.status_code != 200:
+            return self.error_response(
+                f"API call failed: {put_resp.status_code} - {put_resp.text}",
+                {"request_body": payload, "group_id": access_group_id}
+            )
+
+        rj = {}
+        try:
+            rj = put_resp.json() or {}
+        except Exception:
+            pass
+
+        summary = {
+            "group_id": access_group_id,
+            "before": before,
+            "after": after,
+            "added": changed_added,
+            "removed": changed_removed
+        }
+        out_msg = f"Access levels {'added to' if op=='add' else 'removed from'} group {access_group_id}."
+
+        return self.success_response({
+            "message": out_msg,
+            "summary": summary,
+            "request_body": payload,
+            "device_response": rj.get("DeviceResponse")
+        })
+
+    # Public endpoints (tool handlers)
+    async def add_access_level_to_group(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Add one or more access levels to a group (preserves other fields)."""
+        try:
+            return await self._add_or_remove_access_levels(op="add", args=args)
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def assign_access_level_to_group(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Backward-compatible handler for legacy tool name "assign-access-level-to-group".
+        Delegates to add operation and supports single or multiple ids.
+        """
+        try:
+            # Accept both 'access_level_id' and 'access_level_ids' for compatibility
+            return await self._add_or_remove_access_levels(op="add", args=args)
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def remove_access_level_from_group(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Remove one or more access levels from a group (preserves other fields)."""
+        try:
+            return await self._add_or_remove_access_levels(op="remove", args=args)
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    # ----------------------------------------------------------------------
+    # Helper methods (formatters)
+    # ----------------------------------------------------------------------
+    def format_access_group_info(self, group: Dict[str, Any]) -> Dict[str, Any]:
+        """Format access group information for response."""
+        users_field = group.get("users") or []
+        user_count = len(users_field) if isinstance(users_field, list) else 0
+
+        al_field = group.get("access_levels") or []
+        access_level_ids = [x.get("id") for x in al_field] if isinstance(al_field, list) else []
+
+        parent_id = group.get("parent_id", {}).get("id") if isinstance(group.get("parent_id"), dict) else group.get("parent_id")
+
+        return {
+            "id": group.get("id"),
+            "name": group.get("name"),
+            "description": group.get("description"),
+            "parent_id": parent_id,
+            "user_count": user_count,
+            "access_level_ids": access_level_ids
+        }
+
+    def format_access_level_info(self, level: Dict[str, Any]) -> Dict[str, Any]:
+        """Format access level information for response."""
+        access_items = level.get("access_level_items", [])
+        first_item = access_items[0] if access_items else {}
+
+        return {
+            "id": level.get("id"),
+            "name": level.get("name"),
+            "description": level.get("description"),
+            "doors": first_item.get("doors", []),
+            "schedule_id": first_item.get("schedule_id", {})
+        }