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

biostar_x_mcp_server/schemas/__init__.py

@@ -0,0 +1,21 @@
+from .tool_response import ToolResponse
+from .users import (
+    CreateUserInput,
+    DeleteUserInput,
+    UpdateUserInput,
+    AdvancedSearchUserInput,
+    ExportCSVInput,
+    BulkAddUsersInput,
+    BulkEditUsersInput,
+)
+
+__all__ = [
+    "ToolResponse",
+    "CreateUserInput",
+    "DeleteUserInput",
+    "UpdateUserInput",
+    "AdvancedSearchUserInput",
+    "ExportCSVInput",
+    "BulkAddUsersInput",
+    "BulkEditUsersInput",
+]

biostar_x_mcp_server/schemas/access.py

@@ -0,0 +1,158 @@
+from typing import Optional, Union, List, Dict, Any
+from pydantic import BaseModel, Field, model_validator
+
+
+# ============================================================================
+# Access Group Schemas
+# ============================================================================
+
+class GetAccessGroupsInput(BaseModel):
+    """Input schema for get-access-groups tool"""
+    pass  # No required fields
+
+
+class GetAccessGroupInput(BaseModel):
+    """Input schema for get-access-group tool"""
+    group_id: int = Field(..., description="ID of the access group to retrieve")
+
+
+class CreateAccessGroupInput(BaseModel):
+    """Input schema for create-access-group tool"""
+    name: str = Field(..., description="Access group name")
+    description: Optional[str] = Field(default="", description="Description for the access group")
+    user_ids: Optional[List[Union[str, int]]] = Field(None, description="Explicit list of user ids to include. Do NOT auto-select.")
+    access_level_ids: Optional[List[Union[str, int]]] = Field(None, description="Existing access level ids to assign to this group.")
+    user_group_ids: Optional[List[Union[int, str]]] = Field(None, description="Explicit user group ids to include (validated against GET /api/user_groups)")
+    user_group_search_text: Optional[str] = Field(None, description="Substring to search user group name (3-case resolution)")
+
+
+class UpdateAccessGroupInput(BaseModel):
+    """Input schema for update-access-group tool"""
+    group_id: int = Field(..., description="ID of the access group to update")
+    name: Optional[str] = Field(None, description="New name")
+    description: Optional[str] = Field(None, description="New description")
+
+    # Users
+    user_ids: Optional[List[Union[str, int]]] = Field(None, description="Final set of user ids (replacement).")
+    new_users: Optional[List[Union[str, int]]] = Field(None, description="User ids to add (delta).")
+    delete_users: Optional[List[Union[str, int]]] = Field(None, description="User ids to remove (delta).")
+
+    # Access Levels (replacement)
+    access_level_ids: Optional[List[Union[str, int]]] = Field(None, description="Replace the group's access_levels with these ids.")
+
+    # User Groups - Replacement
+    user_group_ids: Optional[List[Union[int, str]]] = Field(None, description="Replace user_groups with these ids. If [], clears all.")
+    user_group_search_text: Optional[str] = Field(None, description="(Legacy) Single-match replacement by name.")
+
+    # User Groups - Delta
+    add_user_group_ids: Optional[List[Union[int, str]]] = Field(None, description="Add these user group ids (delta).")
+    remove_user_group_ids: Optional[List[Union[int, str]]] = Field(None, description="Remove these user group ids (delta).")
+    add_user_group_search_text: Optional[str] = Field(None, description="Add by name (3-case resolution).")
+    remove_user_group_search_text: Optional[str] = Field(None, description="Remove by name (3-case resolution).")
+
+
+class DeleteAccessGroupInput(BaseModel):
+    """Input schema for delete-access-group tool"""
+    group_id: int = Field(..., description="ID of the access group to delete")
+
+
+class SearchAccessGroupsInput(BaseModel):
+    """Input schema for search-access-groups tool"""
+    limit: int = Field(..., description="To limit result by n record(s), 0 to show all")
+    order_by: str = Field(..., description="Order by string like 'id:false' or 'name:true'")
+
+
+# ============================================================================
+# Access Level Schemas
+# ============================================================================
+
+class GetAccessLevelsInput(BaseModel):
+    """Input schema for get-access-levels tool"""
+    limit: Optional[int] = Field(default=50, description="Limit number of records (0 to show all)")
+    offset: Optional[int] = Field(default=0, description="Offset/skip records")
+    order_by: Optional[str] = Field(default="id:false", description="Order by (e.g., 'id:false')")
+
+
+class GetAccessLevelInput(BaseModel):
+    """Input schema for get-access-level tool"""
+    level_id: int = Field(..., description="ID of the access level to retrieve")
+
+
+class AccessLevelItemInput(BaseModel):
+    """Input schema for access_level_items array item"""
+    doors: List[Union[int, str]] = Field(..., min_length=1, description="Door IDs or names; de-duplicated per item.")
+
+
+class CreateAccessLevelInput(BaseModel):
+    """Input schema for create-access-level tool"""
+    name: str = Field(..., description="Unique Access Level name.")
+    description: Optional[str] = Field(default="", description="Description for the Access Level.")
+    confirm: Optional[bool] = Field(default=True, description="If true, create the Access Level; otherwise preview only. Defaults to True for automatic creation.")
+    door_ids: Optional[List[int]] = Field(None, description="🆕 Simple mode: List of door IDs to include (e.g., [177, 178, 179]). Mutually exclusive with access_level_items.")
+    door_names: Optional[List[str]] = Field(None, description="🆕 Simple mode: List of door names to include (e.g., ['Main Entrance', 'CEO Office']). Will be resolved to IDs. Mutually exclusive with access_level_items.")
+    auto_update_on_exist: Optional[bool] = Field(default=True, description="🆕 If true (default), automatically update if Access Level with same name exists. If false, skip creation and return existing info.")
+    access_level_items: Optional[List[AccessLevelItemInput]] = Field(None, min_length=1, description="Advanced mode: Array tying doors (1..n) to the enforced 'Always' schedule (applied internally). Each item must include `doors`. Mutually exclusive with door_ids/door_names.")
+
+    @model_validator(mode="after")
+    def validate_door_specification(self):
+        """Ensure at least one door specification method is provided"""
+        has_door_ids = self.door_ids is not None and len(self.door_ids) > 0
+        has_door_names = self.door_names is not None and len(self.door_names) > 0
+        has_access_level_items = self.access_level_items is not None and len(self.access_level_items) > 0
+
+        if not (has_door_ids or has_door_names or has_access_level_items):
+            raise ValueError("At least one of door_ids, door_names, or access_level_items must be provided")
+
+        # Check mutual exclusivity
+        provided = sum([has_door_ids, has_door_names, has_access_level_items])
+        if provided > 1:
+            raise ValueError("Only one of door_ids, door_names, or access_level_items can be provided")
+
+        return self
+
+
+class UpdateAccessLevelInput(BaseModel):
+    """Input schema for update-access-level tool"""
+    level_id: Optional[int] = Field(None, description="ID of the access level to update")
+    level_name: Optional[str] = Field(None, description="Exact name of the access level to update")
+    search_text: Optional[str] = Field(None, description="Fuzzy search text (name/description contains)")
+    name: Optional[str] = Field(None, description="New name (optional)")
+    description: Optional[str] = Field(None, description="New description (optional; empty string clears)")
+    set_doors: Optional[List[Union[int, str]]] = Field(None, description="Full replacement of door ids (takes precedence over add/remove)")
+    add_doors: Optional[List[Union[int, str]]] = Field(None, description="Door ids to add")
+    remove_doors: Optional[List[Union[int, str]]] = Field(None, description="Door ids to remove (ignored if not currently assigned)")
+    dry_run: Optional[bool] = Field(default=False, description="Preview changes without calling the API")
+
+
+class DeleteAccessLevelInput(BaseModel):
+    """Input schema for delete-access-level tool"""
+    level_id: int = Field(..., description="ID of the access level to delete")
+
+
+class AddAccessLevelToGroupInput(BaseModel):
+    """Input schema for add-access-level-to-group tool"""
+    access_group_id: int = Field(..., description="Target access group ID")
+    access_level_id: Optional[int] = Field(None, description="An access level id to add (single)")
+    access_level_ids: Optional[List[Union[int, str]]] = Field(None, description="Access level ids to add (one or many)")
+
+    @model_validator(mode="after")
+    def validate_access_level_specification(self):
+        """Ensure at least one access level is specified"""
+        if self.access_level_id is None and (self.access_level_ids is None or len(self.access_level_ids) == 0):
+            raise ValueError("Either access_level_id or access_level_ids must be provided")
+        return self
+
+
+class RemoveAccessLevelFromGroupInput(BaseModel):
+    """Input schema for remove-access-level-from-group tool"""
+    access_group_id: int = Field(..., description="Target access group ID")
+    access_level_id: Optional[int] = Field(None, description="An access level id to remove (single)")
+    access_level_ids: Optional[List[Union[int, str]]] = Field(None, description="Access level ids to remove (one or many)")
+
+    @model_validator(mode="after")
+    def validate_access_level_specification(self):
+        """Ensure at least one access level is specified"""
+        if self.access_level_id is None and (self.access_level_ids is None or len(self.access_level_ids) == 0):
+            raise ValueError("Either access_level_id or access_level_ids must be provided")
+        return self
+

biostar_x_mcp_server/schemas/audit.py

@@ -0,0 +1,73 @@
+from typing import Optional, List
+from pydantic import BaseModel, Field
+
+
+# ============================================================================
+# Audit Condition Schemas (nested)
+# ============================================================================
+
+class AuditConditionInput(BaseModel):
+    """Input schema for audit condition item"""
+    column: str = Field(..., description="Column to search (e.g., 'datetime', 'user_id', 'target_type')")
+    operator: int = Field(..., description="Search operator (0=EQUAL, 1=NOT_EQUAL, 2=CONTAINS, 3=BETWEEN, 5=GREATER, 6=LESS)")
+    values: List[str] = Field(..., description="Values to search for")
+
+
+# ============================================================================
+# Audit Search Schemas
+# ============================================================================
+
+class AuditSearchInput(BaseModel):
+    """Input schema for audit-search tool"""
+    conditions: Optional[List[AuditConditionInput]] = Field(None, description="Search conditions for audit trail")
+    limit: Optional[int] = Field(default=100, description="Maximum number of results")
+    offset: Optional[int] = Field(default=0, description="Offset for pagination")
+
+
+class AuditSearchUserInput(BaseModel):
+    """Input schema for audit-search-user tool"""
+    search: Optional[str] = Field(None, description="Search string for user name")
+    limit: Optional[int] = Field(default=201, description="Maximum number of results")
+    offset: Optional[int] = Field(default=0, description="Offset for pagination")
+
+
+class AuditSearchOperatorLevelInput(BaseModel):
+    """Input schema for audit-search-operator-level tool"""
+    search: Optional[str] = Field(None, description="Search string for permission level")
+    limit: Optional[int] = Field(default=201, description="Maximum number of results")
+    offset: Optional[int] = Field(default=0, description="Offset for pagination")
+
+
+class AuditSearchIPListInput(BaseModel):
+    """Input schema for audit-search-ip-list tool"""
+    search: Optional[str] = Field(None, description="Search string for IP address")
+    limit: Optional[int] = Field(default=201, description="Maximum number of results")
+    offset: Optional[int] = Field(default=0, description="Offset for pagination")
+
+
+class AuditSearchTargetListInput(BaseModel):
+    """Input schema for audit-search-target-list tool"""
+    search: Optional[str] = Field(None, description="Search string for target")
+    limit: Optional[int] = Field(default=201, description="Maximum number of results")
+    offset: Optional[int] = Field(default=0, description="Offset for pagination")
+
+
+class AuditCSVExportInput(BaseModel):
+    """Input schema for audit-csv-export tool"""
+    conditions: Optional[List[AuditConditionInput]] = Field(None, description="Filter conditions (use 'DATE' for time).")
+    columns: Optional[List[str]] = Field(
+        default=["DATE","USRID","PERM","IP","MENU","TARGET","METHOD","CONTENT"],
+        description="CSV columns (UPPERCASE per API spec)."
+    )
+    headers: Optional[List[str]] = Field(
+        default=["Datetime","User","Operator Level","IP","Category","Target","Action","Modification"],
+        description="CSV header names (same length as columns)."
+    )
+    offset: Optional[int] = Field(default=0, description="Offset for export pagination.")
+    time_offset_minutes: Optional[int] = Field(default=0, description="Timezone offset in minutes (e.g., UTC+8 => 480).")
+    start_datetime: Optional[str] = Field(None, description="Convenience: start time (ISO). Builds a DATE condition if 'conditions' omitted.")
+    end_datetime: Optional[str] = Field(None, description="Convenience: end time (ISO). Builds a DATE condition if 'conditions' omitted.")
+    copy_to_downloads: Optional[bool] = Field(default=True, description="Copy exported CSV to Windows Downloads folder.")
+    dest_dir: Optional[str] = Field(None, description="Optional absolute destination directory (overrides Downloads).")
+    target_username: Optional[str] = Field(None, description="If provided, copies to C:\\Users\\<name>\\Downloads.")
+

biostar_x_mcp_server/schemas/auth.py

@@ -0,0 +1,24 @@
+from typing import Optional
+from pydantic import BaseModel, Field
+
+
+class LoginInput(BaseModel):
+    """Input schema for login tool"""
+    username: Optional[str] = Field(None, description="Optional: BioStar 2 username (defaults to BIOSTAR_USERNAME from .env)")
+    password: Optional[str] = Field(None, description="Optional: BioStar 2 password (defaults to BIOSTAR_PASSWORD from .env)")
+
+
+class LogoutInput(BaseModel):
+    """Input schema for logout tool"""
+    pass  # No required fields
+
+
+class GetSessionInfoInput(BaseModel):
+    """Input schema for get-session-info tool"""
+    pass  # No required fields
+
+
+class GetServerPreferencesInput(BaseModel):
+    """Input schema for get-server-preferences tool"""
+    pass  # No required fields
+

biostar_x_mcp_server/schemas/cards.py

@@ -0,0 +1,128 @@
+from typing import Optional, Union
+from pydantic import BaseModel, Field, model_validator
+
+
+# ============================================================================
+# Card Creation Schemas
+# ============================================================================
+
+class CreateCardCSNInput(BaseModel):
+    """Input schema for create-card-csn tool"""
+    card_id: Union[str, int] = Field(..., description="Value shown/read when scanning the card")
+    card_type_type: Optional[int] = Field(None, description="Type allocation of the card type; auto-resolved if omitted")
+    assign_to_user_id: Optional[Union[str, int]] = Field(None, description="If provided, assign the created card to this user immediately")
+    skip_availability_check: Optional[bool] = Field(default=False, description="Skip server-side availability check before create (default: false)")
+    dry_run: Optional[bool] = Field(default=False, description="Return the request body without calling the API (default: false)")
+
+
+class CreateCardWiegandInput(BaseModel):
+    """Input schema for create-card-wiegand tool"""
+    card_id: Union[str, int] = Field(..., description="Numeric required")
+    facility_code: int = Field(..., description="Facility Code (required)")
+    card_number: int = Field(..., description="Card Number (required)")
+    wiegand_format_id: Optional[int] = Field(None, description="Format id (e.g., 0=26bit/H10301, 1=HID37/H10302)")
+    wiegand_format: Optional[str] = Field(None, description="Format alias (e.g., '26bit', 'H10301', 'HID37')")
+    display_card_id: Optional[str] = Field(None, description="Override display (must be 'FC-ID', e.g., '12-3456')")
+    card_type_type: Optional[int] = None
+    assign_to_user_id: Optional[Union[str, int]] = None
+    skip_availability_check: Optional[bool] = None
+    dry_run: Optional[bool] = None
+
+    @model_validator(mode="after")
+    def validate_wiegand_format(self):
+        """Ensure either wiegand_format_id or wiegand_format is provided"""
+        if self.wiegand_format_id is None and self.wiegand_format is None:
+            raise ValueError("Either wiegand_format_id or wiegand_format must be provided")
+        return self
+
+
+class CreateCardSecureCredentialInput(BaseModel):
+    """Input schema for create-card-secure-credential tool"""
+    card_id: Union[str, int] = Field(..., description="Card ID")
+    card_type_type: Optional[int] = None
+    assign_to_user_id: Optional[Union[str, int]] = None
+    skip_availability_check: Optional[bool] = None
+    dry_run: Optional[bool] = None
+
+
+class CreateCardAccessOnCardInput(BaseModel):
+    """Input schema for create-card-access-on-card tool"""
+    card_id: Union[str, int] = Field(..., description="Card ID")
+    card_type_type: Optional[int] = None
+    assign_to_user_id: Optional[Union[str, int]] = None
+    skip_availability_check: Optional[bool] = None
+    dry_run: Optional[bool] = None
+
+
+class CreateCardMobileCSNInput(BaseModel):
+    """Input schema for create-card-mobile-csn tool"""
+    card_id: Union[str, int] = Field(..., description="Card ID")
+    card_type_type: Optional[int] = None
+    assign_to_user_id: Optional[Union[str, int]] = None
+    isUserPhoto: Optional[bool] = None
+    isDepartment: Optional[bool] = None
+    isTitle: Optional[bool] = None
+    start_datetime: Optional[str] = None
+    expiry_datetime: Optional[str] = None
+    display_card_id: Optional[str] = None
+    skip_availability_check: Optional[bool] = None
+    dry_run: Optional[bool] = None
+
+
+class CreateCardWiegandMobileInput(BaseModel):
+    """Input schema for create-card-wiegand-mobile tool"""
+    card_id: Union[str, int] = Field(..., description="Card ID")
+    facility_code: int = Field(..., description="Facility Code (required)")
+    card_number: int = Field(..., description="Card Number (required)")
+    wiegand_format_id: Optional[int] = Field(None, description="Format id")
+    wiegand_format: Optional[str] = Field(None, description="Format alias")
+    display_card_id: Optional[str] = None
+    card_type_type: Optional[int] = None
+    assign_to_user_id: Optional[Union[str, int]] = None
+    skip_availability_check: Optional[bool] = None
+    dry_run: Optional[bool] = None
+
+    @model_validator(mode="after")
+    def validate_wiegand_format(self):
+        """Ensure either wiegand_format_id or wiegand_format is provided"""
+        if self.wiegand_format_id is None and self.wiegand_format is None:
+            raise ValueError("Either wiegand_format_id or wiegand_format must be provided")
+        return self
+
+
+class CreateCardQRBarcodeInput(BaseModel):
+    """Input schema for create-card-qr-barcode tool"""
+    card_id: Union[str, int] = Field(..., description="Card ID")
+    card_type_type: Optional[int] = None
+    assign_to_user_id: Optional[Union[str, int]] = None
+    skip_availability_check: Optional[bool] = None
+    dry_run: Optional[bool] = None
+
+
+class CreateCardBioStar2QRInput(BaseModel):
+    """Input schema for create-card-biostar2-qr tool"""
+    card_id: Union[str, int] = Field(..., description="Card ID")
+    card_type_type: Optional[int] = None
+    assign_to_user_id: Optional[Union[str, int]] = None
+    skip_availability_check: Optional[bool] = None
+    dry_run: Optional[bool] = None
+
+
+# ============================================================================
+# Supporting Tool Schemas
+# ============================================================================
+
+class GetCardTypesInput(BaseModel):
+    """Input schema for get-card-types tool"""
+    pass  # No required fields
+
+
+class CheckCardAvailabilityInput(BaseModel):
+    """Input schema for check-card-availability tool"""
+    card_id: Union[str, int] = Field(..., description="Card ID to check")
+
+
+class GetWiegandFormatPresetsInput(BaseModel):
+    """Input schema for get-wiegand-format-presets tool"""
+    pass  # No required fields
+