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

biostar_x_mcp_server/tools/events.py

@@ -0,0 +1,305 @@
+from mcp.types import Tool
+
+GET_EVENT_TYPES_TOOL = Tool(
+    name="get-event-types",
+    description=(
+        "List event types from BioStar 2 via /api/event_types with useful filters. "
+        "Server flags: is_break_glass, setting_alert, setting_all. "
+        "Client-side filters: search, codes, only_alertable, only_enable_alert. "
+        "Supports sorting, limit/offset, and grouping."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "is_break_glass": {
+                "type": "boolean",
+                "description": "If true, list user-renamed (break-glass) names. When true and others not specified, setting_alert/setting_all default to false.",
+                "default": False
+            },
+            "setting_alert": {
+                "type": "boolean",
+                "description": "If true, list alertable event types (server-side filter).",
+                "default": True
+            },
+            "setting_all": {
+                "type": "boolean",
+                "description": "If true, list all event types (server-side filter).",
+                "default": True
+            },
+            "search": {
+                "type": "string",
+                "description": "Case-insensitive contains across code, name, and description."
+            },
+            "codes": {
+                "type": "array",
+                "items": {"type": ["string", "number"]},
+                "description": "Restrict to specific event code(s)."
+            },
+            "only_alertable": {
+                "type": "boolean",
+                "description": "Keep only items with alertable == true.",
+                "default": False
+            },
+            "only_enable_alert": {
+                "type": "boolean",
+                "description": "Keep only items with enable_alert == true.",
+                "default": False
+            },
+            "sort_by": {
+                "type": "string",
+                "enum": ["code", "name"],
+                "description": "Sort field (default: code).",
+                "default": "code"
+            },
+            "sort_desc": {
+                "type": "boolean",
+                "description": "Descending sort if true.",
+                "default": False
+            },
+            "offset": {
+                "type": "integer",
+                "description": "Start index for slicing.",
+                "default": 0
+            },
+            "limit": {
+                "type": "integer",
+                "description": "Maximum number of items to return (client-side slicing)."
+            },
+            "group_by": {
+                "type": "string",
+                "enum": ["none", "alertable", "enable_alert"],
+                "description": "Group the result by a boolean field.",
+                "default": "none"
+            }
+        },
+        "required": []
+    }
+)
+
+SEARCH_EVENTS_TOOL = Tool(
+    name="search-events",
+    description="""Advanced search for events with multiple filter criteria.
+
+    CRITICAL DATE/TIME RULES:
+    - If no date specified by user, use CURRENT date/time (last 24 hours from NOW)
+    - NEVER hardcode dates like 2024-XX-XX
+    - Calculate dates dynamically from current system time
+    - Format: "YYYY-MM-DDTHH:MM:SS" (without timezone, server will convert to UTC)
+    - Example: "2025-11-07T00:00:00" (NOT "2025-11-07T00:00:00.000Z")
+
+    USER SEARCH:
+    - Use user_id parameter (NOT conditions array) for filtering by user ID
+    - Use user_name parameter to search by name (will be resolved to user_id)
+    """,
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "conditions": {
+                "type": "array",
+                "description": "Array of search conditions (for advanced filters only, do NOT use for datetime or user_id)",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "column": {"type": "string"},
+                        "operator": {
+                            "type": "integer",
+                            "enum": [0, 1, 2, 3, 4, 5, 6]
+                        },
+                        "value": {
+                            "type": "array",
+                            "items": {"type": ["string","number"]}
+                        },
+                        "values": {
+                            "type": "array",
+                            "items": {"type": ["string","number"]}
+                        }
+                    },
+                    "required": ["column", "operator"]
+                }
+            },
+            "user_id": {
+                "type": ["string","number"],
+                "description": "User ID to filter events (e.g., '61061'). Use this instead of conditions array."
+            },
+            "user_name": {
+                "type": "string",
+                "description": "User name to filter events. Server will resolve name to user_id."
+            },
+            "start_datetime": {
+                "type": "string",
+                "description": "Start datetime: 'YYYY-MM-DDTHH:MM:SS' (e.g., '2025-11-07T00:00:00'). WITHOUT timezone. Server converts to UTC."
+            },
+            "end_datetime": {
+                "type": "string",
+                "description": "End datetime: 'YYYY-MM-DDTHH:MM:SS' (e.g., '2025-11-07T23:59:59'). WITHOUT timezone. Server converts to UTC."
+            },
+            "limit": {"type": "integer", "default": 100},
+            "offset": {"type": "integer", "default": 0},
+            "order_by": {"type": "string", "default": "datetime"},
+            "order_type": {"type": "string", "enum": ["asc","desc"], "default": "desc"}
+        },
+        "required": []
+    }
+)
+
+
+GET_REALTIME_EVENTS_TOOL = Tool(
+    name="get-realtime-events",
+    description="Connect to BioStar 2 websocket for real-time event monitoring",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "duration": {
+                "type": "integer",
+                "description": "Duration to monitor events in seconds (max: 300)",
+                "maximum": 300,
+                "default": 60
+            },
+            "event_types": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Filter real-time events by specific event type IDs"
+            }
+        },
+        "required": []
+    }
+)
+
+GET_ACCESS_LOGS_TOOL = Tool(
+    name="get-access-logs",
+    description="""Get access control specific logs (simplified event search focused on access).
+
+    IMPORTANT: If no date specified, defaults to last 24 hours from current system time.
+    NEVER use hardcoded dates like 2024-XX-XX. Always calculate from NOW.
+    """,
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "start_datetime": {
+                "type": "string",
+                "description": "Start datetime in ISO 8601 format (e.g., \"2025-10-27T00:00:00.000Z\"). If not provided, defaults to 24 hours ago from NOW. NEVER use hardcoded dates."
+            },
+            "end_datetime": {
+                "type": "string",
+                "description": "End datetime in ISO 8601 format (e.g., \"2025-10-27T23:59:59.999Z\"). If not provided, defaults to NOW. NEVER use hardcoded dates."
+            },
+            "user_name": {
+                "type": "string",
+                "description": "Filter by user name (partial match)"
+            },
+            "success_only": {
+                "type": "boolean",
+                "description": "Show only successful access attempts",
+                "default": False
+            },
+            "limit": {
+                "type": "integer",
+                "description": "Maximum number of logs to retrieve",
+                "default": 100
+            }
+        },
+        "required": []
+    }
+)
+
+EXPORT_EVENTS_CSV_TOOL = Tool(
+    name="export-events-csv",
+    description="Export event logs to CSV via /api/events/export and copy the file to the Windows Downloads folder.",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "start_datetime": {"type": "string", "description": "Start datetime (ISO 8601 with Z). If 'conditions' omitted, this and end_datetime build a BETWEEN."},
+            "end_datetime": {"type": "string", "description": "End datetime (ISO 8601 with Z)."},
+            "conditions": {
+                "type": "array",
+                "description": "Custom conditions for the Query. If provided, takes precedence.",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "column": {"type": "string"},
+                        "operator": {"type": "integer"},
+                        "values": {"type": "array", "items": {"type": ["string","number"]}}
+                    },
+                    "required": ["column","operator","values"]
+                }
+            },
+            "user_id": {
+                "type": ["string","number"],
+                "description": "Convenience filter: constrains to this user_id (mapped to column 'user_id.user_id')."
+            },
+            "user_name": {
+                "type": "string",
+                "description": "Convenience filter: resolve name -> user_id and filter (exact match preferred)."
+            },
+            "event_types": {
+                "type": "array",
+                "items": {"type": ["string","number"]},
+                "description": "Convenience filter: adds EQUAL condition on event_type_id with provided values."
+            },
+            "columns": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Columns to export (default matches BioStar example).",
+                "default": ["datetime","door_id.name","device_id.id","device_id.name","user_group_id","user_id","temperature","event_type_id","tna_key"]
+            },
+            "headers": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "CSV headers (must match columns length).",
+                "default": ["Date","Door","Device ID","Device","User Group","User","Temperature","Event","TNA Key"]
+            },
+            "offset": {"type": "integer", "description": "Offset for pagination.", "default": 0},
+            "time_offset_minutes": {"type": "integer", "description": "Timezone offset in minutes, e.g., 480 for UTC+8.", "default": 0},
+            "use_centigrade": {"type": "boolean", "description": "Whether to export temperature in centigrade.", "default": True},
+            "copy_to_downloads": {"type": "boolean", "description": "Copy exported CSV to Windows Downloads.", "default": True},
+            "dest_dir": {"type": "string", "description": "Optional absolute destination directory (overrides Downloads)."},
+            "target_username": {"type": "string", "description": "If provided, copies to C:\\Users\\<name>\\Downloads."},
+            "filename": {"type": "string", "description": "Legacy/unused: server decides filename. Returned as 'filename' in response.", "default": "events_export.csv"}
+        },
+        "required": ["start_datetime", "end_datetime"]
+    }
+)
+
+GET_TEMPERATURE_LOGS_TOOL = Tool(
+    name="get-temperature-logs",
+    description="Get temperature measurement logs from thermal cameras",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "start_datetime": {
+                "type": "string",
+                "description": "Start datetime for temperature log search in ISO 8601 format with Z suffix (e.g., \"2025-07-26T15:00:00.000Z\")"
+            },
+            "end_datetime": {
+                "type": "string",
+                "description": "End datetime for temperature log search in ISO 8601 format with Z suffix (e.g., \"2025-08-02T14:59:59.000Z\")"
+            },
+            "user_id": {
+                "type": "string",
+                "description": "Filter by specific user ID"
+            },
+            "abnormal_only": {
+                "type": "boolean",
+                "description": "Show only abnormal temperature readings",
+                "default": False
+            },
+            "temperature_threshold": {
+                "type": "number",
+                "description": "Temperature threshold in Celsius (e.g., 37.5)",
+                "minimum": 35.0,
+                "maximum": 42.0
+            }
+        },
+        "required": []
+    }
+)
+
+# Export all tools
+EVENT_TOOLS = [
+    GET_EVENT_TYPES_TOOL,
+    SEARCH_EVENTS_TOOL,
+    GET_REALTIME_EVENTS_TOOL,
+    GET_ACCESS_LOGS_TOOL,
+    EXPORT_EVENTS_CSV_TOOL,
+    GET_TEMPERATURE_LOGS_TOOL
+]

biostar_x_mcp_server/tools/files.py

@@ -0,0 +1,28 @@
+from mcp.types import Tool
+
+# File handling tools for processing uploaded files
+READ_UPLOADED_FILE_TOOL = Tool(
+    name="read-uploaded-file",
+    description=(
+        "Read the content of an uploaded file from the current request context. "
+        "Use this when the user has attached files (CSV, PDF, PNG, JPEG, JPG, etc.) to their message. "
+        "Returns the file content as text (for CSV/text), OCR extracted text (for images), or base64 (for binary/PDF files). "
+        "For image files (PNG, JPEG, JPG), automatically performs OCR to extract text content. "
+        "This tool can be used to get file content before calling import-users-csv-smart or other tools."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "filename": {
+                "type": "string",
+                "description": "Name of the uploaded file to read (e.g., 'users.csv')"
+            }
+        },
+        "required": ["filename"]
+    }
+)
+
+# List of all file tools
+FILE_TOOLS = [
+    READ_UPLOADED_FILE_TOOL
+]

biostar_x_mcp_server/tools/help.py

@@ -0,0 +1,80 @@
+"""
+Help Tool Definitions (Web-based)
+
+Tools for searching documentation from docs.supremainc.com
+No vector database required - fetches directly from web
+"""
+from mcp.types import Tool
+
+# Help search tool (web-based)
+HELP_SEARCH_TOOL = Tool(
+    name="search-biostar-docs",
+    description="[DOCUMENTATION] Search BioStar X documentation from docs.supremainc.com. Use this when user asks 'how to', 'what is', 'explain', or wants information about BioStar X features. Fetches live documentation - always up to date. Returns relevant pages with content. For actual system operations, use action tools (get-users, create-user, control-door, etc.) instead.",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "Question or keyword to search (e.g., 'how to create user', 'access group setup', 'door monitoring')"
+            },
+            "language": {
+                "type": "string",
+                "enum": ["ko", "en"],
+                "description": "Language selection (default: auto-detect from query)",
+                "default": "en"
+            }
+        },
+        "required": ["query"]
+    }
+)
+
+# Get specific docs page
+GET_DOCS_PAGE_TOOL = Tool(
+    name="get-docs-page",
+    description="[DOCUMENTATION] Fetch a specific BioStar X documentation page by URL or path. Use when you need detailed information from a specific documentation section.",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "url": {
+                "type": "string",
+                "description": "Full URL or path (e.g., '/user/add-user', 'https://docs.supremainc.com/en/platform/biostar_x/user')"
+            },
+            "language": {
+                "type": "string",
+                "enum": ["ko", "en"],
+                "description": "Language for path-based URLs (default: en)",
+                "default": "en"
+            }
+        },
+        "required": ["url"]
+    }
+)
+
+# Tool help lookup
+TOOL_HELP_TOOL = Tool(
+    name="get-tool-help",
+    description="Get usage information and documentation for a specific BioStar X MCP tool.",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "tool_name": {
+                "type": "string",
+                "description": "Tool name (e.g., 'create-user', 'control-door', 'search-events')"
+            },
+            "language": {
+                "type": "string",
+                "enum": ["ko", "en"],
+                "description": "Language selection (default: en)",
+                "default": "en"
+            }
+        },
+        "required": ["tool_name"]
+    }
+)
+
+# Export help tools
+HELP_TOOLS = [
+    HELP_SEARCH_TOOL,
+    GET_DOCS_PAGE_TOOL,
+    TOOL_HELP_TOOL
+]

biostar_x_mcp_server/tools/logs.py

@@ -0,0 +1,123 @@
+"""
+BioStar X 로그 분석 도구 정의
+"""
+from mcp.types import Tool
+from typing import List
+
+LOG_TOOLS: List[Tool] = [
+    Tool(
+        name="analyze_server_logs",
+        description="BioStar X 서버 로그 파일을 분석하여 오류, 경고, 이벤트를 파악합니다. "
+                   "메인서버, 장치, 게이트웨이, API 서버 로그의 최신 50줄을 분석합니다. "
+                   "로그 기반 오류 분석, 문제 진단에 사용하세요. "
+                   "인증 없이 로컬 로그 파일을 직접 읽어 분석합니다.",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "log_path": {
+                    "type": "string",
+                    "description": "로그 파일 경로 (기본값: C:\\Program Files\\BioStar X\\logs)",
+                    "default": "C:\\Program Files\\BioStar X\\logs"
+                },
+                "lines_to_read": {
+                    "type": "integer",
+                    "description": "각 로그 파일에서 읽을 줄 수 (기본값: 50)",
+                    "default": 50,
+                    "minimum": 20,
+                    "maximum": 100
+                }
+            },
+            "required": []
+        }
+    ),
+    Tool(
+        name="get_log_file_info",
+        description="BioStar X 로그 디렉토리의 파일 목록과 정보를 조회합니다.",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "log_path": {
+                    "type": "string",
+                    "description": "로그 파일 경로 (기본값: C:\\Program Files\\BioStar X\\logs)",
+                    "default": "C:\\Program Files\\BioStar X\\logs"
+                }
+            },
+            "required": []
+        }
+    ),
+    Tool(
+        name="read_specific_log",
+        description="특정 로그 파일의 내용을 읽어 분석합니다.",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "log_file_path": {
+                    "type": "string",
+                    "description": "읽을 로그 파일의 전체 경로"
+                },
+                "lines_to_read": {
+                    "type": "integer",
+                    "description": "읽을 줄 수 (기본값: 50)",
+                    "default": 50,
+                    "minimum": 20,
+                    "maximum": 100
+                },
+                "from_end": {
+                    "type": "boolean",
+                    "description": "파일 끝에서부터 읽을지 여부 (기본값: true)",
+                    "default": True
+                }
+            },
+            "required": ["log_file_path"]
+        }
+    ),
+    Tool(
+        name="get_system_resources",
+        description="시스템 리소스 사용량을 실시간으로 모니터링합니다. "
+                   "CPU, 메모리, 디스크 사용량과 BioStar 프로세스의 메모리 사용량을 확인합니다. "
+                   "시스템 성능, 메모리 사용량, CPU 사용률 확인에 사용하세요. "
+                   "로그 분석이 아닌 실시간 시스템 모니터링 도구입니다.",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "include_all_processes": {
+                    "type": "boolean",
+                    "description": "모든 프로세스 정보 포함 여부 (기본값: false, BioStar 관련만)",
+                    "default": False
+                }
+            },
+            "required": []
+        }
+    ),
+    Tool(
+        name="analyze_server_status",
+        description="BioStar X 서버의 종합적인 상태를 분석합니다. "
+                   "로그 분석(오류/경고)과 시스템 리소스(CPU/메모리) 모니터링을 결합하여 전체적인 서버 상태를 파악합니다. "
+                   "사용자가 '서버 종합 분석', '서버 전체 상태', '서버 진단'을 요청하면 이 도구를 사용하세요. "
+                   "단순 로그 분석이나 리소스 모니터링만 필요하면 각각의 전용 도구를 사용하세요. "
+                   "인증 없이 로컬 로그와 시스템 정보를 직접 분석합니다.",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "log_path": {
+                    "type": "string",
+                    "description": "로그 파일 경로 (기본값: C:\\Program Files\\BioStar X\\logs)",
+                    "default": "C:\\Program Files\\BioStar X\\logs"
+                },
+                "lines_to_read": {
+                    "type": "integer",
+                    "description": "각 로그 파일에서 읽을 줄 수 (기본값: 50)",
+                    "default": 50,
+                    "minimum": 20,
+                    "maximum": 100
+                },
+                "include_system_resources": {
+                    "type": "boolean",
+                    "description": "시스템 리소스 정보 포함 여부 (기본값: true)",
+                    "default": True
+                }
+            },
+            "required": []
+        }
+    )
+]

biostar_x_mcp_server/tools/navigation.py

@@ -0,0 +1,89 @@
+"""
+Navigation Tools for Frontend Page Routing
+LLM이 작업 완료 후 적절한 페이지로 자동 이동을 제안
+"""
+from mcp.types import Tool
+
+NAVIGATION_TOOLS = [
+    Tool(
+        name="navigate-to-page",
+        description=""" MANDATORY: Call this tool at the END of every successful operation to navigate frontend to appropriate page.
+
+ YOU MUST ALWAYS CALL THIS TOOL after any operation (list, create, update, search) completes successfully.
+
+Navigation Rules (MANDATORY):
+- List devices (장치 조회) -> navigate-to-page(page_type="device_list")
+- List users (사용자 조회) -> navigate-to-page(page_type="user_list")
+- List doors (도어 조회) -> navigate-to-page(page_type="door_list")
+- Create user (사용자 생성) -> navigate-to-page(page_type="user_detail", resource_id="USER_ID")
+- Update user (사용자 수정) -> navigate-to-page(page_type="user_detail", resource_id="USER_ID")
+- Update door (도어 설정) -> navigate-to-page(page_type="door_detail", resource_id="DOOR_ID")
+- Update device (장치 설정) -> navigate-to-page(page_type="device_detail", resource_id="DEVICE_ID")
+- Search events (이벤트 조회) -> navigate-to-page(page_type="monitoring")
+
+Example workflow:
+```
+User: "현재 사용가능한 장치들 알려줘"
+Step 1: list-devices() <- Get device list
+Step 2: navigate-to-page(page_type="device_list") <- MUST CALL THIS!
+Step 3: Respond to user
+```
+
+```
+User: "홍길동 사용자를 추가해줘"
+Step 1: create-user(name="홍길동") <- Create user
+Step 2: navigate-to-page(page_type="user_detail", resource_id="12345") <- MUST CALL THIS!
+Step 3: Respond to user
+```
+
+ CRITICAL: If you see this tool in your tool list, you MUST call it at the end of your operation. Do NOT skip it.
+""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "page_type": {
+                    "type": "string",
+                    "enum": [
+                        "user_list",
+                        "user_detail",
+                        "door_list",
+                        "door_detail",
+                        "device_list",
+                        "device_detail",
+                        "monitoring",
+                        "custom_url"
+                    ],
+                    "description": "Type of page to navigate to"
+                },
+                "resource_id": {
+                    "type": "string",
+                    "description": "Resource ID (user_id, door_id, device_id) for detail pages. Required for *_detail page types."
+                },
+                "custom_url": {
+                    "type": "string",
+                    "description": "Custom URL path for custom_url page type. Example: /team/user/detail/123"
+                },
+                "action": {
+                    "type": "object",
+                    "description": "Optional action to perform on the page (click or scroll to element)",
+                    "properties": {
+                        "type": {
+                            "type": "string",
+                            "enum": ["click", "scroll"],
+                            "description": "Action type"
+                        },
+                        "ng_label_key": {
+                            "type": "string",
+                            "description": "Angular label key to target (e.g., 'common.information')"
+                        }
+                    }
+                },
+                "reason": {
+                    "type": "string",
+                    "description": "Brief explanation of why navigating to this page (for user context)"
+                }
+            },
+            "required": ["page_type"]
+        }
+    )
+]