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

biostar_x_mcp_server/handlers/navigation_handler.py

@@ -0,0 +1,109 @@
+"""
+Navigation Handler
+프론트엔드 페이지 이동 정보를 생성
+"""
+import json
+import logging
+from typing import Dict, Any, Optional
+from .base_handler import BaseHandler
+
+logger = logging.getLogger(__name__)
+
+
+class NavigationHandler(BaseHandler):
+    """Handle navigation requests"""
+    
+    def __init__(self, session=None):
+        """Initialize without session (navigation doesn't need API calls)"""
+        self.client_session_id = None
+    
+    async def navigate_to_page(self, args: dict):
+        """
+        Generate navigation information for frontend
+        
+        Args:
+            args: {
+                "page_type": "user_list" | "user_detail" | "door_list" | "door_detail" | 
+                            "device_list" | "device_detail" | "monitoring" | "custom_url",
+                "resource_id": "123" (optional, for detail pages),
+                "custom_url": "/custom/path" (optional, for custom_url type),
+                "action": {
+                    "type": "click" | "scroll",
+                    "ng_label_key": "common.information"
+                } (optional),
+                "reason": "Brief explanation" (optional)
+            }
+        
+        Returns:
+            Navigation metadata for frontend
+        """
+        page_type = args.get("page_type")
+        resource_id = args.get("resource_id")
+        custom_url = args.get("custom_url")
+        action = args.get("action")
+        reason = args.get("reason", "")
+        
+        # Build navigation object
+        navigation = {
+            "enabled": True,
+            "page_type": page_type,
+            "resource_id": resource_id,
+            "custom_url": custom_url,
+            "action": action,
+            "reason": reason
+        }
+        
+        # Generate user-friendly path
+        path = self._generate_path(page_type, resource_id, custom_url)
+        
+        # Create response message
+        message_parts = []
+        
+        if reason:
+            message_parts.append(f" {reason}")
+        
+        message_parts.append(f" 페이지 이동: {path}")
+        
+        if action:
+            action_type = action.get("type", "")
+            if action_type == "click":
+                message_parts.append(f"    클릭: {action.get('ng_label_key', '')}")
+            elif action_type == "scroll":
+                message_parts.append(f"    스크롤: {action.get('ng_label_key', '')}")
+        
+        message = "\n".join(message_parts)
+        
+        logger.info(f" Navigation: {page_type} → {path}")
+        
+        # Return as TextContent with navigation metadata
+        return [{
+            "type": "text",
+            "text": json.dumps({
+                "message": message,
+                "navigation": navigation,
+                "path": path
+            }, ensure_ascii=False)
+        }]
+    
+    def _generate_path(self, page_type: str, resource_id: Optional[str] = None, 
+                      custom_url: Optional[str] = None) -> str:
+        """Generate frontend path from navigation info"""
+        
+        if page_type == "custom_url" and custom_url:
+            return custom_url
+        
+        path_map = {
+            "user_list": "/team",
+            "user_detail": f"/team/user/detail/{resource_id}" if resource_id else "/team",
+            "door_list": "/settings/door",
+            "door_detail": f"/settings/door/detail/{resource_id}" if resource_id else "/settings/door",
+            "device_list": "/settings/device",
+            "device_detail": f"/settings/device/detail/{resource_id}" if resource_id else "/settings/device",
+            "access_control": "/settings/access-control",
+            "access_group_list": "/settings/access-control",
+            "access_group_detail": f"/settings/access-control/detail/{resource_id}" if resource_id else "/settings/access-control",
+            "monitoring": "/arena"
+        }
+        
+        return path_map.get(page_type, "/")
+

biostar_x_mcp_server/handlers/occupancy_handler.py

@@ -0,0 +1,541 @@
+"""
+Occupancy Analysis Handler
+재실 현황 분석 핸들러
+"""
+
+import json
+import logging
+from typing import Any, Dict, Optional, List
+from datetime import datetime, timedelta
+from mcp.types import TextContent
+from .base_handler import BaseHandler
+from .event_handler import EventHandler
+
+logger = logging.getLogger(__name__)
+
+
+class OccupancyHandler(BaseHandler):
+    """Handle occupancy analysis operations"""
+    
+    def __init__(self, session):
+        super().__init__(session)
+        self.event_handler = EventHandler(session)
+
+    async def get_occupancy_status(self, args: Dict[str, Any]) -> list[TextContent]:
+        """
+        Analyze current occupancy status of a door.
+        출입문의 현재 재실 현황을 분석합니다.
+        """
+        try:
+            # Extract parameters from args dict
+            door_name = args.get("door_name")
+            door_id = args.get("door_id")
+            
+            # Handle both days and hours parameters
+            days = args.get("days")
+            hours_param = args.get("hours")
+            
+            if days is not None:
+                # Convert days to hours
+                hours = int(days) * 24
+            elif hours_param is not None:
+                hours = int(hours_param)
+            else:
+                hours = 24  # Default to today
+            
+            include_details = bool(args.get("include_details", True))
+            
+            logger.info(f" Starting occupancy analysis for door: {door_name or door_id}")
+            
+            # Step 1: Get door information
+            door_info = None
+            if door_id:
+                logger.info(f"   Searching by door_id: {door_id}")
+                # Get specific door by ID
+                response = await self.session.get(f"/api/doors/{door_id}")
+                response_data = response.json() if response else {}
+                if response_data and 'Door' in response_data:
+                    door_info = response_data['Door']
+                    logger.info(f"    Found door: {door_info.get('name')}")
+            elif door_name:
+                logger.info(f"   Searching by door_name: {door_name}")
+                # Search for door by name (flexible matching)
+                response = await self.session.get("/api/doors")
+                response_data = response.json() if response else {}
+                if response_data and 'DoorCollection' in response_data:
+                    doors = response_data['DoorCollection'].get('rows', [])
+                    logger.info(f"   Total doors available: {len(doors)}")
+                    
+                    # Log all door names for debugging
+                    for d in doors:
+                        logger.info(f"      - {d.get('name')} (ID: {d.get('id')})")
+                    
+                    # Normalize search string (remove spaces)
+                    search_normalized = door_name.lower().replace(' ', '').replace('　', '')
+                    logger.info(f"   Normalized search: {search_normalized}")
+                    
+                    # Try exact match first
+                    for door in doors:
+                        door_normalized = door.get('name', '').lower().replace(' ', '').replace('　', '')
+                        if search_normalized == door_normalized:
+                            door_info = door
+                            logger.info(f"    Exact match found: {door.get('name')}")
+                            break
+                    
+                    # If no exact match, try partial match
+                    if not door_info:
+                        for door in doors:
+                            door_normalized = door.get('name', '').lower().replace(' ', '').replace('　', '')
+                            if search_normalized in door_normalized or door_normalized in search_normalized:
+                                door_info = door
+                                logger.info(f"    Partial match found: {door.get('name')}")
+                                break
+            
+            if not door_info:
+                error_msg = f"출입문을 찾을 수 없습니다: {door_name or door_id}"
+                logger.error(f"    {error_msg}")
+                return self.error_response(
+                    error_msg,
+                    {"door_name": door_name, "door_id": door_id}
+                )
+
+            # Step 2: Extract entry/exit device information
+            door_id_actual = door_info.get('id')
+            door_name_actual = door_info.get('name', 'Unknown')
+            entry_device_raw = door_info.get('entry_device_id')
+            exit_device_raw = door_info.get('exit_device_id')
+
+            # Extract device IDs (handle both dict and string formats)
+            entry_device_id = None
+            exit_device_id = None
+            
+            if entry_device_raw:
+                if isinstance(entry_device_raw, dict):
+                    entry_device_id = entry_device_raw.get('id')
+                else:
+                    entry_device_id = str(entry_device_raw)
+            
+            if exit_device_raw:
+                if isinstance(exit_device_raw, dict):
+                    exit_device_id = exit_device_raw.get('id')
+                else:
+                    exit_device_id = str(exit_device_raw)
+
+            logger.info(f" Door Info:")
+            logger.info(f"   Door ID: {door_id_actual}")
+            logger.info(f"   Door Name: {door_name_actual}")
+            logger.info(f"   Entry Device RAW: {entry_device_raw}")
+            logger.info(f"   Exit Device RAW: {exit_device_raw}")
+            logger.info(f"   Entry Device ID (extracted): {entry_device_id}")
+            logger.info(f"   Exit Device ID (extracted): {exit_device_id}")
+
+            # Get device names
+            entry_device_name = "Unknown"
+            exit_device_name = "Unknown"
+            
+            if entry_device_id:
+                try:
+                    dev_response = await self.session.get(f"/api/devices/{entry_device_id}")
+                    dev_data = dev_response.json() if dev_response else {}
+                    if dev_data and 'Device' in dev_data:
+                        entry_device_name = dev_data['Device'].get('name', 'Unknown')
+                        logger.info(f"    Entry Device: {entry_device_name}")
+                except Exception as e:
+                    logger.warning(f"    Failed to get entry device name: {e}")
+
+            # Step 2.5: If no exit device is configured, try to find slave device (exit device)
+            if not exit_device_id and entry_device_id:
+                logger.info(f"    No exit device configured, checking for slave device...")
+                try:
+                    dev_response = await self.session.get(f"/api/devices/{entry_device_id}")
+                    dev_data = dev_response.json() if dev_response else {}
+                    if dev_data and 'Device' in dev_data:
+                        device_info = dev_data['Device']
+                        # Check for slave device
+                        slave_device = device_info.get('slave_device')
+                        if slave_device:
+                            if isinstance(slave_device, dict):
+                                exit_device_id = slave_device.get('id')
+                                exit_device_name = slave_device.get('name', 'Unknown')
+                            else:
+                                exit_device_id = str(slave_device)
+                                # Try to get slave device name
+                                try:
+                                    slave_response = await self.session.get(f"/api/devices/{exit_device_id}")
+                                    slave_data = slave_response.json() if slave_response else {}
+                                    if slave_data and 'Device' in slave_data:
+                                        exit_device_name = slave_data['Device'].get('name', 'Unknown')
+                                except:
+                                    exit_device_name = f"Device {exit_device_id}"
+                            logger.info(f"    Found slave device (exit): {exit_device_name} (ID: {exit_device_id})")
+                        else:
+                            logger.info(f"   ℹ  No slave device found for entry device")
+                except Exception as e:
+                    logger.warning(f"    Failed to check for slave device: {e}")
+            
+            if exit_device_id:
+                try:
+                    dev_response = await self.session.get(f"/api/devices/{exit_device_id}")
+                    dev_data = dev_response.json() if dev_response else {}
+                    if dev_data and 'Device' in dev_data:
+                        exit_device_name = dev_data['Device'].get('name', 'Unknown')
+                        logger.info(f"    Exit Device: {exit_device_name}")
+                except Exception as e:
+                    logger.warning(f"    Failed to get exit device name: {e}")
+
+            # Step 3: Get authentication events for entry and exit devices
+            end_time = datetime.now()
+            
+            # Use today's date (00:00:00) as start if hours parameter is default (24)
+            # This ensures we only get TODAY's events, not last 24 hours
+            if hours == 24:
+                # Today from midnight
+                start_time = end_time.replace(hour=0, minute=0, second=0, microsecond=0)
+                logger.info(f"   Using TODAY (from midnight): {start_time}")
+            else:
+                # Custom hours range
+                start_time = end_time - timedelta(hours=hours)
+                logger.info(f"   Using last {hours} hours: {start_time}")
+            
+            # Format datetime for API (ISO 8601 format with timezone)
+            start_datetime = start_time.strftime("%Y-%m-%dT%H:%M:%S.000Z")
+            end_datetime = end_time.strftime("%Y-%m-%dT%H:%M:%S.999Z")
+
+            logger.info(f" Searching authentication events for devices of door: {door_name_actual}")
+            logger.info(f"   Entry Device ID: {entry_device_id}")
+            logger.info(f"   Exit Device ID: {exit_device_id}")
+            logger.info(f"   Time range: {start_datetime} ~ {end_datetime}")
+
+            # Search for authentication events from both entry and exit devices
+            device_ids = []
+            if entry_device_id:
+                device_ids.append(str(entry_device_id))
+            if exit_device_id and exit_device_id != entry_device_id:
+                device_ids.append(str(exit_device_id))
+
+            if not device_ids:
+                logger.warning(f" No devices configured for door {door_name_actual}")
+                return self.error_response(
+                    f"출입문 {door_name_actual}에 입실/퇴실 장치가 설정되지 않았습니다.",
+                    {"door_id": door_id_actual, "door_name": door_name_actual}
+                )
+
+            # Use search_events with AUTHENTICATION SUCCESS event codes
+            # These are all "authentication succeeded" event types from BioStar
+            AUTH_SUCCESS_CODES = [
+                "4112", "4107", "4106", "4113", "4105", "4104", "4103", "4102", "4114", "4101", 
+                "4100", "4115", "4099", "4098", "4097", "4145", "4128", "4123", "4122", "4129", 
+                "4121", "4120", "4119", "4118", "4139", "4138", "4137", "4140", "4136", "4135", 
+                "4134", "4133", "4624", "4625", "4617", "4616", "4626", "4627", "4611", "4610", 
+                "4640", "4641", "4633", "4632", "4651", "4652", "4648", "4647", "4870", "4869", 
+                "4868", "4867", "4872", "4871", "4866", "4865", "5382", "5381", "5384", "5383", 
+                "5378", "5377"
+            ]
+            
+            search_args = {
+                "start_datetime": start_datetime,
+                "end_datetime": end_datetime,
+                "conditions": [
+                    {
+                        "column": "datetime",
+                        "operator": 3,  # BETWEEN
+                        "values": [start_datetime, end_datetime]
+                    },
+                    {
+                        "column": "event_type_id.code",
+                        "operator": 2,  # IN (BioStar API uses 2 for IN operation)
+                        "values": AUTH_SUCCESS_CODES
+                    }
+                ],
+                "limit": 1000,
+                "offset": 0,
+                "order_by": "datetime",
+                "order_type": "desc"
+            }
+
+            logger.info(f" Searching authentication events for door: {door_name_actual} (ID: {door_id_actual})")
+            logger.info(f" Search with {len(AUTH_SUCCESS_CODES)} auth event codes")
+            events_result = await self.event_handler.search_events(search_args)
+            
+            # Extract events from EventHandler response
+            events = []
+            logger.info(f" Event search result type: {type(events_result)}")
+            
+            # Log the actual query sent to API
+            if isinstance(events_result, list) and len(events_result) > 0:
+                result_text = events_result[0].text if hasattr(events_result[0], 'text') else str(events_result[0])
+                try:
+                    result_data = json.loads(result_text)
+                    if 'data' in result_data and 'request_query' in result_data['data']:
+                        logger.info(f" Actual API query sent: {json.dumps(result_data['data']['request_query'], indent=2, ensure_ascii=False)}")
+                except:
+                    pass
+            
+            if events_result and len(events_result) > 0:
+                # Parse the TextContent response
+                result_text = events_result[0].text
+                logger.info(f" Result text length: {len(result_text)} chars")
+                logger.info(f" Result preview: {result_text[:200]}...")
+                
+                try:
+                    result_data = json.loads(result_text)
+                    logger.info(f" Result status: {result_data.get('status')}")
+                    
+                    if result_data.get('status') == 'success':
+                        events = result_data.get('data', {}).get('events', [])
+                        logger.info(f" Found {len(events)} events for door {door_name_actual}")
+                        
+                        # Log sample events
+                        if events:
+                            logger.info(f" Sample events (first 3):")
+                            for i, evt in enumerate(events[:3]):
+                                logger.info(f"   {i+1}. Time: {evt.get('datetime')}, User: {evt.get('user_id')}, Device: {evt.get('device_id')}, Event: {evt.get('event_type_id')}")
+                            
+                            # DEBUG: Print FULL first event to see actual structure
+                            logger.info(f" FULL first event structure:")
+                            logger.info(json.dumps(events[0], indent=2, ensure_ascii=False, default=str)[:2000])
+                    else:
+                        logger.error(f" Event search failed: {result_data.get('error', 'Unknown error')}")
+                except json.JSONDecodeError as e:
+                    logger.error(f" Failed to parse event result: {e}")
+            else:
+                logger.warning(f" No event result returned")
+
+            # Step 4: Analyze entry/exit patterns
+            user_status = {}  # user_id -> {"name": str, "entries": [], "exits": [], "status": str}
+            
+            # Step 4.1: If still no exit device, dynamically detect from events
+            # Collect all unique device IDs from events
+            if not exit_device_id:
+                logger.info(f"    Dynamically detecting exit device from events...")
+                event_devices = set()
+                for event in events:
+                    device_obj = event.get('device_id', {})
+                    if isinstance(device_obj, dict):
+                        device_id_temp = device_obj.get('id')
+                    else:
+                        device_id_temp = device_obj
+                    if device_id_temp:
+                        event_devices.add(str(device_id_temp))
+                
+                logger.info(f"    Devices found in events: {event_devices}")
+                
+                # If there's a device that's NOT the entry device, treat it as exit device
+                other_devices = event_devices - {str(entry_device_id)}
+                if other_devices:
+                    # Use the first other device as exit device
+                    exit_device_id = list(other_devices)[0]
+                    logger.info(f"    Auto-detected exit device: {exit_device_id}")
+                    
+                    # Try to get device name
+                    try:
+                        dev_response = await self.session.get(f"/api/devices/{exit_device_id}")
+                        dev_data = dev_response.json() if dev_response else {}
+                        if dev_data and 'Device' in dev_data:
+                            exit_device_name = dev_data['Device'].get('name', 'Unknown')
+                            logger.info(f"    Auto-detected exit device name: {exit_device_name}")
+                    except:
+                        exit_device_name = f"Device {exit_device_id}"
+                else:
+                    logger.info(f"   ℹ  Only entry device found in events, no exit device")
+            
+            skipped_no_user = 0
+            for event in events:
+                # Extract nested values (API returns nested dicts)
+                user_obj = event.get('user_id', {})
+                device_obj = event.get('device_id', {})
+                event_type = event.get('event_type_id', {})
+                
+                # Handle both dict and direct value formats
+                if isinstance(user_obj, dict):
+                    user_id = user_obj.get('user_id')
+                    user_name = user_obj.get('name', f"User {user_id}")
+                else:
+                    user_id = user_obj
+                    user_name = f"User {user_id}"
+                
+                if isinstance(device_obj, dict):
+                    device_id = device_obj.get('id')
+                else:
+                    device_id = device_obj
+                
+                event_datetime = event.get('datetime')
+                event_code = event_type.get('code') if isinstance(event_type, dict) else event_type
+
+                if not user_id:
+                    skipped_no_user += 1
+                    logger.info(f"     Skipping event (no user_id): device={device_id}, code={event_code}")
+                    continue
+                
+                logger.info(f"    Processing: user={user_id} ({user_name}), device={device_id}, code={event_code}")
+
+                # Initialize user tracking
+                if user_id not in user_status:
+                    user_status[user_id] = {
+                        "name": user_name,
+                        "entries": [],
+                        "exits": [],
+                        "status": "unknown"
+                    }
+
+                # Categorize as entry or exit based on device (if exit device is configured)
+                if exit_device_id and str(device_id) == str(exit_device_id):
+                    # Exit device detected
+                    user_status[user_id]["exits"].append({
+                        "datetime": event_datetime,
+                        "device": exit_device_name
+                    })
+                else:
+                    # Default: treat as entry (includes entry device and any unrecognized devices)
+                    user_status[user_id]["entries"].append({
+                        "datetime": event_datetime,
+                        "device": entry_device_name if str(device_id) == str(entry_device_id) else f"Device {device_id}"
+                    })
+
+            # Log analysis start
+            logger.info(f" Analyzing entry/exit patterns for {len(user_status)} users")
+            logger.info(f"   Total events: {len(events)}, User events: {len(events) - skipped_no_user}, Skipped (no user): {skipped_no_user}")
+            
+            # Step 5: Determine current status for each user
+            currently_inside = []
+            recently_exited = []
+
+            for user_id, data in user_status.items():
+                entries = sorted(data["entries"], key=lambda x: x["datetime"], reverse=True)
+                exits = sorted(data["exits"], key=lambda x: x["datetime"], reverse=True)
+
+                # Get most recent entry and exit
+                last_entry = entries[0] if entries else None
+                last_exit = exits[0] if exits else None
+
+                # Determine status
+                if last_entry and not last_exit:
+                    # Entered but never exited
+                    data["status"] = "inside"
+                    data["last_entry_time"] = last_entry["datetime"]
+                    currently_inside.append(data)
+                elif last_entry and last_exit:
+                    # Compare timestamps
+                    if last_entry["datetime"] > last_exit["datetime"]:
+                        # Last action was entry
+                        data["status"] = "inside"
+                        data["last_entry_time"] = last_entry["datetime"]
+                        currently_inside.append(data)
+                    else:
+                        # Last action was exit
+                        data["status"] = "outside"
+                        data["last_exit_time"] = last_exit["datetime"]
+                        recently_exited.append(data)
+                elif last_exit:
+                    # Only exits recorded (unusual)
+                    data["status"] = "outside"
+                    data["last_exit_time"] = last_exit["datetime"]
+                    recently_exited.append(data)
+
+            # Step 6: Prepare response
+            result = {
+                "door": {
+                    "id": door_id_actual,
+                    "name": door_name_actual,
+                    "entry_device": {
+                        "id": entry_device_id,
+                        "name": entry_device_name
+                    },
+                    "exit_device": {
+                        "id": exit_device_id,
+                        "name": exit_device_name
+                    }
+                },
+                "analysis_period": {
+                    "start": start_datetime,
+                    "end": end_datetime,
+                    "hours": hours
+                },
+                "summary": {
+                    "total_users_tracked": len(user_status),
+                    "currently_inside": len(currently_inside),
+                    "recently_exited": len(recently_exited),
+                    "total_events": len(events)
+                },
+                "currently_inside": [
+                    {
+                        "user_id": uid,
+                        "name": data["name"],
+                        "entry_time": data.get("last_entry_time"),
+                        "total_entries": len(data["entries"]),
+                        "total_exits": len(data["exits"])
+                    }
+                    for uid, data in user_status.items()
+                    if data["status"] == "inside"
+                ],
+                "recently_exited": [
+                    {
+                        "user_id": uid,
+                        "name": data["name"],
+                        "exit_time": data.get("last_exit_time"),
+                        "total_entries": len(data["entries"]),
+                        "total_exits": len(data["exits"])
+                    }
+                    for uid, data in user_status.items()
+                    if data["status"] == "outside"
+                ][:10]  # Limit to last 10 exited users
+            }
+
+            if include_details:
+                result["all_events"] = events[:50]  # Include first 50 events for reference
+
+            # Log final summary
+            logger.info(f" Analysis Summary:")
+            logger.info(f"   Currently inside: {len(currently_inside)} users")
+            logger.info(f"   Recently exited: {len(recently_exited)} users")
+            logger.info(f"   Total events analyzed: {len(events)}")
+            
+            if currently_inside:
+                logger.info(f"   Users currently inside:")
+                for u in currently_inside[:5]:  # Show first 5
+                    logger.info(f"      - {u['name']} (entered at {u.get('last_entry_time')})")
+
+            return self.success_response(
+                result,
+                f" {door_name_actual} 재실 현황 분석 완료 (최근 {hours}시간)"
+            )
+
+        except Exception as e:
+            logger.error(f" Error in occupancy analysis: {e}")
+            import traceback
+            logger.error(traceback.format_exc())
+            return self.error_response(
+                f"재실 현황 분석 중 오류 발생: {str(e)}",
+                {"exception": str(e), "traceback": traceback.format_exc()}
+            )
+
+    async def analyze_door_traffic(self, args: Dict[str, Any]) -> list[TextContent]:
+        """
+        Analyze door traffic patterns.
+        출입문의 출입 패턴을 분석합니다.
+        """
+        try:
+            # Extract parameters from args dict
+            door_name = args.get("door_name")
+            door_id = args.get("door_id")
+            start_date = args.get("start_date")
+            end_date = args.get("end_date")
+            
+            # This is a simplified version - can be expanded
+            return self.success_response(
+                {
+                    "message": "Door traffic analysis feature - Coming soon!",
+                    "door_name": door_name,
+                    "door_id": door_id,
+                    "start_date": start_date,
+                    "end_date": end_date
+                },
+                "출입 패턴 분석 기능 (준비 중)"
+            )
+
+        except Exception as e:
+            return self.error_response(
+                f"출입 패턴 분석 중 오류 발생: {str(e)}",
+                {"exception": str(e)}
+            )
+