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

biostar_x_mcp_server/utils/__init__.py

@@ -0,0 +1,31 @@
+"""Utility functions for BioStar X MCP Server"""
+
+from .timezone import (
+    TIMEZONE_OFFSETS,
+    get_timezone_offset,
+    get_timezone_string,
+    convert_utc_to_local,
+)
+from .search import search_users_by_name
+from .decorators import (
+    handle_api_errors,
+    require_auth,
+    log_execution,
+    validate_args,
+)
+
+__all__ = [
+    # Timezone utilities
+    "TIMEZONE_OFFSETS",
+    "get_timezone_offset",
+    "get_timezone_string",
+    "convert_utc_to_local",
+    # Search utilities
+    "search_users_by_name",
+    # Decorators
+    "handle_api_errors",
+    "require_auth",
+    "log_execution",
+    "validate_args",
+]
+

biostar_x_mcp_server/utils/category_mapper.py

@@ -0,0 +1,206 @@
+"""
+Category Mapper Module
+
+Maps documents and endpoints to BioStar MCP Server categories based on content and structure.
+"""
+import logging
+import re
+from typing import Dict, List, Optional, Set, Any
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class CategoryMapper:
+    """Maps content to BioStar MCP Server categories"""
+
+    # Category keywords mapping (Korean + English)
+    CATEGORY_KEYWORDS: Dict[str, List[str]] = {
+        "auth": [
+            "authentication", "login", "logout", "session", "credential", "token",
+            "인증", "로그인", "로그아웃", "세션", "토큰", "인증서"
+        ],
+        "users": [
+            "user", "users", "person", "people", "employee", "staff", "member",
+            "사용자", "유저", "직원", "인원", "멤버", "회원",
+            "user group", "user management", "사용자 그룹", "사용자 관리"
+        ],
+        "cards": [
+            "card", "cards", "credential", "credentials", "badge", "smartcard",
+            "카드", "크리덴셜", "배지", "스마트카드",
+            "card type", "wiegand", "csn", "카드 타입", "위간드"
+        ],
+        "doors": [
+            "door", "doors", "gate", "gates", "entry", "entrance", "exit",
+            "문", "도어", "출입문", "게이트", "입구", "출구",
+            "door group", "door control", "도어 그룹", "도어 제어"
+        ],
+        "access": [
+            "access", "permission", "authorization", "access level", "access group",
+            "출입", "권한", "액세스", "접근", "권한 그룹", "접근 레벨",
+            "access control", "permission management", "접근 제어", "권한 관리"
+        ],
+        "devices": [
+            "device", "devices", "reader", "readers", "terminal", "controller",
+            "장치", "디바이스", "리더", "터미널", "컨트롤러",
+            "device group", "device management", "장치 그룹", "장치 관리"
+        ],
+        "events": [
+            "event", "events", "log", "logs", "record", "records", "history",
+            "이벤트", "로그", "기록", "이력", "히스토리",
+            "access log", "event log", "출입 기록", "이벤트 로그"
+        ],
+        "audit": [
+            "audit", "audits", "trail", "tracking", "change history",
+            "감사", "추적", "변경 이력", "감사 추적",
+            "audit log", "audit trail", "감사 로그"
+        ],
+        "navigation": [
+            "navigation", "navigate", "page", "route",
+            "네비게이션", "페이지", "이동"
+        ],
+        "occupancy": [
+            "occupancy", "occupied", "entry", "exit", "inside", "present",
+            "재실", "입실", "퇴실", "재실 현황", "재실자"
+        ],
+        "files": [
+            "file", "files", "upload", "import", "export", "csv", "pdf",
+            "파일", "업로드", "임포트", "내보내기"
+        ],
+        "logs": [
+            "server log", "system log", "log file", "server status",
+            "서버 로그", "시스템 로그", "로그 파일", "서버 상태"
+        ],
+    }
+
+    # API endpoint path to category mapping
+    ENDPOINT_CATEGORY_MAP: Dict[str, str] = {
+        "/api/auth": "auth",
+        "/api/users": "users",
+        "/api/user-groups": "users",
+        "/api/cards": "cards",
+        "/api/card-types": "cards",
+        "/api/doors": "doors",
+        "/api/door-groups": "doors",
+        "/api/access": "access",
+        "/api/access-groups": "access",
+        "/api/access-levels": "access",
+        "/api/devices": "devices",
+        "/api/device-groups": "devices",
+        "/api/events": "events",
+        "/api/audit": "audit",
+    }
+
+    def __init__(self):
+        """Initialize CategoryMapper"""
+        # Build reverse keyword index for faster lookup
+        self._keyword_to_category: Dict[str, str] = {}
+        for category, keywords in self.CATEGORY_KEYWORDS.items():
+            for keyword in keywords:
+                self._keyword_to_category[keyword.lower()] = category
+
+    def map_endpoint_to_category(self, endpoint: Dict[str, Any]) -> Optional[str]:
+        """
+        Map API endpoint to category based on path and tags
+
+        Args:
+            endpoint: Endpoint information with path, method, tags, etc.
+
+        Returns:
+            Category name or None if not found
+        """
+        path = endpoint.get("path", "").lower()
+        tags = endpoint.get("tags", [])
+
+        # Check path mapping first
+        for endpoint_pattern, category in self.ENDPOINT_CATEGORY_MAP.items():
+            if path.startswith(endpoint_pattern.lower()):
+                return category
+
+        # Check tags
+        for tag in tags:
+            tag_lower = tag.lower()
+            if tag_lower in self._keyword_to_category:
+                return self._keyword_to_category[tag_lower]
+
+        # Check path segments
+        path_segments = [seg for seg in path.split("/") if seg and seg != "api"]
+        if path_segments:
+            first_segment = path_segments[0]
+            if first_segment in self._keyword_to_category:
+                return self._keyword_to_category[first_segment]
+
+        # Default: try to infer from path
+        for keyword, category in self._keyword_to_category.items():
+            if keyword in path:
+                return category
+
+        return None
+
+    def map_text_to_category(self, text: str, title: Optional[str] = None) -> Optional[str]:
+        """
+        Map text content to category based on keywords
+
+        Args:
+            text: Text content to analyze
+            title: Optional title (has higher weight)
+
+        Returns:
+            Category name or None if not found
+        """
+        if not text:
+            return None
+
+        text_lower = text.lower()
+        title_lower = title.lower() if title else ""
+
+        # Score categories based on keyword matches
+        category_scores: Dict[str, int] = {}
+
+        for category, keywords in self.CATEGORY_KEYWORDS.items():
+            score = 0
+            for keyword in keywords:
+                keyword_lower = keyword.lower()
+                # Title matches have higher weight
+                if title_lower and keyword_lower in title_lower:
+                    score += 3
+                # Text matches
+                if keyword_lower in text_lower:
+                    score += 1
+
+            if score > 0:
+                category_scores[category] = score
+
+        if not category_scores:
+            return None
+
+        # Return category with highest score
+        return max(category_scores.items(), key=lambda x: x[1])[0]
+
+    def map_section_to_category(self, section: Dict[str, Any]) -> Optional[str]:
+        """
+        Map PDF section to category
+
+        Args:
+            section: Section information with title and content
+
+        Returns:
+            Category name or None if not found
+        """
+        title = section.get("title", "")
+        content = section.get("content", "")
+
+        # Try title first (more reliable)
+        category = self.map_text_to_category(title, title=title)
+        if category:
+            return category
+
+        # Try content (first 500 chars for performance)
+        content_preview = content[:500] if content else ""
+        category = self.map_text_to_category(content_preview, title=title)
+
+        return category
+
+    def get_all_categories(self) -> List[str]:
+        """Get list of all available categories"""
+        return list(self.CATEGORY_KEYWORDS.keys())

biostar_x_mcp_server/utils/decorators.py

@@ -0,0 +1,101 @@
+"""
+Decorator utilities for BioStar X MCP Server handlers
+Provides common decorators for error handling, authentication, and logging
+"""
+import logging
+import functools
+from typing import Callable, Any
+
+logger = logging.getLogger(__name__)
+
+
+def handle_api_errors(func: Callable) -> Callable:
+    """
+    Decorator to handle API errors consistently across all handler methods
+
+    Usage:
+        @handle_api_errors
+        async def my_handler_method(self, args):
+            # Your code here
+            pass
+    """
+    @functools.wraps(func)
+    async def wrapper(self, *args, **kwargs):
+        try:
+            return await func(self, *args, **kwargs)
+        except Exception as e:
+            logger.error(f"Error in {func.__name__}: {e}", exc_info=True)
+            return await self.handle_api_error(e)
+    return wrapper
+
+
+def require_auth(func: Callable) -> Callable:
+    """
+    Decorator to ensure authentication before executing handler method
+
+    Usage:
+        @require_auth
+        @handle_api_errors
+        async def my_handler_method(self, args):
+            # Your code here (auth is guaranteed)
+            pass
+    """
+    @functools.wraps(func)
+    async def wrapper(self, *args, **kwargs):
+        self.check_auth()
+        return await func(self, *args, **kwargs)
+    return wrapper
+
+
+def log_execution(func: Callable) -> Callable:
+    """
+    Decorator to log method execution start and end
+
+    Usage:
+        @log_execution
+        @require_auth
+        @handle_api_errors
+        async def my_handler_method(self, args):
+            # Your code here
+            pass
+    """
+    @functools.wraps(func)
+    async def wrapper(self, *args, **kwargs):
+        logger.debug(f"Starting execution: {func.__name__}")
+        try:
+            result = await func(self, *args, **kwargs)
+            logger.debug(f"Completed execution: {func.__name__}")
+            return result
+        except Exception as e:
+            logger.error(f"Failed execution: {func.__name__} - {e}")
+            raise
+    return wrapper
+
+
+def validate_args(*required_keys: str):
+    """
+    Decorator to validate required arguments in args dict
+
+    Usage:
+        @validate_args("user_id", "name")
+        @require_auth
+        @handle_api_errors
+        async def my_handler_method(self, args):
+            # user_id and name are guaranteed to exist in args
+            pass
+
+    Args:
+        required_keys: Keys that must exist in args dict
+    """
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        async def wrapper(self, args: dict, *extra_args, **kwargs):
+            missing = [key for key in required_keys if key not in args]
+            if missing:
+                return self.error_response(
+                    "Missing required parameters",
+                    {"missing": missing, "required": list(required_keys)}
+                )
+            return await func(self, args, *extra_args, **kwargs)
+        return wrapper
+    return decorator

biostar_x_mcp_server/utils/language_detector.py

@@ -0,0 +1,51 @@
+"""
+Language detection utility for determining user's preferred language.
+"""
+import re
+from typing import Literal
+
+
+def detect_language(text: str) -> Literal["ko", "en"]:
+    """
+    Detect if text is primarily Korean or English.
+
+    Args:
+        text: Input text to analyze
+
+    Returns:
+        "ko" if Korean, "en" if English (default)
+    """
+    if not text or not isinstance(text, str):
+        return "en"
+
+    # Remove whitespace and common punctuation
+    text = text.strip()
+    if not text:
+        return "en"
+
+    # Check for Korean characters (Hangul)
+    korean_pattern = re.compile(r'[가-힣]')
+    korean_chars = len(korean_pattern.findall(text))
+
+    # Check for English characters (Latin alphabet)
+    english_pattern = re.compile(r'[a-zA-Z]')
+    english_chars = len(english_pattern.findall(text))
+
+    # Count total meaningful characters (excluding numbers, spaces, punctuation)
+    total_chars = korean_chars + english_chars
+
+    if total_chars == 0:
+        return "en"  # Default to English if no meaningful characters
+
+    # If Korean characters make up more than 20% of meaningful characters, consider it Korean
+    korean_ratio = korean_chars / total_chars if total_chars > 0 else 0
+
+    if korean_ratio > 0.2:
+        return "ko"
+    else:
+        return "en"
+
+
+def is_korean(text: str) -> bool:
+    """Check if text is primarily Korean."""
+    return detect_language(text) == "ko"

biostar_x_mcp_server/utils/search.py

@@ -0,0 +1,42 @@
+import httpx
+from typing import List, Dict
+import os
+
+API_BASE = os.getenv("API_BASE", "https://192.168.120.114:443/api")
+
+
+async def search_users_by_name(session_token: str, name: str) -> List[Dict]:
+    """
+    Search for users by name using the BioStar API.
+
+    CRITICAL: BioStar API's name parameter seems unreliable, so we do client-side filtering
+    to ensure exact or partial matches only.
+    """
+    headers = {
+        "bs-session-id": session_token,
+        "Content-Type": "application/json"
+    }
+
+    async with httpx.AsyncClient(verify=False) as client:
+        response = await client.get(
+            f"{API_BASE}/users",
+            headers=headers,
+            params={"name": name}
+        )
+
+        if response.status_code == 200:
+            data = response.json()
+            all_users = data.get("UserCollection", {}).get("rows", [])
+
+            # Client-side filtering: only return users whose name contains the search term
+            # (case-insensitive)
+            search_lower = name.lower().strip()
+            filtered_users = [
+                {"user_id": u["user_id"], "name": u["name"]}
+                for u in all_users
+                if search_lower in u.get("name", "").lower()
+            ]
+
+            return filtered_users
+
+        return []

biostar_x_mcp_server/utils/timezone.py

@@ -0,0 +1,122 @@
+"""
+Timezone utility functions
+Convert BioStar X API timezone IDs to UTC offsets (in minutes)
+"""
+from typing import Optional
+from datetime import datetime, timedelta
+
+
+# BioStar Timezone ID to UTC offset mapping (in minutes)
+TIMEZONE_OFFSETS = {
+    "0": -720,   # (UTC -12:00) Eniwetok, Kwajalein
+    "1": -660,   # (UTC -11:00) Midway Island, Samoa
+    "2": -600,   # (UTC -10:00) Hawaii
+    "3": -540,   # (UTC -9:00) Alaska
+    "4": -480,   # (UTC -8:00) Pacific Time (US & Canada)
+    "5": -420,   # (UTC -7:00) Mountain Time (US & Canada)
+    "6": -360,   # (UTC -6:00) Central Time (US & Canada), Mexico City
+    "7": -300,   # (UTC -5:00) Eastern Time (US & Canada), Bogota, Lima
+    "8": -240,   # (UTC -4:00) Atlantic Time (Canada), Caracas, La Paz
+    "9": -210,   # (UTC -3:30) Newfoundland
+    "10": -180,  # (UTC -3:00) Brazil, Buenos Aires, Georgetown
+    "11": -120,  # (UTC -2:00) Mid-Atlantic
+    "12": -60,   # (UTC -1:00) Azores, Cape Verde Islands
+    "13": 0,     # (UTC) Western Europe Time, London, Lisbon, Casablanca
+    "14": 60,    # (UTC +1:00) Brussels, Copenhagen, Madrid, Paris
+    "15": 120,   # (UTC +2:00) Kaliningrad, South Africa
+    "16": 180,   # (UTC +3:00) Baghdad, Riyadh, Moscow, St. Petersburg
+    "17": 210,   # (UTC +3:30) Tehran
+    "18": 240,   # (UTC +4:00) Abu Dhabi, Muscat, Baku, Tbilisi
+    "19": 270,   # (UTC +4:30) Kabul
+    "20": 300,   # (UTC +5:00) Ekaterinburg, Islamabad, Karachi, Tashkent
+    "21": 330,   # (UTC +5:30) Bombay, Calcutta, Madras, New Delhi, Colombo
+    "22": 345,   # (UTC +5:45) Kathmandu
+    "23": 360,   # (UTC +6:00) Almaty, Dhaka
+    "24": 420,   # (UTC +7:00) Bangkok, Hanoi, Jakarta
+    "25": 480,   # (UTC +8:00) Beijing, Perth, Singapore, Hong Kong
+    "26": 540,   # (UTC +9:00) Seoul, Tokyo, Osaka, Sapporo, Yakutsk
+    "27": 570,   # (UTC +9:30) Adelaide, Darwin
+    "28": 600,   # (UTC +10:00) Eastern Australia, Guam, Vladivostok
+    "29": 660,   # (UTC +11:00) Magadan, Solomon Islands, New Caledonia
+    "30": 720,   # (UTC +12:00) Auckland, Wellington, Fiji, Kamchatka
+}
+
+
+def get_timezone_offset(timezone_id: str, default: int = 540) -> int:
+    """
+    Convert BioStar timezone ID to UTC offset in minutes
+
+    Args:
+        timezone_id: BioStar timezone ID (string)
+        default: Default offset to return if timezone_id not found (default: 540 = UTC+9 Seoul)
+
+    Returns:
+        UTC offset in minutes
+    """
+    return TIMEZONE_OFFSETS.get(str(timezone_id), default)
+
+
+def get_timezone_string(timezone_id: str, default: int = 540) -> str:
+    """
+    Convert BioStar timezone ID to "UTC+9:00" format string
+
+    Args:
+        timezone_id: BioStar timezone ID (string)
+        default: Default offset to use if timezone_id not found (in minutes)
+
+    Returns:
+        Timezone string in "UTC+9:00" format
+    """
+    offset_minutes = get_timezone_offset(timezone_id, default)
+    offset_hours = offset_minutes / 60
+    minutes = abs(offset_minutes % 60)
+
+    if offset_minutes >= 0:
+        return f"UTC+{int(offset_hours)}:{minutes:02d}"
+    else:
+        return f"UTC{int(offset_hours)}:{minutes:02d}"
+
+
+def convert_utc_to_local(utc_time_str: str, timezone_offset_minutes: int) -> str:
+    """
+    Convert UTC time string to local time
+
+    Args:
+        utc_time_str: ISO 8601 UTC time string
+                      (e.g., "2024-01-15T10:30:00.00Z" or "2025-01-20T00:00:08.00+00:00")
+        timezone_offset_minutes: Timezone offset in minutes (e.g., 540 = UTC+9)
+
+    Returns:
+        Local time string in "2024-01-15 19:30:00 (UTC+9:00)" format
+    """
+    try:
+        # Normalize time string
+        time_str = utc_time_str.strip()
+
+        # Handle UTC format
+        if time_str.endswith('Z'):
+            time_str = time_str.replace('Z', '+00:00')
+
+        # Fix millisecond format: .00 -> .000 (Python requires 3 or 6 digits)
+        if '.00+' in time_str or '.00-' in time_str:
+            time_str = time_str.replace('.00+', '.000+').replace('.00-', '.000-')
+
+        # Parse UTC time
+        dt_utc = datetime.fromisoformat(time_str)
+
+        # Apply timezone offset
+        dt_local = dt_utc + timedelta(minutes=timezone_offset_minutes)
+
+        # Generate timezone string
+        hours = int(timezone_offset_minutes / 60)
+        minutes = abs(timezone_offset_minutes % 60)
+        if timezone_offset_minutes >= 0:
+            tz_str = f"UTC+{hours}:{minutes:02d}"
+        else:
+            tz_str = f"UTC{hours}:{minutes:02d}"
+
+        return f"{dt_local.strftime('%Y-%m-%d %H:%M:%S')} ({tz_str})"
+
+    except Exception as e:
+        # Return original on conversion failure
+        return utc_time_str