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

biostar_x_mcp_server/schemas/users.py

@@ -0,0 +1,166 @@
+from typing import Optional, Union, List, Dict, Any
+from pydantic import BaseModel, Field, field_validator, model_validator
+import json
+from datetime import datetime
+
+
+class CreateUserInput(BaseModel):
+    user_id: Optional[Union[str, int]] = Field(default=None, description="User ID (automatically generated if omitted)")
+    name: str = Field(..., min_length=1, max_length=48, description="User's full name (max 48 characters)")
+    email: Optional[str] = Field(None, pattern=r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$', description="User's email address")
+    department: Optional[str] = Field(None, max_length=64, description="Department name (max 64 characters)")
+    user_title: Optional[str] = Field(None, description="Job title")
+    phone: Optional[str] = Field(None, description="Phone number")
+    disabled: Optional[bool] = Field(False, description="Whether the user is disabled (default: False)")
+    permission: Optional[int] = Field(None, description="Admin permission level (None for regular users)")
+    access_groups: Optional[List[int]] = Field(None, description="List of access group IDs")
+    login_id: Optional[str] = Field(None, description="Login ID (required for admin users)")
+    password: Optional[str] = Field(None, description="Password (required for admin users)")
+    user_ip: Optional[str] = Field(None, pattern=r'^(\d{1,3}\.){3}\d{1,3}$', description="IP address restriction (format: xxx.xxx.xxx.xxx)")
+    pin: Optional[int] = Field(None, ge=0, le=99999999999999999999999999999999, description="PIN number (up to 32 digits)")
+    photo: Optional[str] = Field(None, description="Base64-encoded user photo")
+
+
+class DeleteUserInput(BaseModel):
+    id: Optional[Union[str, int, List[Union[str, int]]]] = Field(None, description="ID(s) of the user to delete")
+    name: Optional[str] = Field(None, description="Name of the user to delete (supports partial match)")
+    confirm_multiple: Optional[bool] = Field(False, description="Safety flag: Must be true to delete multiple users at once")
+
+
+class BulkAddUsersInput(BaseModel):
+    base_name: str = Field(default="user", min_length=1, max_length=40, description="Base prefix for user names to generate")
+    count: int = Field(default=10, ge=1, le=30, description="Number of users to create in bulk (1-30)")
+
+
+class UpdateUserInput(BaseModel):
+    user_id: Optional[Union[str, int]] = Field(None, description="ID of the user to update")
+    name: Optional[str] = Field(None, description="Current name of the user (used to find the target)")
+    new_name: Optional[str] = Field(None, description="New name for the user")
+    user_group_id: Optional[int] = Field(None, description="ID of the user group to assign")
+    disabled: Optional[bool] = Field(None, description="Disable or enable the user")
+    start_datetime: Optional[str] = Field(None, description="Start date for user validity (ISO format or flexible formats like 20251225, 12.25.2025)")
+    expiry_datetime: Optional[str] = Field(None, description="Expiration date for user validity (ISO format or flexible formats like 20251225, 12.25.2025)")
+    start_date: Optional[str] = Field(None, description="Alias for start_datetime (flexible date format)")
+    end_date: Optional[str] = Field(None, description="Alias for expiry_datetime (flexible date format)")
+    email: Optional[str] = Field(None, description="Email address")
+    department: Optional[str] = Field(None, description="Department name")
+    user_title: Optional[str] = Field(None, description="Job title")
+    photo: Optional[str] = Field(None, description="Base64-encoded user photo")
+    phone: Optional[str] = Field(None, description="Phone number")
+    permission: Optional[int] = Field(None, description="Admin permission level")
+    access_groups: Optional[List[int]] = Field(None, description="List of access group IDs")
+    access_group_names: Optional[List[str]] = Field(None, description="List of access group names (alternative to access_groups)")
+    login_id: Optional[str] = Field(None, description="Login ID")
+    password: Optional[str] = Field(None, description="Login password")
+    user_ip: Optional[str] = Field(None, description="IP address restriction")
+    pin: Optional[int] = Field(None, description="PIN number")
+
+
+class AdvancedSearchUserInput(BaseModel):
+    limit: Optional[int] = Field(50, description="The maximum number of users to return. Default is 50.")
+    offset: Optional[str] = Field("0", description="The number of users to skip before starting to return results. Default is 0.")
+    user_id: Optional[str] = Field(None, description="The User ID to search, supports like search")
+    user_group_id: Optional[str] = Field(None, description="Group ID for search user. Also gets the child user group")
+    user_group_ids: Optional[List[int]] = Field(None, description="Array of Group IDs for advanced search parameter")
+    user_name: Optional[str] = Field(None, description="User name for Advance Search parameter, supports like search both encrypted and unencrypted")
+    user_email: Optional[str] = Field(None, description="User email, supports like search both encrypted and unencrypted")
+    user_phone: Optional[str] = Field(None, description="User Phone for Advance Search parameter, supports like search both encrypted and unencrypted")
+    user_department: Optional[str] = Field(None, description="User Department for Advance Search parameter, supports like search on unencrypted and exact search on encrypted")
+    user_access_group_ids: Optional[str] = Field(None, description="User access group id for advance search parameter, supports multiple value with format String with Delimiter , i.e 1,2,3")
+    user_title: Optional[str] = Field(None, description="User title for advance search parameter, supports like search on unencrypted and exact search on encrypted")
+    user_card: Optional[str] = Field(None, description="User card ID")
+    user_status: Optional[bool] = Field(None, description="User status for advance search parameter")
+    user_operator_level_id: Optional[str] = Field("255", description="User operator level id for Advance Search parameter")
+    user_custom_field_1: Optional[str] = Field(None, description="Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted")
+    user_custom_field_2: Optional[str] = Field(None, description="Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted")
+    user_custom_field_3: Optional[str] = Field(None, description="Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted")
+    user_custom_field_4: Optional[str] = Field(None, description="Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted")
+    user_custom_field_5: Optional[str] = Field(None, description="Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted")
+    user_custom_field_6: Optional[str] = Field(None, description="Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted")
+    user_custom_field_7: Optional[str] = Field(None, description="Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted")
+    user_custom_field_8: Optional[str] = Field(None, description="Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted")
+    user_custom_field_9: Optional[str] = Field(None, description="Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted")
+    user_custom_field_10: Optional[str] = Field(None, description="Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted")
+    order_by: Optional[str] = Field("user_id:false", description="Order, will accept with format properties:false, for example if we want to order by name, it will be user_name:false. false = ASCENDING and true = DESCENDING")
+
+
+class ExportCSVInput(BaseModel):
+    ids: Optional[List[Union[str, int]]] = Field(
+        default=None,
+        description="List of user IDs to export, or ['*'] to export all users"
+    )
+    search_text: Optional[str] = Field(
+        default=None,
+        description="Search text to find users for export. If provided, will search and export matching users."
+    )
+    limit: Optional[int] = Field(
+        default=50,
+        description="Maximum number of users to export (default: 50)"
+    )
+
+
+class BulkEditUsersInput(BaseModel):
+    """Input model for bulk editing users via PUT /api/users?adv=mode1."""
+
+    adv_criteria: Dict[str, Any] = Field(
+        ..., description="Advanced criteria object to select target users (e.g., {'user_group_id': 4037})."
+    )
+
+    # --- Optional change set (at least one must be provided) ---
+    new_user_group_id: Optional[Union[int, str]] = Field(
+        default=None, description="Destination user group id to assign to all matched users."
+    )
+    new_user_group: Optional[Dict[str, Any]] = Field(
+        default=None, description="Full user_group_id object to pass-through (e.g., {'id': '4036', 'name': 'ACE'})."
+    )
+
+    start_datetime: Optional[str] = Field(
+        default=None, description="New start datetime in ISO8601 (e.g., '2001-01-01T00:00:00')."
+    )
+    expiry_datetime: Optional[str] = Field(
+        default=None, description="New expiry datetime in ISO8601 (e.g., '2034-12-31T23:59:00')."
+    )
+
+    access_group_ids: Optional[List[Union[int, str]]] = Field(
+        default=None, description="List of Access Group IDs to assign (minimal form [{'id': <id>}])."
+    )
+    access_groups: Optional[List[Dict[str, Any]]] = Field(
+        default=None, description="Full AccessGroup objects to pass-through (supports accessLevels, users, etc.)."
+    )
+    clear_access_groups: bool = Field(
+        default=False, description="If true, sets 'access_groups': [] (ignores access_group_ids/access_groups)."
+    )
+
+    # --- Utility flags ---
+    dry_run: bool = Field(default=False, description="If true, returns planned payload without calling the API.")
+    timeout: int = Field(default=30, ge=1, le=120, description="HTTP timeout seconds for the PUT request.")
+
+    @model_validator(mode="after")
+    def _validate_changes(self):
+        """Ensure at least one change is requested and datetimes are consistent."""
+        has_group_change = self.new_user_group_id is not None or self.new_user_group is not None
+        has_period_change = self.start_datetime is not None or self.expiry_datetime is not None
+        has_access_change = self.clear_access_groups or self.access_group_ids is not None or self.access_groups is not None
+
+        if not (has_group_change or has_period_change or has_access_change):
+            raise ValueError(
+                "Provide at least one change among: new_user_group_id/new_user_group, "
+                "start_datetime/expiry_datetime, access_group_ids/access_groups/clear_access_groups."
+            )
+
+        # Validate datetime ordering if both provided
+        if self.start_datetime and self.expiry_datetime:
+            def _parse(s: str) -> datetime:
+                s = s.strip()
+                if s.endswith("Z"):
+                    s = s.replace("Z", "+00:00")
+                return datetime.fromisoformat(s)
+            try:
+                sdt = _parse(self.start_datetime)
+                edt = _parse(self.expiry_datetime)
+                if sdt >= edt:
+                    raise ValueError("start_datetime must be earlier than expiry_datetime.")
+            except Exception as e:
+                raise ValueError(f"Invalid datetime format or ordering: {e}")
+
+        return self

biostar_x_mcp_server/server.py

@@ -0,0 +1,335 @@
+"""
+BioStar X MCP Server
+Pure JSON-RPC STDIO server for MCP protocol
+
+Compatible with:
+- Claude Desktop
+- Claude Code
+- Any MCP-compatible client
+"""
+import asyncio
+import json
+import sys
+import logging
+from pathlib import Path
+
+# Setup logging to stderr (MCP uses stdout for protocol)
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+    stream=sys.stderr
+)
+logger = logging.getLogger(__name__)
+
+from .config import Config
+from .session import BioStarSession
+from .tool_manager import ToolManager
+from .handlers import (
+    AuthHandler,
+    UserHandler,
+    DoorHandler,
+    AccessHandler,
+    DeviceHandler,
+    EventHandler,
+    AuditHandler,
+    CardsHandler,
+    NavigationHandler,
+    FileHandler,
+    LogHandler,
+    OccupancyHandler,
+    HelpWebHandler
+)
+
+
+class BioStarMCPServer:
+    """BioStar X MCP Server implementation."""
+
+    def __init__(self):
+        logger.info("Initializing Suprema BioStar MCP Server...")
+
+        self.config = Config()
+
+        # Validate required credentials at startup
+        errors = self.config.validate_required()
+        if errors:
+            logger.error("=" * 60)
+            logger.error("CONFIGURATION ERROR - Missing required settings")
+            logger.error("=" * 60)
+            for err in errors:
+                logger.error(f"  ✗ {err}")
+            logger.error("")
+            logger.error("Set environment variables in Claude Desktop config:")
+            logger.error("")
+            logger.error('  "mcpServers": {')
+            logger.error('    "suprema-biostar": {')
+            logger.error('      "command": "uvx",')
+            logger.error('      "args": ["suprema-biostar-mcp"],')
+            logger.error('      "env": {')
+            logger.error('        "BIOSTAR_URL": "https://your-biostar-server",')
+            logger.error('        "BIOSTAR_USERNAME": "admin",')
+            logger.error('        "BIOSTAR_PASSWORD": "your-password"')
+            logger.error('      }')
+            logger.error('    }')
+            logger.error('  }')
+            logger.error("")
+            logger.error("Config file location:")
+            logger.error("  Windows: %APPDATA%\\Claude\\claude_desktop_config.json")
+            logger.error("  macOS: ~/Library/Application Support/Claude/claude_desktop_config.json")
+            logger.error("=" * 60)
+            raise RuntimeError(f"Missing required configuration: {', '.join(errors)}")
+
+        self.session = BioStarSession(self.config)
+        self.tool_manager = ToolManager()
+
+        # Initialize all handlers
+        self.handlers = {
+            "auth": AuthHandler(self.session),
+            "users": UserHandler(self.session),
+            "doors": DoorHandler(self.session),
+            "access": AccessHandler(self.session),
+            "devices": DeviceHandler(self.session),
+            "events": EventHandler(self.session),
+            "audit": AuditHandler(self.session),
+            "cards": CardsHandler(self.session),
+            "navigation": NavigationHandler(),  # No session needed
+            "files": FileHandler(),  # No session needed
+            "logs": LogHandler(self.session),
+            "occupancy": OccupancyHandler(self.session),
+            "help": HelpWebHandler(cache_ttl=self.config.docs_cache_ttl),
+        }
+
+        # Load all tool categories
+        categories = [
+            "auth", "users", "doors", "access", "devices",
+            "events", "audit", "cards", "navigation",
+            "files", "logs", "occupancy", "help"
+        ]
+
+        for category in categories:
+            success = self.tool_manager.load_category(category)
+            logger.info(f"Loading category '{category}': {'OK' if success else 'FAILED'}")
+
+        # Verify tools are loaded
+        all_tools = self.tool_manager.get_active_tools()
+        logger.info(f"Total tools loaded: {len(all_tools)}")
+        logger.info(f"Connected to: {self.config.biostar_url}")
+        logger.info("Suprema BioStar MCP Server initialized successfully")
+
+    async def handle_initialize(self, request):
+        """Handle MCP initialize request."""
+        logger.info("Handling initialize request")
+
+        response = {
+            "jsonrpc": "2.0",
+            "id": request.get("id", 0),
+            "result": {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {
+                    "tools": {
+                        "listChanged": True
+                    }
+                },
+                "serverInfo": {
+                    "name": "suprema-biostar-mcp",
+                    "version": "1.0.0"
+                }
+            }
+        }
+
+        print(json.dumps(response), flush=True)
+        logger.info("Sent initialize response")
+
+        # Send tools/listChanged notification
+        await asyncio.sleep(0.1)
+        notification = {
+            "jsonrpc": "2.0",
+            "method": "notifications/tools/listChanged",
+            "params": {}
+        }
+        print(json.dumps(notification), flush=True)
+
+    async def handle_list_tools(self, request):
+        """Handle MCP tools/list request."""
+        logger.info("Handling tools/list request")
+
+        tools = self.tool_manager.get_active_tools()
+        tools_data = []
+
+        for tool in tools:
+            tools_data.append({
+                "name": tool.name,
+                "description": tool.description,
+                "inputSchema": tool.inputSchema
+            })
+
+        response = {
+            "jsonrpc": "2.0",
+            "id": request.get("id", 0),
+            "result": {
+                "tools": tools_data
+            }
+        }
+
+        print(json.dumps(response), flush=True)
+        logger.info(f"Returned {len(tools_data)} tools")
+
+    async def handle_call_tool(self, request):
+        """Handle MCP tools/call request."""
+        params = request.get("params", {})
+        tool_name = params.get("name")
+        arguments = params.get("arguments", {})
+
+        logger.info(f"Handling tools/call for: {tool_name}")
+
+        try:
+            # Get the category for this tool
+            category = self.tool_manager.get_tool_category(tool_name)
+            handler = self.handlers.get(category)
+
+            # Special handling for help tools
+            help_tool_mapping = {
+                "search-biostar-docs": ("help", "search_help"),
+                "get-docs-page": ("help", "get_docs_page"),
+                "get-tool-help": ("help", "get_tool_help"),
+            }
+
+            result = None
+
+            if tool_name in help_tool_mapping:
+                cat, method_name = help_tool_mapping[tool_name]
+                handler = self.handlers.get(cat)
+                if handler and hasattr(handler, method_name):
+                    method_func = getattr(handler, method_name)
+                    result = await method_func(arguments)
+                else:
+                    raise ValueError(f"Handler {cat} has no method: {method_name}")
+            elif handler:
+                # Convert tool-name to method_name (e.g., get-users -> get_users)
+                method_name = tool_name.replace("-", "_")
+                if hasattr(handler, method_name):
+                    method_func = getattr(handler, method_name)
+                    result = await method_func(arguments)
+                else:
+                    raise ValueError(f"Handler has no method: {method_name}")
+            else:
+                raise ValueError(f"No handler for tool: {tool_name}")
+
+            # Convert result to proper MCP format
+            if isinstance(result, list):
+                content = []
+                for item in result:
+                    if hasattr(item, 'type') and hasattr(item, 'text'):
+                        content.append({
+                            "type": item.type,
+                            "text": item.text
+                        })
+                    else:
+                        content.append({"type": "text", "text": str(item)})
+            elif hasattr(result, 'type') and hasattr(result, 'text'):
+                content = [{"type": result.type, "text": result.text}]
+            else:
+                content = [{"type": "text", "text": str(result)}]
+
+            response = {
+                "jsonrpc": "2.0",
+                "id": request.get("id", 0),
+                "result": {
+                    "content": content
+                }
+            }
+
+            # Record tool usage
+            self.tool_manager.record_tool_usage(tool_name)
+
+        except Exception as e:
+            logger.error(f"Error executing tool {tool_name}: {e}", exc_info=True)
+            response = {
+                "jsonrpc": "2.0",
+                "id": request.get("id", 0),
+                "error": {
+                    "code": -32603,
+                    "message": f"Internal error: {str(e)}"
+                }
+            }
+
+        print(json.dumps(response), flush=True)
+
+    async def run(self):
+        """Main server loop - reads from stdin, writes to stdout."""
+        logger.info("Starting BioStar X MCP Server...")
+
+        while True:
+            try:
+                # Read input from stdin
+                line = await asyncio.get_event_loop().run_in_executor(
+                    None, sys.stdin.readline
+                )
+                if not line:
+                    logger.info("Stdin closed, shutting down")
+                    break
+
+                # Parse JSON-RPC request
+                request = json.loads(line.strip())
+                method = request.get("method")
+
+                logger.debug(f"Received request: {method}")
+
+                # Handle different MCP methods
+                if method == "initialize":
+                    await self.handle_initialize(request)
+                elif method == "tools/list":
+                    await self.handle_list_tools(request)
+                elif method == "tools/call":
+                    await self.handle_call_tool(request)
+                elif method == "notifications/initialized":
+                    logger.info("Received notifications/initialized")
+                    continue
+                elif method == "notifications/cancelled":
+                    logger.info("Received notifications/cancelled")
+                    continue
+                elif method == "resources/list":
+                    response = {
+                        "jsonrpc": "2.0",
+                        "id": request.get("id", 0),
+                        "result": {"resources": []}
+                    }
+                    print(json.dumps(response), flush=True)
+                elif method == "prompts/list":
+                    response = {
+                        "jsonrpc": "2.0",
+                        "id": request.get("id", 0),
+                        "result": {"prompts": []}
+                    }
+                    print(json.dumps(response), flush=True)
+                else:
+                    response = {
+                        "jsonrpc": "2.0",
+                        "id": request.get("id", 0),
+                        "error": {
+                            "code": -32601,
+                            "message": f"Method not found: {method}"
+                        }
+                    }
+                    print(json.dumps(response), flush=True)
+
+            except json.JSONDecodeError as e:
+                logger.error(f"JSON decode error: {e}")
+                continue
+            except Exception as e:
+                logger.error(f"Unexpected error: {e}", exc_info=True)
+                continue
+
+
+async def async_main():
+    """Async main entry point."""
+    server = BioStarMCPServer()
+    await server.run()
+
+
+def main():
+    """Synchronous main entry point for CLI."""
+    asyncio.run(async_main())
+
+
+if __name__ == "__main__":
+    main()