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

biostar_x_mcp_server/tools/doors.py

@@ -0,0 +1,865 @@
+from mcp.types import Tool
+
+# Door management tools
+GET_DOORS_TOOL = Tool(
+    name="get-doors",
+    description=(
+        "[ACTION TOOL] Retrieve doors from BioStar X with robust filtering. "
+        "Use this when user asks to 'list doors', 'show doors', 'get doors', 'display doors', or needs door information. "
+        "This performs actual system operations - do NOT use vector search for this. "
+        "Supports API params (limit, order_by) and client-side filters for LLM-friendly use."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "limit": {
+                "type": "integer",
+                "description": "Number of records (0 = all). Default: 0."
+            },
+            "order_by": {
+                "type": "string",
+                "description": "Sort order, e.g., 'id:true' (asc) or 'id:false' (desc)."
+            },
+            "ids": {
+                "type": "array",
+                "items": {"type": "integer"},
+                "description": "Filter by specific door IDs."
+            },
+            "name": {
+                "type": "string",
+                "description": "Exact door name match."
+            },
+            "name_contains": {
+                "type": "string",
+                "description": "Case-insensitive substring match for door name."
+            },
+            "group_id": {
+                "type": "integer",
+                "description": "Filter by door group ID."
+            },
+            "group_name": {
+                "type": "string",
+                "description": "Case-insensitive substring match for door group name."
+            },
+            "status": {
+                "type": "string",
+                "description": "Filter by status value (as returned by API), e.g., '0'."
+            },
+            "include_raw": {
+                "type": "boolean",
+                "description": "Attach raw API row for each door (debugging). Default: false."
+            },
+            "minimal": {
+                "type": "boolean",
+                "description": "Return only id and name (for access level creation). Reduces response size from 13KB to <1KB. Default: false."
+            }
+        },
+        "required": []
+    }
+)
+
+GET_DOOR_TOOL = Tool(
+    name="get-door",
+    description=(
+        "Search and retrieve a single door. "
+        "If 'door_id' is given, fetch details directly. "
+        "Otherwise it will POST /api/v2/doors/search with the provided criteria. "
+        "When zero or multiple matches are found, the tool returns a choice list and requests user selection."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "door_id": {
+                "type": "integer",
+                "description": "ID of the door to retrieve. If provided, the tool skips search and fetches details."
+            },
+            "search_text": {
+                "type": "string",
+                "description": "Free-text query for door search (POST /api/v2/doors/search)."
+            },
+            "door_group_id": {
+                "type": "integer",
+                "description": "Filter by door group ID in search (POST /api/v2/doors/search)."
+            },
+            "limit": {
+                "type": "integer",
+                "description": "Max results for search (default: 50)."
+            }
+        },
+        "required": [],
+        "anyOf": [
+            {"required": ["door_id"]},
+            {"required": ["search_text"]},
+            {"required": ["door_group_id"]}
+        ]
+    }
+)
+
+CREATE_DOOR_TOOL = Tool(
+    name="create-door",
+    description="""[ACTION TOOL] Create a new door in BioStar X system. Use this when user explicitly asks to 'create door', 'add door', 'new door', or 'make door'. This performs actual system operations - do NOT use vector search for this.
+    Create a new door with HARD-STOP guardrails.
+
+    STRICT, NON-NEGOTIABLE RULES:
+    - NEVER discover, register, or select any device automatically.
+    - NEVER create a door with any device other than the EXACT provided `entry_device_id`.
+    - If `entry_device_id` is already linked to another door (1:1 policy), DO NOT create anything.
+    - Perform UDP discovery (LIST ONLY), FILTER OUT devices already used by any door, RETURN the candidate list, and STOP.
+    - Do NOT call create-door again with a different device. The client must explicitly choose and call again.
+    - If the device is not registered, DO NOT register it and DO NOT create. Optionally return a UDP candidate list (LIST ONLY) and STOP.
+    - If `relay_index` is missing, RETURN available relay indices for the provided device and STOP. DO NOT create.
+    - Actual creation occurs ONLY when `confirm=true` AND ALL required fields are present AND there is NO conflict for the provided `entry_device_id`.
+
+    ABSOLUTE PROHIBITIONS:
+    - Do NOT call other tools implicitly (no device registration, no alternative device selection, no follow-up create).
+    - Do NOT "help" by choosing a different device. If the provided device is invalid or in conflict, return info and STOP.
+
+    OUTPUT CONTRACT:
+    - Conflict -> return: `{ conflict: {...}, udp_discovery: { devices: [...] }, available_registered_devices: [...] }` and STOP.
+    - Missing relay -> return: `{ relay_options: [...] }` and STOP.
+    - Success -> return: `{ door_id, request_body, door_groups: [...] }` (no group reassignment).
+    - AFTER ANY RETURN, END THE TURN. The client must make the next explicit call.
+    """,
+    inputSchema={
+        "type": "object",
+        "properties": {
+            # flow controls
+            "confirm": {"type": "boolean", "description": "If true, actually create the door. If false, return a preview.", "default": False},
+            "default_group_id": {"type": "integer", "description": "Fallback group id when door_group_id is not provided.", "default": 1},
+
+            # door core
+            "name": {"type": "string", "description": "Door name"},
+            "description": {"type": "string"},
+            "door_group_id": {"type": "integer", "description": "Optional group id at creation time. If omitted, default_group_id is used."},
+            "open_timeout": {"type": "integer", "default": 10},
+            "open_duration": {"type": "integer", "default": 5},
+            "open_once": {"type": "boolean", "default": True},
+            "unconditional_lock": {"type": "boolean", "default": True},
+
+            # device / IO
+            "entry_device_id": {"type": "integer", "description": "Device id to control the lock (1:1 mapping enforced)."},
+            "relay_index": {
+                "type": "integer",
+                "description": "Relay index on the entry device. If omitted, the tool returns relay list and exits."
+            },
+
+            "exit_device_id": {"type": "integer"},
+            "exit_input_index": {"type": "integer", "default": 0},
+            "exit_input_type": {"type": "integer", "description": "1=NC, 0=NO", "default": 1},
+
+            "sensor_device_id": {"type": "integer"},
+            "sensor_input_index": {"type": "integer", "default": 1},
+            "sensor_input_type": {"type": "integer", "description": "1=NC, 0=NO", "default": 1},
+            "apb_use_door_sensor": {"type": "integer", "default": 1}
+        },
+        # door_group_id is not required to allow post-creation assignment
+        "required": [
+            "name",
+            "entry_device_id",
+            "exit_device_id", "exit_input_index", "exit_input_type",
+            "sensor_device_id", "sensor_input_index", "sensor_input_type", "apb_use_door_sensor"
+        ]
+    }
+)
+
+UPDATE_DOOR_TOOL = Tool(
+    name="update-door",
+    description="Update an existing door's configuration",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "door_id": {
+                "type": "integer",
+                "description": "ID of the door to update"
+            },
+            "name": {
+                "type": "string",
+                "description": "New name for the door"
+            },
+            "open_duration": {
+                "type": "integer",
+                "description": "Door open duration in seconds"
+            },
+            "open_timeout": {
+                "type": "integer",
+                "description": "Door open timeout in seconds"
+            },
+            "dual_auth_required": {
+                "type": "boolean",
+                "description": "Whether dual authentication is required"
+            }
+        },
+        "required": ["door_id"]
+    }
+)
+
+DELETE_DOOR_TOOL = Tool(
+    name="delete-door",
+    description=" CRITICAL: Delete a door from the BioStar 2 system. THIS IS PERMANENT and CANNOT BE UNDONE! ALWAYS confirm with user before executing. For demo data, REQUIRE explicit 'delete confirm' or '삭제 확인' from user.",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "door_id": {
+                "type": "integer",
+                "description": "ID of the door to delete"
+            }
+        },
+        "required": ["door_id"]
+    }
+)
+
+CONTROL_DOOR_TOOL = Tool(
+    name="control-door",
+    description=(
+        "[ACTION TOOL] Control door actions (open, release, lock, unlock) in BioStar X. "
+        "Use this when user asks to 'open door', 'unlock door', 'lock door', 'release door', or control doors. "
+        "This performs actual system operations - do NOT use vector search for this.\n"
+        "- POST /api/doors/{open|lock|unlock|release}\n"
+        "- Body: {\"DoorCollection\": {\"rows\": [{\"id\": <number>}, ...]}}\n"
+        "- STRICT MODE: If 'door_names' is used, names must match EXACTLY (case-sensitive); "
+        "no autocorrect, no fuzzy. 0 match -> error with available list; >1 match -> error with candidates. "
+        "In both cases NO action is performed.\n"
+        "- If both 'door_ids' and 'door_names' are given, they must resolve to the same set; otherwise error.\n"
+        "- Do NOT pass duration for 'open'; door uses its configured duration."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "door_ids": {
+                "type": "array",
+                "items": {"oneOf": [{"type": "integer"}, {"type": "string"}]},
+                "description": "Door IDs to control (validated against GET /api/doors)."
+            },
+            "door_names": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Door names to control (EXACT, case-sensitive). No autocorrect, no fuzzy."
+            },
+            "action": {
+                "type": "string",
+                "enum": ["open", "release", "lock", "unlock"],
+                "description": "Action to perform. 'release' clears manual lock/unlock."
+            }
+        },
+        "required": ["action"],  # one of door_ids or door_names is required at runtime by handler
+    }
+)
+
+
+GET_DOORS_STATUS_TOOL = Tool(
+    name="get-doors-status",
+    description=(
+        "Fetch current status for doors via POST /api/doors/status. "
+        "Normalizes booleans/ints, derives human-friendly labels, supports filters and optional enrichment."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "monitoring_permission": {
+                "type": "boolean",
+                "description": "Pass-through flag for the status API. Default: true."
+            },
+            "include_enrichment": {
+                "type": "boolean",
+                "description": "If true, joins names/groups from GET /api/doors and enables group/name filters. Default: true."
+            },
+            "include_device_response": {
+                "type": "boolean",
+                "description": "Include normalized DeviceResponse with error summary. Default: true."
+            },
+            "include_raw": {
+                "type": "boolean",
+                "description": "Attach raw status row for debugging. Default: false."
+            },
+            "door_ids": {
+                "type": "array",
+                "items": {"type": "integer"},
+                "description": "Filter to specific door IDs."
+            },
+            "is_open": {
+                "type": "boolean",
+                "description": "Filter by open state."
+            },
+            "is_unlocked": {
+                "type": "boolean",
+                "description": "Filter by unlocked state."
+            },
+            "has_alarm": {
+                "type": "boolean",
+                "description": "Filter by alarm state."
+            },
+            "status_in": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Filter by raw status code values (as strings)."
+            },
+            "group_id": {
+                "type": "integer",
+                "description": "Filter by door group ID (requires include_enrichment=true)."
+            },
+            "group_name": {
+                "type": "string",
+                "description": "Substring match for group name (requires include_enrichment=true)."
+            },
+            "name_contains": {
+                "type": "string",
+                "description": "Substring match for door name (requires include_enrichment=true)."
+            },
+            "sort_by": {
+                "type": "string",
+                "enum": ["door_id", "name", "group_name"],
+                "description": "Client-side sort key. Default: 'door_id'."
+            },
+            "sort_desc": {
+                "type": "boolean",
+                "description": "Sort descending when true. Default: false."
+            }
+        },
+        "required": []
+    }
+)
+
+GET_DOOR_GROUPS_TOOL = Tool(
+    name="get-door-groups",
+    description=(
+        "Retrieve all door groups (non-breaking). "
+        "Keeps the legacy output shape {message,total,groups} and, when available, "
+        "adds optional fields per group: depth, parent, children, child_count, path, door_ids."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            # When true (default), enrich with hierarchy info via v2 search (depth/parent/children/path)
+            "include_hierarchy": {
+                "type": "boolean",
+                "description": "Enrich with /api/v2/door_groups/only_permission_item/search (depth/parent/children/path). Default: true"
+            },
+            # When true (default), scan /api/doors to compute door_ids & door_count if missing in v1 payload
+            "include_doors_scan": {
+                "type": "boolean",
+                "description": "Enrich with /api/doors to fill door_ids and door_count when absent. Default: true"
+            }
+        },
+        "required": []
+    }
+)
+GET_DOOR_GROUP_TOOL = Tool(
+    name="get-door-group",
+    description="Get detailed information about a specific door group (by id or by name).",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "group_id": {
+                "type": ["integer", "string"],
+                "description": "ID of the door group to retrieve"
+            },
+            "group_name": {
+                "type": "string",
+                "description": "Name of the door group to resolve (supports exact/iexact/icontains via name_match_mode)"
+            },
+            "name_match_mode": {
+                "type": "string",
+                "enum": ["auto", "exact", "iexact", "contains", "icontains"],
+                "default": "auto",
+                "description": "Name matching strategy when group_name is provided"
+            },
+            "include_hierarchy": {
+                "type": "boolean",
+                "default": True,
+                "description": "Include depth/parent/children/path if available"
+            },
+            "include_doors": {
+                "type": "boolean",
+                "default": True,
+                "description": "Include door_ids (scan /api/doors if missing)"
+            },
+            "include_doors_detail": {
+                "type": "boolean",
+                "default": False,
+                "description": "Also include brief door objects (id, name, description, group)"
+            },
+            "include_raw": {
+                "type": "boolean",
+                "default": False,
+                "description": "Attach raw DoorGroup payload"
+            }
+        },
+        "anyOf": [
+            {"required": ["group_id"]},
+            {"required": ["group_name"]}
+        ]
+    }
+)
+
+CREATE_DOOR_GROUP_TOOL = Tool(
+    name="create-door-group",
+    description="Create a new door group. Parent ID defaults to 1 (root), depth defaults to 1.",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "name": {
+                "type": "string",
+                "description": "Name of the door group (e.g., 'Ground Floor', '1st Floor', '2nd Floor')"
+            },
+            "parent_id": {
+                "type": "integer",
+                "description": "Parent door group ID (default: 1 for root group)"
+            },
+            "depth": {
+                "type": "integer",
+                "description": "Depth level of the door group (1-8, default: 1)",
+                "minimum": 1,
+                "maximum": 8
+            }
+        },
+        "required": ["name"]
+    }
+)
+
+UPDATE_DOOR_GROUP_TOOL = Tool(
+    name="update-door-group",
+    description="Update an existing door group",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "group_id": {
+                "type": "integer",
+                "description": "ID of the door group to update"
+            },
+            "name": {
+                "type": "string",
+                "description": "New name for the door group"
+            },
+            "parent_id": {
+                "type": "integer",
+                "description": "New parent door group ID"
+            }
+        },
+        "required": ["group_id"]
+    }
+)
+
+DELETE_DOOR_GROUP_TOOL = Tool(
+    name="delete-door-group",
+    description="Delete a door group",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "group_id": {
+                "type": "integer",
+                "description": "ID of the door group to delete"
+            }
+        },
+        "required": ["group_id"]
+    }
+)
+
+ADD_DOORS_TO_GROUP_TOOL = Tool(
+    name="add-doors-to-group",
+    description="""
+Assign one or more doors to a door group by updating each Door via PUT /api/doors/:id.
+- Supports resolving by door_ids or door_names (exact match). At least one must be provided.
+- Supports resolving the target group by group_id or group_name (exact match). One must be provided.
+- If a door is already assigned to another single group, use `force=true` to overwrite. Otherwise a conflict is returned.
+- If the door supports multiple groups (id_list), the tool will union the id into the list (idempotent).
+""".strip(),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "group_id": {"type": "integer", "description": "Target door group ID"},
+            "group_name": {"type": "string", "description": "Target door group name (used when group_id is not provided)"},
+            "door_ids": {
+                "type": "array",
+                "items": {"type": "integer"},
+                "description": "List of door IDs to assign"
+            },
+            "door_names": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "List of door names to assign (exact match)"
+            },
+            "force": {
+                "type": "boolean",
+                "description": "Overwrite an existing single-group assignment if different.",
+                "default": False
+            }
+        },
+        "required": []
+    }
+)
+
+REMOVE_DOORS_FROM_GROUP_TOOL = Tool(
+    name="remove-doors-from-group",
+    description="""
+Remove one or more doors from a door group.
+
+IMPORTANT:
+- BioStar 2 does not accept clearing 'door_group_id' to null/empty. If removal would leave
+  a door with no group, it must be reassigned somewhere.
+
+FALLBACK BEHAVIOR (when removal would leave no group):
+- fallback_mode:
+  - "auto" (default): reassign to a root-like group (All Door Groups/All Doors/기본/전체),
+    else group id == 1, else the smallest group id.
+  - "ask": make NO changes; return a list of candidate groups and `needs_fallback_choice=true`.
+  - "assign": reassign to the exact `fallback_group_id` you provide.
+
+USAGE:
+- If you want the tool to ask you for where to move: set `fallback_mode="ask"`.
+- If you already know the destination group: set `fallback_mode="assign"` and pass `fallback_group_id`.
+""",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "door_ids": {"type":"array","items":{"type":"integer"}},
+            "door_names": {"type":"array","items":{"type":"string"}},
+            "group_id": {"type":"integer", "description":"Remove from this group id"},
+            "group_name": {"type":"string", "description":"Or remove from this group name"},
+
+            # NEW:
+            "fallback_mode": {
+                "type":"string",
+                "enum":["auto","ask","assign"],
+                "default":"auto",
+                "description":"What to do if removal would leave no group"
+            },
+            "fallback_group_id": {
+                "type":"integer",
+                "description":"Required when fallback_mode='assign'"
+            }
+        },
+        "required": []  # (group_id or group_name required at runtime by handler)
+    }
+)
+
+UPDATE_DOOR_DESCRIPTION_TOOL = Tool(
+    name="update-door-description",
+    description=(
+        "Update only the 'description' field of a Door via PUT /api/doors/:id with a minimal payload. "
+        "This tool does NOT fetch or send any other fields, ensuring no unintended changes."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "door_id": {
+                "type": "integer",
+                "description": "ID of the door to update"
+            },
+            "description": {
+                "type": "string",
+                "description": "New description to set. Pass an empty string to clear."
+            }
+        },
+        "required": ["door_id", "description"]
+    }
+)
+
+SET_DOOR_AUTO_MODE_TOOL = Tool(
+    name="set-door-auto-mode",
+    description=(
+        "Enable/disable the door's 'auto door' option (unconditional_lock) with XOR validation "
+        "against 'relock on close' (open_once). Steps: GET -> XOR check -> NO-OP or PUT with preserved fields."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "door_id": {"type": "integer", "description": "Door ID"},
+            "door_name": {"type": "string", "description": "Exact door name (alternative to door_id)"},
+            "enable": {"type": "boolean", "description": "true to enable, false to disable"}
+        },
+        "anyOf": [
+            {"required": ["door_id", "enable"]},
+            {"required": ["door_name", "enable"]}
+        ]
+    }
+)
+
+SET_DOOR_RELOCK_ON_CLOSE_TOOL = Tool(
+    name="set-door-relock-on-close",
+    description=(
+        "Enable/disable 'relock on close' (open_once) with XOR validation against 'auto door' "
+        "(unconditional_lock). Steps: GET -> XOR check -> NO-OP or PUT with preserved fields."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+                "door_id": {"type": "integer", "description": "Door ID"},
+                "door_name": {"type": "string", "description": "Exact door name (alternative to door_id)"},
+                "enable": {"type": "boolean", "description": "true to enable, false to disable"}
+        },
+        "anyOf": [
+            {"required": ["door_id", "enable"]},
+            {"required": ["door_name", "enable"]}
+        ]
+    }
+)
+
+SET_DOOR_OPEN_DURATION_TOOL = Tool(
+    name="set-door-open-duration",
+    description=(
+        "Update only the door 'open_duration' (seconds) while preserving all other fields. "
+        "Idempotent: if the current value equals the requested one, returns no-op."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "door_id": {"type": "integer", "description": "ID of the door to update"},
+            "door_name": {"type": "string", "description": "Exact door name (alternative to door_id)"},
+            "seconds": {
+                "type": "integer",
+                "description": "New open duration in seconds (sent as string). Range: 1-900 (inclusive).",
+                "minimum": 1,
+                "maximum": 900
+            }
+        },
+        "anyOf": [
+            {"required": ["door_id", "seconds"]},
+            {"required": ["door_name", "seconds"]}
+        ]
+    }
+)
+
+
+# ---------------------------------------------------------------------------
+# Timed APB Unified Tool
+# - Turn OFF (no device), turn ON for entry-only or exit-only, and optionally
+#   set/reset the reset_time in minutes (0..60 inclusive).
+# - Business rules:
+#   * Allowed modes depend on connected devices of the door:
+#       - no entry, no exit => {off}
+#       - both entry and exit => {off, entry, exit}
+#       - entry only => {off, entry}
+#       - exit only  => {off, exit}
+#   * When turning ON (entry/exit), force:
+#       - 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.
+# ---------------------------------------------------------------------------
+SET_DOOR_TIMED_APB_TOOL = Tool(
+    name="set-door-timed-apb",
+    description=(
+        "Set door Timed APB (Anti-Passback) mode. Turn OFF (no device), or turn ON for entry-only/exit-only "
+        "with reset_time (0..60 minutes). Rejects invalid requests based on the door's "
+        "device configuration. When enabling APB, it forces classic APB off and sensor APB off. "
+        "All other fields remain intact."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "door_id": {
+                "type": "integer",
+                "description": "Door ID (optional). Either door_id or door_name is required."
+            },
+            "door_name": {
+                "type": "string",
+                "description": "Exact door name (optional). Either door_id or door_name is required."
+            },
+            "mode": {
+                "description": "APB mode: off | entry | exit (also accepts 0/1/2).",
+                "anyOf": [
+                    {"type": "string", "enum": ["off", "entry", "exit", "0", "1", "2"]},
+                    {"type": "integer", "enum": [0, 1, 2]}
+                ]
+            },
+            "reset_time": {
+                "type": "integer",
+                "description": "APB reset time in minutes. 0..60 inclusive. Required when mode != off.",
+                "minimum": 0,
+                "maximum": 60
+            },
+            "bypass_group_ids": {
+                "type": "array",
+                "items": {"type": "integer"},
+                "description": "Optional: Access Group IDs for timed APB bypass. If omitted, preserves current."
+            }
+        },
+        "anyOf": [
+            {"required": ["door_id", "mode"]},
+            {"required": ["door_name", "mode"]}
+        ]
+    }
+)
+
+
+SET_DOOR_CLASSIC_APB_TOOL = Tool(
+    name="set-door-classic-apb",
+    description=(
+        "Set door Classic APB (Anti-Passback) mode. "
+        "Controls the door_anti_passback.apb_type setting. "
+        "Options: none (0), soft (1), hard (2). "
+        "Preserves existing reset_time and open_when_disconnected values."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "door_id": {
+                "type": "integer",
+                "description": "Door ID (optional). Either door_id or door_name is required."
+            },
+            "door_name": {
+                "type": "string",
+                "description": "Exact door name (optional). Either door_id or door_name is required."
+            },
+            "apb_type": {
+                "description": "APB type: none | soft | hard (also accepts 0/1/2).",
+                "anyOf": [
+                    {"type": "string", "enum": ["none", "soft", "hard", "0", "1", "2"]},
+                    {"type": "integer", "enum": [0, 1, 2]}
+                ]
+            }
+        },
+        "anyOf": [
+            {"required": ["door_id", "apb_type"]},
+            {"required": ["door_name", "apb_type"]}
+        ]
+    }
+)
+
+
+SET_DOOR_IO_TOOL = Tool(
+    name="set-door-io",
+    description=(
+        "Update a door's 4 IO fields (entry_device_id, relay_output_id, "
+        "exit_button_input_id, sensor_input_id) in a single PUT while preserving "
+        "all other fields. Accepts either IDs or names; when names are provided, "
+        "the tool searches /api/v2/devices/search to resolve them to IDs. "
+        "To clear the entry device, pass entry_device_id=null or entry_device_name='none'."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            # Door target (id or name)
+            "door_id": {"type": "integer", "description": "ID of the door to update."},
+            "door_name": {"type": "string", "description": "Exact door name to update."},
+
+            # 1) Entry device (reader) - either id or name (name can be 'none' to clear)
+            "entry_device_id": {"type": ["integer", "null"], "description": "Device id for entry reader, or null to clear."},
+            "entry_device_name": {"type": ["string", "null"], "description": "Device name for entry reader; 'none' to clear."},
+
+            # 2) Relay output (door relay) - either id or name
+            "relay_device_id": {"type": "integer", "description": "Device id hosting the relay."},
+            "relay_device_name": {"type": "string", "description": "Device name hosting the relay."},
+            "relay_index": {"type": "integer", "description": "Relay index on the device."},
+
+            # 3) Exit button input - either id or name
+            "exit_button_device_id": {"type": "integer", "description": "Device id for the exit button input."},
+            "exit_button_device_name": {"type": "string", "description": "Device name for the exit button input."},
+            "exit_button_input_index": {"type": "integer", "description": "Input index (e.g., 0 or 1)."},
+            "exit_button_input_type": {
+                "type": "integer",
+                "enum": [0, 1],
+                "description": "Input type: 1=NC, 0=NO"
+            },
+
+            # 4) Door sensor input - either id or name
+            "sensor_device_id": {"type": "integer", "description": "Device id for the door sensor input."},
+            "sensor_device_name": {"type": "string", "description": "Device name for the door sensor input."},
+            "sensor_input_index": {"type": "integer", "description": "Input index (e.g., 0 or 1)."},
+            "sensor_input_type": {
+                "type": "integer",
+                "enum": [0, 1],
+                "description": "Input type: 1=NC, 0=NO"
+            },
+            "sensor_apb_use": {
+                "description": "Whether to use the door sensor for APB (apb_use_door_sensor). Accepts boolean or 0/1/'0'/'1'.",
+                "oneOf": [
+                    {"type": "boolean"},
+                    {"type": "integer", "enum": [0, 1]},
+                    {"type": "string", "enum": ["0", "1", "true", "false", "True", "False"]}
+                ]
+            }
+        },
+        "anyOf": [
+            {"required": ["door_id"]},
+            {"required": ["door_name"]}
+        ]
+    }
+)
+
+BULK_CREATE_DOORS_TOOL = Tool(
+    name="bulk-create-doors",
+    description=(
+        "Create multiple doors by iterating the single 'create-door' logic sequentially. "
+        "This tool NEVER performs any automatic device discovery/registration/selection. "
+        "Each item MUST follow the exact schema of 'create-door'. "
+        "Results are aggregated as created / preview-needed / failed."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "doors": {
+                "type": "array",
+                "description": "List of door payloads. Each item uses the same schema as 'create-door'.",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        # flow controls
+                        "confirm": {"type": "boolean", "description": "If true and all required fields are valid, creation proceeds.", "default": False},
+                        "default_group_id": {"type": "integer", "description": "Fallback door group id when 'door_group_id' is not provided.", "default": 1},
+
+                        # door core
+                        "name": {"type": "string", "description": "Door name"},
+                        "description": {"type": "string", "description": "Door description"},
+                        "door_group_id": {"type": "integer", "description": "Door group id to assign at creation time"},
+                        "open_timeout": {"type": "integer", "description": "Door open timeout (sec).", "default": 10},
+                        "open_duration": {"type": "integer", "description": "Door open duration (sec).", "default": 5},
+                        "open_once": {"type": "boolean", "description": "Open once option.", "default": True},
+                        "unconditional_lock": {"type": "boolean", "description": "Unconditional lock option.", "default": True},
+
+                        # device / IO (same guardrails as 'create-door')
+                        "entry_device_id": {"type": "integer", "description": "Device id to control the lock (1:1 mapping enforced)."},
+                        "relay_index": {"type": "integer", "description": "Required to actually create. If missing, tool returns relay options and stops."},
+
+                        "exit_device_id": {"type": "integer", "description": "Exit button device id."},
+                        "exit_input_index": {"type": "integer", "description": "Exit input index.", "default": 0},
+                        "exit_input_type": {"type": "integer", "description": "Exit input type.", "default": 1},
+
+                        "sensor_device_id": {"type": "integer", "description": "Door sensor device id."},
+                        "sensor_input_index": {"type": "integer", "description": "Sensor input index.", "default": 1},
+                        "sensor_input_type": {"type": "integer", "description": "Sensor input type.", "default": 1},
+                        "apb_use_door_sensor": {"type": "integer", "description": "Use door sensor for APB.", "default": 1}
+                    },
+                    # Keep in sync with CREATE_DOOR_TOOL
+                    "required": [
+                        "name",
+                        "entry_device_id",
+                        "exit_device_id", "exit_input_index", "exit_input_type",
+                        "sensor_device_id", "sensor_input_index", "sensor_input_type", "apb_use_door_sensor"
+                    ]
+                }
+            },
+            "continue_on_error": {
+                "type": "boolean",
+                "description": "If false, stop at the first failure. Default: true.",
+                "default": True
+            }
+        },
+        "required": ["doors"]
+    }
+)
+
+# Export all door tools
+DOOR_TOOLS = [
+    GET_DOORS_TOOL,
+    GET_DOOR_TOOL,
+    CREATE_DOOR_TOOL,
+    UPDATE_DOOR_TOOL,
+    DELETE_DOOR_TOOL,
+    CONTROL_DOOR_TOOL,
+    GET_DOORS_STATUS_TOOL,
+    GET_DOOR_GROUPS_TOOL,
+    GET_DOOR_GROUP_TOOL,
+    CREATE_DOOR_GROUP_TOOL,
+    UPDATE_DOOR_GROUP_TOOL,
+    DELETE_DOOR_GROUP_TOOL,
+    ADD_DOORS_TO_GROUP_TOOL,
+    REMOVE_DOORS_FROM_GROUP_TOOL,
+    UPDATE_DOOR_DESCRIPTION_TOOL,
+    SET_DOOR_AUTO_MODE_TOOL,
+    SET_DOOR_RELOCK_ON_CLOSE_TOOL,
+    SET_DOOR_OPEN_DURATION_TOOL,
+    SET_DOOR_TIMED_APB_TOOL,
+    SET_DOOR_CLASSIC_APB_TOOL,
+    SET_DOOR_IO_TOOL,
+    BULK_CREATE_DOORS_TOOL
+]