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

biostar_x_mcp_server/handlers/file_handler.py

@@ -0,0 +1,212 @@
+"""
+File Handler - Handle uploaded files from requests
+"""
+import logging
+import base64
+import io
+from typing import Dict, Any, List, Sequence
+from mcp.types import TextContent
+from biostar_x_mcp_server.handlers.base_handler import BaseHandler
+
+# OCR imports
+try:
+    import pytesseract
+    from PIL import Image
+    import os
+    
+    # Windows에서 Tesseract 경로 설정
+    if os.name == 'nt':  # Windows
+        tesseract_paths = [
+            r'C:\Program Files\Tesseract-OCR\tesseract.exe',
+            r'C:\Program Files (x86)\Tesseract-OCR\tesseract.exe',
+            r'C:\Users\{}\AppData\Local\Programs\Tesseract-OCR\tesseract.exe'.format(os.getenv('USERNAME', ''))
+        ]
+        
+        for path in tesseract_paths:
+            if os.path.exists(path):
+                pytesseract.pytesseract.tesseract_cmd = path
+                # Tesseract path configured
+                break
+    
+    # Test OCR library
+    try:
+        version = pytesseract.get_tesseract_version()
+        # Tesseract OCR is available
+        OCR_AVAILABLE = True
+    except Exception:
+        # Tesseract test failed
+        OCR_AVAILABLE = False
+    
+except ImportError:
+    # OCR library import failed
+    OCR_AVAILABLE = False
+
+logger = logging.getLogger(__name__)
+
+
+class FileHandler(BaseHandler):
+    """Handler for file operations on uploaded files"""
+    
+    def __init__(self):
+        """Initialize FileHandler without session (no API calls needed)"""
+        super().__init__(session=None)
+        self.uploaded_files = {}  # Store uploaded files per session
+        
+    def set_uploaded_files(self, session_id: str, files: List[Dict[str, Any]]):
+        """Store uploaded files for a session"""
+        self.uploaded_files[session_id] = files
+        logger.info(f" Stored {len(files)} files for session {session_id}")
+    
+    def _extract_text_from_image(self, base64_content: str) -> str:
+        """Extract text from image using OCR"""
+        logger.info(" OCR started")
+        
+        if not OCR_AVAILABLE:
+            logger.error(" OCR library not available")
+            return " OCR library is not installed. Please install pytesseract and Pillow."
+        
+        try:
+            # Decode base64 to bytes
+            image_bytes = base64.b64decode(base64_content)
+            
+            # Open image with PIL
+            image = Image.open(io.BytesIO(image_bytes))
+            
+            # Extract text using pytesseract
+            text = pytesseract.image_to_string(image, lang='eng')
+            
+            result = text.strip() if text.strip() else "No text found in image."
+            logger.info(" OCR completed")
+            return result
+            
+        except Exception as e:
+            logger.error(f" OCR error: {e}")
+            return f" Error occurred during OCR processing: {str(e)}"
+        
+    async def read_uploaded_file(self, args: dict) -> Sequence[TextContent]:
+        """
+        Read the content of an uploaded file
+        
+        Args:
+            filename: Name of the uploaded file
+        
+        Returns:
+            File content as text or base64
+        """
+        filename = args.get("filename", "").strip()
+        logger.info(f" Reading file: {filename}")
+        
+        if not filename:
+            return [TextContent(type="text", text=" filename parameter is required")]
+        
+        # Get session ID
+        session_id = getattr(self, 'client_session_id', 'default')
+        
+        # Check if files exist for this session
+        if session_id not in self.uploaded_files:
+            return [TextContent(type="text", text=f" No uploaded files found for this session")]
+        
+        files = self.uploaded_files[session_id]
+        
+        # Find the file
+        file_data = None
+        for f in files:
+            if f.get("filename", "").lower() == filename.lower():
+                file_data = f
+                break
+        
+        if not file_data:
+            available = [f.get("filename") for f in files]
+            return [TextContent(
+                type="text",
+                text=f" File '{filename}' not found.\n"
+                     f"Available files: {', '.join(available)}"
+            )]
+        
+        # Return file content based on type
+        file_type = file_data.get("type")
+        
+        if file_type == "csv":
+            content = file_data.get("content", "")
+            base64_content = file_data.get("base64", "")
+            original_format = file_data.get("original_format", "csv")
+            
+            file_type_label = "XLSX" if original_format == "xlsx" else "CSV"
+            format_note = "(Converted from XLSX to CSV format)\n\n" if original_format == "xlsx" else ""
+            
+            return [TextContent(
+                type="text",
+                text=f" {file_type_label} file read successfully: {filename}\n\n"
+                     f"File size: {file_data.get('size', 0)} bytes\n"
+                     f"{format_note}"
+                     f"Preview:\n```csv\n{file_data.get('preview', '')}\n```\n\n"
+                     f"Full content:\n```csv\n{content}\n```\n\n"
+                     f"Base64 (for import tools):\n{base64_content[:100]}... (total {len(base64_content)} chars)\n\n"
+                     f" To add users, call import-users-csv-smart tool with:\n"
+                     f"- file_text: (full content above)\n"
+                     f"- original_file_name: {filename}"
+            )]
+            
+        elif file_type == "pdf":
+            base64_content = file_data.get("base64", "")
+            return [TextContent(
+                type="text",
+                text=f" PDF file read successfully: {filename}\n\n"
+                     f"File size: {file_data.get('size', 0)} bytes\n"
+                     f"Base64 content:\n{base64_content[:100]}... (total {len(base64_content)} chars)\n\n"
+                     f" PDF file requires text extraction."
+            )]
+            
+        elif file_type == "image":
+            base64_content = file_data.get("base64", "")
+            
+            # Extract text using OCR
+            extracted_text = self._extract_text_from_image(base64_content)
+            
+            # Natural response based on OCR results
+            if "No text found in image." in extracted_text:
+                response_text = f" Image file confirmed: {filename}\n\n"
+                response_text += f"File size: {file_data.get('size', 0)} bytes\n\n"
+                response_text += f"This image appears to be primarily graphics or icons with unclear text.\n"
+                response_text += f"Please describe the image content directly for more accurate assistance."
+            elif "Error occurred during OCR processing" in extracted_text:
+                response_text = f" Image file confirmed: {filename}\n\n"
+                response_text += f"File size: {file_data.get('size', 0)} bytes\n\n"
+                response_text += f"There was a temporary issue with image analysis.\n"
+                response_text += f"Please briefly describe the main content of the image for assistance."
+            else:
+                response_text = f" Image analysis completed: {filename}\n\n"
+                response_text += f"File size: {file_data.get('size', 0)} bytes\n\n"
+                response_text += f" Extracted text:\n```\n{extracted_text}\n```\n\n"
+                response_text += f" Please let me know what assistance you need based on the above content."
+            
+            return [TextContent(type="text", text=response_text)]
+            
+        elif file_type == "text":
+            content = file_data.get("content", "")
+            return [TextContent(
+                type="text",
+                text=f" Text file read successfully: {filename}\n\n"
+                     f"File size: {file_data.get('size', 0)} bytes\n\n"
+                     f"Content:\n```\n{content}\n```"
+            )]
+            
+        elif file_type == "binary":
+            base64_content = file_data.get("base64", "")
+            return [TextContent(
+                type="text",
+                text=f" Binary file read successfully: {filename}\n\n"
+                     f"File size: {file_data.get('size', 0)} bytes\n"
+                     f"Base64 content:\n{base64_content[:100]}... (total {len(base64_content)} chars)"
+            )]
+            
+        elif file_type == "error":
+            error = file_data.get("error", "Unknown error")
+            return [TextContent(
+                type="text",
+                text=f" File read error: {filename}\n\n"
+                     f"Error: {error}"
+            )]
+        
+        return [TextContent(type="text", text=f" Unknown file type: {file_type}")]
+

biostar_x_mcp_server/handlers/help_web_handler.py

@@ -0,0 +1,379 @@
+"""
+Web-based Help Handler for BioStar X MCP Server
+Fetches documentation directly from docs.supremainc.com instead of using vector DB
+"""
+import logging
+import json
+import re
+from typing import Sequence, Dict, Any, Optional, List
+from datetime import datetime, timedelta
+from mcp.types import TextContent
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+class HelpWebHandler:
+    """Web-based documentation search handler using docs.supremainc.com"""
+
+    DOCS_BASE = "https://docs.supremainc.com"
+
+    # BioStar X documentation section mapping (keyword -> URL path)
+    DOC_SECTIONS = {
+        # Getting Started
+        "overview": "/en/platform/biostar_x/overview",
+        "install": "/en/platform/biostar_x/express-install",
+        "custom install": "/en/platform/biostar_x/custom-install",
+        "setup": "/en/platform/biostar_x/initial-setup-guide",
+        "launcher": "/en/platform/biostar_x/ui-launcher",
+        "server management": "/en/platform/biostar_x/server-management",
+
+        # User Management
+        "user": "/en/platform/biostar_x/user",
+        "add user": "/en/platform/biostar_x/user/add-user",
+        "edit user": "/en/platform/biostar_x/user/editing-user",
+        "delete user": "/en/platform/biostar_x/user/deleting-user",
+        "credential": "/en/platform/biostar_x/user/credential-enrollment",
+        "user group": "/en/platform/biostar_x/user/user-group",
+        "csv import": "/en/platform/biostar_x/user/csv-import",
+        "csv export": "/en/platform/biostar_x/user/exporting-users",
+
+        # Monitoring
+        "monitoring": "/en/platform/biostar_x/monitoring",
+        "door monitoring": "/en/platform/biostar_x/monitoring/door-monitoring",
+        "device monitoring": "/en/platform/biostar_x/monitoring/device-monitoring",
+        "event": "/en/platform/biostar_x/monitoring/event-log",
+        "event log": "/en/platform/biostar_x/monitoring/event-log",
+        "map": "/en/platform/biostar_x/monitoring/map-monitoring",
+        "video": "/en/platform/biostar_x/monitoring/video-monitoring",
+
+        # Data
+        "data": "/en/platform/biostar_x/data",
+        "backup": "/en/platform/biostar_x/data/backup-restore",
+        "restore": "/en/platform/biostar_x/data/backup-restore",
+
+        # Dashboard
+        "dashboard": "/en/platform/biostar_x/dashboard",
+
+        # Settings
+        "settings": "/en/platform/biostar_x/settings",
+        "access group": "/en/platform/biostar_x/settings/access-group",
+        "access level": "/en/platform/biostar_x/settings/access-level",
+        "floor": "/en/platform/biostar_x/settings/floor",
+        "zone": "/en/platform/biostar_x/settings/zone",
+        "schedule": "/en/platform/biostar_x/settings/schedule",
+        "door setting": "/en/platform/biostar_x/settings/door",
+        "device setting": "/en/platform/biostar_x/settings/device",
+        "elevator": "/en/platform/biostar_x/settings/elevator",
+        "email": "/en/platform/biostar_x/settings/email",
+        "smtp": "/en/platform/biostar_x/settings/email",
+        "card format": "/en/platform/biostar_x/settings/credential-format",
+        "wiegand": "/en/platform/biostar_x/settings/credential-format",
+        "operator": "/en/platform/biostar_x/settings/operator",
+
+        # Advanced Settings
+        "apb": "/en/platform/biostar_x/advanced-settings/anti-passback",
+        "anti-passback": "/en/platform/biostar_x/advanced-settings/anti-passback",
+        "fire alarm": "/en/platform/biostar_x/advanced-settings/fire-alarm-zone",
+        "interlock": "/en/platform/biostar_x/advanced-settings/interlock",
+        "intrusion": "/en/platform/biostar_x/advanced-settings/intrusion-alarm",
+        "muster": "/en/platform/biostar_x/advanced-settings/muster",
+        "occupancy": "/en/platform/biostar_x/advanced-settings/occupancy-management",
+        "roll call": "/en/platform/biostar_x/advanced-settings/roll-call",
+
+        # Plugins
+        "plugin": "/en/platform/biostar_x/plugins",
+        "ta": "/en/platform/biostar_x/plugins/ta-integration",
+        "airfob": "/en/platform/biostar_x/plugins/airfob",
+
+        # Licensing
+        "license": "/en/platform/biostar_x/licensing",
+
+        # Korean keywords
+        "사용자": "/ko/platform/biostar_x/user",
+        "출입문": "/ko/platform/biostar_x/monitoring/door-monitoring",
+        "장치": "/ko/platform/biostar_x/monitoring/device-monitoring",
+        "이벤트": "/ko/platform/biostar_x/monitoring/event-log",
+        "접근그룹": "/ko/platform/biostar_x/settings/access-group",
+        "접근레벨": "/ko/platform/biostar_x/settings/access-level",
+        "설치": "/ko/platform/biostar_x/express-install",
+        "대시보드": "/ko/platform/biostar_x/dashboard",
+        "설정": "/ko/platform/biostar_x/settings",
+    }
+
+    # Language detection keywords
+    KOREAN_KEYWORDS = ["사용자", "출입문", "장치", "이벤트", "접근", "설정", "설치", "카드", "로그", "모니터링"]
+
+    def __init__(self, cache_ttl: int = 3600):
+        """Initialize HelpWebHandler with cache settings."""
+        self.cache_ttl = cache_ttl
+        self._cache: Dict[str, Dict[str, Any]] = {}
+
+    def _detect_language(self, text: str) -> str:
+        """Detect language from query text."""
+        korean_chars = len(re.findall(r'[가-힣]', text))
+        total_chars = len(text.replace(" ", ""))
+
+        if total_chars > 0 and korean_chars / total_chars > 0.2:
+            return "ko"
+        return "en"
+
+    def _find_relevant_urls(self, query: str, language: str) -> List[str]:
+        """Find relevant documentation URLs based on query keywords."""
+        query_lower = query.lower()
+        matches = []
+
+        # Check each section for keyword matches
+        for keyword, path in self.DOC_SECTIONS.items():
+            if keyword.lower() in query_lower:
+                # Adjust path for language
+                if language == "ko" and path.startswith("/en/"):
+                    path = path.replace("/en/", "/ko/", 1)
+                elif language == "en" and path.startswith("/ko/"):
+                    path = path.replace("/ko/", "/en/", 1)
+
+                full_url = f"{self.DOCS_BASE}{path}"
+                if full_url not in matches:
+                    matches.append(full_url)
+
+        # If no matches, return overview page
+        if not matches:
+            matches.append(f"{self.DOCS_BASE}/{language}/platform/biostar_x/overview")
+
+        return matches[:5]  # Limit to 5 URLs
+
+    def _extract_main_content(self, html: str) -> str:
+        """Extract main content from HTML page."""
+        # Remove script and style tags
+        html = re.sub(r'<script[^>]*>.*?</script>', '', html, flags=re.DOTALL | re.IGNORECASE)
+        html = re.sub(r'<style[^>]*>.*?</style>', '', html, flags=re.DOTALL | re.IGNORECASE)
+
+        # Try to find main content area
+        main_match = re.search(r'<main[^>]*>(.*?)</main>', html, flags=re.DOTALL | re.IGNORECASE)
+        if main_match:
+            html = main_match.group(1)
+        else:
+            # Try article tag
+            article_match = re.search(r'<article[^>]*>(.*?)</article>', html, flags=re.DOTALL | re.IGNORECASE)
+            if article_match:
+                html = article_match.group(1)
+
+        # Remove HTML tags but preserve text
+        text = re.sub(r'<[^>]+>', ' ', html)
+
+        # Clean up whitespace
+        text = re.sub(r'\s+', ' ', text).strip()
+
+        # Decode HTML entities
+        text = text.replace('&nbsp;', ' ')
+        text = text.replace('&lt;', '<')
+        text = text.replace('&gt;', '>')
+        text = text.replace('&amp;', '&')
+        text = text.replace('&quot;', '"')
+
+        return text[:4000]  # Limit content length
+
+    def _get_cached(self, url: str) -> Optional[str]:
+        """Get cached content if not expired."""
+        if url in self._cache:
+            cached = self._cache[url]
+            if datetime.now() - cached["timestamp"] < timedelta(seconds=self.cache_ttl):
+                return cached["content"]
+        return None
+
+    def _set_cache(self, url: str, content: str):
+        """Cache content with timestamp."""
+        self._cache[url] = {
+            "content": content,
+            "timestamp": datetime.now()
+        }
+
+    async def search_help(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Search BioStar X documentation from docs.supremainc.com
+
+        Args:
+            args: Dictionary containing:
+                - query: Search query (required)
+                - language: Language code ("ko" or "en", default: auto-detect)
+
+        Returns:
+            Documentation search results with URLs
+        """
+        query = args.get("query", "").strip()
+        if not query:
+            return self._error_response("Search query is required.")
+
+        # Auto-detect language if not specified
+        language = args.get("language") or self._detect_language(query)
+
+        # Find relevant URLs
+        urls = self._find_relevant_urls(query, language)
+
+        # Fetch content from URLs
+        results = []
+        async with httpx.AsyncClient(timeout=10.0, follow_redirects=True) as client:
+            for url in urls[:3]:  # Fetch max 3 pages
+                try:
+                    # Check cache first
+                    cached_content = self._get_cached(url)
+                    if cached_content:
+                        results.append({
+                            "url": url,
+                            "content": cached_content,
+                            "source": "cache"
+                        })
+                        continue
+
+                    response = await client.get(url)
+                    if response.status_code == 200:
+                        content = self._extract_main_content(response.text)
+                        self._set_cache(url, content)
+                        results.append({
+                            "url": url,
+                            "content": content,
+                            "source": "web"
+                        })
+                except Exception as e:
+                    logger.warning(f"Failed to fetch {url}: {e}")
+                    continue
+
+        if not results:
+            return self._no_results_response(query)
+
+        return self._success_response({
+            "message": f"Found {len(results)} documentation pages for: '{query}'",
+            "search_query": query,
+            "language": language,
+            "source": "docs.supremainc.com",
+            "total_results": len(results),
+            "results": results,
+            "docs_url": f"{self.DOCS_BASE}/{language}/platform/biostar_x"
+        })
+
+    async def get_docs_page(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Get a specific documentation page by URL or path
+
+        Args:
+            args: Dictionary containing:
+                - url: Full URL or path (required)
+                - language: Language code ("ko" or "en", default: "en")
+
+        Returns:
+            Page content
+        """
+        url = args.get("url", "").strip()
+        if not url:
+            return self._error_response("URL or path is required.")
+
+        # If it's a path, convert to full URL
+        if not url.startswith("http"):
+            language = args.get("language", "en")
+            if not url.startswith("/"):
+                url = "/" + url
+            if not url.startswith(f"/{language}/"):
+                url = f"/{language}/platform/biostar_x{url}"
+            url = f"{self.DOCS_BASE}{url}"
+
+        try:
+            # Check cache first
+            cached_content = self._get_cached(url)
+            if cached_content:
+                return self._success_response({
+                    "url": url,
+                    "content": cached_content,
+                    "source": "cache"
+                })
+
+            async with httpx.AsyncClient(timeout=10.0, follow_redirects=True) as client:
+                response = await client.get(url)
+
+                if response.status_code == 200:
+                    content = self._extract_main_content(response.text)
+                    self._set_cache(url, content)
+                    return self._success_response({
+                        "url": url,
+                        "content": content,
+                        "source": "web"
+                    })
+                else:
+                    return self._error_response(f"Failed to fetch page: HTTP {response.status_code}")
+
+        except Exception as e:
+            logger.error(f"Error fetching docs page: {e}")
+            return self._error_response(f"Failed to fetch documentation: {str(e)}")
+
+    async def search_api_docs(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Search API documentation - redirects to help search with API focus
+        """
+        query = args.get("query", "")
+        args["query"] = f"API {query}"
+        return await self.search_help(args)
+
+    async def search_manual(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Search user manual - redirects to help search
+        """
+        return await self.search_help(args)
+
+    async def get_tool_help(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Get help for a specific MCP tool
+        """
+        tool_name = args.get("tool_name", "")
+        if not tool_name:
+            return self._error_response("Tool name is required.")
+
+        # Map tool names to documentation sections
+        tool_to_section = {
+            "login": "setup",
+            "logout": "setup",
+            "get-users": "user",
+            "create-user": "add user",
+            "update-user": "edit user",
+            "delete-user": "delete user",
+            "get-doors": "door monitoring",
+            "control-door": "door monitoring",
+            "list-devices": "device monitoring",
+            "search-events": "event log",
+            "get-access-groups": "access group",
+            "create-access-group": "access group",
+            "get-access-levels": "access level",
+        }
+
+        section = tool_to_section.get(tool_name, "overview")
+        args["query"] = section
+        return await self.search_help(args)
+
+    def _success_response(self, data: Dict[str, Any]) -> Sequence[TextContent]:
+        """Create success response."""
+        return [TextContent(
+            type="text",
+            text=json.dumps({
+                "status": "success",
+                "data": data
+            }, ensure_ascii=False, indent=2)
+        )]
+
+    def _error_response(self, message: str) -> Sequence[TextContent]:
+        """Create error response."""
+        return [TextContent(
+            type="text",
+            text=json.dumps({
+                "status": "error",
+                "error": message
+            }, ensure_ascii=False, indent=2)
+        )]
+
+    def _no_results_response(self, query: str) -> Sequence[TextContent]:
+        """Create no results response."""
+        return [TextContent(
+            type="text",
+            text=json.dumps({
+                "status": "no_results",
+                "message": f"Could not find documentation for: '{query}'",
+                "suggestion": f"Try browsing the documentation directly at {self.DOCS_BASE}/en/platform/biostar_x"
+            }, ensure_ascii=False, indent=2)
+        )]