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

biostar_x_mcp_server/schemas/devices.py

@@ -0,0 +1,496 @@
+from typing import Optional, Union, List
+from pydantic import BaseModel, Field, model_validator
+
+
+# ============================================================================
+# Device Management Schemas
+# ============================================================================
+
+class ListDevicesInput(BaseModel):
+    """Input schema for list-devices tool"""
+    group_id: Optional[int] = Field(None, description="Filter devices by device group ID")
+    device_type: Optional[str] = Field(None, description="Filter by device type (e.g., 'BioStation', 'BioEntry', 'FaceStation')")
+
+
+class GetDeviceInput(BaseModel):
+    """Input schema for get-device tool"""
+    device_id: int = Field(..., description="ID of the device to retrieve")
+
+
+class AddDeviceInput(BaseModel):
+    """Input schema for add-device tool"""
+    device_id: int = Field(..., description="Unique device ID")
+    name: str = Field(..., description="Name of the device")
+    ip_address: str = Field(..., description="IP address of the device")
+    device_group_id: int = Field(..., description="ID of the device group to add this device to")
+    device_type_id: Optional[int] = Field(None, description="Device type ID (e.g., 8 for BioStation 2, 9 for BioStation A2, 10 for FaceStation 2, 35 for BioStation 3)")
+    device_type_name: Optional[str] = Field(None, description="Device type name (e.g., 'BioStation 2', 'BioStation A2', 'FaceStation 2')")
+    port: Optional[int] = Field(default=51211, description="Port number (default: 51211)")
+    use_ssl: Optional[bool] = Field(default=False, description="Whether to use SSL connection")
+
+
+class UpdateDeviceInput(BaseModel):
+    """Input schema for update-device tool"""
+    device_id: int = Field(..., description="ID of the device to update")
+    name: Optional[str] = Field(None, description="New name for the device")
+    description: Optional[str] = Field(None, description="Device description")
+    time_zone: Optional[str] = Field(None, description="Time zone for the device (e.g., 'America/New_York')")
+    volume: Optional[int] = Field(None, ge=0, le=100, description="Device volume level (0-100)")
+
+
+class RebootDeviceInput(BaseModel):
+    """Input schema for reboot-device tool"""
+    device_ids: Optional[List[Union[int, str]]] = Field(None, description="One or more device IDs to restart (existence validated).")
+    device_id: Optional[int] = Field(None, description="Legacy single device id input.")
+    device_names: Optional[List[str]] = Field(None, description="Device names to restart (EXACT, case-sensitive; no fuzzy).")
+    device_search_text: Optional[str] = Field(None, description="Browse candidates by substring (case-insensitive). Returns candidates only; no action.")
+    confirm_multi: Optional[bool] = Field(default=False, description="Must be true to act on more than one device.")
+
+
+class GetDeviceStatusInput(BaseModel):
+    """Input schema for get-device-status tool"""
+    device_id: int = Field(..., description="ID of the device to check status")
+
+
+class ScanDevicesInput(BaseModel):
+    """Input schema for scan-devices tool"""
+    network_range: Optional[str] = Field(None, description="IP range to scan (e.g., '192.168.1.0/24')")
+    port: Optional[int] = Field(default=51211, description="Port to scan (default: 51211)")
+
+
+class SyncDeviceTimeInput(BaseModel):
+    """Input schema for sync-device-time tool"""
+    device_id: int = Field(..., description="ID of the device to sync time")
+
+
+class ClearDeviceLogInput(BaseModel):
+    """Input schema for clear-device-log tool"""
+    device_id: int = Field(..., description="ID of the device")
+    log_type: Optional[str] = Field(default="all", description="Type of logs to clear")
+
+
+class LockDeviceInput(BaseModel):
+    """Input schema for lock-device tool"""
+    device_id: int = Field(..., description="ID of the device to lock")
+
+
+class UnlockDeviceInput(BaseModel):
+    """Input schema for unlock-device tool"""
+    device_id: int = Field(..., description="ID of the device to unlock")
+
+
+class TCPSearchInput(BaseModel):
+    """Input schema for tcp-search tool"""
+    ip_address: str = Field(..., description="IP address of the device to connect to")
+    port: Optional[int] = Field(default=51211, description="Port number (default: 51211)")
+    timeout: Optional[int] = Field(default=10, description="Connection timeout in seconds (default: 10)")
+    retry_count: Optional[int] = Field(default=2, description="Number of retry attempts (default: 2)")
+
+
+class UDPSearchInput(BaseModel):
+    """Input schema for udp-search tool"""
+    timeout: Optional[int] = Field(default=5, description="Search timeout in seconds (default: 5)")
+
+
+class DisconnectDeviceInput(BaseModel):
+    """Input schema for disconnect-device tool"""
+    device_id: int = Field(..., description="ID of the device to disconnect")
+
+
+class RemoveDeviceInput(BaseModel):
+    """Input schema for remove-device tool"""
+    device_id: int = Field(..., description="ID of the device to remove")
+
+
+# ============================================================================
+# Device Group Schemas
+# ============================================================================
+
+class GetDeviceGroupsInput(BaseModel):
+    """Input schema for get-device-groups tool"""
+    group_search_text: Optional[str] = Field(None, description="Case-insensitive substring filter on group name")
+
+
+class GetDeviceGroupInput(BaseModel):
+    """Input schema for get-device-group tool"""
+    group_id: Optional[int] = Field(None, description="Exact device group ID to fetch.")
+    group_name: Optional[str] = Field(None, description="EXACT (case-sensitive) device group name.")
+    group_search_text: Optional[str] = Field(None, description="Substring browse for group names. Returns candidates only.")
+
+
+class CreateDeviceGroupInput(BaseModel):
+    """Input schema for create-device-group tool"""
+    name: str = Field(..., description="Name of the device group")
+    description: Optional[str] = Field(None, description="Description of the device group")
+    parent_id: Optional[int] = Field(default=1, description="Parent device group ID (default: 1 for root group)")
+    device_ids: Optional[List[int]] = Field(None, description="List of device IDs to include in the group")
+
+
+class UpdateDeviceGroupInput(BaseModel):
+    """Input schema for update-device-group tool"""
+    group_id: int = Field(..., description="ID of the device group to update")
+    name: Optional[str] = Field(None, description="New name for the device group")
+    description: Optional[str] = Field(None, description="New description for the device group")
+    device_ids: Optional[List[int]] = Field(None, description="New list of device IDs for the group")
+
+
+class DeleteDeviceGroupInput(BaseModel):
+    """Input schema for delete-device-group tool"""
+    group_id: int = Field(..., description="ID of the device group to delete")
+
+
+class MoveDeviceToGroupInput(BaseModel):
+    """Input schema for move-device-to-group tool"""
+    device_id: Optional[int] = Field(None, description="Device ID (preferred if known)")
+    device_name: Optional[str] = Field(None, description="Device name (substring match)")
+    device_search_text: Optional[str] = Field(None, description="Alternate device query (substring)")
+    target_group_id: Optional[int] = Field(None, description="Target device group ID")
+    target_group_name: Optional[str] = Field(None, description="Target device group name (substring match)")
+    group_search_text: Optional[str] = Field(None, description="Alternate group query (substring)")
+
+    @model_validator(mode="after")
+    def validate_identifiers(self):
+        """Ensure device and group identifiers are provided"""
+        has_device = any([self.device_id, self.device_name, self.device_search_text])
+        has_group = any([self.target_group_id, self.target_group_name, self.group_search_text])
+
+        if not has_device:
+            raise ValueError("At least one device identifier (device_id, device_name, device_search_text) must be provided")
+        if not has_group:
+            raise ValueError("At least one group identifier (target_group_id, target_group_name, group_search_text) must be provided")
+        return self
+
+
+class RemoveDeviceFromGroupInput(BaseModel):
+    """Input schema for remove-device-from-group tool"""
+    device_id: Optional[int] = Field(None, description="Device ID (preferred if known)")
+    device_name: Optional[str] = Field(None, description="Device name (substring match)")
+    device_search_text: Optional[str] = Field(None, description="Alternate device query (substring)")
+
+    @model_validator(mode="after")
+    def validate_identifier(self):
+        """Ensure at least one device identifier is provided"""
+        if not any([self.device_id, self.device_name, self.device_search_text]):
+            raise ValueError("At least one device identifier (device_id, device_name, device_search_text) must be provided")
+        return self
+
+
+# ============================================================================
+# Device Configuration Schemas
+# ============================================================================
+
+class UpdateDeviceAuthModeInput(BaseModel):
+    """Input schema for update-device-auth-mode tool"""
+    device_id: Optional[int] = Field(None, description="Target device id to update")
+    device_name: Optional[str] = Field(None, description="Target device name")
+    door_id: Optional[int] = Field(None, description="Door id; entry device will be used")
+    door_name: Optional[str] = Field(None, description="Door name; entry device will be used")
+    mode_codes: Optional[List[int]] = Field(None, description="Extended auth mode codes (11..49). Takes precedence over 'auth_specs'.")
+    auth_specs: Optional[List[str]] = Field(None, description="Specs like 'card+face+fingerprint' or 'face+pin' (ASCII-only).")
+    action: Optional[str] = Field(default="set", description="How to apply target modes.")
+    conflict_policy: Optional[str] = Field(default="overwrite", description="Policy when 'add' conflicts with business rules.")
+    schedule_id: Optional[int] = Field(default=1, description="Schedule id for each operation mode row.")
+
+    @model_validator(mode="after")
+    def validate_identifiers(self):
+        """Ensure device identifier and auth mode are provided"""
+        if not any([self.device_id, self.device_name, self.door_id, self.door_name]):
+            raise ValueError("At least one device/door identifier must be provided")
+        if not any([self.mode_codes, self.auth_specs]):
+            raise ValueError("Either mode_codes or auth_specs must be provided")
+        return self
+
+
+class UpdateDeviceFaceDistanceInput(BaseModel):
+    """Input schema for update-device-face-distance tool"""
+    device_id: Optional[int] = Field(None, description="Target device id to update")
+    device_name: Optional[str] = Field(None, description="Target device name")
+    door_id: Optional[int] = Field(None, description="Door id; entry device will be used")
+    door_name: Optional[str] = Field(None, description="Door name; entry device will be used")
+    max_cm: Optional[Union[int, str]] = Field(None, description="One of 30,40,...,130 or 'over_130' (→255).")
+
+    @model_validator(mode="after")
+    def validate_identifiers(self):
+        """Ensure device identifier and max_cm are provided"""
+        if not any([self.device_id, self.device_name, self.door_id, self.door_name]):
+            raise ValueError("At least one device/door identifier must be provided")
+        if self.max_cm is None:
+            raise ValueError("max_cm must be provided")
+        return self
+
+
+class UpdateDeviceDateTypeInput(BaseModel):
+    """Input schema for update-device-date-type tool"""
+    device_id: Optional[int] = Field(None, description="Target device id")
+    device_name: Optional[str] = Field(None, description="Target device name (exact or substring depending on resolver)")
+    device_search_text: Optional[str] = Field(None, description="Alternate device query (substring)")
+    door_id: Optional[int] = Field(None, description="Door id; entry device will be used unless 'edge' says otherwise")
+    door_name: Optional[str] = Field(None, description="Door name (substring) → entry/exit device")
+    edge: Optional[str] = Field(None, description="When resolving by door, choose entry or exit device (default: entry)")
+    date_type: Optional[Union[int, str]] = Field(None, description="Date type code: 0=YYYY/MM/DD, 1=MM/DD/YYYY, 2=DD/MM/YYYY")
+    date_format: Optional[str] = Field(None, description="Alternative to 'date_type'. Will be mapped to 0|1|2.")
+
+    @model_validator(mode="after")
+    def validate_identifiers(self):
+        """Ensure device identifier and date type are provided"""
+        if not any([self.device_id, self.device_name, self.device_search_text, self.door_id, self.door_name]):
+            raise ValueError("At least one device/door identifier must be provided")
+        if not any([self.date_type, self.date_format]):
+            raise ValueError("Either date_type or date_format must be provided")
+        return self
+
+
+class UpdateDeviceTimezoneInput(BaseModel):
+    """Input schema for update-device-timezone tool"""
+    device_id: Optional[int] = Field(None, description="Target device ID (preferred)")
+    device_name: Optional[str] = Field(None, description="Exact device name (strict match)")
+    door_id: Optional[int] = Field(None, description="Resolve via door's entry device")
+    door_name: Optional[str] = Field(None, description="Resolve via door's entry device (exact)")
+    offset_seconds: Optional[int] = Field(None, description="Final UTC offset in seconds (e.g., 32400 for UTC+9, -28800 for UTC-8).")
+    utc_offset: Optional[str] = Field(None, description="UTC offset string like '+09:00', '-08:00', '+03:30', etc.")
+    tz_label: Optional[str] = Field(None, description="Dropdown label or alias (Korean), or short city/abbr like '서울','하와이','테헤란','PST'.")
+    dry_run: Optional[bool] = Field(default=False, description="If true, do not PUT; only resolve and return the computed offset.")
+
+    @model_validator(mode="after")
+    def validate_identifiers(self):
+        """Ensure device identifier and timezone are provided"""
+        if not any([self.device_id, self.device_name, self.door_id, self.door_name]):
+            raise ValueError("At least one device/door identifier must be provided")
+        if not any([self.offset_seconds, self.utc_offset, self.tz_label]):
+            raise ValueError("At least one timezone specification (offset_seconds, utc_offset, tz_label) must be provided")
+        return self
+
+
+class FactoryResetDeviceInput(BaseModel):
+    """Input schema for factory-reset-device tool"""
+    device_id: Optional[int] = Field(None, description="Target device id")
+    device_name: Optional[str] = Field(None, description="Target device name")
+    device_search_text: Optional[str] = Field(None, description="Alternate device query (substring)")
+    door_id: Optional[int] = Field(None, description="Resolve device by door id (entry by default)")
+    door_name: Optional[str] = Field(None, description="Resolve device by door name (substring)")
+    edge: Optional[str] = Field(None, description="When resolving by door, choose entry or exit device (default: entry)")
+    is_reset_without_network: Optional[bool] = Field(None, description="If true, perform reset without network; default false")
+    dry_run: Optional[bool] = Field(None, description="If true, only report what would happen without calling the reset API")
+
+    @model_validator(mode="after")
+    def validate_identifier(self):
+        """Ensure at least one device identifier is provided"""
+        if not any([self.device_id, self.device_name, self.device_search_text, self.door_id, self.door_name]):
+            raise ValueError("At least one device/door identifier must be provided")
+        return self
+
+
+class UpdateDeviceAuthDisplayInput(BaseModel):
+    """Input schema for update-device-auth-and-display tool"""
+    device_id: Optional[Union[int, str]] = Field(None, description="Target device id. If omitted, use device_name.")
+    device_name: Optional[str] = Field(None, description="Exact device name when device_id is not provided.")
+    auth_timeout: Optional[Union[int, str]] = Field(None, ge=3, le=20, description="Authentication wait time in seconds (3–20).")
+    enable_server_matching: Optional[bool] = None
+    enable_full_access: Optional[bool] = None
+    display_userid_option: Optional[Union[int, str]] = Field(None, description="User ID display: 0=all, 1=first-only, 2=hidden")
+    display_username_option: Optional[Union[int, str]] = Field(None, description="User name display: 0=all, 1=first-only, 2=hidden")
+    dry_run: Optional[bool] = None
+
+
+class BulkAddDeviceItemInput(BaseModel):
+    """Input schema for bulk-add-devices device item"""
+    device_id: int = Field(..., description="Unique device ID")
+    name: str = Field(..., description="Device name")
+    ip_address: str = Field(..., description="IP address")
+    device_group_id: int = Field(..., description="Target device group id")
+    device_type_id: Optional[int] = Field(None, description="Optional device type id")
+    device_type_name: Optional[str] = Field(None, description="Optional device type name")
+    port: Optional[int] = Field(default=51211, description="Port (default 51211)")
+    use_ssl: Optional[bool] = Field(None, description="Use SSL")
+
+
+class BulkAddDevicesInput(BaseModel):
+    """Input schema for bulk-add-devices tool"""
+    devices: List[BulkAddDeviceItemInput] = Field(..., description="List of device objects; each item uses the same fields as 'add-device'.")
+    continue_on_error: Optional[bool] = Field(default=True, description="If false, stop at the first failure.")
+
+
+class UpdateDeviceNetworkInput(BaseModel):
+    """Input schema for update-device-network tool"""
+    device_id: Optional[int] = Field(None, description="Target device id")
+    device_name: Optional[str] = Field(None, description="Target device name")
+    device_search_text: Optional[str] = Field(None, description="Alternate device query (substring)")
+    door_id: Optional[int] = Field(None, description="Resolve via door id (entry by default)")
+    door_name: Optional[str] = Field(None, description="Resolve via door name (substring)")
+    edge: Optional[str] = Field(None, description="When resolving by door, choose entry or exit device (default: entry)")
+    dhcp_enabled: bool = Field(..., description="When true, static fields are ignored and disabled.")
+    ip_address: Optional[str] = Field(None, description="IPv4 address (required when dhcp_enabled=false)")
+    subnet_mask: Optional[str] = Field(None, description="IPv4 subnet mask (required when dhcp_enabled=false)")
+    gateway: Optional[str] = Field(None, description="IPv4 gateway (optional when dhcp_enabled=false)")
+    dns_server: Optional[str] = Field(None, description="IPv4 DNS server (optional when dhcp_enabled=false)")
+    device_port: Optional[int] = Field(default=51211, ge=1, le=65535, description="Device port (default 51211)")
+
+    @model_validator(mode="after")
+    def validate_identifiers(self):
+        """Ensure device identifier and network settings are provided"""
+        if not any([self.device_id, self.device_name, self.device_search_text, self.door_id, self.door_name]):
+            raise ValueError("At least one device/door identifier must be provided")
+        if not self.dhcp_enabled and (not self.ip_address or not self.subnet_mask):
+            raise ValueError("ip_address and subnet_mask are required when dhcp_enabled=false")
+        return self
+
+
+class UpdateDeviceSerialCommInput(BaseModel):
+    """Input schema for update-device-serial-comm tool"""
+    device_id: Optional[int] = Field(None, description="Target device id")
+    device_name: Optional[str] = Field(None, description="Target device name (exact match or resolver policy)")
+    device_search_text: Optional[str] = Field(None, description="Alternate device query (substring)")
+    door_id: Optional[int] = Field(None, description="Resolve via door id (entry by default)")
+    door_name: Optional[str] = Field(None, description="Resolve via door name (substring)")
+    edge: Optional[str] = Field(None, description="When resolving by door, choose entry or exit device (default: entry)")
+    rs485_mode: Union[int, str] = Field(..., description="RS-485 role: 1|master, 2|slave, 3|device_default (follow device default).")
+    baud_rate: int = Field(..., description="RS-485 baud rate.")
+    show_osdp_result: Optional[Union[int, str]] = Field(None, description="Only applicable when rs485_mode='slave'. 0|'controller' = show controller result, 1|'device' = show device result.")
+    dry_run: Optional[bool] = Field(default=False, description="If true, do not PUT; only resolve and return the computed payload.")
+
+    @model_validator(mode="after")
+    def validate_identifiers(self):
+        """Ensure device identifier is provided"""
+        if not any([self.device_id, self.device_name, self.device_search_text, self.door_id, self.door_name]):
+            raise ValueError("At least one device/door identifier must be provided")
+        return self
+
+
+class UpdateDeviceServerCommInput(BaseModel):
+    """Input schema for update-device-server-comm tool"""
+    device_id: Optional[int] = Field(None, description="Target device id")
+    device_name: Optional[str] = Field(None, description="Target device name (exact/contains per handler policy)")
+    device_search_text: Optional[str] = Field(None, description="Alternative substring search text")
+    door_id: Optional[int] = Field(None, description="Resolve via door id")
+    door_name: Optional[str] = Field(None, description="Resolve via door name")
+    edge: Optional[str] = Field(None, description="When resolving via door, choose entry or exit (default: entry)")
+    connect_from_device: Optional[bool] = Field(None, description="Checkbox 'Connect to server from device' (True=enable)")
+    server_address: Optional[str] = Field(None, description="Server address (IPv4 or hostname)")
+    server_port: Optional[int] = Field(default=51212, ge=1, le=65535, description="Server port (default 51212)")
+    dry_run: Optional[bool] = Field(default=False, description="If true, do not PUT; return payload preview only")
+
+    @model_validator(mode="after")
+    def validate_identifiers(self):
+        """Ensure device identifier and server comm settings are provided"""
+        if not any([self.device_id, self.device_name, self.device_search_text, self.door_id, self.door_name]):
+            raise ValueError("At least one device/door identifier must be provided")
+        if not any([self.connect_from_device, self.server_address, self.server_port]):
+            raise ValueError("At least one server communication setting must be provided")
+        return self
+
+
+class UpdateDeviceFingerprintInput(BaseModel):
+    """Input schema for update-device-fingerprint tool"""
+    device_id: Optional[Union[int, str]] = Field(None, description="Device id")
+    device_name: Optional[str] = Field(None, description="Device name (exact or substring depending on resolver)")
+    device_search_text: Optional[str] = Field(None, description="Alternate device query (substring)")
+    door_id: Optional[int] = Field(None, description="Resolve by door id (entry by default unless edge is specified)")
+    door_name: Optional[str] = Field(None, description="Resolve by door name (substring)")
+    edge: Optional[str] = Field(None, description="Edge selector when resolving by door")
+    security_level: Optional[Union[int, str]] = Field(None, description="Fingerprint 1:N security level (0=normal, 1=secure, 2=most secure) → fingerprint.security_level")
+    fast_mode: Optional[Union[int, str]] = Field(None, description="Fingerprint Fast Mode (0=auto, 1=normal, 2=fast, 3=fastest) → fingerprint.fast_mode")
+    sensitivity: Optional[int] = Field(None, ge=1, le=7, description="Sensor sensitivity (1..7) → fingerprint.sensitivity")
+    scan_wait_time: Optional[int] = Field(None, ge=1, le=20, description="Scan wait time in seconds (1..20) → fingerprint.scan_timeout")
+    matching_wait_time: Optional[int] = Field(None, ge=1, le=20, description="Matching wait time in seconds (1..20) → authentication.matching_timeout")
+    show_image: Optional[bool] = Field(None, description="Display fingerprint image → fingerprint.show_image")
+    sensor_mode: Optional[Union[int, str]] = Field(None, description="Sensor Mode (0=Auto On, 1=Always On) → fingerprint.sensor_mode")
+    advanced_enrollment: Optional[bool] = Field(None, description="Enrollment quality check → fingerprint.advanced_enrollment")
+    lfd_level: Optional[Union[int, str]] = Field(None, description="Fingerprint LFD level (0=Off, 1=Normal, 2=Strong, 3=Very Strong) → fingerprint.lfd_level")
+    duplicate_check: Optional[bool] = Field(None, description="Duplicate check → fingerprint.duplicate_check")
+    dry_run: Optional[bool] = Field(default=False, description="If true, do not PUT; return payload preview only")
+
+    @model_validator(mode="after")
+    def validate_identifier(self):
+        """Ensure at least one device identifier is provided"""
+        if not any([self.device_id, self.device_name, self.device_search_text, self.door_id, self.door_name]):
+            raise ValueError("At least one device/door identifier must be provided")
+        return self
+
+
+class UpdateDeviceFaceInput(BaseModel):
+    """Input schema for update-device-face tool"""
+    device_id: Optional[Union[int, str]] = Field(None, description="Device id")
+    device_name: Optional[str] = Field(None, description="Device name (resolved to id internally)")
+    device_search_text: Optional[str] = Field(None, description="Alternate device query (resolved to id internally)")
+    door_id: Optional[int] = Field(None, description="Optional: resolve by door (fallback uses generic resolver)")
+    door_name: Optional[str] = Field(None, description="Optional: resolve by door (fallback uses generic resolver)")
+    edge: Optional[str] = Field(None, description="Edge selector for door resolution")
+    security_level: Optional[Union[int, str]] = Field(None, description="→ face.security_level")
+    motion_sensor: Optional[Union[int, str]] = Field(None, description="→ face.sensitivity")
+    sensitivity: Optional[Union[int, str]] = Field(None, description="[Alias of motion_sensor] → face.sensitivity")
+    lfd_level: Optional[Union[int, str]] = Field(None, description="→ face.lfd_level")
+    enroll_timeout: Optional[int] = Field(None, ge=10, le=20, description="→ face.scan_wait_time")
+    max_rotation: Optional[int] = Field(None, description="→ face.max_rotation")
+    detect_distance_min: Optional[int] = Field(None, description="→ face.detection_distance_min")
+    detect_distance_max: Optional[Union[int, str]] = Field(None, description="→ face.detection_distance_max")
+    face_width_min: Optional[int] = Field(None, ge=0, le=100, description="→ face.face_width_min")
+    face_width_max: Optional[int] = Field(None, ge=0, le=100, description="→ face.face_width_max")
+    operation_mode: Optional[Union[int, str]] = Field(None, description="→ face.operation_mode")
+    wide_search: Optional[bool] = Field(None, description="→ face.face_wide_search")
+    fast_enroll: Optional[bool] = Field(None, description="→ face.quick_enrollment")
+    save_image: Optional[bool] = Field(None, description="→ face.store_visual_face_image")
+    duplicate_check: Optional[bool] = Field(None, description="→ face.duplicate_check")
+    light_brightness: Optional[Union[int, str]] = Field(None, description="Mapped to face.proximity_level (0/1/3 only; 2 is unused)")
+    dry_run: Optional[bool] = Field(default=False, description="If true, do not PUT; return payload preview only")
+
+    @model_validator(mode="after")
+    def validate_identifier(self):
+        """Ensure at least one device identifier is provided"""
+        if not any([self.device_id, self.device_name, self.device_search_text, self.door_id, self.door_name]):
+            raise ValueError("At least one device/door identifier must be provided")
+        return self
+
+
+class UpdateDeviceCardCSNInput(BaseModel):
+    """Input schema for update-device-card-csn tool"""
+    device_id: Optional[int] = Field(None, description="Target device id")
+    device_name: Optional[str] = Field(None, description="Target device name (resolver-dependent)")
+    device_search_text: Optional[str] = Field(None, description="Alternate device query (substring)")
+    door_id: Optional[int] = Field(None, description="Resolve via door id (entry by default)")
+    door_name: Optional[str] = Field(None, description="Resolve via door name (substring)")
+    edge: Optional[str] = Field(None, description="Door edge selector when resolving by door")
+    csn_enabled: bool = Field(..., description="Map to Device.card.use_csn (required)")
+    em4100_enabled: Optional[bool] = Field(None, description="Map to Device.card.use_em")
+    mifare_felica_enabled: Optional[bool] = Field(None, description="Map to Device.card.use_mifare_felica")
+    byte_order: Optional[Union[str, int]] = Field(None, description="Map to Device.card.byte_order (LSB='1', MSB='0').")
+    format_type: Optional[str] = Field(None, description="Map to Device.card.use_wiegand_format")
+    wiegand_format: Optional[str] = Field(None, description="Human-friendly Wiegand CSN name. Will be translated to id using a static map.")
+    wiegand_format_id: Optional[Union[int, str]] = Field(None, description="Map to Device.wiegand.wiegand_csn_id.id (e.g., 7 for 'DESFire 56bit').")
+
+    @model_validator(mode="after")
+    def validate_identifier(self):
+        """Ensure at least one device identifier is provided"""
+        if not any([self.device_id, self.device_name, self.device_search_text, self.door_id, self.door_name]):
+            raise ValueError("At least one device/door identifier must be provided")
+        return self
+
+
+# ============================================================================
+# Waiting Device Schemas
+# ============================================================================
+
+class ListWaitingDevicesInput(BaseModel):
+    """Input schema for list-waiting-devices tool"""
+    ip_filter: Optional[str] = Field(None, description="Filter devices by IP address (substring match)")
+    device_type_id: Optional[int] = Field(None, description="Filter by device type ID (e.g., 35 for BioStation 3)")
+
+
+class AddWaitingDeviceInput(BaseModel):
+    """Input schema for add-waiting-device tool"""
+    waiting_device_id: Union[int, str] = Field(..., description="Device ID from the waiting list (required)")
+    name: Optional[str] = Field(None, description="Name for the device. If not provided, auto-generates from device type and ID")
+    device_type_id: Optional[int] = Field(None, description="Device type ID (usually obtained from waiting device info)")
+    ip_address: Optional[str] = Field(None, description="IP address (from waiting device info)")
+    device_group_id: Optional[int] = Field(default=1, description="Device group ID to assign (default: 1 for root group)")
+    use_alphanumeric: Optional[bool] = Field(default=True, description="Enable alphanumeric user IDs")
+    follower_server_id: Optional[Union[int, str]] = Field(default=1, description="Follower server ID (default: 1)")
+
+
+class BulkAddWaitingDevicesInput(BaseModel):
+    """Input schema for bulk-add-waiting-devices tool"""
+    waiting_device_ids: List[Union[int, str]] = Field(..., description="Array of waiting device IDs to add")
+    device_group_id: Optional[int] = Field(default=1, description="Device group ID for all devices (default: 1)")
+    name_prefix: Optional[str] = Field(None, description="Optional prefix for auto-generated device names")
+    use_alphanumeric: Optional[bool] = Field(default=True, description="Enable alphanumeric user IDs for all devices")
+    continue_on_error: Optional[bool] = Field(default=True, description="Continue adding remaining devices if one fails")
+