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

biostar_x_mcp_server/handlers/door_handler.py

@@ -0,0 +1,3969 @@
+import logging
+from typing import Sequence, Dict, Any, List, Optional, Set, Tuple
+from mcp.types import TextContent
+import httpx
+import asyncio
+import json
+from .base_handler import BaseHandler
+import unicodedata
+
+logger = logging.getLogger(__name__)
+
+
+class DoorHandler(BaseHandler):
+    """Handle door-related operations."""
+
+    async def get_doors(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Get list of doors (enhanced):
+        - Honors API params (limit, order_by) with sensible defaults.
+        - Adds retry/backoff and timeouts for resilience.
+        - Normalizes nested fields and casts numbers/booleans.
+        - Provides rich client-side filters for LLM-friendly use.
+        - Optional include_raw to attach original API rows for debugging.
+        """
+        try:
+            self.check_auth()
+
+            # -------- 1) Compose API query params (spec-compliant) --------
+            #  CRITICAL: limit=0 means "return 0 results"! Use 9999 for "all".
+            limit = int(args.get("limit", 9999))
+            order_by = str(args.get("order_by", "id:true"))
+            params = {"limit": str(limit), "order_by": order_by}
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            # -------- 2) HTTP call with timeout + simple retries --------
+            response = None
+            last_exc = None
+            for attempt in range(3):
+                try:
+                    async with httpx.AsyncClient(
+                        verify=False,
+                        timeout=httpx.Timeout(10.0, read=20.0)
+                    ) as client:
+                        response = await client.get(
+                            f"{self.session.config.biostar_url}/api/doors",
+                            headers=headers,
+                            params=params
+                        )
+                    # Retry on transient server errors
+                    if response.status_code >= 500:
+                        await asyncio.sleep(0.6 * (attempt + 1))
+                        continue
+                    break
+                except Exception as e:
+                    last_exc = e
+                    await asyncio.sleep(0.6 * (attempt + 1))
+
+            if response is None:
+                return self.error_response(f"API temporary failure: {repr(last_exc)}")
+
+            if response.status_code != 200:
+                return self.error_response(f"API call failed: {response.status_code} - {response.text}")
+
+            data = response.json()
+            collection = (data.get("DoorCollection") or {})
+            rows = collection.get("rows") or []
+            total_from_api = int(collection.get("total") or len(rows))
+
+            # -------- 3) Helpers for normalization --------
+            def _to_int(x, default=None):
+                try:
+                    return int(x)
+                except Exception:
+                    return default
+
+            def _to_bool(x):
+                if isinstance(x, bool):
+                    return x
+                s = str(x).strip().lower()
+                return s in ("1", "true", "t", "yes", "y")
+
+            # Parse filtering args (LLM-friendly)
+            ids = args.get("ids") or []
+            if isinstance(ids, (str, int)):
+                ids = [ids]
+            ids_set = {_to_int(i) for i in ids if _to_int(i) is not None}
+
+            name_equals = (args.get("name") or "").strip() or None
+            name_contains = (args.get("name_contains") or "").strip() or None
+
+            group_id_val = _to_int(args.get("group_id")) if args.get("group_id") is not None else None
+            group_name_arg = (args.get("group_name") or "").strip() or None
+
+            status_val = str(args.get("status")).strip() if args.get("status") is not None else None
+
+            include_raw = bool(args.get("include_raw", False))
+            minimal = bool(args.get("minimal", False))  # ← For access level creation: return only id+name
+
+            # -------- 4) Normalize nested door structure (flatten + cast) --------
+            def _dev_slim(dev_obj):
+                if not dev_obj:
+                    return None
+                return {
+                    "id": _to_int(dev_obj.get("id")),
+                    "name": dev_obj.get("name")
+                }
+
+            def normalize_door(d: Dict[str, Any]) -> Dict[str, Any]:
+                group = d.get("door_group_id") or {}
+                entry = d.get("entry_device_id") or {}
+                exit_dev = d.get("exit_device_id") or {}
+                relay = d.get("relay_output_id") or {}
+                relay_dev = relay.get("device_id") or {}
+                sensor = d.get("sensor_input_id") or {}
+                sensor_dev = sensor.get("device_id") or {}
+                exit_btn = d.get("exit_button_input_id") or {}
+                exit_btn_dev = exit_btn.get("device_id") or {}
+
+                return {
+                    "id": _to_int(d.get("id")),
+                    "name": d.get("name"),
+                    "description": d.get("description"),
+                    "status": str(d.get("status")) if d.get("status") is not None else None,
+                    "open_duration_sec": _to_int(d.get("open_duration")),
+                    "open_timeout_sec": _to_int(d.get("open_timeout")),
+                    "open_once": _to_bool(d.get("open_once")),
+                    "unconditional_lock": _to_bool(d.get("unconditional_lock")),
+                    "extended_auto_lock_timeout_sec": _to_int(d.get("extended_auto_lock_timeout")),
+                    "group": {
+                        "id": _to_int(group.get("id")),
+                        "name": group.get("name")
+                    },
+                    "devices": {
+                        "entry": _dev_slim(entry),
+                        "exit": _dev_slim(exit_dev),
+                        "relay_output": (
+                            {
+                                "device": _dev_slim(relay_dev),
+                                "relay_index": _to_int(relay.get("relay_index"))
+                            } if relay else None
+                        ),
+                        "sensor_input": (
+                            {
+                                "device": _dev_slim(sensor_dev),
+                                "input_index": _to_int(sensor.get("input_index")),
+                                "type": _to_int(sensor.get("type")),
+                                "apb_use_door_sensor": _to_bool(sensor.get("apb_use_door_sensor"))
+                            } if sensor else None
+                        ),
+                        "exit_button_input": (
+                            {
+                                "device": _dev_slim(exit_btn_dev),
+                                "input_index": _to_int(exit_btn.get("input_index")),
+                                "type": _to_int(exit_btn.get("type"))
+                            } if exit_btn else None
+                        )
+                    }
+                }
+
+            doors_norm = [normalize_door(d) for d in rows]
+
+            # -------- 5) Apply client-side filters --------
+            if ids_set:
+                doors_norm = [d for d in doors_norm if d.get("id") in ids_set]
+            if name_equals:
+                doors_norm = [d for d in doors_norm if (d.get("name") or "") == name_equals]
+            if name_contains:
+                q = name_contains.lower()
+                doors_norm = [d for d in doors_norm if q in (d.get("name") or "").lower()]
+            if group_id_val is not None:
+                doors_norm = [d for d in doors_norm if ((d.get("group") or {}).get("id") == group_id_val)]
+            if group_name_arg:
+                gq = group_name_arg.lower()
+                doors_norm = [d for d in doors_norm if gq in ((d.get("group") or {}).get("name") or "").lower()]
+            if status_val is not None:
+                doors_norm = [d for d in doors_norm if str(d.get("status")) == status_val]
+
+            # Attach raw API row when requested (useful for debugging/tracing)
+            if include_raw:
+                raw_by_id = {}
+                for r in rows:
+                    rid = _to_int(r.get("id"))
+                    raw_by_id[rid] = r
+                for d in doors_norm:
+                    d["raw"] = raw_by_id.get(d.get("id"))
+
+            # -------- 6) Lightweight summary for LLM-friendly responses --------
+            #  CRITICAL: For access level creation, return ONLY id+name (minimal mode)
+            if minimal:
+                minimal_doors = []
+                for d in doors_norm:
+                    door_id = d.get("id")
+                    door_name = d.get("name", "")
+                    if door_id is not None:
+                        minimal_doors.append({"id": door_id, "name": door_name})
+                
+                logger.info(f" Returning {len(minimal_doors)} doors in minimal mode (id+name only) for access level creation")
+                
+                return self.success_response({
+                    "message": f"Found {len(minimal_doors)} doors (minimal mode for access level creation)",
+                    "total": len(minimal_doors),
+                    "doors": minimal_doors
+                })
+            
+            # Normal mode: return full details
+            groups_breakdown = {}
+            for d in doors_norm:
+                gname = (d.get("group") or {}).get("name") or "Unknown"
+                groups_breakdown[gname] = groups_breakdown.get(gname, 0) + 1
+
+            return self.success_response({
+                "message": f"Fetched {len(doors_norm)} doors (API total={total_from_api}, limit={limit}, order_by='{order_by}')",
+                "total": len(doors_norm),
+                "api_total": total_from_api,
+                "groups_breakdown": groups_breakdown,
+                "doors": doors_norm
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def get_door(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Search→disambiguate→fetch one door.
+        Behavior:
+        - If 'door_id' is provided, fetch details directly.
+        - Else, POST /api/v2/doors/search with {limit, search_text, door_group_id}.
+        - If 0 results: return a choice list of existing doors and require user input.
+        - If 1 result: auto-fetch details by id and return normalized payload.
+        - If >1 results: return the candidate list and require user input.
+        All tool-facing messages are in English. The chat layer may localize/ask the user.
+        """
+        try:
+            self.check_auth()
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            # ---------- helpers ----------
+            def _to_int(x, default=None):
+                try:
+                    return int(x)
+                except Exception:
+                    return default
+
+            def _to_bool(x):
+                if isinstance(x, bool):
+                    return x
+                s = str(x).strip().lower()
+                return s in ("1", "true", "t", "yes", "y")
+
+            def _dev_slim(dev_obj):
+                if not dev_obj:
+                    return None
+                return {"id": _to_int(dev_obj.get("id")), "name": dev_obj.get("name")}
+
+            def _normalize_brief(d: Dict[str, Any]) -> Dict[str, Any]:
+                # Brief item for choice lists
+                g = d.get("door_group_id") or {}
+                return {
+                    "id": _to_int(d.get("id")),
+                    "name": d.get("name"),
+                    "group": {"id": _to_int(g.get("id")), "name": g.get("name")}
+                }
+
+            def _normalize_detail(d: Dict[str, Any]) -> Dict[str, Any]:
+                # Full detail normalization (flatten + type cast)
+                g = d.get("door_group_id") or {}
+                entry = d.get("entry_device_id") or {}
+                exit_dev = d.get("exit_device_id") or {}
+                relay = d.get("relay_output_id") or {}
+                relay_dev = relay.get("device_id") or {}
+                sensor = d.get("sensor_input_id") or {}
+                sensor_dev = sensor.get("device_id") or {}
+                exit_btn = d.get("exit_button_input_id") or {}
+                exit_btn_dev = exit_btn.get("device_id") or {}
+
+                return {
+                    "id": _to_int(d.get("id")),
+                    "name": d.get("name"),
+                    "description": d.get("description"),
+                    "status": str(d.get("status")) if d.get("status") is not None else None,
+                    "open_duration_sec": _to_int(d.get("open_duration")),
+                    "open_timeout_sec": _to_int(d.get("open_timeout")),
+                    "open_once": _to_bool(d.get("open_once")),
+                    "unconditional_lock": _to_bool(d.get("unconditional_lock")),
+                    "group": {"id": _to_int(g.get("id")), "name": g.get("name")},
+                    "devices": {
+                        "entry": _dev_slim(entry),
+                        "exit": _dev_slim(exit_dev),
+                        "relay_output": (
+                            {"device": _dev_slim(relay_dev), "relay_index": _to_int(relay.get("relay_index"))}
+                            if relay else None
+                        ),
+                        "sensor_input": (
+                            {
+                                "device": _dev_slim(sensor_dev),
+                                "input_index": _to_int(sensor.get("input_index")),
+                                "type": _to_int(sensor.get("type")),
+                                "apb_use_door_sensor": _to_bool(sensor.get("apb_use_door_sensor"))
+                            }
+                            if sensor else None
+                        ),
+                        "exit_button_input": (
+                            {
+                                "device": _dev_slim(exit_btn_dev),
+                                "input_index": _to_int(exit_btn.get("input_index")),
+                                "type": _to_int(exit_btn.get("type"))
+                            }
+                            if exit_btn else None
+                        )
+                    }
+                }
+
+            async def _http_with_retry(method: str, url: str, **kwargs) -> httpx.Response:
+                # Simple retry/backoff for resilience
+                last_exc = None
+                for attempt in range(3):
+                    try:
+                        async with httpx.AsyncClient(
+                            verify=False,
+                            timeout=httpx.Timeout(10.0, read=20.0)
+                        ) as client:
+                            resp = await client.request(method, url, **kwargs)
+                        if resp.status_code >= 500:
+                            await asyncio.sleep(0.6 * (attempt + 1))
+                            continue
+                        return resp
+                    except Exception as e:
+                        last_exc = e
+                        await asyncio.sleep(0.6 * (attempt + 1))
+                raise RuntimeError(f"HTTP temporary failure: {repr(last_exc)}")
+
+            async def _fetch_detail(door_id: int) -> Dict[str, Any]:
+                # GET /api/doors/{id} and normalize "Door"
+                resp = await _http_with_retry(
+                    "GET",
+                    f"{self.session.config.biostar_url}/api/doors/{door_id}",
+                    headers=headers
+                )
+                if resp.status_code != 200:
+                    return self.error_response(f"API call failed: {resp.status_code} - {resp.text}")
+                raw = resp.json()
+                door_obj = (raw.get("Door") or {})
+                return self.success_response({
+                    "status": "resolved",
+                    "message": "Door detail fetched.",
+                    "door": _normalize_detail(door_obj),
+                    "api_calls": [
+                        {"method": "GET", "path": f"/api/doors/{door_id}", "status": resp.status_code}
+                    ]
+                })
+
+            # ---------- direct by id ----------
+            if args.get("door_id") is not None:
+                did = _to_int(args.get("door_id"))
+                if did is None:
+                    return self.error_response("Invalid 'door_id' provided.")
+                return await _fetch_detail(did)
+
+            # ---------- search-first path ----------
+            # POST /api/v2/doors/search with raw JSON payload: {"limit":50,"search_text":"...","door_group_id":1}
+            limit = _to_int(args.get("limit"), 50) or 50
+            payload = {"limit": limit}
+
+            if args.get("search_text") is not None:
+                payload["search_text"] = str(args.get("search_text"))
+            if args.get("door_group_id") is not None:
+                dg = _to_int(args.get("door_group_id"))
+                if dg is not None:
+                    payload["door_group_id"] = dg
+
+            # Safety: ensure at least one search hint exists (search_text or door_group_id)
+            if "search_text" not in payload and "door_group_id" not in payload:
+                # If nothing to search by, instruct caller to provide at least one criterion.
+                return self.success_response({
+                    "status": "need_user_input",
+                    "reason": "missing_search_criteria",
+                    "message": "Please provide at least one search criterion (e.g., 'search_text' or 'door_group_id'), or pass 'door_id' directly.",
+                    "expected_params": {"door_id": "integer", "search_text": "string", "door_group_id": "integer", "limit": "integer"}
+                })
+
+            search_resp = await _http_with_retry(
+                "POST",
+                f"{self.session.config.biostar_url}/api/v2/doors/search",
+                headers=headers,
+                json=payload
+            )
+            if search_resp.status_code != 200:
+                return self.error_response(f"Search API failed: {search_resp.status_code} - {search_resp.text}")
+
+            search_json = search_resp.json()
+            # Accept both shapes: {DoorCollection:{rows:[...]}} or {rows:[...]}
+            collection = search_json.get("DoorCollection") or {}
+            rows = collection.get("rows")
+            if rows is None:
+                rows = search_json.get("rows") or []
+
+            candidates = [_normalize_brief(r) for r in rows if _to_int(r.get("id")) is not None]
+
+            # ---------- branch by candidate count ----------
+            api_calls_meta = [
+                {"method": "POST", "path": "/api/v2/doors/search", "status": search_resp.status_code, "payload": payload}
+            ]
+
+            if len(candidates) == 0:
+                # When no match, list all existing doors so the user can choose from valid names/ids.
+                all_resp = await _http_with_retry(
+                    "GET",
+                    f"{self.session.config.biostar_url}/api/doors",
+                    headers=headers,
+                    params={"limit": "0", "order_by": "id:true"}
+                )
+                all_rows = []
+                if all_resp.status_code == 200:
+                    all_json = all_resp.json()
+                    all_rows = ((all_json.get("DoorCollection") or {}).get("rows") or [])
+                all_choices = [_normalize_brief(r) for r in all_rows if _to_int(r.get("id")) is not None]
+
+                return self.success_response({
+                    "status": "need_user_input",
+                    "reason": "no_match",
+                    "message": "No matching doors found. Please choose one from 'choices' and call again with 'door_id'.",
+                    "choices": all_choices,
+                    "next_step": "Provide 'door_id' to fetch details.",
+                    "api_calls": api_calls_meta + [
+                        {"method": "GET", "path": "/api/doors?limit=0&order_by=id:true", "status": all_resp.status_code}
+                    ]
+                })
+
+            if len(candidates) == 1:
+                # Auto-resolve by id → fetch detail
+                door_id = candidates[0]["id"]
+                detail = await _fetch_detail(door_id)
+                # Attach api_calls provenance
+                if isinstance(detail, list) and detail and isinstance(detail[0].text, str):
+                    # keep default formatting
+                    return detail
+                if isinstance(detail, dict) and "data" in detail:
+                    # not expected given BaseHandler style; fallback to success_response path already used
+                    return detail
+                # if detail is TextContent list from success_response, enrich is tricky; return as-is
+                return detail
+
+            # Multiple candidates: require user selection
+            return self.success_response({
+                "status": "need_user_input",
+                "reason": "multiple_matches",
+                "message": "Multiple doors matched. Please choose one from 'choices' and call again with 'door_id'.",
+                "choices": candidates,
+                "next_step": "Provide 'door_id' to fetch details.",
+                "api_calls": api_calls_meta
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def _get_device(self, *, device_id: int, headers: Dict[str, str]) -> Optional[Dict[str, Any]]:
+        """Fetch device detail; return None if not found."""
+        async with httpx.AsyncClient(verify=False) as client:
+            r = await client.get(f"{self.session.config.biostar_url}/api/devices/{device_id}", headers=headers)
+        if r.status_code != 200:
+            logger.info(f"Device {device_id} not found or API error: {r.status_code}")
+            return None
+        body = r.json()
+        return body.get("Device", body)
+
+    async def _list_registered_devices(self, headers: Dict[str, str]) -> List[Dict[str, Any]]:
+        """List registered devices from the system."""
+        async with httpx.AsyncClient(verify=False) as client:
+            resp = await client.get(f"{self.session.config.biostar_url}/api/devices", headers=headers)
+        if resp.status_code != 200:
+            logger.warning(f"Failed to list registered devices: {resp.status_code} - {resp.text}")
+            return []
+        data = resp.json()
+        rows = (data.get("DeviceCollection") or {}).get("rows", []) or []
+        return rows
+
+    async def _get_used_device_ids(self, headers: Dict[str, str]) -> Set[str]:
+        """Return a set of device ids that are already linked to any door."""
+        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:
+            logger.warning(f"Failed to fetch doors for used ids: {resp.status_code}")
+            return set()
+        rows = (resp.json().get("DoorCollection") or {}).get("rows", []) or []
+
+        def _extract_dev_id(node: Any) -> Optional[str]:
+            if not isinstance(node, dict):
+                return None
+            if "id" in node and isinstance(node.get("id"), (str, int)):
+                return str(node["id"])
+            if "device_id" in node:
+                dv = node["device_id"]
+                if isinstance(dv, dict) and "id" in dv:
+                    return str(dv["id"])
+                if isinstance(dv, (str, int)):
+                    return str(dv)
+            return None
+
+        used: Set[str] = set()
+        for d in rows:
+            for key in ("entry_device_id", "relay_output_id", "exit_button_input_id", "sensor_input_id"):
+                dev = _extract_dev_id(d.get(key) or {})
+                if dev:
+                    used.add(dev)
+        return used
+
+    async def _device_in_use_by_other_door(self, *, device_id: int, headers: Dict[str, str]) -> Optional[Dict[str, Any]]:
+        """Return door info if the given device_id is already used by a door; otherwise None."""
+        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:
+            raise RuntimeError(f"Failed to fetch doors: {resp.status_code} - {resp.text}")
+
+        rows = (resp.json().get("DoorCollection") or {}).get("rows", []) or []
+
+        def _extract_dev_id(node: Any) -> Optional[str]:
+            # Support both {"id": X} and {"device_id": {"id": X}} shapes
+            if not isinstance(node, dict):
+                return None
+            if "id" in node and isinstance(node.get("id"), (str, int)):
+                return str(node["id"])
+            if "device_id" in node:
+                dv = node["device_id"]
+                if isinstance(dv, dict) and "id" in dv:
+                    return str(dv["id"])
+                if isinstance(dv, (str, int)):
+                    return str(dv)
+            return None
+
+        target = str(device_id)
+        for d in rows:
+            used_ids = set()
+            for key in ("entry_device_id", "relay_output_id", "exit_button_input_id", "sensor_input_id"):
+                dev = _extract_dev_id(d.get(key) or {})
+                if dev:
+                    used_ids.add(dev)
+            if target in used_ids:
+                return {"door_id": d.get("id"), "door_name": d.get("name")}
+        return None
+
+    async def _list_device_relay_indices(self, *, device_id: int, headers: Dict[str, str]) -> List[int]:
+        """Try to infer available relay indices for the device; [] if device missing; fallback [0] when unknown."""
+        dev = await self._get_device(device_id=device_id, headers=headers)
+        if not dev:
+            return []
+
+        # 1) explicit list
+        for key in ("relays", "relay_outputs", "output_relays"):
+            if isinstance(dev.get(key), list) and dev[key]:
+                idxs: List[int] = []
+                for it in dev[key]:
+                    if isinstance(it, dict):
+                        for k2 in ("index", "relay_index", "id"):
+                            if it.get(k2) is not None:
+                                try:
+                                    idxs.append(int(it[k2]))
+                                    break
+                                except Exception:
+                                    continue
+                if idxs:
+                    return sorted(list(set(idxs)))
+
+        # 2) count-based inference
+        for key in ("relay_count", "num_of_relays", "number_of_relays"):
+            if dev.get(key) is not None:
+                try:
+                    cnt = int(dev[key])
+                    return list(range(max(cnt, 1)))
+                except Exception:
+                    pass
+
+        # 3) safe fallback
+        return [0]
+
+    async def _get_door_groups(self, headers: Dict[str, str]) -> List[Dict[str, Any]]:
+        """Return list of door groups for selection prompts."""
+        async with httpx.AsyncClient(verify=False) as client:
+            response = await client.get(
+                f"{self.session.config.biostar_url}/api/door_groups",
+                headers=headers
+            )
+        if response.status_code != 200:
+            logger.warning(f"Failed to fetch door groups: {response.status_code} - {response.text}")
+            return []
+        data = response.json()
+        return (data.get("DoorGroupCollection") or {}).get("rows", []) or []
+
+    async def _udp_search_devices(self, headers: Dict[str, str]) -> Dict[str, Any]:
+        """
+        Try UDP/network discovery endpoints without registering anything.
+        Returns a dict with 'endpoint_used', 'devices' (simplified list).
+        """
+        candidates = [
+            ("GET", "/api/devices/discover"),
+            ("GET", "/api/devices/udp_search"),
+            ("GET", "/api/devices/search"),
+        ]
+        for method, path in candidates:
+            try:
+                async with httpx.AsyncClient(verify=False) as client:
+                    if method == "GET":
+                        resp = await client.get(f"{self.session.config.biostar_url}{path}", headers=headers)
+                    else:
+                        resp = await client.post(f"{self.session.config.biostar_url}{path}", headers=headers)
+                if resp.status_code != 200:
+                    continue
+                data = resp.json()
+                rows = (
+                    (data.get("DeviceCollection") or {}).get("rows", None)
+                    or data.get("devices")
+                    or data.get("rows")
+                )
+                if not isinstance(rows, list):
+                    continue
+
+                simplified: List[Dict[str, Any]] = []
+                for d in rows:
+                    if not isinstance(d, dict):
+                        continue
+                    simplified.append({
+                        "id": d.get("id") or d.get("device_id") or d.get("serial") or d.get("mac"),
+                        "name": d.get("name") or d.get("model_name") or d.get("model"),
+                        "model": d.get("model") or d.get("type"),
+                        "ip": d.get("ip") or d.get("ip_address")
+                    })
+                return {"endpoint_used": path, "devices": simplified}
+            except Exception as ex:
+                logger.info(f"UDP search failed on {path}: {ex}")
+
+        return {"endpoint_used": None, "devices": []}
+
+    async def _list_doors(self, headers: Dict[str, str]) -> List[Dict[str, Any]]:
+        """List doors (rows)."""
+        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:
+            logger.warning(f"Failed to list doors: {resp.status_code} - {resp.text}")
+            return []
+        data = resp.json()
+        return (data.get("DoorCollection") or {}).get("rows", []) or []
+
+    async def _get_door_detail(self, door_id: int, headers: Dict[str, str]) -> Optional[Dict[str, Any]]:
+        """Get a single door detail."""
+        async with httpx.AsyncClient(verify=False) as client:
+            resp = await client.get(f"{self.session.config.biostar_url}/api/doors/{door_id}", headers=headers)
+        if resp.status_code != 200:
+            logger.warning(f"Failed to get door {door_id}: {resp.status_code} - {resp.text}")
+            return None
+        return (resp.json() or {}).get("Door") or {}
+
+    async def _resolve_group_id(
+        self,
+        *,
+        group_id: Optional[int],
+        group_name: Optional[str],
+        headers: Dict[str, str]
+    ) -> Tuple[Optional[int], Optional[str]]:
+        """Resolve group id from (group_id | group_name). Return (id, error_message)."""
+        groups = await self._get_door_groups(headers)
+        if group_id is not None:
+            for g in groups:
+                try:
+                    if int(g.get("id")) == int(group_id):
+                        return int(group_id), None
+                except Exception:
+                    continue
+            return None, f"Group id {group_id} not found."
+        if group_name:
+            matches = [g for g in groups if isinstance(g.get("name"), str) and g["name"].lower() == group_name.lower()]
+            if len(matches) == 1:
+                return int(matches[0]["id"]), None
+            if len(matches) > 1:
+                return None, f"Multiple groups named '{group_name}'. Use group_id. Matches: {[{'id': g.get('id'), 'name': g.get('name')} for g in matches]}"
+            return None, f"Group name '{group_name}' not found."
+        return None, "Either group_id or group_name is required."
+
+    async def _resolve_doors(
+        self,
+        *,
+        door_ids: Optional[List[int]],
+        door_names: Optional[List[str]],
+        headers: Dict[str, str]
+    ) -> Tuple[List[Dict[str, Any]], Optional[str]]:
+        """Resolve doors from ids and/or names. Returns (list of {id, name}, error_message)."""
+        results: Dict[int, Dict[str, Any]] = {}
+
+        # resolve by ids
+        if door_ids:
+            for did in door_ids:
+                detail = await self._get_door_detail(int(did), headers=headers)
+                if not detail:
+                    return [], f"Door id {did} not found."
+                results[int(did)] = {"id": int(did), "name": detail.get("name")}
+
+        # resolve by names
+        if door_names:
+            rows = await self._list_doors(headers)
+            index: Dict[str, List[Dict[str, Any]]] = {}
+            for r in rows:
+                nm = r.get("name")
+                if isinstance(nm, str):
+                    index.setdefault(nm.lower(), []).append({"id": r.get("id"), "name": nm})
+
+            for nm in door_names:
+                cands = index.get(nm.lower(), [])
+                if len(cands) == 0:
+                    return [], f"Door name '{nm}' not found."
+                if len(cands) > 1:
+                    return [], f"Multiple doors found for name '{nm}'. Please specify door_id. Matches: {cands}"
+                d = cands[0]
+                results[int(d["id"])] = {"id": int(d["id"]), "name": d["name"]}
+
+        if not results:
+            return [], "Either door_ids or door_names must be provided."
+
+        return list(results.values()), None
+
+    async def _put_door_group_with_fallbacks(
+        self,
+        *,
+        door_id: int,
+        payloads: List[Dict[str, Any]],
+        headers: Dict[str, str]
+    ) -> Tuple[bool, Optional[str], Optional[str]]:
+        """
+        Try multiple minimal PUT payload variants until success.
+        Returns (ok, last_status, last_text).
+        """
+        last_status = None
+        last_text = None
+        async with httpx.AsyncClient(verify=False) as client:
+            for body in payloads:
+                resp = await client.put(
+                    f"{self.session.config.biostar_url}/api/doors/{door_id}",
+                    headers=headers,
+                    json=body
+                )
+                last_status = str(resp.status_code)
+                last_text = resp.text
+                if resp.status_code in (200, 204):
+                    return True, last_status, last_text
+        return False, last_status, last_text
+    
+    async def _fetch_doors_raw(self, headers: Dict[str, str]) -> List[Dict[str, Any]]:
+        """
+        GET /api/doors and return its 'rows' as-is for strict name matching and validation.
+        """
+        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:
+                logger.error("fetch_doors_raw failed: %s %s", resp.status_code, resp.text)
+                return []
+            data = resp.json() or {}
+            rows = data.get("DoorCollection", {}).get("rows") or data.get("rows") or []
+            return rows
+        except Exception as e:
+            logger.exception("fetch_doors_raw error: %s", e)
+            return []
+
+    async def control_door(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Control door(s) with STRICT selection rules:
+        - NO typo correction. NO fuzzy matching.
+        - If 'door_names' is provided, perform EXACT (case-sensitive) name match.
+        * 0 match  -> return error (door_not_found) + available list, DO NOT control.
+        * >1 match -> return error (ambiguous_name) + candidates, DO NOT control.
+        * 1 match  -> resolve to that door id.
+        - If 'door_ids' is provided, validate existence; unknown ids -> error, DO NOT control.
+        - If both door_ids and door_names are provided, both sets MUST match exactly; else error.
+        - On success, POST /api/doors/{open|lock|unlock|release} with DoorCollection only.
+
+        Also:
+        - Parse DeviceResponse per door to report success/failure/unknown.
+        - DO NOT include 'duration' or any extra field for 'open' (spec compliance).
+        """
+        try:
+            self.check_auth()
+
+            action = str(args["action"]).strip().lower()
+            raw_ids = args.get("door_ids")
+            raw_names = args.get("door_names")
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            # Map actions to endpoints (adjust here if your deployment differs)
+            action_map = {
+                "open": "open",
+                "lock": "lock",
+                "unlock": "unlock",
+                "release": "release",  # change to "normal" etc. if your API uses a different path
+            }
+            if action not in action_map:
+                return self.error_response(
+                    f"Invalid action: {action}. Allowed: {', '.join(action_map.keys())}"
+                )
+
+            # Normalize IDs (accept scalar/str/list)
+            def _norm_ids(raw) -> List[int]:
+                if raw is None:
+                    return []
+                if not isinstance(raw, (list, tuple, set)):
+                    raw = [raw]
+                out, seen = [], set()
+                for x in raw:
+                    s = str(x).strip()
+                    if not s:
+                        continue
+                    try:
+                        v = int(s)
+                        if v not in seen:
+                            seen.add(v); out.append(v)
+                    except Exception:
+                        continue
+                return out
+
+            door_ids_from_ids: List[int] = _norm_ids(raw_ids)
+            door_names_from_args: List[str] = []
+            if raw_names is not None:
+                # accept scalar or list of strings; NO normalization besides trimming
+                if not isinstance(raw_names, (list, tuple, set)):
+                    raw_names = [raw_names]
+                door_names_from_args = [str(n) for n in raw_names]
+
+            if not door_ids_from_ids and not door_names_from_args:
+                return self.error_response(
+                    "Provide either 'door_ids' or 'door_names' for strict selection."
+                )
+
+            # Fetch all doors once for validation/resolution
+            all_rows = await self._fetch_doors_raw(headers)
+            known_id_set: Set[int] = set()
+            by_name: Dict[str, List[Dict[str, Any]]] = {}
+
+            for d in all_rows:
+                did = d.get("id")
+                try:
+                    did_int = int(str(did))
+                    known_id_set.add(did_int)
+                except Exception:
+                    pass
+                nm = str(d.get("name") or "")
+                by_name.setdefault(nm, []).append(d)
+
+            # Resolve names strictly (case-sensitive equals)
+            resolved_from_names: List[int] = []
+            name_not_found: List[str] = []
+            name_ambiguous: List[Dict[str, Any]] = []
+
+            for nm in door_names_from_args:
+                exact = by_name.get(nm, [])
+                if len(exact) == 0:
+                    name_not_found.append(nm)
+                elif len(exact) > 1:
+                    # include rich candidates for the user to choose from
+                    cands = []
+                    for r in exact:
+                        cands.append({
+                            "id": r.get("id"),
+                            "name": r.get("name"),
+                            # include helpful fields if present in your deployment
+                            "door_group_id_list": r.get("door_group_id_list"),
+                            "entry_device_id": r.get("entry_device_id") or r.get("device_id"),
+                            "description": r.get("description")
+                        })
+                    name_ambiguous.append({"name": nm, "candidates": cands})
+                else:
+                    try:
+                        resolved_from_names.append(int(str(exact[0].get("id"))))
+                    except Exception:
+                        name_not_found.append(nm)
+
+            # Hard stop on not-found or ambiguous names
+            if name_not_found or name_ambiguous:
+                return self.error_response(
+                    "Strict name match failed; explicit selection required.",
+                    {
+                        "status": "needs_selection",
+                        "unresolved_names": name_not_found,
+                        "ambiguous": name_ambiguous,
+                        "available_doors": [
+                            {"id": r.get("id"), "name": r.get("name")}
+                            for r in all_rows
+                            if r.get("id") is not None
+                        ]
+                    }
+                )
+
+            # Validate id existence (if provided)
+            unknown_ids = [i for i in door_ids_from_ids if i not in known_id_set]
+            if unknown_ids:
+                return self.error_response(
+                    "Unknown door id(s). No action performed.",
+                    {
+                        "status": "unknown_ids",
+                        "unknown_ids": unknown_ids,
+                        "available_doors": [
+                            {"id": r.get("id"), "name": r.get("name")}
+                            for r in all_rows
+                            if r.get("id") is not None
+                        ]
+                    }
+                )
+
+            # Merge/consistency check if both names and ids are given
+            final_ids: List[int]
+            if door_ids_from_ids and resolved_from_names:
+                set_ids, set_names = set(door_ids_from_ids), set(resolved_from_names)
+                if set_ids != set_names:
+                    return self.error_response(
+                        "door_ids and door_names do not resolve to the same set. No action performed.",
+                        {
+                            "status": "mismatched_selection",
+                            "ids_from_door_ids": sorted(list(set_ids)),
+                            "ids_from_door_names": sorted(list(set_names))
+                        }
+                    )
+                final_ids = sorted(list(set_ids))
+            elif resolved_from_names:
+                final_ids = sorted(list(set(resolved_from_names)))
+            else:
+                final_ids = sorted(list(set(door_ids_from_ids)))
+
+            # Build spec-compliant payload
+            endpoint_action = action_map[action]
+            payload = {
+                "DoorCollection": {
+                    "rows": [{"id": did} for did in final_ids]
+                }
+            }
+
+            async with httpx.AsyncClient(verify=False) as client:
+                resp = await client.post(
+                    f"{self.session.config.biostar_url}/api/doors/{endpoint_action}",
+                    headers=headers,
+                    json=payload
+                )
+
+            if resp.status_code != 200:
+                try:
+                    rj = resp.json() or {}
+                except Exception:
+                    rj = {}
+                dev = rj.get("DeviceResponse")
+                return self.error_response(
+                    f"API call failed: {resp.status_code} - {resp.text}",
+                    {"request_body": payload, "device_response": dev}
+                )
+
+            # Parse DeviceResponse per door
+            try:
+                body = resp.json() or {}
+            except Exception:
+                body = {}
+            device_resp = body.get("DeviceResponse") or {}
+            rows = device_resp.get("rows") or []
+
+            successes: List[int] = []
+            failures: List[Dict[str, Any]] = []
+            requested_set = set(final_ids)
+
+            for r in rows:
+                rid = r.get("id")
+                code = r.get("code")
+                try:
+                    rid_int = int(str(rid))
+                except Exception:
+                    rid_int = None
+                is_ok = (str(code) == "0" or code == 0)
+                if is_ok and rid_int is not None:
+                    successes.append(rid_int)
+                else:
+                    failures.append({
+                        "id": rid if rid is not None else None,
+                        "code": code,
+                        "message": r.get("message")
+                    })
+
+            echoed = {i for i in successes} | {int(str(f["id"])) for f in failures if f.get("id") is not None}
+            unknown_ids_echo = sorted(list(requested_set - echoed))
+
+            summary_msg = (
+                f"{action.capitalize()} executed: "
+                f"{len(successes)} success"
+                f"{', ' + str(len(failures)) + ' failure' if failures else ''}"
+                f"{', ' + str(len(unknown_ids_echo)) + ' unknown' if unknown_ids_echo else ''}."
+            )
+
+            return self.success_response({
+                "message": summary_msg,
+                "action": action,
+                "requested": final_ids,
+                "success_ids": sorted(successes),
+                "failed": failures,
+                "unknown_ids": unknown_ids_echo,
+                "device_response": device_resp,
+                "request_body": payload
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    # ----------------------------
+    # Creation with guarded flow and conflict UDP listing
+    # ----------------------------
+
+    async def create_door(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Create a new door using a guarded flow:
+        - No automatic discovery/registration or automatic door creation with other devices.
+        - If confirm=False (default), returns a plan preview and group list.
+        - On 1:1 conflict, returns only UDP discovery list (filtered to not-in-use devices) and stops.
+        - On success, returns door info and the full list of door groups.
+        """
+        try:
+            self.check_auth()
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            confirm: bool = bool(args.get("confirm", False))
+            default_group_id: int = int(args.get("default_group_id", 1))
+
+            # Minimal fields to start a plan
+            minimal_required = ["name", "entry_device_id"]
+            minimal_missing = [f for f in minimal_required if args.get(f) in (None, "")]
+            if minimal_missing:
+                return self.error_response(
+                    "Missing required fields.",
+                    {"missing_fields": minimal_missing, "required_minimal": minimal_required}
+                )
+
+            entry_device_id = int(args["entry_device_id"])
+
+            # Device must exist; no auto-registration here
+            device = await self._get_device(device_id=entry_device_id, headers=headers)
+            if not device:
+                groups = await self._get_door_groups(headers)
+                return self.error_response(
+                    "Specified device is not registered in the system.",
+                    {
+                        "device_id": entry_device_id,
+                        "available_groups": [{"id": g.get("id"), "name": g.get("name")} for g in groups],
+                        "note": "Register the device first, then retry."
+                    }
+                )
+
+            # Enforce 1:1 mapping
+            conflict = await self._device_in_use_by_other_door(device_id=entry_device_id, headers=headers)
+            if conflict:
+                # UDP discovery only; filter out devices already in use
+                udp_info = await self._udp_search_devices(headers)
+                used_ids = await self._get_used_device_ids(headers)
+                filtered_devices: List[Dict[str, Any]] = []
+                for d in udp_info.get("devices", []):
+                    did = d.get("id")
+                    if did is None:
+                        continue
+                    if str(did) in used_ids:
+                        continue
+                    filtered_devices.append(d)
+
+                # Stop here without any follow-up or hints
+                return self.error_response(
+                    "This device is already mapped to another door (1:1 policy).",
+                    {
+                        "conflict": {
+                            "device_id": entry_device_id,
+                            "door_id": conflict["door_id"],
+                            "door_name": conflict["door_name"]
+                        },
+                        "udp_discovery": {
+                            "endpoint_used": udp_info.get("endpoint_used"),
+                            "devices": filtered_devices
+                        },
+                        "note": "Select one device from the list...y manually. No automatic registration or creation is performed."
+                    }
+                )
+
+            # relay_index must be provided to create; otherwise only show options
+            relay_index = args.get("relay_index", None)
+            if relay_index is None:
+                relay_options = await self._list_device_relay_indices(device_id=entry_device_id, headers=headers)
+                groups = await self._get_door_groups(headers)
+                return self.success_response({
+                    "message": "relay_index is required to create the door.",
+                    "device_id": entry_device_id,
+                    "relay_options": relay_options,
+                    "available_groups": [{"id": g.get("id"), "name": g.get("name")} for g in groups]
+                })
+
+            # Determine group used at creation time
+            create_group_id = int(args.get("door_group_id", default_group_id))
+
+            # ---- XOR-safe mode defaults and validation ----
+            # Default both 'open_once' and 'unconditional_lock' to OFF if not provided.
+            def _b(x, default=False) -> bool:
+                if x is None:
+                    return default
+                if isinstance(x, bool):
+                    return x
+                s = str(x).strip().lower()
+                return s in ("1", "true", "t", "yes", "y")
+
+            desired_open_once = _b(args.get("open_once"), False)  # default OFF
+            desired_auto = _b(args.get("unconditional_lock"), False)  # default OFF
+
+            # XOR rule: they cannot both be true
+            if desired_open_once and desired_auto:
+                return self.error_response(
+                    "Business rule violation: 'open_once' and 'unconditional_lock' cannot both be true on creation.",
+                    {"hint": "Turn one of them off.", "received": {"open_once": True, "unconditional_lock": True}}
+                )
+
+            # Build payload
+            planned_payload: Dict[str, Any] = {
+                "Door": {
+                    "name": args["name"],
+                    "description": args.get("description") or "",
+                    "door_group_id": {"id": create_group_id},
+                    "open_timeout": int(args.get("open_timeout", 10)),
+                    "open_duration": str(int(args.get("open_duration", 5))),
+                    # Enforce defaults (OFF) and XOR-safe values
+                    "open_once": "true" if desired_open_once else "false",
+                    "unconditional_lock": "true" if desired_auto else "false",
+                    "entry_device_id": {"id": entry_device_id},
+                    "relay_output_id": {
+                        "device_id": {"id": entry_device_id},
+                        "relay_index": int(relay_index)
+                    }
+                }
+            }
+
+            # Helper function to safely convert to int
+            def safe_int(value, default=0):
+                """Safely convert value to int, handling 'none', 'false', 'true', etc."""
+                if value is None or value == "" or str(value).lower() == "none":
+                    return default
+                if isinstance(value, bool):
+                    return 1 if value else 0
+                if isinstance(value, str):
+                    if value.lower() == "false":
+                        return 0
+                    if value.lower() == "true":
+                        return 1
+                try:
+                    return int(value)
+                except (ValueError, TypeError):
+                    return default
+            
+            required_for_creation = [
+                "exit_device_id", "exit_input_index", "exit_input_type",
+                "sensor_device_id", "sensor_input_index", "sensor_input_type", "apb_use_door_sensor"
+            ]
+            # Filter out 'none' and invalid values
+            missing_for_creation = [
+                f for f in required_for_creation 
+                if args.get(f) in (None, "", "none") or str(args.get(f)).lower() == "none"
+            ]
+            if not missing_for_creation:
+                planned_payload["Door"]["exit_button_input_id"] = {
+                    "device_id": {"id": safe_int(args["exit_device_id"])},
+                    "input_index": safe_int(args["exit_input_index"]),
+                    "type": str(safe_int(args["exit_input_type"]))
+                }
+                planned_payload["Door"]["sensor_input_id"] = {
+                    "device_id": {"id": safe_int(args["sensor_device_id"])},
+                    "input_index": safe_int(args["sensor_input_index"]),
+                    "type": str(safe_int(args["sensor_input_type"])),
+                    "apb_use_door_sensor": str(safe_int(args["apb_use_door_sensor"]))
+                }
+
+            # Always provide group list in preview
+            groups_for_prompt = await self._get_door_groups(headers)
+
+            if not confirm:
+                return self.success_response({
+                    "message": "Preview the door creation plan.",
+                    "needs_confirmation": True,
+                    "group_prompt": {
+                        "group_used_for_creation": create_group_id,
+                        "available_groups": [{"id": g.get("id"), "name": g.get("name")} for g in groups_for_prompt],
+                        "question": "Would you like to assign the door to one of these groups after creation?"
+                    },
+                    "missing_for_creation": missing_for_creation,
+                    "relay_index": int(relay_index),
+                    "request_body_preview": planned_payload
+                })
+
+            # Confirmed path requires all blocks
+            if missing_for_creation:
+                return self.error_response(
+                    "Missing fields required for confirmed creation.",
+                    {"missing_fields": missing_for_creation, "request_body_preview": planned_payload}
+                )
+
+            # Create now
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.post(
+                    f"{self.session.config.biostar_url}/api/doors",
+                    headers=headers,
+                    json=planned_payload
+                )
+
+            if response.status_code not in (200, 201):
+                return self.error_response(
+                    f"API call failed: {response.status_code} - {response.text}",
+                    {"request_body": planned_payload}
+                )
+
+            try:
+                resp_json = response.json()
+            except Exception:
+                resp_json = {}
+            new_id = (
+                    resp_json.get("Door", {}).get("id")
+                    or resp_json.get("id")
+                    or resp_json.get("Door", {}).get("door_id")
+            )
+
+            # Post-creation: include door groups for optional assignment
+            groups_after = await self._get_door_groups(headers)
+            return self.success_response({
+                "message": f"Door '{args['name']}' has been created.",
+                "door_id": new_id,
+                "request_body": planned_payload,
+                "group_prompt": {
+                    "group_used_for_creation": create_group_id,
+                    "available_groups": [{"id": g.get("id"), "name": g.get("name")} for g in groups_after],
+                    "question": "Would you like to move the door to a specific group now?"
+                }
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def update_door(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Update an existing door."""
+        try:
+            self.check_auth()
+
+            door_id = args["door_id"]
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            # First get existing door data
+            async with httpx.AsyncClient(verify=False) as client:
+                get_response = await client.get(
+                    f"{self.session.config.biostar_url}/api/doors/{door_id}",
+                    headers=headers
+                )
+
+                if get_response.status_code != 200:
+                    return self.error_response(f"Failed to get door: {get_response.status_code}")
+
+                door_data = get_response.json()
+
+                # Update only provided fields
+                if "name" in args:
+                    door_data["Door"]["name"] = args["name"]
+                if "open_duration" in args:
+                    door_data["Door"]["open_duration"] = args["open_duration"]
+                if "open_timeout" in args:
+                    door_data["Door"]["open_timeout"] = args["open_timeout"]
+                if "dual_auth_required" in args:
+                    door_data["Door"]["dual_auth_required"] = args["dual_auth_required"]
+
+                # Update the door
+                update_response = await client.put(
+                    f"{self.session.config.biostar_url}/api/doors/{door_id}",
+                    headers=headers,
+                    json=door_data
+                )
+
+            if update_response.status_code != 200:
+                return self.error_response(f"API call failed: {update_response.status_code} - {update_response.text}")
+
+            return self.success_response({
+                "message": f"Door {door_id} updated successfully"
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def delete_door(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Delete a door."""
+        try:
+            self.check_auth()
+
+            door_id = args["door_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/doors/{door_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"Door {door_id} deleted successfully"
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def get_doors_status(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Get status of doors with normalization, filters, enrichment and summary.
+
+        Features:
+        - Calls POST /api/doors/status with {"monitoring_permission": true} unless overridden.
+        - Normalizes booleans/ints and derives a human-friendly label from open/unlock/alarm.
+        - Optional enrichment to join door names/groups via GET /api/doors?limit=0.
+        - Flexible filters: door_ids, is_open, is_unlocked, has_alarm, status_in, group/name (when enriched).
+        - Returns summary breakdowns and optional device response analysis.
+        - Supports include_raw for debugging and api_calls provenance.
+        """
+        try:
+            self.check_auth()
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            # ---------------- Helpers ----------------
+            def _to_int(x, default=None):
+                try:
+                    return int(str(x))
+                except Exception:
+                    return default
+
+            def _to_bool(x):
+                if isinstance(x, bool):
+                    return x
+                s = str(x).strip().lower()
+                return s in ("1", "true", "t", "yes", "y")
+
+            def _epoch_to_iso(ts) -> Optional[str]:
+                v = _to_int(ts)
+                if v is None or v <= 0:
+                    return None
+                # Interpret as seconds since epoch
+                try:
+                    from datetime import datetime, timezone
+                    return datetime.fromtimestamp(v, tz=timezone.utc).isoformat()
+                except Exception:
+                    return None
+
+            async def _http_with_retry(method: str, url: str, **kwargs) -> httpx.Response:
+                last_exc = None
+                for attempt in range(3):
+                    try:
+                        async with httpx.AsyncClient(
+                            verify=False,
+                            timeout=httpx.Timeout(10.0, read=20.0)
+                        ) as client:
+                            resp = await client.request(method, url, **kwargs)
+                        if resp.status_code >= 500:
+                            await asyncio.sleep(0.6 * (attempt + 1))
+                            continue
+                        return resp
+                    except Exception as e:
+                        last_exc = e
+                        await asyncio.sleep(0.6 * (attempt + 1))
+                raise RuntimeError(f"HTTP temporary failure: {repr(last_exc)}")
+
+            # Heuristic label from flags; 'status' numeric mapping is vendor-specific, so we derive safely.
+            def _derived_label(is_open: bool, is_unlocked: bool, has_alarm: bool) -> str:
+                if has_alarm:
+                    return "Alarm"
+                if is_open and is_unlocked:
+                    return "Open & Unlocked"
+                if is_open and not is_unlocked:
+                    return "Open"
+                if not is_open and is_unlocked:
+                    return "Unlocked"
+                return "Normal"  # closed & locked
+
+            # ---------------- Read args ----------------
+            monitoring_permission = bool(args.get("monitoring_permission", True))
+            include_raw = bool(args.get("include_raw", False))
+            include_enrichment = bool(args.get("include_enrichment", True))  # join door names/groups
+            include_device_response = bool(args.get("include_device_response", True))
+
+            # Basic filters
+            door_ids = args.get("door_ids") or []
+            if isinstance(door_ids, (int, str)):
+                door_ids = [door_ids]
+            door_ids = {_to_int(did) for did in door_ids if _to_int(did) is not None}
+
+            is_open_filter = args.get("is_open")  # None or bool
+            is_unlocked_filter = args.get("is_unlocked")
+            has_alarm_filter = args.get("has_alarm")
+            status_in = args.get("status_in") or []  # list of acceptable status codes as str/int
+            status_in = {str(s) for s in status_in} if status_in else set()
+
+            # Enrichment filters (only applied when include_enrichment=True)
+            group_id_filter = _to_int(args.get("group_id")) if args.get("group_id") is not None else None
+            group_name_filter = (args.get("group_name") or "").strip().lower() or None
+            name_contains_filter = (args.get("name_contains") or "").strip().lower() or None
+
+            # Sorting options
+            sort_by = (args.get("sort_by") or "door_id").strip()  # "door_id" | "name" | "group_name"
+            sort_desc = bool(args.get("sort_desc", False))
+
+            # ---------------- Call Status API ----------------
+            payload = {"monitoring_permission": monitoring_permission}
+            api_calls_meta = []
+            status_resp = await _http_with_retry(
+                "POST",
+                f"{self.session.config.biostar_url}/api/doors/status",
+                headers=headers,
+                json=payload
+            )
+            api_calls_meta.append({"method": "POST", "path": "/api/doors/status", "status": status_resp.status_code, "payload": payload})
+
+            if status_resp.status_code != 200:
+                return self.error_response(f"API call failed: {status_resp.status_code} - {status_resp.text}")
+
+            status_json = status_resp.json() or {}
+            ds_coll = status_json.get("DoorStatusCollection") or {}
+            ds_rows = ds_coll.get("rows") or []
+
+            # DeviceResponse normalization (optional)
+            device_resp_info = None
+            if include_device_response:
+                dev = status_json.get("DeviceResponse") or {}
+                dev_rows = dev.get("rows") or []
+                nonzero = [r for r in dev_rows if str(r.get("code")) not in ("0", "")]
+                device_resp_info = {
+                    "result": _to_bool(dev.get("result", False)),
+                    "rows": [{"id": _to_int(r.get("id")), "code": str(r.get("code"))} for r in dev_rows],
+                    "nonzero_codes": [{"id": _to_int(r.get("id")), "code": str(r.get("code"))} for r in nonzero],
+                    "has_errors": len(nonzero) > 0
+                }
+
+            # ---------------- Optional enrichment: GET /api/doors (name/group join) ----------------
+            door_map = {}  # id -> {name, group:{id,name}}
+            if include_enrichment:
+                doors_resp = await _http_with_retry(
+                    "GET",
+                    f"{self.session.config.biostar_url}/api/doors",
+                    headers=headers,
+                    params={"limit": "0", "order_by": "id:true"}
+                )
+                api_calls_meta.append({"method": "GET", "path": "/api/doors?limit=0&order_by=id:true", "status": doors_resp.status_code})
+                if doors_resp.status_code == 200:
+                    dj = doors_resp.json() or {}
+                    rows = ((dj.get("DoorCollection") or {}).get("rows") or [])
+                    for r in rows:
+                        rid = _to_int((r.get("id")))
+                        if rid is None:
+                            continue
+                        g = r.get("door_group_id") or {}
+                        door_map[rid] = {
+                            "name": r.get("name"),
+                            "group": {"id": _to_int(g.get("id")), "name": g.get("name")}
+                        }
+
+            # ---------------- Normalize each status row ----------------
+            normalized: List[Dict[str, Any]] = []
+            for r in ds_rows:
+                did = _to_int(((r.get("door_id") or {}).get("id")))
+                if did is None:
+                    continue
+                is_open = _to_bool(r.get("opened"))
+                is_unlocked = _to_bool(r.get("unlocked"))
+                has_alarm = _to_bool(r.get("alarm"))
+                status_code = None
+                if r.get("status") is not None:
+                    status_code = str(r.get("status"))
+
+                last_open_epoch = _to_int(r.get("last_open_time"))
+                item = {
+                    "door_id": did,
+                    "is_open": is_open,
+                    "is_unlocked": is_unlocked,
+                    "has_alarm": has_alarm,
+                    "status_code": status_code,                 # pass-through; vendor-specific
+                    "derived_label": _derived_label(is_open, is_unlocked, has_alarm),
+                    "last_open_time_epoch": last_open_epoch,
+                    "last_open_time_iso": _epoch_to_iso(last_open_epoch)
+                }
+
+                if include_enrichment:
+                    meta = door_map.get(did, {})
+                    item["door"] = {
+                        "name": meta.get("name"),
+                        "group": meta.get("group")
+                    }
+
+                if include_raw:
+                    item["raw"] = r
+
+                normalized.append(item)
+
+            # ---------------- Apply filters ----------------
+            def _by_enrichment_group(item) -> bool:
+                if not include_enrichment:
+                    return True
+                g = ((item.get("door") or {}).get("group") or {})
+                if group_id_filter is not None and g.get("id") != group_id_filter:
+                    return False
+                if group_name_filter and group_name_filter not in (g.get("name") or "").lower():
+                    return False
+                if name_contains_filter and name_contains_filter not in (item.get("door") or {}).get("name", "").lower():
+                    return False
+                return True
+
+            filtered = []
+            for it in normalized:
+                if door_ids and it["door_id"] not in door_ids:
+                    continue
+                if is_open_filter is not None and bool(it["is_open"]) != bool(is_open_filter):
+                    continue
+                if is_unlocked_filter is not None and bool(it["is_unlocked"]) != bool(is_unlocked_filter):
+                    continue
+                if has_alarm_filter is not None and bool(it["has_alarm"]) != bool(has_alarm_filter):
+                    continue
+                if status_in and (str(it.get("status_code")) not in status_in):
+                    continue
+                if not _by_enrichment_group(it):
+                    continue
+                filtered.append(it)
+
+            # ---------------- Sort ----------------
+            def _key(it):
+                if sort_by == "name" and include_enrichment:
+                    return (it.get("door") or {}).get("name") or ""
+                if sort_by == "group_name" and include_enrichment:
+                    return ((it.get("door") or {}).get("group") or {}).get("name") or ""
+                return it.get("door_id") or 0
+
+            filtered.sort(key=_key, reverse=sort_desc)
+
+            # ---------------- Summary ----------------
+            total = len(filtered)
+            opened_count = sum(1 for x in filtered if x["is_open"])
+            unlocked_count = sum(1 for x in filtered if x["is_unlocked"])
+            alarm_count = sum(1 for x in filtered if x["has_alarm"])
+
+            # breakdowns
+            from collections import Counter
+            label_breakdown = Counter(x["derived_label"] for x in filtered)
+            status_code_breakdown = Counter(str(x.get("status_code")) for x in filtered)
+
+            groups_breakdown = None
+            if include_enrichment:
+                groups_breakdown = Counter((((x.get("door") or {}).get("group") or {}).get("name") or "Unknown") for x in filtered)
+
+            result = {
+                "message": f"Fetched status for {total} doors",
+                "total": total,
+                "summary": {
+                    "opened": opened_count,
+                    "unlocked": unlocked_count,
+                    "alarms": alarm_count,
+                    "derived_label_breakdown": dict(label_breakdown),
+                    "status_code_breakdown": dict(status_code_breakdown),
+                    "groups_breakdown": dict(groups_breakdown) if groups_breakdown is not None else None
+                },
+                "doors_status": filtered,
+                "api_calls": api_calls_meta
+            }
+
+            if include_device_response and device_resp_info is not None:
+                result["device_responses"] = device_resp_info
+
+            return self.success_response(result)
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def get_door_groups(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Return all door groups (non-breaking) with optional enrichment.
+        - Keep top-level shape: { message, total, groups }
+        - Keep legacy per-group fields: { id, name, description, door_count }
+        - Add optional fields when available: depth, parent, children, child_count, path, door_ids
+        - No change to _get_door_groups(); this method reuses it as the single source of truth.
+        """
+        try:
+            self.check_auth()
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            # -------- helpers (local only) --------
+            def _to_int(x, default=None):
+                try:
+                    return int(str(x))
+                except Exception:
+                    return default
+
+            def _sid(x):
+                """Normalize id to string key for internal mapping; do NOT alter output type."""
+                if x is None:
+                    return None
+                try:
+                    return str(int(str(x)))
+                except Exception:
+                    return str(x)
+
+            # 1) Base list from v1 (kept as single source shared by other methods)
+            v1_rows = await self._get_door_groups(headers)
+            by_id = { _sid(g.get("id")): g for g in v1_rows if _sid(g.get("id")) }
+
+            # Prebuild base nodes, preserving the legacy fields
+            nodes: Dict[str, Dict[str, Any]] = {}
+            needs_doors_scan = False
+            for gid, g in by_id.items():
+                v1_door_ids = g.get("door_id_list") or []
+                if not isinstance(v1_door_ids, list) or not v1_door_ids:
+                    needs_doors_scan = True
+                # NOTE: Do not cast id/name/description types to avoid breaking callers
+                nodes[gid] = {
+                    "id": g.get("id"),
+                    "name": g.get("name"),
+                    "description": g.get("description"),
+                    "door_count": len(v1_door_ids) if isinstance(v1_door_ids, list) else 0,
+                    # Optional fields populated later (non-breaking additions)
+                    "door_ids": v1_door_ids if isinstance(v1_door_ids, list) and v1_door_ids else None,
+                    "depth": None,
+                    "parent": None,
+                    "children": [],
+                    "child_count": 0,
+                    "path": None,
+                }
+
+            # 2) Try to enrich with hierarchy (v2 search) inline (no new helper)
+            id2parent: Dict[str, Optional[str]] = {}
+            id2depth: Dict[str, Optional[int]] = {}
+            order_ids: List[str] = []
+            try:
+                async with httpx.AsyncClient(
+                    verify=False,
+                    timeout=httpx.Timeout(10.0, read=20.0)
+                ) as client:
+                    v2_resp = await client.post(
+                        f"{self.session.config.biostar_url}/api/v2/door_groups/only_permission_item/search",
+                        headers=headers,
+                        json={"order_by": "depth:false"}  # root first
+                    )
+                if v2_resp.status_code == 200:
+                    v2_json = v2_resp.json() or {}
+                    v2_rows = ((v2_json.get("DoorGroupCollection") or {}).get("rows") or []) or []
+                    for r in v2_rows:
+                        gid = _sid(r.get("id"))
+                        if not gid or gid not in nodes:
+                            continue
+                        order_ids.append(gid)
+                        id2depth[gid] = _to_int(r.get("depth"))
+                        p = r.get("parent_id") or {}
+                        id2parent[gid] = _sid(p.get("id")) if isinstance(p, dict) else None
+            except Exception as ex:
+                # Best-effort enrichment; never fail the tool on v2 issues
+                logger.info("get_door_groups: v2 enrichment skipped due to error: %s", ex)
+
+            # 3) If door_ids missing, compute from /api/doors once
+            if needs_doors_scan:
+                try:
+                    async with httpx.AsyncClient(
+                        verify=False,
+                        timeout=httpx.Timeout(10.0, read=20.0)
+                    ) as client:
+                        d_resp = await client.get(
+                            f"{self.session.config.biostar_url}/api/doors",
+                            headers=headers,
+                            params={"limit": "0", "order_by": "id:true"}
+                        )
+                    if d_resp.status_code == 200:
+                        d_json = d_resp.json() or {}
+                        d_rows = ((d_json.get("DoorCollection") or {}).get("rows") or [])
+                        for d in d_rows:
+                            gid = _sid((d.get("door_group_id") or {}).get("id"))
+                            did = d.get("id")
+                            if gid and gid in nodes and did is not None:
+                                # initialize list lazily to avoid writing empty lists
+                                if nodes[gid].get("door_ids") is None:
+                                    nodes[gid]["door_ids"] = []
+                                nodes[gid]["door_ids"].append(did)
+                        # refresh door_count after scan
+                        for g in nodes.values():
+                            if isinstance(g.get("door_ids"), list):
+                                g["door_count"] = len(g["door_ids"])
+                except Exception as ex:
+                    logger.info("get_door_groups: doors scan skipped due to error: %s", ex)
+
+            # 4) Link parent/children and compute path if v2 data exists
+            if id2parent:
+                children_index: Dict[str, List[str]] = {}
+                for gid in nodes.keys():
+                    pid = id2parent.get(_sid(gid))
+                    if pid:
+                        children_index.setdefault(pid, []).append(_sid(gid))
+
+                for gid, node in nodes.items():
+                    sid = _sid(gid)
+                    # depth
+                    node["depth"] = id2depth.get(sid)
+                    # parent
+                    pid = id2parent.get(sid)
+                    if pid and pid in nodes:
+                        node["parent"] = {"id": nodes[pid]["id"], "name": nodes[pid]["name"]}
+                    # children
+                    ch = children_index.get(sid, [])
+                    node["children"] = [{"id": nodes[c]["id"], "name": nodes[c]["name"]} for c in ch if c in nodes]
+                    node["child_count"] = len(node["children"])
+
+                def _path(sid: str) -> str:
+                    chain = []
+                    cur = sid
+                    guard = 0
+                    while cur and cur in nodes and guard < 128:
+                        chain.append(nodes[cur]["name"])
+                        cur = id2parent.get(cur)
+                        guard += 1
+                    chain.reverse()
+                    return " / ".join([s for s in chain if isinstance(s, str) and s.strip()])
+
+                for gid in list(nodes.keys()):
+                    sid = _sid(gid)
+                    nodes[sid]["path"] = _path(sid)
+
+            # 5) Decide output order: prefer v2 order (depth:false), else insertion order
+            if order_ids:
+                ordered_ids = [gid for gid in order_ids if gid in nodes]
+            else:
+                ordered_ids = list(nodes.keys())
+
+            groups_out = [nodes[gid] for gid in ordered_ids]
+
+            return self.success_response({
+                "message": f"Found {len(groups_out)} door groups",
+                "total": len(groups_out),
+                "groups": groups_out
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+
+    async def get_door_group(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Get one door group by id OR name (non-breaking):
+        - Backwards compatible: if group_id is given, behave like before.
+        - If group_name is given, resolve to id using robust name matching:
+        exact -> iexact (NFKC+lower) -> icontains (NFKC+lower).
+        - Optional enrichment:
+        * include_hierarchy=True: depth/parent/path/children
+        * include_doors=True: door_ids
+        * include_doors_detail=True: full door objects (joins via /api/doors)
+        """
+        try:
+            self.check_auth()
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            # ---------- args ----------
+            group_id_arg = args.get("group_id", None)
+            group_name_arg = args.get("group_name", None)
+            name_match_mode = str(args.get("name_match_mode", "auto")).lower()
+            include_hierarchy = bool(args.get("include_hierarchy", True))
+            include_doors = bool(args.get("include_doors", True))
+            include_doors_detail = bool(args.get("include_doors_detail", False))
+            include_raw = bool(args.get("include_raw", False))
+
+            # ---------- helpers ----------
+            def _to_int(x, default=None):
+                try:
+                    return int(str(x))
+                except Exception:
+                    return default
+
+            def _sid(x):
+                if x is None:
+                    return None
+                try:
+                    return str(int(str(x)))
+                except Exception:
+                    return str(x)
+
+            def _norm(s: str) -> str:
+                if not isinstance(s, str):
+                    return ""
+                return unicodedata.normalize("NFKC", s).strip()
+
+            async def _http_with_retry(method: str, url: str, **kwargs) -> httpx.Response:
+                last_exc = None
+                for attempt in range(3):
+                    try:
+                        async with httpx.AsyncClient(
+                            verify=False,
+                            timeout=httpx.Timeout(10.0, read=20.0)
+                        ) as client:
+                            resp = await client.request(method, url, **kwargs)
+                        if resp.status_code >= 500:
+                            await asyncio.sleep(0.6 * (attempt + 1))
+                            continue
+                        return resp
+                    except Exception as e:
+                        last_exc = e
+                        await asyncio.sleep(0.6 * (attempt + 1))
+                raise RuntimeError(f"HTTP temporary failure: {repr(last_exc)}")
+
+            # ---------- resolve group_id (by id or by name) ----------
+            resolved_group_id: Optional[int] = None
+
+            if group_id_arg is not None:
+                resolved_group_id = _to_int(group_id_arg)
+                if resolved_group_id is None:
+                    return self.error_response("Invalid 'group_id'.")
+            elif group_name_arg:
+                # list all groups once
+                groups = await self._get_door_groups(headers)
+                if not groups:
+                    return self.error_response("No door groups available to resolve by name.")
+
+                # build normalized buckets
+                q_raw = str(group_name_arg)
+                q = _norm(q_raw)
+                groups_aug = []
+                for g in groups:
+                    nm = g.get("name")
+                    groups_aug.append({
+                        **g,
+                        "__name": nm,
+                        "__norm": _norm(nm if isinstance(nm, str) else "")
+                    })
+
+                exact = [g for g in groups_aug if g["__name"] == q_raw]
+                iexact = [g for g in groups_aug if g["__norm"].lower() == q.lower()]
+                icontains = [g for g in groups_aug if q.lower() in g["__norm"].lower()]
+
+                if name_match_mode == "exact":
+                    chosen = exact
+                elif name_match_mode == "iexact":
+                    chosen = iexact
+                elif name_match_mode == "contains":
+                    chosen = [g for g in groups_aug if q_raw in (g["__name"] or "")]
+                elif name_match_mode == "icontains":
+                    chosen = icontains
+                else:
+                    # auto ladder: prefer single unique match
+                    chosen = None
+                    for bucket in (exact, iexact, icontains):
+                        if len(bucket) == 1:
+                            chosen = bucket
+                            break
+                    if chosen is None:
+                        chosen = exact or iexact or icontains
+
+                if not chosen:
+                    # nothing matched → provide choices
+                    choices = [{"id": g.get("id"), "name": g.get("name")} for g in groups if g.get("id") is not None]
+                    return self.success_response({
+                        "status": "need_user_input",
+                        "reason": "no_match",
+                        "message": "No matching group found. Choose one and call again with 'group_id'.",
+                        "choices": choices,
+                        "next_step": "Provide 'group_id'."
+                    })
+
+                if len(chosen) > 1:
+                    # try to enrich choices with simple tree path
+                    choice_out = [{"id": g.get("id"), "name": g.get("name")} for g in chosen if g.get("id") is not None]
+                    if include_hierarchy:
+                        try:
+                            v2 = await _http_with_retry(
+                                "POST",
+                                f"{self.session.config.biostar_url}/api/v2/door_groups/only_permission_item/search",
+                                headers=headers,
+                                json={"order_by": "depth:false"}
+                            )
+                            if v2.status_code == 200:
+                                tree = (v2.json() or {}).get("DoorGroupCollection", {}).get("rows", []) or []
+                                by_id = { _sid(r.get("id")): r for r in tree }
+                                def _path(gid):
+                                    path = []
+                                    cur = by_id.get(_sid(gid))
+                                    guard = 0
+                                    while cur and guard < 64:
+                                        path.append(cur.get("name"))
+                                        pid = _sid((cur.get("parent_id") or {}).get("id"))
+                                        cur = by_id.get(pid)
+                                        guard += 1
+                                    return " / ".join(reversed([p for p in path if isinstance(p, str)]))
+                                choice_out = [{"id": g["id"], "name": g["name"], "path": _path(g["id"])} for g in choice_out]
+                        except Exception:
+                            pass
+
+                    return self.success_response({
+                        "status": "need_user_input",
+                        "reason": "multiple_matches",
+                        "message": "Multiple groups matched. Choose one and call again with 'group_id'.",
+                        "choices": choice_out,
+                        "next_step": "Provide 'group_id'."
+                    })
+
+                resolved_group_id = _to_int(chosen[0].get("id"))
+
+            else:
+                return self.error_response("Either 'group_id' or 'group_name' is required.")
+
+            # ---------- fetch base detail by id ----------
+            resp = await _http_with_retry(
+                "GET",
+                f"{self.session.config.biostar_url}/api/door_groups/{resolved_group_id}",
+                headers=headers
+            )
+            if resp.status_code != 200:
+                return self.error_response(f"API call failed: {resp.status_code} - {resp.text}")
+
+            body = resp.json() or {}
+            g = (body.get("DoorGroup") or {})
+
+            out = {
+                "id": g.get("id"),
+                "name": g.get("name"),
+                "description": g.get("description"),
+                "door_ids": g.get("door_id_list", []) or None  # some deployments omit this
+            }
+
+            # ---------- enrichment: hierarchy ----------
+            if include_hierarchy:
+                try:
+                    v2 = await _http_with_retry(
+                        "POST",
+                        f"{self.session.config.biostar_url}/api/v2/door_groups/only_permission_item/search",
+                        headers=headers,
+                        json={"order_by": "depth:false"}
+                    )
+                    if v2.status_code == 200:
+                        rows = (v2.json() or {}).get("DoorGroupCollection", {}).get("rows", []) or []
+                        by_id = { _sid(r.get("id")): r for r in rows }
+                        sid = _sid(out["id"])
+                        cur = by_id.get(sid)
+                        # depth
+                        try:
+                            out["depth"] = _to_int((cur or {}).get("depth"))
+                        except Exception:
+                            out["depth"] = None
+                        # parent
+                        pid = _sid(((cur or {}).get("parent_id") or {}).get("id"))
+                        if pid and pid in by_id:
+                            out["parent"] = {"id": by_id[pid].get("id"), "name": by_id[pid].get("name")}
+                        # children
+                        children = [r for r in rows if _sid(((r.get("parent_id") or {}).get("id"))) == sid]
+                        out["children"] = [{"id": c.get("id"), "name": c.get("name")} for c in children]
+                        out["child_count"] = len(out["children"])
+                        # path
+                        def _path(gid):
+                            chain = []
+                            cur2 = by_id.get(_sid(gid))
+                            guard = 0
+                            while cur2 and guard < 64:
+                                chain.append(cur2.get("name"))
+                                pid2 = _sid(((cur2.get("parent_id") or {}).get("id")))
+                                cur2 = by_id.get(pid2)
+                                guard += 1
+                            return " / ".join(reversed([p for p in chain if isinstance(p, str) and p.strip()]))
+                        out["path"] = _path(out["id"])
+                except Exception as ex:
+                    logger.info("get_door_group: hierarchy enrichment skipped: %s", ex)
+
+            # ---------- enrichment: doors (ids + optional details) ----------
+            if include_doors and (not isinstance(out.get("door_ids"), list) or not out.get("door_ids")):
+                # Build door_ids by scanning all doors (one shot)
+                try:
+                    d_resp = await _http_with_retry(
+                        "GET",
+                        f"{self.session.config.biostar_url}/api/doors",
+                        headers=headers,
+                        params={"limit": "0", "order_by": "id:true"}
+                    )
+                    if d_resp.status_code == 200:
+                        d_json = d_resp.json() or {}
+                        d_rows = ((d_json.get("DoorCollection") or {}).get("rows") or [])
+                        gids = _sid(out["id"])
+                        door_ids = []
+                        for d in d_rows:
+                            if _sid((d.get("door_group_id") or {}).get("id")) == gids:
+                                door_ids.append(d.get("id"))
+                        out["door_ids"] = door_ids or None
+                except Exception as ex:
+                    logger.info("get_door_group: door scan skipped: %s", ex)
+
+            if include_doors_detail and isinstance(out.get("door_ids"), list) and out["door_ids"]:
+                # Join brief details from /api/doors (single GET, no N calls)
+                try:
+                    d_resp = await _http_with_retry(
+                        "GET",
+                        f"{self.session.config.biostar_url}/api/doors",
+                        headers=headers,
+                        params={"limit": "0", "order_by": "id:true"}
+                    )
+                    if d_resp.status_code == 200:
+                        d_json = d_resp.json() or {}
+                        d_rows = ((d_json.get("DoorCollection") or {}).get("rows") or [])
+                        idset = { _to_int(x) for x in out["door_ids"] if _to_int(x) is not None }
+                        joined = []
+                        for d in d_rows:
+                            did = _to_int(d.get("id"))
+                            if did in idset:
+                                gmeta = d.get("door_group_id") or {}
+                                joined.append({
+                                    "id": did,
+                                    "name": d.get("name"),
+                                    "description": d.get("description"),
+                                    "group": {"id": _to_int(gmeta.get("id")), "name": gmeta.get("name")}
+                                })
+                        if joined:
+                            out["doors"] = joined
+                except Exception as ex:
+                    logger.info("get_door_group: doors detail join skipped: %s", ex)
+
+            if include_raw:
+                out["raw"] = g
+
+            # keep top-level shape backward-compatible
+            return self.success_response({"group": out})
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def create_door_group(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Create a new door group."""
+        try:
+            self.check_auth()
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            # Build payload matching BioStar API format
+            group_name = args["name"]
+            parent_id = args.get("parent_id", 1)  # Default to root group (ID: 1)
+            depth = args.get("depth", 1)  # Default depth: 1
+            
+            # 1) Check if group already exists
+            async with httpx.AsyncClient(verify=False) as client:
+                existing_resp = await client.get(
+                    f"{self.session.config.biostar_url}/api/door_groups",
+                    headers=headers
+                )
+            
+            if existing_resp.status_code == 200:
+                existing_data = existing_resp.json()
+                rows = existing_data.get("DoorGroupCollection", {}).get("rows", [])
+                for row in rows:
+                    existing_name = row.get("name", "")
+                    if existing_name.strip().lower() == group_name.strip().lower():
+                        existing_id = row.get("id")
+                        logger.info(f"Door group '{group_name}' already exists (ID: {existing_id})")
+                        return self.success_response({
+                            "message": f"Door group '{group_name}' already exists. Skipping creation.",
+                            "group_id": existing_id,
+                            "exists": True
+                        })
+            
+            group_data = {
+                "DoorGroup": {
+                    "parent_id": {"id": str(parent_id)},
+                    "isDoorGroups": True,
+                    "depth": depth,
+                    "sync_device_groups": [],
+                    "sync_devices": [],
+                    "inherited": True,
+                    "iconCls": "doorGroupIcon",
+                    "text": group_name,
+                    "name": group_name
+                }
+            }
+            
+            logger.info(f"Creating door group with payload: {json.dumps(group_data, indent=2)}")
+
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.post(
+                    f"{self.session.config.biostar_url}/api/door_groups",
+                    headers=headers,
+                    json=group_data
+                )
+
+            if response.status_code not in [200, 201]:
+                logger.error(f"Door group creation failed: {response.status_code} - {response.text}")
+                return self.error_response(f"API call failed: {response.status_code} - {response.text}")
+
+            result = response.json()
+            group_id = result.get("DoorGroup", {}).get("id") or result.get("id")
+
+            return self.success_response({
+                "message": f"Door group '{group_name}' created successfully",
+                "group_id": group_id,
+                "parent_id": parent_id,
+                "depth": depth
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def update_door_group(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Update an existing door group."""
+        try:
+            self.check_auth()
+
+            group_id = args["group_id"]
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            # Build update data with only name and parent_id
+            group_data = {
+                "DoorGroup": {}
+            }
+
+            # Add name if provided
+            if "name" in args:
+                group_data["DoorGroup"]["name"] = args["name"]
+
+            # Add parent_id if provided
+            if "parent_id" in args:
+                group_data["DoorGroup"]["parent_id"] = {
+                    "id": args["parent_id"]
+                }
+
+            # Make sure we have something to update
+            if not group_data["DoorGroup"]:
+                return self.error_response("No fields to update. Provide 'name' or 'parent_id'.")
+
+            async with httpx.AsyncClient(verify=False) as client:
+                # Update the group
+                update_response = await client.put(
+                    f"{self.session.config.biostar_url}/api/door_groups/{group_id}",
+                    headers=headers,
+                    json=group_data
+                )
+
+            if update_response.status_code != 200:
+                return self.error_response(f"API call failed: {update_response.status_code} - {update_response.text}")
+
+            return self.success_response({
+                "message": f"Door group {group_id} updated successfully"
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def delete_door_group(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Delete a door 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/door_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"Door group {group_id} deleted successfully"
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def add_doors_to_group(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Assign one or more doors to the specified (single) group.
+
+        Rules (single-membership):
+        - If door already in the target group -> unchanged
+        - If door in a different group:
+            * force=false -> conflict
+            * force=true  -> overwrite to target group (PUT {"Door": {"door_group_id": {"id": <target>}}})
+        """
+        try:
+            self.check_auth()
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            # Resolve group
+            gid, gerr = await self._resolve_group_id(
+                group_id=args.get("group_id"),
+                group_name=args.get("group_name"),
+                headers=headers
+            )
+            if gerr:
+                groups = await self._get_door_groups(headers)
+                return self.error_response(
+                    gerr,
+                    {"available_groups": [{"id": g.get("id"), "name": g.get("name")} for g in groups]}
+                )
+            target_gid = int(gid)
+
+            # Resolve doors
+            doors, derr = await self._resolve_doors(
+                door_ids=args.get("door_ids"),
+                door_names=args.get("door_names"),
+                headers=headers
+            )
+            if derr:
+                return self.error_response(derr)
+
+            force: bool = bool(args.get("force", False))
+
+            updated: List[Dict[str, Any]] = []
+            unchanged: List[Dict[str, Any]] = []
+            conflicts: List[Dict[str, Any]] = []
+            failures: List[Dict[str, Any]] = []
+
+            for d in doors:
+                did = int(d["id"])
+                ddetail = await self._get_door_detail(did, headers)
+                if not ddetail:
+                    failures.append({"door_id": did, "name": d.get("name"), "reason": "door not found"})
+                    continue
+
+                # single-membership only
+                dg = ddetail.get("door_group_id") or {}
+                current_gid = None
+                if isinstance(dg, dict) and dg.get("id") is not None:
+                    try:
+                        current_gid = int(dg.get("id"))
+                    except Exception:
+                        current_gid = None
+
+                if current_gid == target_gid:
+                    unchanged.append({"door_id": did, "name": d.get("name"), "reason": "already in group"})
+                    continue
+
+                if current_gid is not None and current_gid != target_gid and not force:
+                    conflicts.append({
+                        "door_id": did, "name": d.get("name"),
+                        "current_group_id": current_gid, "target_group_id": target_gid
+                    })
+                    continue
+
+                # Overwrite/Assign to target (minimal payload)
+                payloads = [
+                    {"Door": {"door_group_id": {"id": target_gid}}}
+                ]
+                ok, st, txt = await self._put_door_group_with_fallbacks(door_id=did, payloads=payloads, headers=headers)
+                if ok:
+                    updated.append({"door_id": did, "name": d.get("name"), "assigned_group_id": target_gid})
+                else:
+                    failures.append({"door_id": did, "name": d.get("name"), "status": st, "error": txt})
+
+            return self.success_response({
+                "message": f"Processed {len(doors)} door(s) for assignment to group {target_gid}.",
+                "summary": {
+                    "updated": len(updated),
+                    "unchanged": len(unchanged),
+                    "conflicts": len(conflicts),
+                    "failed": len(failures)
+                },
+                "updated": updated,
+                "unchanged": unchanged,
+                "conflicts": conflicts,
+                "failed": failures
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def remove_doors_from_group(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Remove one or more doors from the specified group (single-membership system).
+
+        Since clearing to null/empty is not allowed, if the door is currently in that group,
+        it must be reassigned to another group based on fallback_mode:
+        - "auto"  (default): pick a root-like/default group (exclude the group being removed)
+        - "ask"   : do nothing; return candidates + needs_fallback_choice=true
+        - "assign": reassign to provided fallback_group_id
+        """
+        try:
+            self.check_auth()
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            # fallback parameters
+            fallback_mode = str(args.get("fallback_mode", "auto")).lower()
+            explicit_fallback_gid = args.get("fallback_group_id")
+            if fallback_mode == "assign" and explicit_fallback_gid is None:
+                return self.error_response("fallback_mode is 'assign' but fallback_group_id is missing.")
+
+            # Resolve group to remove from
+            gid, gerr = await self._resolve_group_id(
+                group_id=args.get("group_id"),
+                group_name=args.get("group_name"),
+                headers=headers
+            )
+            if gerr:
+                groups = await self._get_door_groups(headers)
+                return self.error_response(
+                    gerr,
+                    {"available_groups": [{"id": g.get("id"), "name": g.get("name")} for g in groups]}
+                )
+            target_gid = int(gid)
+
+            # Resolve doors
+            doors, derr = await self._resolve_doors(
+                door_ids=args.get("door_ids"),
+                door_names=args.get("door_names"),
+                headers=headers
+            )
+            if derr:
+                return self.error_response(derr)
+
+            updated: List[Dict[str, Any]] = []
+            unchanged: List[Dict[str, Any]] = []
+            failures: List[Dict[str, Any]] = []
+
+            for d in doors:
+                did = int(d["id"])
+                ddetail = await self._get_door_detail(did, headers)
+                if not ddetail:
+                    failures.append({"door_id": did, "name": d.get("name"), "reason": "door not found"})
+                    continue
+
+                # single-membership only
+                dg = ddetail.get("door_group_id") or {}
+                current_gid = None
+                if isinstance(dg, dict) and dg.get("id") is not None:
+                    try:
+                        current_gid = int(dg.get("id"))
+                    except Exception:
+                        current_gid = None
+
+                if current_gid is None:
+                    unchanged.append({"door_id": did, "name": d.get("name"), "reason": "no group assigned"})
+                    continue
+                if current_gid != target_gid:
+                    unchanged.append({"door_id": did, "name": d.get("name"), "reason": f"assigned to different group ({current_gid})"})
+                    continue
+
+                # current_gid == target_gid → reassign according to fallback_mode
+                if fallback_mode == "assign":
+                    fallback_gid = int(explicit_fallback_gid)
+                    if fallback_gid == target_gid:
+                        failures.append({"door_id": did, "name": d.get("name"), "reason": "fallback_group_id equals target group"})
+                        continue
+                elif fallback_mode == "ask":
+                    fc = await self._fallback_candidates(headers=headers, exclude_group_id=target_gid)
+                    return self.success_response({
+                        "needs_fallback_choice": True,
+                        "reason": "Removal would leave the door with no group.",
+                        "door": {"id": did, "name": d.get("name")},
+                        "group_being_removed": target_gid,
+                        "candidates": fc["candidates"],
+                        "suggested_fallback_group_id": fc["suggested_fallback_group_id"],
+                        "hint": "Call remove-doors-from-group again with fallback_mode='assign' and fallback_group_id=<id>."
+                    })
+                else:  # auto
+                    fallback_gid = await self._choose_fallback_group_id(headers=headers, exclude_group_id=target_gid)
+                    if fallback_gid is None:
+                        failures.append({"door_id": did, "name": d.get("name"), "reason": "no fallback group available"})
+                        continue
+
+                # Reassign to fallback group (minimal payload)
+                payloads = [
+                    {"Door": {"door_group_id": {"id": int(fallback_gid)}}}
+                ]
+                ok, st, txt = await self._put_door_group_with_fallbacks(door_id=did, payloads=payloads, headers=headers)
+                if ok:
+                    updated.append({"door_id": did, "name": d.get("name"), "reassigned_group_id": int(fallback_gid)})
+                else:
+                    failures.append({"door_id": did, "name": d.get("name"), "status": st, "error": txt})
+
+            return self.success_response({
+                "message": f"Processed {len(doors)} door(s) for removal from group {target_gid}.",
+                "summary": {
+                    "updated": len(updated),
+                    "unchanged": len(unchanged),
+                    "failed": len(failures)
+                },
+                "updated": updated,
+                "unchanged": unchanged,
+                "failed": failures
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+
+    async def _choose_fallback_group_id(
+        self, *, headers: Dict[str, str], exclude_group_id: Optional[int] = None
+    ) -> Optional[int]:
+        groups = await self._get_door_groups(headers)
+
+        ex = None
+        if exclude_group_id is not None:
+            try:
+                ex = int(exclude_group_id)
+            except Exception:
+                ex = None
+
+        def _id(g):
+            try:
+                return int(g.get("id"))
+            except Exception:
+                return None
+
+        def _name(g):
+            return (g.get("name") or "").strip().lower()
+
+        # 이름 기반 우선 후보
+        preferred = {"all door groups", "all doors", "기본", "전체", "default"}
+        for g in groups:
+            gid = _id(g)
+            if gid is None or (ex is not None and gid == ex):
+                continue
+            if _name(g) in preferred:
+                return gid
+
+        # id == 1 시도
+        for g in groups:
+            gid = _id(g)
+            if gid == 1 and (ex is None or gid != ex):
+                return gid
+
+        # 남은 것 중 가장 작은 id
+        cands = sorted([_id(g) for g in groups if _id(g) is not None and (ex is None or _id(g) != ex)])
+        return cands[0] if cands else None
+
+
+    async def _fallback_candidates(
+        self, *, headers: Dict[str, str], exclude_group_id: Optional[int] = None
+    ) -> Dict[str, Any]:
+        groups = await self._get_door_groups(headers)
+
+        ex = None
+        if exclude_group_id is not None:
+            try:
+                ex = int(exclude_group_id)
+            except Exception:
+                ex = None
+
+        cands: List[Dict[str, Any]] = []
+        for g in groups:
+            try:
+                gid = int(g.get("id"))
+            except Exception:
+                continue
+            if ex is not None and gid == ex:
+                continue
+            cands.append({"id": gid, "name": g.get("name")})
+
+        suggested = await self._choose_fallback_group_id(headers=headers, exclude_group_id=exclude_group_id)
+        return {"candidates": cands, "suggested_fallback_group_id": suggested}
+    async def update_door_description(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Update only the 'description' of an existing door (minimal PUT payload).
+        Spec:
+        - PUT /api/doors/:id
+        - Body: {"Door": {"description": "<text>"}}
+        Behavior:
+        - Sends ONLY the description field; no other fields are fetched or sent.
+        - Returns success on HTTP 200 or 204.
+        """
+        try:
+            self.check_auth()
+
+            # --- args validation ---
+            try:
+                door_id = int(args["door_id"])
+            except Exception:
+                return self.error_response("Invalid 'door_id'. Must be an integer.")
+
+            # Allow empty string to clear the description explicitly.
+            description = str(args.get("description", ""))
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+            body = {"Door": {"description": description}}
+
+            async with httpx.AsyncClient(
+                verify=False,
+                timeout=httpx.Timeout(10.0, read=20.0)
+            ) as client:
+                resp = await client.put(
+                    f"{self.session.config.biostar_url}/api/doors/{door_id}",
+                    headers=headers,
+                    json=body
+                )
+
+            if resp.status_code not in (200, 204):
+                # Surface API error details for debugging
+                return self.error_response(
+                    f"API call failed: {resp.status_code} - {resp.text}",
+                    {"request_body": body}
+                )
+
+            return self.success_response({
+                "message": f"Door {door_id} description updated.",
+                "door_id": door_id,
+                "request_body": body
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def set_door_auto_mode(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Idempotent toggle for 'auto door' (unconditional_lock) with XOR rule enforcement against open_once.
+        - If enable=true and open_once is currently true -> reject with business-rule message.
+        - If state is already desired -> return NO-OP.
+        - Otherwise PUT with preserved fields and the single change applied.
+        """
+        try:
+            self.check_auth()
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            if "enable" not in args:
+                return self.error_response("'enable' is required (true|false).")
+            desired_enable = bool(args["enable"])
+
+            # Resolve door id
+            door_id = None
+            if args.get("door_id") is not None:
+                try:
+                    door_id = int(args["door_id"])
+                except Exception:
+                    return self.error_response("Invalid 'door_id'. Must be an integer.")
+            else:
+                name = (args.get("door_name") or "").strip()
+                if not name:
+                    return self.error_response("Either 'door_id' or 'door_name' must be provided.")
+                # assume you have a resolver
+                resolved, err = await self._resolve_doors(door_ids=None, door_names=[name], headers=headers)
+                if err:
+                    return self.error_response(err)
+                door_id = int(resolved[0]["id"])
+
+            # Fetch current state
+            raw = await self._get_door_detail(door_id, headers=headers)
+            cur_auto = self._to_bool(raw.get("unconditional_lock"))
+            cur_relock = self._to_bool(raw.get("open_once"))
+
+            # XOR guard
+            if desired_enable and cur_relock:
+                return self.error_response(
+                    "Cannot enable 'auto door' because 'relock on close' is currently enabled (XOR rule)."
+                )
+
+            # Idempotency
+            if cur_auto == desired_enable:
+                return self.success_response({
+                    "message": f"Door {door_id}: unconditional_lock already {'enabled' if cur_auto else 'disabled'}.",
+                    "door_id": door_id,
+                    "unchanged": True,
+                    "current_value": cur_auto
+                })
+
+            # Build preserving payload with override
+            overrides = {"unconditional_lock": self._bool_str(desired_enable)}
+            body = self._build_preserving_payload(raw, overrides)
+
+            # PUT
+            async with httpx.AsyncClient(verify=False, timeout=httpx.Timeout(10.0, read=20.0)) as client:
+                resp = await client.put(
+                    f"{self.session.config.biostar_url}/api/doors/{door_id}",
+                    headers=headers,
+                    json=body
+                )
+            if resp.status_code not in (200, 204):
+                return self.error_response(f"API call failed: {resp.status_code} - {resp.text}", {"request_body": body})
+
+            return self.success_response({
+                "message": f"Door {door_id}: unconditional_lock set to {desired_enable}.",
+                "door_id": door_id,
+                "previous_value": cur_auto,
+                "new_value": desired_enable,
+                "request_body": body
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def set_door_relock_on_close(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Idempotent toggle for 'relock on close' (open_once) with XOR rule enforcement against unconditional_lock.
+        - If enable=true and unconditional_lock is currently true -> reject (XOR rule).
+        - If state is already desired -> NO-OP.
+        - Otherwise PUT with preserved fields and the single change applied.
+        """
+        try:
+            self.check_auth()
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            if "enable" not in args:
+                return self.error_response("'enable' is required (true|false).")
+            desired_enable = bool(args["enable"])
+
+            # Resolve door id
+            door_id = None
+            if args.get("door_id") is not None:
+                try:
+                    door_id = int(args["door_id"])
+                except Exception:
+                    return self.error_response("Invalid 'door_id'. Must be an integer.")
+            else:
+                name = (args.get("door_name") or "").strip()
+                if not name:
+                    return self.error_response("Either 'door_id' or 'door_name' must be provided.")
+                resolved, err = await self._resolve_doors(door_ids=None, door_names=[name], headers=headers)
+                if err:
+                    return self.error_response(err)
+                door_id = int(resolved[0]["id"])
+
+            # Fetch current state
+            raw = await self._get_door_detail(door_id, headers=headers)
+            cur_relock = self._to_bool(raw.get("open_once"))
+            cur_auto = self._to_bool(raw.get("unconditional_lock"))
+
+            # XOR guard
+            if desired_enable and cur_auto:
+                return self.error_response(
+                    "Cannot enable 'relock on close' because 'auto door' is currently enabled (XOR rule)."
+                )
+
+            # Idempotency
+            if cur_relock == desired_enable:
+                return self.success_response({
+                    "message": f"Door {door_id}: open_once already {'enabled' if cur_relock else 'disabled'}.",
+                    "door_id": door_id,
+                    "unchanged": True,
+                    "current_value": cur_relock
+                })
+
+            # Build preserving payload with override
+            overrides = {"open_once": self._bool_str(desired_enable)}
+            body = self._build_preserving_payload(raw, overrides)
+
+            # PUT
+            async with httpx.AsyncClient(verify=False, timeout=httpx.Timeout(10.0, read=20.0)) as client:
+                resp = await client.put(
+                    f"{self.session.config.biostar_url}/api/doors/{door_id}",
+                    headers=headers,
+                    json=body
+                )
+            if resp.status_code not in (200, 204):
+                return self.error_response(f"API call failed: {resp.status_code} - {resp.text}", {"request_body": body})
+
+            return self.success_response({
+                "message": f"Door {door_id}: open_once set to {desired_enable}.",
+                "door_id": door_id,
+                "previous_value": cur_relock,
+                "new_value": desired_enable,
+                "request_body": body
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    # ---- shared helpers for toggle tools ----
+    def _bool_str(self, x: bool) -> str:
+        return "true" if bool(x) else "false"
+
+    def _to_bool(self, x) -> bool:
+        if isinstance(x, bool):
+            return x
+        s = str(x).strip().lower()
+        return s in ("1", "true", "t", "yes", "y")
+
+    def _build_preserving_payload(self, raw: Dict[str, Any], overrides: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Preserve existing writable fields from GET /api/doors/:id response and
+        apply overrides (e.g., {'unconditional_lock': 'true'}).
+        We intentionally slim nested blocks to API-accepted shapes.
+        """
+        def _to_int(v, default=None):
+            try:
+                return int(v)
+            except Exception:
+                return default
+
+        d: Dict[str, Any] = {}
+
+        # Basics
+        if raw.get("name") is not None:
+            d["name"] = raw.get("name")
+        if raw.get("description") is not None:
+            d["description"] = raw.get("description") or ""
+
+        grp = raw.get("door_group_id") or {}
+        if grp.get("id") is not None:
+            d["door_group_id"] = {"id": _to_int(grp.get("id"))}
+
+        if raw.get("open_timeout") is not None:
+            d["open_timeout"] = _to_int(raw.get("open_timeout"))
+        if raw.get("open_duration") is not None:
+            od = _to_int(raw.get("open_duration"))
+            if od is not None:
+                d["open_duration"] = str(od)
+
+        if raw.get("open_once") is not None:
+            d["open_once"] = self._bool_str(self._to_bool(raw.get("open_once")))
+        if raw.get("unconditional_lock") is not None:
+            d["unconditional_lock"] = self._bool_str(self._to_bool(raw.get("unconditional_lock")))
+
+        # Devices / IO (slim forms)
+        entry = raw.get("entry_device_id") or {}
+        if entry.get("id") is not None:
+            d["entry_device_id"] = {"id": _to_int(entry.get("id"))}
+
+        relay = raw.get("relay_output_id") or {}
+        relay_dev = relay.get("device_id") or {}
+        rid = _to_int(relay_dev.get("id") or entry.get("id"))
+        rindex = _to_int(relay.get("relay_index"))
+        if rid is not None and rindex is not None:
+            d["relay_output_id"] = {"device_id": {"id": rid}, "relay_index": rindex}
+
+        exit_btn = raw.get("exit_button_input_id") or {}
+        exit_dev = exit_btn.get("device_id") or {}
+        xdid = _to_int(exit_dev.get("id"))
+        xidx = _to_int(exit_btn.get("input_index"))
+        xtype = exit_btn.get("type")
+        if xdid is not None and xidx is not None and xtype is not None:
+            d["exit_button_input_id"] = {
+                "device_id": {"id": xdid},
+                "input_index": xidx,
+                "type": str(_to_int(xtype))
+            }
+
+        sensor = raw.get("sensor_input_id") or {}
+        sdev = sensor.get("device_id") or {}
+        sdid = _to_int(sdev.get("id"))
+        sidx = _to_int(sensor.get("input_index"))
+        stype = sensor.get("type")
+        sapb = sensor.get("apb_use_door_sensor")
+        if sdid is not None and sidx is not None and stype is not None:
+            d["sensor_input_id"] = {
+                "device_id": {"id": sdid},
+                "input_index": sidx,
+                "type": str(_to_int(stype))
+            }
+            if sapb is not None:
+                d["sensor_input_id"]["apb_use_door_sensor"] = "1" if self._to_bool(sapb) else "0"
+
+        # apply overrides last
+        d.update(overrides)
+        return {"Door": d}
+
+    async def set_door_open_duration(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Set door 'open_duration' (seconds) preserving all other options.
+        Behavior:
+        1) Resolve door by id or exact name.
+        2) GET current detail; if already desired, return no-op.
+        3) PUT with a body built from preserved fields + open_duration override.
+        Notes:
+        - API expects 'open_duration' as string; we convert int -> str for compatibility.
+        - All other fields are preserved from the GET result via _build_preserving_payload().
+        """
+        try:
+            self.check_auth()
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            # --- parse input
+            if "seconds" not in args:
+                return self.error_response("'seconds' is required (integer).")
+            try:
+                desired_seconds = int(args["seconds"])
+            except Exception:
+                return self.error_response("'seconds' must be an integer.")
+
+            # --- enforce range: 1..900 inclusive
+            if desired_seconds < 1 or desired_seconds > 900:
+                return self.error_response(
+                    "'seconds' must be between 1 and 900 (inclusive).",
+                    {"received": desired_seconds, "allowed_range": [1, 900]}
+                )
+
+            # --- resolve door id (id or name)
+            door_id = None
+            if args.get("door_id") is not None:
+                try:
+                    door_id = int(args["door_id"])
+                except Exception:
+                    return self.error_response("Invalid 'door_id'. Must be an integer.")
+            else:
+                door_name = (args.get("door_name") or "").strip()
+                if not door_name:
+                    return self.error_response("Either 'door_id' or 'door_name' must be provided.")
+                resolved, err = await self._resolve_doors(door_ids=None, door_names=[door_name], headers=headers)
+                if err:
+                    return self.error_response(err)
+                door_id = int(resolved[0]["id"])
+
+            # --- fetch current detail
+            raw = await self._get_door_detail(door_id, headers=headers)
+            cur_str = str(raw.get("open_duration") if raw.get("open_duration") is not None else "")
+            try:
+                cur_seconds = int(cur_str) if cur_str != "" else None
+            except Exception:
+                cur_seconds = None
+
+            # --- idempotency
+            if cur_seconds is not None and cur_seconds == desired_seconds:
+                return self.success_response({
+                    "message": f"Door {door_id}: open_duration already {desired_seconds} seconds. No update performed.",
+                    "door_id": door_id,
+                    "unchanged": True,
+                    "current_value": cur_seconds
+                })
+
+            # --- build payload (preserve others, override open_duration)
+            overrides = {"open_duration": str(desired_seconds)}
+            body = self._build_preserving_payload(raw, overrides)
+
+            # --- PUT
+            async with httpx.AsyncClient(verify=False, timeout=httpx.Timeout(10.0, read=20.0)) as client:
+                resp = await client.put(
+                    f"{self.session.config.biostar_url}/api/doors/{door_id}",
+                    headers=headers,
+                    json=body
+                )
+            if resp.status_code not in (200, 204):
+                return self.error_response(
+                    f"API call failed: {resp.status_code} - {resp.text}",
+                    {"request_body": body}
+                )
+
+            return self.success_response({
+                "message": f"Door {door_id}: open_duration set to {desired_seconds} seconds.",
+                "door_id": door_id,
+                "previous_value": cur_seconds,
+                "new_value": desired_seconds,
+                "request_body": body
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def set_door_timed_apb(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Update Timed Anti-Passback while preserving every other field.
+        Business rules:
+        - reset_time: 0..60 (inclusive)
+        - selected_device allowed options depend on presence of entry/exit devices
+          (0=NO_DEVICE, 1=ENTRY_ONLY, 2=EXIT_ONLY)
+        - When enabling (selected_device!=0), force:
+            door_anti_passback.apb_type = 0 (NONE)
+            sensor_input_id.apb_use_door_sensor = "0" (OFF)
+        - Timed APB apb_type defaults to 2 (HARD_APB). Other values rejected.
+        """
+        try:
+            self.check_auth()
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            # ---- normalize selected_device ----
+            sel_raw = args.get("selected_device", None)
+            if sel_raw is None:
+                return self.error_response("'selected_device' is required.")
+            sd_map = {
+                "0": 0, "1": 1, "2": 2,
+                "NO_DEVICE": 0, "ENTRY_ONLY": 1, "EXIT_ONLY": 2,
+                "none": 0, "entry": 1, "exit": 2
+            }
+            if isinstance(sel_raw, str):
+                sel_key = sel_raw.strip()
+                if sel_key not in sd_map:
+                    return self.error_response("Invalid 'selected_device'. Use 0/1/2 or NO_DEVICE/ENTRY_ONLY/EXIT_ONLY.")
+                selected_device = sd_map[sel_key]
+            else:
+                try:
+                    selected_device = int(sel_raw)
+                except Exception:
+                    return self.error_response("Invalid 'selected_device'. Must be 0, 1, or 2.")
+            if selected_device not in (0, 1, 2):
+                return self.error_response("Invalid 'selected_device'. Must be 0, 1, or 2.")
+
+            # ---- reset_time 0..60 inclusive ----
+            if "reset_time" not in args:
+                return self.error_response("'reset_time' is required (minutes).")
+            try:
+                reset_time = int(args["reset_time"])
+            except Exception:
+                return self.error_response("'reset_time' must be an integer (minutes).")
+            if reset_time < 0 or reset_time > 60:
+                return self.error_response(
+                    "'reset_time' must be between 0 and 60 (inclusive).",
+                    {"received": reset_time, "allowed_range": [0, 60]}
+                )
+
+            # ---- apb_type (Timed) default 2 (HARD) ----
+            apb_type = int(args.get("apb_type", 2))
+            if apb_type != 2:
+                return self.error_response("Only Timed APB type '2' (HARD_APB) is supported.", {"received": apb_type})
+
+            # ---- resolve door ----
+            if args.get("door_id") is not None:
+                try:
+                    door_id = int(args["door_id"])
+                except Exception:
+                    return self.error_response("Invalid 'door_id'. Must be an integer.")
+            else:
+                name = (args.get("door_name") or "").strip()
+                if not name:
+                    return self.error_response("Either 'door_id' or 'door_name' must be provided.")
+                resolved, err = await self._resolve_doors(door_ids=None, door_names=[name], headers=headers)
+                if err:
+                    return self.error_response(err)
+                door_id = int(resolved[0]["id"])
+
+            # ---- fetch current detail ----
+            raw = await self._get_door_detail(door_id, headers=headers)
+            entry_present = bool((raw.get("entry_device_id") or {}).get("id"))
+            exit_present  = bool((raw.get("exit_device_id")  or {}).get("id"))
+
+            # ---- selected_device vs device availability ----
+            if not entry_present and not exit_present:
+                allowed = [0]
+            elif entry_present and exit_present:
+                allowed = [0, 1, 2]
+            elif entry_present:
+                allowed = [0, 1]
+            else:  # exit only
+                allowed = [0, 2]
+
+            if selected_device not in allowed:
+                return self.error_response(
+                    "Selected device option not allowed for current door setup.",
+                    {
+                        "entry_device_present": entry_present,
+                        "exit_device_present": exit_present,
+                        "allowed_selected_device": allowed,
+                        "received": selected_device
+                    }
+                )
+
+            # ---- build preserving body ----
+            body = self._build_preserving_payload(raw, overrides={})
+            d = body["Door"]
+
+            # ensure sensor block exists if present in raw
+            if "sensor_input_id" in d:
+                # When enabling Timed APB, force door sensor APB OFF
+                if selected_device != 0:
+                    d["sensor_input_id"]["apb_use_door_sensor"] = "0"
+
+            # door_anti_passback NONE when enabling
+            if selected_device != 0:
+                d["door_anti_passback"] = {"apb_type": "0"}
+
+            # Timed APB block (preserve id / bypass_groups if not overridden)
+            tapb_raw = raw.get("door_timed_anti_passback") or {}
+            tapb: Dict[str, Any] = {
+                "apb_type": str(apb_type),
+                "reset_time": str(reset_time),
+                "selected_device": str(selected_device)
+            }
+            if tapb_raw.get("id") is not None:
+                tapb["id"] = str(tapb_raw.get("id"))
+
+            # bypass groups
+            if "bypass_group_ids" in args and args["bypass_group_ids"] is not None:
+                try:
+                    gids = [int(x) for x in args["bypass_group_ids"]]
+                except Exception:
+                    return self.error_response("'bypass_group_ids' must be an array of integers.")
+                tapb["bypass_groups"] = [{"id": g} for g in gids]
+            elif isinstance(tapb_raw.get("bypass_groups"), list):
+                # preserve existing if present and not overridden
+                tapb["bypass_groups"] = [
+                    {"id": bg.get("id")} for bg in tapb_raw.get("bypass_groups") if isinstance(bg, dict) and bg.get("id") is not None
+                ]
+
+            d["door_timed_anti_passback"] = tapb
+
+            # ---- PUT ----
+            async with httpx.AsyncClient(verify=False, timeout=httpx.Timeout(10.0, read=20.0)) as client:
+                resp = await client.put(
+                    f"{self.session.config.biostar_url}/api/doors/{door_id}",
+                    headers=headers,
+                    json=body
+                )
+
+            if resp.status_code not in (200, 204):
+                return self.error_response(
+                    f"API call failed: {resp.status_code} - {resp.text}",
+                    {"request_body": body}
+                )
+
+            return self.success_response({
+                "message": f"Door {door_id}: Timed APB updated.",
+                "door_id": door_id,
+                "selected_device": selected_device,
+                "reset_time": reset_time,
+                "apb_type": apb_type,
+                "request_body": body
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def set_door_apb(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Unified Timed APB tool:
+          - mode: off | entry | exit (or 0/1/2)
+          - reset_time: 0..60 inclusive (required when mode != off)
+          - bypass_group_ids: optional
+        Business rules:
+          - Allowed modes depend on door device configuration:
+              (no entry, no exit) => {off}
+              (entry & exit)      => {off, entry, exit}
+              (entry only)        => {off, entry}
+              (exit only)         => {off, exit}
+          - When enabling (entry/exit):
+              door_anti_passback.apb_type = "0" (NONE)
+              sensor_input_id.apb_use_door_sensor = "0" (OFF)
+          - All other fields must be preserved exactly as-is.
+        """
+        try:
+            # --- Auth check ---
+            self.check_auth()
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json",
+            }
+
+            # --- Normalize mode ---
+            raw_mode = args.get("mode")
+            if raw_mode is None:
+                return self.error_response("Missing required field: mode")
+
+            if isinstance(raw_mode, int):
+                mode_i = raw_mode
+            else:
+                s = str(raw_mode).strip().lower()
+                if s in ("off", "0"):
+                    mode_i = 0
+                elif s in ("entry", "1"):
+                    mode_i = 1
+                elif s in ("exit", "2"):
+                    mode_i = 2
+                else:
+                    return self.error_response(
+                        "Invalid mode. Use off/entry/exit or 0/1/2.",
+                        {"received": raw_mode},
+                    )
+
+            # --- Validate reset_time ---
+            reset_time = args.get("reset_time", None)
+            if mode_i != 0:
+                if reset_time is None:
+                    return self.error_response("reset_time (0..60) is required when mode != off")
+                try:
+                    reset_time = int(reset_time)
+                except Exception:
+                    return self.error_response("reset_time must be an integer (minutes)")
+                if reset_time < 0 or reset_time > 60:
+                    return self.error_response("reset_time must be within 0..60 inclusive", {"received": reset_time})
+            else:
+                # OFF: if provided, still validate; if omitted, we keep the current one.
+                if reset_time is not None:
+                    try:
+                        reset_time = int(reset_time)
+                    except Exception:
+                        return self.error_response("reset_time must be an integer (minutes)")
+                    if reset_time < 0 or reset_time > 60:
+                        return self.error_response("reset_time must be within 0..60 inclusive", {"received": reset_time})
+
+            # --- Identify door ---
+            if args.get("door_id") is not None:
+                try:
+                    door_id = int(args["door_id"])
+                except Exception:
+                    return self.error_response("door_id must be an integer")
+            else:
+                door_name = (args.get("door_name") or "").strip()
+                if not door_name:
+                    return self.error_response("Either door_id or door_name is required")
+                resolved, err = await self._resolve_doors(door_ids=None, door_names=[door_name], headers=headers)
+                if err:
+                    return self.error_response(err)
+                door_id = int(resolved[0]["id"])
+
+            # --- Fetch door detail ---
+            raw = await self._get_door_detail(door_id, headers=headers)
+
+            # Determine which device sides exist
+            entry_present = bool((raw.get("entry_device_id") or {}).get("id"))
+            exit_present  = bool((raw.get("exit_device_id")  or {}).get("id"))
+
+            # Compute allowed modes
+            if not entry_present and not exit_present:
+                allowed = {0}
+            elif entry_present and exit_present:
+                allowed = {0, 1, 2}
+            elif entry_present:
+                allowed = {0, 1}
+            else:
+                allowed = {0, 2}
+
+            if mode_i not in allowed:
+                return self.error_response(
+                    "Requested APB mode is not allowed for this door's device configuration.",
+                    {
+                        "entry_device_present": entry_present,
+                        "exit_device_present": exit_present,
+                        "allowed_modes": sorted(list(allowed)),
+                        "requested_mode": mode_i,
+                    },
+                )
+
+            # --- Build preserving payload (keep all fields except we override APB) ---
+            body = self._build_preserving_payload(raw, overrides={})
+            door_block = body["Door"]
+
+            # Prepare Timed APB block
+            tapb_raw = raw.get("door_timed_anti_passback") or {}
+            tapb: Dict[str, Any] = {
+                "apb_type": "2",  # HARD APB only
+                "selected_device": str(mode_i),
+            }
+
+            # reset_time rules
+            if mode_i != 0:
+                tapb["reset_time"] = str(reset_time)
+            else:
+                if reset_time is not None:
+                    tapb["reset_time"] = str(reset_time)
+                elif tapb_raw.get("reset_time") is not None:
+                    tapb["reset_time"] = str(tapb_raw.get("reset_time"))
+
+            # preserve id if present
+            if tapb_raw.get("id") is not None:
+                tapb["id"] = str(tapb_raw.get("id"))
+
+            # bypass_groups: replace only if provided; otherwise, preserve current
+            if args.get("bypass_group_ids") is not None:
+                try:
+                    gids = [int(x) for x in args["bypass_group_ids"]]
+                except Exception:
+                    return self.error_response("bypass_group_ids must be an array of integers")
+                tapb["bypass_groups"] = [{"id": g} for g in gids]
+            elif isinstance(tapb_raw.get("bypass_groups"), list):
+                tapb["bypass_groups"] = [
+                    {"id": bg.get("id")}
+                    for bg in tapb_raw.get("bypass_groups")
+                    if isinstance(bg, dict) and bg.get("id") is not None
+                ]
+
+            door_block["door_timed_anti_passback"] = tapb
+
+            # When enabling APB, force classic APB and sensor APB OFF to avoid conflicts
+            if mode_i != 0:
+                door_block["door_anti_passback"] = {"apb_type": "0"}  # NONE
+                if "sensor_input_id" in door_block and isinstance(door_block["sensor_input_id"], dict):
+                    door_block["sensor_input_id"]["apb_use_door_sensor"] = "0"
+
+            # --- PUT ---
+            async with httpx.AsyncClient(
+                verify=False,
+                timeout=httpx.Timeout(10.0, read=20.0),
+            ) as client:
+                resp = await client.put(
+                    f"{self.session.config.biostar_url}/api/doors/{door_id}",
+                    headers=headers,
+                    json=body,
+                )
+
+            if resp.status_code not in (200, 204):
+                return self.error_response(
+                    f"API request failed: {resp.status_code} - {resp.text}",
+                    {"request_body": body},
+                )
+
+            return self.success_response({
+                "message": "Timed APB has been applied.",
+                "door_id": door_id,
+                "mode": {0: "off", 1: "entry", 2: "exit"}[mode_i],
+                "reset_time": tapb.get("reset_time"),
+                "request_body": body
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def _search_device_v2_by_name(
+        self,
+        *,
+        name: str,
+        headers: Dict[str, str],
+        exclude_device_type_id: Optional[int] = 254
+    ) -> List[Dict[str, Any]]:
+        """
+        Search registered devices by name using /api/v2/devices/search.
+        Returns simplified rows: [{id, name, ip, device_type_id}]
+        Tries exact and contains; falls back to /api/devices list if v2 is unavailable.
+        """
+        def _simplify(rows: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+            out, seen = [], set()
+            for r in rows or []:
+                try:
+                    did = int(r.get("id"))
+                except Exception:
+                    continue
+                if did in seen:
+                    continue
+                seen.add(did)
+                out.append({
+                    "id": did,
+                    "name": r.get("name"),
+                    "ip": ((r.get("lan") or {}).get("ip")),
+                    "device_type_id": ((r.get("device_type_id") or {}).get("id")),
+                })
+            return out
+
+        payload_base: Dict[str, Any] = {}
+        if exclude_device_type_id is not None:
+            payload_base["exclude_device_type_id"] = str(exclude_device_type_id)
+
+        endpoints = [
+            {**payload_base, "name": name},            # exact
+            {**payload_base, "name_contains": name},   # contains
+            {**payload_base, "keyword": name},         # generic
+        ]
+
+        for p in endpoints:
+            try:
+                async with httpx.AsyncClient(verify=False) as client:
+                    r = await client.post(
+                        f"{self.session.config.biostar_url}/api/v2/devices/search",
+                        headers=headers,
+                        json=p
+                    )
+                if r.status_code == 200:
+                    rows = (r.json().get("DeviceCollection") or {}).get("rows", []) or []
+                    if rows:
+                        return _simplify(rows)
+            except Exception as ex:
+                logger.info(f"/api/v2/devices/search failed for payload {p}: {ex}")
+
+        # Fallback to registered device list filtering
+        regs = await self._list_registered_devices(headers=headers)
+        norm = unicodedata.normalize("NFKC", name or "").strip().casefold()
+        hits = []
+        for r in regs:
+            nm = unicodedata.normalize("NFKC", str(r.get("name") or "")).strip().casefold()
+            if nm == norm or norm in nm:
+                hits.append({
+                    "id": int(r.get("id")),
+                    "name": r.get("name"),
+                    "ip": ((r.get("lan") or {}).get("ip")),
+                    "device_type_id": ((r.get("device_type_id") or {}).get("id")),
+                })
+        return hits
+
+    async def _resolve_device_id_from_pair(
+        self,
+        *,
+        device_id: Optional[int],
+        device_name: Optional[str],
+        headers: Dict[str, str],
+        label: str
+    ) -> Tuple[Optional[int], Optional[str], Optional[List[Dict[str, Any]]]]:
+        """
+        Resolve a device id from (id, name). Precedence: id > name.
+        Returns (resolved_id, error_str, candidates_if_ambiguous).
+        When multiple matches exist for name, returns error with candidates.
+        """
+        if device_id is not None:
+            try:
+                return int(device_id), None, None
+            except Exception:
+                return None, f"{label}: invalid device_id.", None
+
+        if not device_name:
+            return None, None, None  # not provided => no change
+
+        # Allow clearing semantics for entry_device_name ('none', 'null', 'empty')
+        norm = unicodedata.normalize("NFKC", device_name).strip().lower()
+        if norm in ("none", "null", "empty", "clear"):
+            return -1, None, None  # sentinel for clearing
+
+        hits = await self._search_device_v2_by_name(name=device_name, headers=headers)
+        if not hits:
+            return None, f"{label}: device named '{device_name}' not found.", []
+        if len(hits) == 1:
+            return int(hits[0]["id"]), None, None
+
+        # ambiguous
+        return None, (
+            f"{label}: multiple devices matched '{device_name}'. Please choose one."
+        ), hits
+
+    async def set_door_io(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Update 4 IO fields together in a single PUT, preserving all other fields:
+          - entry_device_id (supports clear)
+          - relay_output_id
+          - exit_button_input_id
+          - sensor_input_id
+
+        Accepts both ids and names. Name inputs are resolved via /api/v2/devices/search.
+        """
+        try:
+            self.check_auth()
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            # ---- resolve door (id or name) ----
+            door_id: Optional[int] = None
+            if args.get("door_id") is not None:
+                try:
+                    door_id = int(args["door_id"])
+                except Exception:
+                    return self.error_response("Invalid 'door_id'.")
+            elif args.get("door_name"):
+                doors, err = await self._resolve_doors(
+                    door_ids=None,
+                    door_names=[str(args["door_name"]).strip()],
+                    headers=headers
+                )
+                if err or not doors:
+                    return self.error_response(err or f"Door '{args.get('door_name')}' not found.")
+                door_id = int(doors[0]["id"])
+            else:
+                return self.error_response("Either 'door_id' or 'door_name' is required.")
+
+            # ---- GET current door detail & base preserving body ----
+            raw = await self._get_door_detail(door_id, headers=headers)
+            if raw is None:
+                return self.error_response(f"Door {door_id} not found.")
+            body = self._build_preserving_payload(raw, overrides={})
+            d = body["Door"]
+
+            # helper to coerce 0/1/"0"/"1"/bool -> "0"/"1"
+            def _to_01_str(x) -> Optional[str]:
+                if x is None:
+                    return None
+                if isinstance(x, bool):
+                    return "1" if x else "0"
+                s = str(x).strip().lower()
+                if s in ("1", "true", "t", "y", "yes"): return "1"
+                if s in ("0", "false", "f", "n", "no"): return "0"
+                return None
+
+            def _to_int(x, default=None):
+                try:
+                    return int(x)
+                except Exception:
+                    return default
+
+            # ===================== 1) entry_device_id =====================
+            # precedence: entry_device_id > entry_device_name
+            entry_id_arg = args.get("entry_device_id")
+            entry_name_arg = args.get("entry_device_name")
+            resolved_entry_id, err, cand = await self._resolve_device_id_from_pair(
+                device_id=entry_id_arg,
+                device_name=entry_name_arg,
+                headers=headers,
+                label="entry_device"
+            )
+            if err:
+                return self.error_response(err, {"needs_selection": True, "candidates": cand or []})
+            if resolved_entry_id is not None:
+                if resolved_entry_id == -1:  # clearing sentinel
+                    d["entry_device_id"] = {}
+                else:
+                    d["entry_device_id"] = {"id": int(resolved_entry_id)}
+
+            # ===================== 2) relay_output_id =====================
+            relay_id_arg = args.get("relay_device_id")
+            relay_name_arg = args.get("relay_device_name")
+            relay_index = _to_int(args.get("relay_index"), None)
+
+            if relay_id_arg is not None or relay_name_arg or relay_index is not None:
+                rid, err, cand = await self._resolve_device_id_from_pair(
+                    device_id=relay_id_arg,
+                    device_name=relay_name_arg,
+                    headers=headers,
+                    label="relay_device"
+                )
+                if err:
+                    return self.error_response(err, {"needs_selection": True, "candidates": cand or []})
+                # require both device id and relay index to set
+                if rid is None or relay_index is None:
+                    return self.error_response("To modify relay_output_id, both 'relay_device_(id|name)' and 'relay_index' are required.")
+                d["relay_output_id"] = {"device_id": {"id": int(rid)}, "relay_index": int(relay_index)}
+
+            # ===================== 3) exit_button_input_id =====================
+            x_dev_id = args.get("exit_button_device_id")
+            x_dev_name = args.get("exit_button_device_name")
+            x_idx = _to_int(args.get("exit_button_input_index"), None)
+            x_type = _to_int(args.get("exit_button_input_type"), None)
+
+            if x_dev_id is not None or x_dev_name or x_idx is not None or x_type is not None:
+                xid, err, cand = await self._resolve_device_id_from_pair(
+                    device_id=x_dev_id,
+                    device_name=x_dev_name,
+                    headers=headers,
+                    label="exit_button_device"
+                )
+                if err:
+                    return self.error_response(err, {"needs_selection": True, "candidates": cand or []})
+                if xid is None or x_idx is None or x_type is None:
+                    return self.error_response("To modify exit_button_input_id, provide device (id|name), input_index, and input_type.")
+                d["exit_button_input_id"] = {
+                    "device_id": {"id": int(xid)},
+                    "input_index": int(x_idx),
+                    "type": str(int(x_type))
+                }
+
+            # ===================== 4) sensor_input_id =====================
+            s_dev_id = args.get("sensor_device_id")
+            s_dev_name = args.get("sensor_device_name")
+            s_idx = _to_int(args.get("sensor_input_index"), None)
+            s_type = _to_int(args.get("sensor_input_type"), None)
+            s_apb = _to_01_str(args.get("sensor_apb_use"))
+
+            if s_dev_id is not None or s_dev_name or s_idx is not None or s_type is not None or s_apb is not None:
+                sid, err, cand = await self._resolve_device_id_from_pair(
+                    device_id=s_dev_id,
+                    device_name=s_dev_name,
+                    headers=headers,
+                    label="sensor_device"
+                )
+                if err:
+                    return self.error_response(err, {"needs_selection": True, "candidates": cand or []})
+                if sid is None or s_idx is None or s_type is None:
+                    return self.error_response("To modify sensor_input_id, provide device (id|name), input_index, and input_type.")
+                d["sensor_input_id"] = {
+                    "device_id": {"id": int(sid)},
+                    "input_index": int(s_idx),
+                    "type": str(int(s_type))
+                }
+                if s_apb is not None:
+                    d["sensor_input_id"]["apb_use_door_sensor"] = s_apb
+
+            # ---- PUT once with preserved + patched fields ----
+            async with httpx.AsyncClient(verify=False, timeout=httpx.Timeout(10.0, read=20.0)) as client:
+                resp = await client.put(
+                    f"{self.session.config.biostar_url}/api/doors/{door_id}",
+                    headers=headers,
+                    json=body
+                )
+
+            if resp.status_code not in (200, 204):
+                return self.error_response(
+                    f"API call failed: {resp.status_code} - {resp.text}",
+                    {"request_body": body}
+                )
+
+            changed = [k for k in ("entry_device_id", "relay_output_id", "exit_button_input_id", "sensor_input_id") if k in d]
+            return self.success_response({
+                "message": f"Door {door_id} IO updated via single PUT.",
+                "door_id": door_id,
+                "changed_fields": changed,
+                "request_body": body
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def bulk_create_doors(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Sequentially create multiple doors by calling create_door() for each item.
+
+        Behavior:
+        - Reuses the exact guarded flow of create_door() (NO auto discovery/registration/selection).
+        - Classifies each item into: created / preview-needed / failed.
+        - If continue_on_error is False, stops at the first failure.
+
+        Input:
+        - doors: List[create-door payload]
+        - continue_on_error: bool (default True)
+
+        Returns (success):
+        {
+          "status": "success",
+          "message": "Processed N door(s): X created, Y preview, Z failed.",
+          "summary": { "total": N, "created": X, "preview": Y, "failed": Z, "continue_on_error": true|false },
+          "created":  [ { "index": i, "door_id": 123, "message": "...", "request": {...} } ],
+          "previews": [ { "index": i, "message": "Preview", "details": {...}, "request": {...} } ],
+          "failed":   [ { "index": i, "message": "...", "details": {...}, "request": {...} } ]
+        }
+        """
+        try:
+            self.check_auth()
+
+            doors: List[Dict[str, Any]] = args.get("doors") or []
+            continue_on_error: bool = bool(args.get("continue_on_error", True))
+
+            if not isinstance(doors, list) or not doors:
+                return self.error_response("`doors` must be a non-empty array of 'create-door' payloads.")
+
+            created: List[Dict[str, Any]] = []
+            previews: List[Dict[str, Any]] = []
+            failed: List[Dict[str, Any]] = []
+
+            for idx, item in enumerate(doors, start=1):
+                # Call the single creation method to guarantee 100% identical behavior
+                single = await self.create_door(item)
+
+                # Parse BaseHandler's TextContent payload safely
+                raw_text = single[0].text if isinstance(single, list) and single else str(single)
+                try:
+                    parsed = json.loads(raw_text)
+                except Exception:
+                    try:
+                        parsed = ast.literal_eval(raw_text)
+                    except Exception:
+                        parsed = {"status": "unknown", "raw": raw_text}
+
+                status = str(parsed.get("status") or "").lower()
+
+                # Classification rules:
+                # - created: status == "success" or door_id exists
+                # - preview: needs_confirmation == True OR relay_options present
+                # - failed : status == "error" (or anything else not matching above)
+                if status == "success" or ("door_id" in parsed):
+                    created.append({
+                        "index": idx,
+                        "door_id": parsed.get("door_id"),
+                        "message": parsed.get("message"),
+                        "request": item,
+                    })
+                elif parsed.get("needs_confirmation") or ("relay_options" in parsed):
+                    previews.append({
+                        "index": idx,
+                        "message": parsed.get("message", "Preview"),
+                        "details": {k: parsed.get(k) for k in ("group_prompt", "missing_for_creation", "relay_index", "relay_options") if k in parsed},
+                        "request": item,
+                    })
+                else:
+                    failed.append({
+                        "index": idx,
+                        "message": parsed.get("message") or parsed.get("error") or "Unknown error",
+                        "details": {k: parsed.get(k) for k in parsed.keys() if k not in ("status", "message")},
+                        "request": item,
+                    })
+                    if not continue_on_error:
+                        break
+
+            summary = {
+                "total": len(doors),
+                "created": len(created),
+                "preview": len(previews),
+                "failed": len(failed),
+                "continue_on_error": continue_on_error,
+            }
+
+            return self.success_response({
+                "message": f"Processed {summary['total']} door(s): {summary['created']} created, "
+                           f"{summary['preview']} preview, {summary['failed']} failed.",
+                "summary": summary,
+                "created": created,
+                "previews": previews,
+                "failed": failed,
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def set_door_classic_apb(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Set door Classic APB (Anti-Passback) mode.
+        - apb_type: none | soft | hard (or 0/1/2)
+        - Preserves existing reset_time and open_when_disconnected values
+        """
+        try:
+            # --- Auth check ---
+            self.check_auth()
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json",
+            }
+
+            # --- Normalize apb_type ---
+            raw_apb_type = args.get("apb_type")
+            if raw_apb_type is None:
+                return self.error_response("Missing required field: apb_type")
+
+            if isinstance(raw_apb_type, int):
+                apb_type_i = raw_apb_type
+            else:
+                s = str(raw_apb_type).strip().lower()
+                if s in ("none", "0"):
+                    apb_type_i = 0
+                elif s in ("soft", "1"):
+                    apb_type_i = 1
+                elif s in ("hard", "2"):
+                    apb_type_i = 2
+                else:
+                    return self.error_response(
+                        "Invalid apb_type. Use none/soft/hard or 0/1/2.",
+                        {"received": raw_apb_type},
+                    )
+
+            # --- Identify door ---
+            if args.get("door_id") is not None:
+                try:
+                    door_id = int(args["door_id"])
+                except Exception:
+                    return self.error_response("door_id must be an integer")
+            else:
+                door_name = (args.get("door_name") or "").strip()
+                if not door_name:
+                    return self.error_response("Either door_id or door_name is required")
+                resolved, err = await self._resolve_doors(door_ids=None, door_names=[door_name], headers=headers)
+                if err:
+                    return self.error_response(err)
+                door_id = int(resolved[0]["id"])
+
+            # --- Fetch door detail ---
+            raw = await self._get_door_detail(door_id, headers=headers)
+
+            # --- Build preserving payload ---
+            body = self._build_preserving_payload(raw, overrides={})
+            door_block = body["Door"]
+
+            # Update door_anti_passback with preserved values
+            current_apb = door_block.get("door_anti_passback", {})
+            door_block["door_anti_passback"] = {
+                "apb_type": str(apb_type_i),
+                "reset_time": current_apb.get("reset_time", "1440"),
+                "open_when_disconnected": current_apb.get("open_when_disconnected", "0")
+            }
+
+            # --- PUT ---
+            async with httpx.AsyncClient(
+                verify=False,
+                timeout=httpx.Timeout(10.0, read=20.0),
+            ) as client:
+                resp = await client.put(
+                    f"{self.session.config.biostar_url}/api/doors/{door_id}",
+                    headers=headers,
+                    json=body,
+                )
+
+            if resp.status_code not in (200, 204):
+                return self.error_response(
+                    f"API request failed: {resp.status_code} - {resp.text}",
+                    {"request_body": body},
+                )
+
+            return self.success_response({
+                "message": "Classic APB has been set.",
+                "door_id": door_id,
+                "apb_type": {0: "none", 1: "soft", 2: "hard"}[apb_type_i],
+                "request_body": body
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def _search_device_v2_by_name(
+        self,
+        *,
+        name: str,
+        headers: Dict[str, str],
+        exclude_device_type_id: Optional[int] = 254
+    ) -> List[Dict[str, Any]]:
+        """
+        Search registered devices by name using /api/v2/devices/search.
+        Returns simplified rows: [{id, name, ip, device_type_id}]
+        Tries exact and contains; falls back to /api/devices list if v2 is unavailable.
+        """
+        def _simplify(rows: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+            out, seen = [], set()
+            for r in rows or []:
+                try:
+                    did = int(r.get("id"))
+                except Exception:
+                    continue
+                if did in seen:
+                    continue
+                seen.add(did)
+                out.append({
+                    "id": did,
+                    "name": r.get("name"),
+                    "ip": ((r.get("lan") or {}).get("ip")),
+                    "device_type_id": ((r.get("device_type_id") or {}).get("id")),
+                })
+            return out
+
+        payload_base: Dict[str, Any] = {}
+        if exclude_device_type_id is not None:
+            payload_base["exclude_device_type_id"] = str(exclude_device_type_id)
+
+        endpoints = [
+            {**payload_base, "name": name},            # exact
+            {**payload_base, "name_contains": name},   # contains
+            {**payload_base, "keyword": name},         # generic
+        ]
+
+        for p in endpoints:
+            try:
+                async with httpx.AsyncClient(verify=False) as client:
+                    r = await client.post(
+                        f"{self.session.config.biostar_url}/api/v2/devices/search",
+                        headers=headers,
+                        json=p
+                    )
+                if r.status_code == 200:
+                    rows = (r.json().get("DeviceCollection") or {}).get("rows", []) or []
+                    if rows:
+                        return _simplify(rows)
+            except Exception as ex:
+                logger.info(f"/api/v2/devices/search failed for payload {p}: {ex}")
+
+        # Fallback to registered device list filtering
+        regs = await self._list_registered_devices(headers=headers)
+        norm = unicodedata.normalize("NFKC", name or "").strip().casefold()
+        hits = []
+        for r in regs:
+            nm = unicodedata.normalize("NFKC", str(r.get("name") or "")).strip().casefold()
+            if nm == norm or norm in nm:
+                hits.append({
+                    "id": int(r.get("id")),
+                    "name": r.get("name"),
+                    "ip": ((r.get("lan") or {}).get("ip")),
+                    "device_type_id": ((r.get("device_type_id") or {}).get("id")),
+                })
+        return hits
+
+    async def _resolve_device_id_from_pair(
+        self,
+        *,
+        device_id: Optional[int],
+        device_name: Optional[str],
+        headers: Dict[str, str],
+        label: str
+    ) -> Tuple[Optional[int], Optional[str], Optional[List[Dict[str, Any]]]]:
+        """
+        Resolve a device id from (id, name). Precedence: id > name.
+        Returns (resolved_id, error_str, candidates_if_ambiguous).
+        When multiple matches exist for name, returns error with candidates.
+        """
+        if device_id is not None:
+            try:
+                return int(device_id), None, None
+            except Exception:
+                return None, f"{label}: invalid device_id.", None
+
+        if not device_name:
+            return None, None, None  # not provided => no change
+
+        # Allow clearing semantics for entry_device_name ('none', 'null', 'empty')
+        norm = unicodedata.normalize("NFKC", device_name).strip().lower()
+        if norm in ("none", "null", "empty", "clear"):
+            return -1, None, None  # sentinel for clearing
+
+        hits = await self._search_device_v2_by_name(name=device_name, headers=headers)
+        if not hits:
+            return None, f"{label}: device named '{device_name}' not found.", []
+        if len(hits) == 1:
+            return int(hits[0]["id"]), None, None
+
+        # ambiguous
+        return None, (
+            f"{label}: multiple devices matched '{device_name}'. Please choose one."
+        ), hits
+
+    async def set_door_io(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Update 4 IO fields together in a single PUT, preserving all other fields:
+          - entry_device_id (supports clear)
+          - relay_output_id
+          - exit_button_input_id
+          - sensor_input_id
+
+        Accepts both ids and names. Name inputs are resolved via /api/v2/devices/search.
+        """
+        try:
+            self.check_auth()
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            # ---- resolve door (id or name) ----
+            door_id: Optional[int] = None
+            if args.get("door_id") is not None:
+                try:
+                    door_id = int(args["door_id"])
+                except Exception:
+                    return self.error_response("Invalid 'door_id'.")
+            elif args.get("door_name"):
+                doors, err = await self._resolve_doors(
+                    door_ids=None,
+                    door_names=[str(args["door_name"]).strip()],
+                    headers=headers
+                )
+                if err or not doors:
+                    return self.error_response(err or f"Door '{args.get('door_name')}' not found.")
+                door_id = int(doors[0]["id"])
+            else:
+                return self.error_response("Either 'door_id' or 'door_name' is required.")
+
+            # ---- GET current door detail & base preserving body ----
+            raw = await self._get_door_detail(door_id, headers=headers)
+            if raw is None:
+                return self.error_response(f"Door {door_id} not found.")
+            body = self._build_preserving_payload(raw, overrides={})
+            d = body["Door"]
+
+            # helper to coerce 0/1/"0"/"1"/bool -> "0"/"1"
+            def _to_01_str(x) -> Optional[str]:
+                if x is None:
+                    return None
+                if isinstance(x, bool):
+                    return "1" if x else "0"
+                s = str(x).strip().lower()
+                if s in ("1", "true", "t", "y", "yes"): return "1"
+                if s in ("0", "false", "f", "n", "no"): return "0"
+                return None
+
+            def _to_int(x, default=None):
+                try:
+                    return int(x)
+                except Exception:
+                    return default
+
+            # ===================== 1) entry_device_id =====================
+            # precedence: entry_device_id > entry_device_name
+            entry_id_arg = args.get("entry_device_id")
+            entry_name_arg = args.get("entry_device_name")
+            resolved_entry_id, err, cand = await self._resolve_device_id_from_pair(
+                device_id=entry_id_arg,
+                device_name=entry_name_arg,
+                headers=headers,
+                label="entry_device"
+            )
+            if err:
+                return self.error_response(err, {"needs_selection": True, "candidates": cand or []})
+            if resolved_entry_id is not None:
+                if resolved_entry_id == -1:  # clearing sentinel
+                    d["entry_device_id"] = {}
+                else:
+                    d["entry_device_id"] = {"id": int(resolved_entry_id)}
+
+            # ===================== 2) relay_output_id =====================
+            relay_id_arg = args.get("relay_device_id")
+            relay_name_arg = args.get("relay_device_name")
+            relay_index = _to_int(args.get("relay_index"), None)
+
+            if relay_id_arg is not None or relay_name_arg or relay_index is not None:
+                rid, err, cand = await self._resolve_device_id_from_pair(
+                    device_id=relay_id_arg,
+                    device_name=relay_name_arg,
+                    headers=headers,
+                    label="relay_device"
+                )
+                if err:
+                    return self.error_response(err, {"needs_selection": True, "candidates": cand or []})
+                # require both device id and relay index to set
+                if rid is None or relay_index is None:
+                    return self.error_response("To modify relay_output_id, both 'relay_device_(id|name)' and 'relay_index' are required.")
+                d["relay_output_id"] = {"device_id": {"id": int(rid)}, "relay_index": int(relay_index)}
+
+            # ===================== 3) exit_button_input_id =====================
+            x_dev_id = args.get("exit_button_device_id")
+            x_dev_name = args.get("exit_button_device_name")
+            x_idx = _to_int(args.get("exit_button_input_index"), None)
+            x_type = _to_int(args.get("exit_button_input_type"), None)
+
+            if x_dev_id is not None or x_dev_name or x_idx is not None or x_type is not None:
+                xid, err, cand = await self._resolve_device_id_from_pair(
+                    device_id=x_dev_id,
+                    device_name=x_dev_name,
+                    headers=headers,
+                    label="exit_button_device"
+                )
+                if err:
+                    return self.error_response(err, {"needs_selection": True, "candidates": cand or []})
+                if xid is None or x_idx is None or x_type is None:
+                    return self.error_response("To modify exit_button_input_id, provide device (id|name), input_index, and input_type.")
+                d["exit_button_input_id"] = {
+                    "device_id": {"id": int(xid)},
+                    "input_index": int(x_idx),
+                    "type": str(int(x_type))
+                }
+
+            # ===================== 4) sensor_input_id =====================
+            s_dev_id = args.get("sensor_device_id")
+            s_dev_name = args.get("sensor_device_name")
+            s_idx = _to_int(args.get("sensor_input_index"), None)
+            s_type = _to_int(args.get("sensor_input_type"), None)
+            s_apb = _to_01_str(args.get("sensor_apb_use"))
+
+            if s_dev_id is not None or s_dev_name or s_idx is not None or s_type is not None or s_apb is not None:
+                sid, err, cand = await self._resolve_device_id_from_pair(
+                    device_id=s_dev_id,
+                    device_name=s_dev_name,
+                    headers=headers,
+                    label="sensor_device"
+                )
+                if err:
+                    return self.error_response(err, {"needs_selection": True, "candidates": cand or []})
+                if sid is None or s_idx is None or s_type is None:
+                    return self.error_response("To modify sensor_input_id, provide device (id|name), input_index, and input_type.")
+                d["sensor_input_id"] = {
+                    "device_id": {"id": int(sid)},
+                    "input_index": int(s_idx),
+                    "type": str(int(s_type))
+                }
+                if s_apb is not None:
+                    d["sensor_input_id"]["apb_use_door_sensor"] = s_apb
+
+            # ---- PUT once with preserved + patched fields ----
+            async with httpx.AsyncClient(verify=False, timeout=httpx.Timeout(10.0, read=20.0)) as client:
+                resp = await client.put(
+                    f"{self.session.config.biostar_url}/api/doors/{door_id}",
+                    headers=headers,
+                    json=body
+                )
+
+            if resp.status_code not in (200, 204):
+                return self.error_response(
+                    f"API call failed: {resp.status_code} - {resp.text}",
+                    {"request_body": body}
+                )
+
+            changed = [k for k in ("entry_device_id", "relay_output_id", "exit_button_input_id", "sensor_input_id") if k in d]
+            return self.success_response({
+                "message": f"Door {door_id} IO updated via single PUT.",
+                "door_id": door_id,
+                "changed_fields": changed,
+                "request_body": body
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)