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

biostar_x_mcp_server/tools/audit.py

@@ -0,0 +1,227 @@
+from mcp.types import Tool
+
+# Audit search tool
+AUDIT_SEARCH_TOOL = Tool(
+    name="audit-search",
+    description="Search audit trail logs in the BioStar 2 system",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "conditions": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "column": {
+                            "type": "string",
+                            "description": "Column to search (e.g., 'datetime', 'user_id', 'target_type')"
+                        },
+                        "operator": {
+                            "type": "integer",
+                            "description": "Search operator (0=EQUAL, 1=NOT_EQUAL, 2=CONTAINS, 3=BETWEEN, 5=GREATER, 6=LESS)"
+                        },
+                        "values": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "description": "Values to search for"
+                        }
+                    },
+                    "required": ["column", "operator", "values"]
+                },
+                "description": "Search conditions for audit trail"
+            },
+            "limit": {
+                "type": "integer",
+                "description": "Maximum number of results",
+                "default": 100
+            },
+            "offset": {
+                "type": "integer",
+                "description": "Offset for pagination",
+                "default": 0
+            }
+        },
+        "required": []
+    }
+)
+
+# Audit search user tool
+AUDIT_SEARCH_USER_TOOL = Tool(
+    name="audit-search-user",
+    description="Search for users by name",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "search": {
+                "type": "string",
+                "description": "Search string for user name"
+            },
+            "limit": {
+                "type": "integer",
+                "description": "Maximum number of results",
+                "default": 201
+            },
+            "offset": {
+                "type": "integer",
+                "description": "Offset for pagination",
+                "default": 0
+            }
+        },
+        "required": []
+    }
+)
+
+# Audit search operator level tool
+AUDIT_SEARCH_OPERATOR_LEVEL_TOOL = Tool(
+    name="audit-search-operator-level",
+    description="Search for operator permission levels",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "search": {
+                "type": "string",
+                "description": "Search string for permission level"
+            },
+            "limit": {
+                "type": "integer",
+                "description": "Maximum number of results",
+                "default": 201
+            },
+            "offset": {
+                "type": "integer",
+                "description": "Offset for pagination",
+                "default": 0
+            }
+        },
+        "required": []
+    }
+)
+
+# Audit search IP list tool
+AUDIT_SEARCH_IP_LIST_TOOL = Tool(
+    name="audit-search-ip-list",
+    description="Search for IP addresses",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "search": {
+                "type": "string",
+                "description": "Search string for IP address"
+            },
+            "limit": {
+                "type": "integer",
+                "description": "Maximum number of results",
+                "default": 201
+            },
+            "offset": {
+                "type": "integer",
+                "description": "Offset for pagination",
+                "default": 0
+            }
+        },
+        "required": []
+    }
+)
+
+# Audit search target list tool
+AUDIT_SEARCH_TARGET_LIST_TOOL = Tool(
+    name="audit-search-target-list",
+    description="Search for audit targets",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "search": {
+                "type": "string",
+                "description": "Search string for target"
+            },
+            "limit": {
+                "type": "integer",
+                "description": "Maximum number of results",
+                "default": 201
+            },
+            "offset": {
+                "type": "integer",
+                "description": "Offset for pagination",
+                "default": 0
+            }
+        },
+        "required": []
+    }
+)
+
+AUDIT_CSV_EXPORT_TOOL = Tool(
+    name="audit-csv-export",
+    description="Export audit trail data to CSV via /api/audit/export and copy the file to the Windows Downloads folder.",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "conditions": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "column": {"type": "string"},
+                        "operator": {"type": "integer"},
+                        "values": {"type": "array", "items": {"type": "string"}}
+                    },
+                    "required": ["column", "operator", "values"]
+                },
+                "description": "Filter conditions (use 'DATE' for time)."
+            },
+            "columns": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "CSV columns (UPPERCASE per API spec).",
+                "default": ["DATE","USRID","PERM","IP","MENU","TARGET","METHOD","CONTENT"]
+            },
+            "headers": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "CSV header names (same length as columns).",
+                "default": ["Datetime","User","Operator Level","IP","Category","Target","Action","Modification"]
+            },
+            "offset": {
+                "type": "integer",
+                "description": "Offset for export pagination.",
+                "default": 0
+            },
+            "time_offset_minutes": {
+                "type": "integer",
+                "description": "Timezone offset in minutes (e.g., UTC+8 => 480).",
+                "default": 0
+            },
+            "start_datetime": {
+                "type": "string",
+                "description": "Convenience: start time (ISO). Builds a DATE condition if 'conditions' omitted."
+            },
+            "end_datetime": {
+                "type": "string",
+                "description": "Convenience: end time (ISO). Builds a DATE condition if 'conditions' omitted."
+            },
+            "copy_to_downloads": {
+                "type": "boolean",
+                "description": "Copy exported CSV to Windows Downloads folder.",
+                "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."
+            }
+        },
+        "required": []
+    }
+)
+
+# Export all audit tools
+AUDIT_TOOLS = [
+    AUDIT_SEARCH_TOOL,
+    AUDIT_SEARCH_USER_TOOL,
+    AUDIT_SEARCH_OPERATOR_LEVEL_TOOL,
+    AUDIT_SEARCH_IP_LIST_TOOL,
+    AUDIT_SEARCH_TARGET_LIST_TOOL,
+    AUDIT_CSV_EXPORT_TOOL
+]

biostar_x_mcp_server/tools/auth.py

@@ -0,0 +1,59 @@
+from mcp.types import Tool
+
+# Authentication tools
+LOGIN_TOOL = Tool(
+    name="login",
+    description="[ACTION TOOL - DEVELOPER USE ONLY] Perform actual login to BioStar X system via API. Use this ONLY when user explicitly asks to 'login now', 'authenticate now', 'connect now', or wants to perform actual system login operation. This is for programmatic API access, NOT for explaining how users login. For user login explanations, use vector-search-manual instead. By default uses credentials from .env file (developer configuration), but you can optionally provide different credentials.",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "username": {
+                "type": "string",
+                "description": "Optional: BioStar 2 username (defaults to BIOSTAR_USERNAME from .env)"
+            },
+            "password": {
+                "type": "string",
+                "description": "Optional: BioStar 2 password (defaults to BIOSTAR_PASSWORD from .env)"
+            }
+        },
+        "required": []
+    }
+)
+
+LOGOUT_TOOL = Tool(
+    name="logout",
+    description="[ACTION TOOL - DEVELOPER USE ONLY] Perform actual logout from BioStar X system via API. Use this ONLY when user explicitly asks to 'logout now' or wants to perform actual system logout operation. This is for programmatic API access, NOT for explaining how users logout. For user logout explanations, use vector-search-manual instead.",
+    inputSchema={
+        "type": "object",
+        "properties": {},
+        "required": []
+    }
+)
+
+GET_SESSION_INFO_TOOL = Tool(
+    name="get-session-info",
+    description="[ACTION TOOL - DEVELOPER USE ONLY] Get current API session information including user details. Use this ONLY when user explicitly asks to 'check session', 'get session info', or wants to query actual session status. This is for programmatic API access, NOT for explaining session management to users. For user session explanations, use vector-search-manual instead.",
+    inputSchema={
+        "type": "object",
+        "properties": {},
+        "required": []
+    }
+)
+
+GET_SERVER_PREFERENCES_TOOL = Tool(
+    name="get-server-preferences",
+    description="Get BioStar server preferences including timezone, language, date/time format. This is essential for displaying event times in the correct timezone.",
+    inputSchema={
+        "type": "object",
+        "properties": {},
+        "required": []
+    }
+)
+
+# List of all auth tools
+AUTH_TOOLS = [
+    LOGIN_TOOL,
+    LOGOUT_TOOL,
+    GET_SESSION_INFO_TOOL,
+    GET_SERVER_PREFERENCES_TOOL
+]

biostar_x_mcp_server/tools/cards.py

@@ -0,0 +1,269 @@
+from mcp.types import Tool
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Card creation tools (one tool per card type)
+# Names follow: create-card-{type}
+# ──────────────────────────────────────────────────────────────────────────────
+
+CREATE_CARD_CSN_TOOL = Tool(
+    name="create-card-csn",
+    description=(
+        "Create a **CSN** card via POST /api/cards.\n"
+        "Required: card_id.\n"
+        "Rules: ASCII digits only (0-9), no leading '0', length 1-32.\n"
+        "If 'card_type_type' is omitted, it will be auto-resolved from /api/cards/types (with fallback).\n"
+        "Optional: assign_to_user_id to immediately assign the created card to a user.\n"
+        "Use this tool to perform the action. Do NOT attempt to do this without the tool."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "card_id": {
+                "oneOf": [{"type": "string"}, {"type": "integer"}],
+                "description": "Value shown/read when scanning the card"
+            },
+            "card_type_type": {
+                "type": "integer",
+                "description": "Type allocation of the card type; auto-resolved if omitted"
+            },
+            "assign_to_user_id": {
+                "oneOf": [{"type": "string"}, {"type": "integer"}],
+                "description": "If provided, assign the created card to this user immediately"
+            },
+            "skip_availability_check": {
+                "type": "boolean",
+                "description": "Skip server-side availability check before create (default: false)"
+            },
+            "dry_run": {
+                "type": "boolean",
+                "description": "Return the request body without calling the API (default: false)"
+            }
+        },
+        "required": ["card_id"]
+    }
+)
+
+CREATE_CARD_WIEGAND_TOOL = Tool(
+    name="create-card-wiegand",
+    description=(
+        "Create a **Wiegand** card via POST /api/cards.\n"
+        "Required: card_id (numeric), faciliy_code, card_number, and either wiegand_format_id or wiegand_format(alias).\n"
+        "The handler strictly validates ranges per format and will fail with: "
+        "'Format entered incorrectly. Support value is x~y.' When out of range.\n"
+        "display_card_id (if provided) must be numeric 'FC-ID' (e.g., '12-3456') and must match facility/card values.\n"
+        "If the user doesn't know the format id, call 'get-wiegand-format-presets' first and ask them to pick one."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "card_id": {"oneOf": [{"type": "string"}, {"type": "integer"}], "description": "Numeric required"},
+            "wiegand_format_id": {"type": "integer", "description": "Format id (e.g., 0=26bit/H10301, 1=HID37/H10302)"},
+            "wiegand_format": {"type": "string", "description": "Format alias (e.g., '26bit', 'H10301', 'HID37')"},
+            "facility_code": {"type": "integer", "description": "Facility Code (required)"},
+            "card_number": {"type": "integer", "description": "Card Number (required)"},
+            "display_card_id": {"type": "string", "description": "Override display (must be 'FC-ID', e.g., '12-3456')"},
+            "card_type_type": {"type": "integer"},
+            "assign_to_user_id": {"oneOf": [{"type": "string"}, {"type": "integer"}]},
+            "skip_availability_check": {"type": "boolean"},
+            "dry_run": {"type": "boolean"},
+        },
+        "allOf": [
+            {
+                "anyOf": [
+                    {"required": ["card_id", "wiegand_format_id"]},
+                    {"required": ["card_id", "wiegand_format"]},
+                ]
+            },
+            {"required": ["facility_code", "card_number"]}
+        ],
+    }
+)
+
+CREATE_CARD_SECURE_CREDENTIAL_TOOL = Tool(
+    name="create-card-secure-credential",
+    description=(
+        "Create a **Secure Credential (Smart card)** via POST /api/cards.\n"
+        "Required: card_id. If 'card_type_type' is omitted, it will be auto-resolved."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "card_id": {"oneOf": [{"type": "string"}, {"type": "integer"}]},
+            "card_type_type": {"type": "integer"},
+            "assign_to_user_id": {"oneOf": [{"type": "string"}, {"type": "integer"}]},
+            "skip_availability_check": {"type": "boolean"},
+            "dry_run": {"type": "boolean"}
+        },
+        "required": ["card_id"]
+    }
+)
+
+CREATE_CARD_ACCESS_ON_CARD_TOOL = Tool(
+    name="create-card-access-on-card",
+    description=(
+        "Create an **Access on Card (Smart card)** via POST /api/cards.\n"
+        "Required: card_id. If 'card_type_type' is omitted, it will be auto-resolved."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "card_id": {"oneOf": [{"type": "string"}, {"type": "integer"}]},
+            "card_type_type": {"type": "integer"},
+            "assign_to_user_id": {"oneOf": [{"type": "string"}, {"type": "integer"}]},
+            "skip_availability_check": {"type": "boolean"},
+            "dry_run": {"type": "boolean"}
+        },
+        "required": ["card_id"]
+    }
+)
+
+CREATE_CARD_MOBILE_CSN_TOOL = Tool(
+    name="create-card-mobile-csn",
+    description=(
+        "Create a **Mobile CSN** card via POST /api/cards.\n"
+        "Required: card_id. Optional: isUserPhoto, isDepartment, isTitle, "
+        "start_datetime, expiry_datetime, display_card_id."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "card_id": {"oneOf": [{"type": "string"}, {"type": "integer"}]},
+            "card_type_type": {"type": "integer"},
+            "assign_to_user_id": {"oneOf": [{"type": "string"}, {"type": "integer"}]},
+            "isUserPhoto": {"type": "boolean"},
+            "isDepartment": {"type": "boolean"},
+            "isTitle": {"type": "boolean"},
+            "start_datetime": {"type": "string"},
+            "expiry_datetime": {"type": "string"},
+            "display_card_id": {"type": "string"},
+            "skip_availability_check": {"type": "boolean"},
+            "dry_run": {"type": "boolean"}
+        },
+        "required": ["card_id"]
+    }
+)
+
+CREATE_CARD_WIEGAND_MOBILE_TOOL = Tool(
+    name="create-card-wiegand-mobile",
+    description=(
+        "Create a **Wiegand Mobile** card via POST /api/cards.\n"
+        "Required: card_id (numeric), facility_code, card_number, and either wiegand_format_id or wiegand_format(alias).\n"
+        "Handler strictly validates ranges per format and rejects invalid values with the supported ranges."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "card_id": {"oneOf": [{"type": "string"}, {"type": "integer"}]},
+            "wiegand_format_id": {"type": "integer"},
+            "wiegand_format": {"type": "string"},
+            "facility_code": {"type": "integer"},
+            "card_number": {"type": "integer"},
+            "display_card_id": {"type": "string"},
+            "card_type_type": {"type": "integer"},
+            "assign_to_user_id": {"oneOf": [{"type": "string"}, {"type": "integer"}]},
+            "skip_availability_check": {"type": "boolean"},
+            "dry_run": {"type": "boolean"}
+        },
+        "allOf": [
+            {
+                "anyOf": [
+                    {"required": ["card_id", "wiegand_format_id"]},
+                    {"required": ["card_id", "wiegand_format"]},
+                ]
+            },
+            {"required": ["facility_code", "card_number"]}
+        ],
+    }
+)
+
+CREATE_CARD_QR_BARCODE_TOOL = Tool(
+    name="create-card-qr-barcode",
+    description=(
+        "Create a **QR/Barcode** card via POST /api/cards.\n"
+        "Required: card_id. If 'card_type_type' is omitted, it will be auto-resolved."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "card_id": {"oneOf": [{"type": "string"}, {"type": "integer"}]},
+            "card_type_type": {"type": "integer"},
+            "assign_to_user_id": {"oneOf": [{"type": "string"}, {"type": "integer"}]},
+            "skip_availability_check": {"type": "boolean"},
+            "dry_run": {"type": "boolean"}
+        },
+        "required": ["card_id"]
+    }
+)
+
+CREATE_CARD_BIOSTAR2_QR_TOOL = Tool(
+    name="create-card-biostar2-qr",
+    description=(
+        "Create a **BioStar 2 QR** card via POST /api/cards.\n"
+        "Required: card_id. If 'card_type_type' is omitted, it will be auto-resolved."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "card_id": {"oneOf": [{"type": "string"}, {"type": "integer"}]},
+            "card_type_type": {"type": "integer"},
+            "assign_to_user_id": {"oneOf": [{"type": "string"}, {"type": "integer"}]},
+            "skip_availability_check": {"type": "boolean"},
+            "dry_run": {"type": "boolean"}
+        },
+        "required": ["card_id"]
+    }
+)
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Supporting tools (UX helpers)
+# ──────────────────────────────────────────────────────────────────────────────
+
+GET_CARD_TYPES_TOOL = Tool(
+    name="get-card-types",
+    description=(
+        "Fetch valid card types and their 'type' allocations from GET /api/cards/types.\n"
+        "Use this to determine valid values for 'card_type.type' when creating cards."
+    ),
+    inputSchema={"type": "object", "properties": {}, "required": []}
+)
+
+CHECK_CARD_AVAILABILITY_TOOL = Tool(
+    name="check-card-availability",
+    description=(
+        "Check if a given card_id is available (not existing) before creation.\n"
+        "If the endpoint is unavailable in your BioStar version, the handler will return a best-effort result."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "card_id": {"oneOf": [{"type": "string"}, {"type": "integer"}]}
+        },
+        "required": ["card_id"]
+    }
+)
+
+GET_WIEGAND_FORMAT_PRESETS_TOOL = Tool(
+    name="get-wiegand-format-presets",
+    description=(
+        "Return common Wiegand formats with IDs, aliases, and supported ranges (facility_code/card_number).\n"
+        "Use this to prompt the user to pick a format before creating a Wiegand/Wiegand Mobile card."
+    ),
+    inputSchema={"type": "object", "properties": {}, "required": []}
+)
+
+# Group for easy import
+CARD_TOOLS = [
+    CREATE_CARD_CSN_TOOL,
+    CREATE_CARD_WIEGAND_TOOL,
+
+    # CREATE_CARD_SECURE_CREDENTIAL_TOOL,
+    # CREATE_CARD_ACCESS_ON_CARD_TOOL,
+    # CREATE_CARD_MOBILE_CSN_TOOL,
+    # CREATE_CARD_WIEGAND_MOBILE_TOOL,
+    # CREATE_CARD_QR_BARCODE_TOOL,
+    # CREATE_CARD_BIOSTAR2_QR_TOOL,
+
+    GET_CARD_TYPES_TOOL,
+    CHECK_CARD_AVAILABILITY_TOOL,
+    GET_WIEGAND_FORMAT_PRESETS_TOOL,
+]