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

biostar_x_mcp_server/tools/users.py

@@ -0,0 +1,1113 @@
+from mcp.types import Tool
+
+# User management tools
+GET_USERS_TOOL = Tool(
+    name="get-users",
+    description="[ACTION TOOL] Retrieve a list of all users from BioStar X system. Use this when user asks to 'list users', 'show users', 'get all users', 'display users', or needs user information. This performs actual system operations - do NOT use vector search for this.",
+    inputSchema={
+        "type": "object",
+        "properties": {},
+        "required": []
+    }
+)
+
+CREATE_USER_TOOL = Tool(
+    name="create-user",
+    description="[ACTION TOOL] Create a new user in BioStar X system. Use this when user explicitly asks to 'create user', 'add user', 'register user', 'new user', or 'make user'. This performs actual system operations - do NOT use vector search for this.",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "name": {
+                "type": "string",
+                "description": "User's full name (max 48 characters)"
+            },
+            "email": {
+                "type": "string",
+                "description": "User's email address"
+            },
+            "department": {
+                "type": "string",
+                "description": "Department name (max 64 characters)"
+            },
+            "user_title": {
+                "type": "string",
+                "description": "Job title"
+            },
+            "phone": {
+                "type": "string",
+                "description": "Phone number"
+            },
+            "disabled": {
+                "type": "boolean",
+                "description": "Whether the user is disabled (default: false)"
+            },
+            "access_groups": {
+                "type": "array",
+                "items": {"type": "integer"},
+                "description": "List of access group IDs"
+            },
+            "pin": {
+                "type": "integer",
+                "description": "PIN number (up to 32 digits)"
+            }
+        },
+        "required": ["name"]
+    }
+)
+
+GET_USER_TOOL = Tool(
+    name="get-user",
+    description="Get detailed information about a specific user",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "user_id": {
+                "oneOf": [{"type": "string"}, {"type": "integer"}],
+                "description": "The ID of the user to retrieve"
+            }
+        },
+        "required": ["user_id"]
+    }
+)
+
+UPDATE_USER_TOOL = Tool(
+    name="update-user",
+    description="Update an existing user's information. Supports flexible date formats (20251225, 12.25.2025, 2025-12-25) and access group names.",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "user_id": {
+                "oneOf": [{"type": "string"}, {"type": "integer"}],
+                "description": "ID of the user to update"
+            },
+            "name": {
+                "type": "string",
+                "description": "Current name of the user (used to find if user_id not provided)"
+            },
+            "new_name": {
+                "type": "string",
+                "description": "New name for the user"
+            },
+            "email": {
+                "type": "string",
+                "description": "Email address"
+            },
+            "department": {
+                "type": "string",
+                "description": "Department name"
+            },
+            "user_title": {
+                "type": "string",
+                "description": "Job title"
+            },
+            "phone": {
+                "type": "string",
+                "description": "Phone number"
+            },
+            "disabled": {
+                "type": "boolean",
+                "description": "Enable or disable the user"
+            },
+            "user_group_id": {
+                "type": "integer",
+                "description": "ID of the user group to assign"
+            },
+            "access_groups": {
+                "type": "array",
+                "items": {"type": "integer"},
+                "description": "List of access group IDs"
+            },
+            "access_group_names": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "List of access group names (alternative to access_groups). Example: ['12 Floor ALL', 'VIP Access']"
+            },
+            "start_datetime": {
+                "type": "string",
+                "description": "Start date for user validity. Supports flexible formats: ISO (2025-12-25T00:00:00.00Z), compact (20251225), or other formats (12.25.2025, 2025/12/25)"
+            },
+            "start_date": {
+                "type": "string",
+                "description": "Alias for start_datetime. Supports flexible date formats."
+            },
+            "expiry_datetime": {
+                "type": "string",
+                "description": "Expiry date for user validity. Supports flexible formats: ISO (2025-12-25T23:59:00.00Z), compact (20251225), or other formats (12.25.2025, 2025/12/25)"
+            },
+            "end_date": {
+                "type": "string",
+                "description": "Alias for expiry_datetime. Supports flexible date formats."
+            },
+            "pin": {
+                "type": "integer",
+                "description": "PIN number"
+            }
+        },
+        "required": []
+    }
+)
+
+DELETE_USER_TOOL = Tool(
+    name="delete-user",
+    description=" CRITICAL: Delete one or more users from the BioStar 2 system. THIS IS PERMANENT and CANNOT BE UNDONE! ALWAYS confirm with user before executing. For demo data, REQUIRE explicit 'delete confirm' or '삭제 확인' from user.",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "id": {
+                "oneOf": [
+                    {"type": "string"},
+                    {"type": "integer"},
+                    {
+                        "type": "array",
+                        "items": {
+                            "oneOf": [
+                                {"type": "string"},
+                                {"type": "integer"}
+                            ]
+                        }
+                    }
+                ],
+                "description": "User ID(s) to delete - can be string, integer, or array of either"
+            },
+            "name": {
+                "type": "string",
+                "description": "Name of the user to delete (supports partial match)"
+            }
+        },
+        "required": []
+    }
+)
+
+SEARCH_USERS_TOOL = Tool(
+    name="search-users",
+    description="Simple search for users using search_text. This searches across all user fields (name, email, department, etc.) for the given text.",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "search_text": {
+                "type": "string",
+                "description": "Search record(s) with the text specified on this parameter. Searches across all user fields."
+            },
+            "limit": {
+                "type": "integer",
+                "description": "Limit response record(s) by the value specified on this parameter (required)"
+            },
+            "user_group_id": {
+                "oneOf": [{"type": "string"}, {"type": "integer"}],
+                "description": "Filter response record(s) according to user_group_id specified on this parameter"
+            },
+            "order_by": {
+                "type": "string",
+                "description": "Order the response record(s) by the User parameter such as user_id or name. False for ascending, True for descending."
+            }
+        },
+        "required": ["search_text", "limit"]
+    }
+)
+
+GET_USER_CARDS_TOOL = Tool(
+    name="get-user-cards",
+    description="Get all access cards assigned to a user",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "user_id": {
+                "oneOf": [{"type": "string"}, {"type": "integer"}],
+                "description": "The ID of the user"
+            }
+        },
+        "required": ["user_id"]
+    }
+)
+
+ADD_USER_CARD_TOOL = Tool(
+    name="add-user-card",
+    description="Add an access card to a user",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "user_id": {
+                "oneOf": [{"type": "string"}, {"type": "integer"}],
+                "description": "The ID of the user"
+            },
+            "card_number": {
+                "type": "string",
+                "description": "The card number to add"
+            },
+            "card_type": {
+                "type": "string",
+                "description": "Type of card (e.g., 'CSN', 'WIEGAND')"
+            }
+        },
+        "required": ["user_id", "card_number"]
+    }
+)
+
+DELETE_USER_CARD_TOOL = Tool(
+    name="delete-user-card",
+    description="Remove an access card from a user",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "user_id": {
+                "oneOf": [{"type": "string"}, {"type": "integer"}],
+                "description": "The ID of the user"
+            },
+            "card_id": {
+                "type": "string",
+                "description": "The ID of the card to remove"
+            }
+        },
+        "required": ["user_id", "card_id"]
+    }
+)
+
+BULK_ADD_USERS_TOOL = Tool(
+    name="bulk-add-users",
+    description=(
+        "Create multiple users at once with optional user-group assignment (single or multiple groups, round-robin or explicit counts). "
+        "If user_group_name (or user_group_names/group_allocations.group_name) matches multiple groups, "
+        "the tool MUST return an error with needs_selection=true, a candidates list, and a selection_token. "
+        "The caller must ask the user to choose and then re-call the tool with user_group_id and selection_token. "
+        "Do not auto-pick a group."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "base_name": {
+                "type": "string",
+                "description": "Base prefix for user names (e.g., 'user' creates user001, user002, ...)"
+            },
+            "count": {
+                "type": "integer",
+                "description": "Number of users to create (max 30)"
+            },
+            # --- NEW: single-group assignment ---
+            "user_group_id": {
+                "oneOf": [{"type": "string"}, {"type": "integer"}],
+                "description": "Assign ALL created users to this user group id."
+            },
+            "user_group_name": {
+                "type": "string",
+                "description": "Assign ALL created users to the group resolved by this name (substring match, 0/1/many flow)."
+            },
+            # --- NEW: multi-group distribution by names ---
+            "user_group_names": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "List of group names to distribute across. If 'distribution' is 'round_robin', users are assigned cyclically."
+            },
+            "group_counts": {
+                "type": "array",
+                "items": {"type": "integer"},
+                "description": "Used with 'user_group_names' when distribution='by_counts'. Must match names length and sum to 'count'."
+            },
+            "distribution": {
+                "type": "string",
+                "enum": ["round_robin", "by_counts"],
+                "description": "How to distribute when multiple groups are provided. Default: 'round_robin'.",
+                "default": "round_robin"
+            },
+            # --- NEW: explicit allocations list ---
+            "group_allocations": {
+                "type": "array",
+                "description": "Explicit allocations, e.g., [{'group_name':'product_line','count':10}, {'group_id':1260,'count':5}]. Counts must sum to 'count'.",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "group_id": {"oneOf": [{"type": "string"}, {"type": "integer"}]},
+                        "group_name": {"type": "string"},
+                        "count": {"type": "integer"}
+                    },
+                    "anyOf": [
+                        {"required": ["group_id", "count"]},
+                        {"required": ["group_name", "count"]}
+                    ]
+                }
+            }
+        },
+        "required": ["base_name", "count"]
+    }
+)
+
+EXPORT_USERS_CSV_TOOL = Tool(
+    name="export-users-csv",
+    description=(
+        "Export user data to CSV and optionally copy the file to the Windows Downloads folder. "
+        "Supports exporting ALL users matching advanced search criteria (no limit). "
+        "Use adv_criteria for filtering by group, department, email, etc. without loading all data into memory."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "ids": {
+                "type": "array",
+                "items": {"oneOf": [{"type": "string"}, {"type": "integer"}]},
+                "description": "List of user IDs to export, or ['*'] for all users. If provided, other filters are ignored."
+            },
+            "search_text": {
+                "type": "string",
+                "description": "Simple search text (searches all fields). For large result sets, use adv_criteria instead."
+            },
+            "limit": {
+                "type": "integer",
+                "description": "DEPRECATED: Max users when using search_text (default 50). Use adv_criteria for unlimited results.",
+                "default": 50
+            },
+            "adv_criteria": {
+                "type": "object",
+                "description": (
+                    "Advanced search criteria to filter users server-side (no limit). "
+                    "Example: {\"user_group_id\": \"1260\", \"user_name\": \"John\", \"user_email\": \"gmail\"}. "
+                    "Server will export ALL matching users directly to CSV without limit."
+                ),
+                "properties": {
+                    "user_group_id": {"type": "string"},
+                    "user_group_ids": {"type": "array", "items": {"type": "integer"}},
+                    "user_name": {"type": "string"},
+                    "user_email": {"type": "string"},
+                    "user_department": {"type": "string"},
+                    "user_phone": {"type": "string"},
+                    "user_title": {"type": "string"},
+                    "user_status": {"type": "boolean"},
+                    "user_operator_level_id": {"type": "string"}
+                }
+            },
+            "copy_to_downloads": {
+                "type": "boolean",
+                "description": "Copy the exported CSV into a Windows Downloads folder",
+                "default": True
+            },
+            "dest_dir": {
+                "type": "string",
+                "description": "Absolute destination directory for the copy (overrides Downloads)"
+            },
+            "target_username": {
+                "type": "string",
+                "description": "Windows username for Downloads path (C:\\Users\\<name>\\Downloads)"
+            }
+        },
+        "required": []
+    }
+)
+
+
+ADVANCED_SEARCH_USERS_TOOL = Tool(
+    name="advanced-search-users",
+    description="Perform advanced search for users with multiple criteria including name, email, department, title, phone, access groups, custom fields, etc. user_email: ASCII lowercase provider token (no '@', no TLD). If a full email is given, extract the provider. ",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "limit": {
+                "type": "integer",
+                "description": "The maximum number of users to return. Default is 50."
+            },
+            "offset": {
+                "type": "string",
+                "description": "The number of users to skip before starting to return results. Default is 0."
+            },
+            "user_id": {
+                "type": "string",
+                "description": "The User ID to search, supports like search"
+            },
+            "user_group_id": {
+                "type": "string",
+                "description": "Group ID for search user. Also gets the child user group"
+            },
+            "user_group_ids": {
+                "type": "array",
+                "items": {"type": "integer"},
+                "description": "Array of Group IDs for advanced search parameter"
+            },
+            "user_name": {
+                "type": "string",
+                "description": "User name for Advance Search parameter, supports like search both encrypted and unencrypted"
+            },
+            "user_email": {
+                "type": "string",
+                "description": "User email, supports like search both encrypted and unencrypted"
+            },
+            "user_phone": {
+                "type": "string",
+                "description": "User Phone for Advance Search parameter, supports like search both encrypted and unencrypted"
+            },
+            "user_department": {
+                "type": "string",
+                "description": "User Department for Advance Search parameter, supports like search on unencrypted and exact search on encrypted"
+            },
+            "user_access_group_ids": {
+                "type": "string",
+                "description": "User access group id for advance search parameter, supports multiple value with format String with Delimiter , i.e 1,2,3"
+            },
+            "user_title": {
+                "type": "string",
+                "description": "User title for advance search parameter, supports like search on unencrypted and exact search on encrypted"
+            },
+            "user_card": {
+                "type": "string",
+                "description": "User card ID"
+            },
+            "user_status": {
+                "type": "boolean",
+                "description": "User status for advance search parameter Operator level (required by API). Defaults to '0' if omitted."
+            },
+            "user_operator_level_id": {
+                "type": "string",
+                "description": "User operator level id for Advance Search parameter"
+            },
+            "user_custom_field_1": {
+                "type": "string",
+                "description": "Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted"
+            },
+            "user_custom_field_2": {
+                "type": "string",
+                "description": "Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted"
+            },
+            "user_custom_field_3": {
+                "type": "string",
+                "description": "Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted"
+            },
+            "user_custom_field_4": {
+                "type": "string",
+                "description": "Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted"
+            },
+            "user_custom_field_5": {
+                "type": "string",
+                "description": "Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted"
+            },
+            "user_custom_field_6": {
+                "type": "string",
+                "description": "Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted"
+            },
+            "user_custom_field_7": {
+                "type": "string",
+                "description": "Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted"
+            },
+            "user_custom_field_8": {
+                "type": "string",
+                "description": "Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted"
+            },
+            "user_custom_field_9": {
+                "type": "string",
+                "description": "Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted"
+            },
+            "user_custom_field_10": {
+                "type": "string",
+                "description": "Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted"
+            },
+            "order_by": {
+                "type": "string",
+                "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"
+            }
+        },
+        "required": []
+    }
+)
+
+UNASSIGN_USER_CARDS_TOOL = Tool(
+    name="unassign-user-cards",
+    description=(
+        "Detach one, multiple, or all cards from a user by updating the user's cards via "
+        "PUT /api/users/{user_id}. "
+        "Supply BioStar card **row ids** to remove (e.g., ['17','18']). "
+        "If remove_all=true, sends {'User': {'cards': []}}."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "user_id": {
+                "oneOf": [{"type": "string"}, {"type": "integer"}],
+                "description": "Target user id. If omitted, provide 'name' to resolve."
+            },
+            "name": {
+                "type": "string",
+                "description": "User name (used to resolve if user_id is not provided; fails on multiple matches)."
+            },
+            "remove_all": {
+                "type": "boolean",
+                "description": "If true, detach all cards from the user."
+            },
+            "remove_card_row_ids": {
+                "type": "array",
+                "items": {"oneOf": [{"type": "string"}, {"type": "integer"}]},
+                "description": "BioStar **card row id(s)** to detach (e.g., ['17','18'])."
+            },
+            "ignore_missing": {
+                "type": "boolean",
+                "default": False,
+                "description": "If false, fail when any requested row id is not assigned to the user."
+            },
+            "dry_run": {
+                "type": "boolean",
+                "default": False,
+                "description": "If true, return the planned PUT body without calling the API."
+            }
+        },
+        "anyOf": [
+            {"required": ["user_id"]},
+            {"required": ["name"]}
+        ]
+    }
+)
+
+CREATE_USER_GROUP_TOOL = Tool(
+    name="create-user-group",
+    description=(
+        "Create a new user group in BioStar 2. "
+        "Blocks if a group with the same name already exists (case-insensitive). "
+        "If 'depth' is omitted, it will be computed as parent.depth + 1 (max total levels: 8; root=0)."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "name": {
+                "type": "string",
+                "description": "Name of the new user group (max 48 chars)"
+            },
+            "parent_id": {
+                "oneOf": [{"type": "string"}, {"type": "integer"}],
+                "description": "Parent group ID (e.g., 1 for 'All Users')"
+            },
+            "depth": {
+                "type": "integer",
+                "description": "Depth of the new group. If omitted, computed automatically."
+            }
+        },
+        "required": ["name", "parent_id"]
+    }
+)
+
+
+GET_USER_GROUPS_TOOL = Tool(
+    name="get-user-groups",
+    description="Retrieve a list of all user groups from the BioStar 2 system (GET /api/user_groups).",
+    inputSchema={
+        "type": "object",
+        "properties": {},
+        "required": []
+    }
+)
+
+
+ADD_USER_TO_GROUP_TOOL = Tool(
+    name="add-user-to-group",
+    description="Assign a user to a specific user group using PUT /api/users/{user_id}. Validates existence and handles 0/1/many selections for both user and group.",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "user_id": {
+                "oneOf": [{"type": "string"}, {"type": "integer"}],
+                "description": "Target user id (if omitted, 'name' is used to resolve)."
+            },
+            "name": {
+                "type": "string",
+                "description": "Target user name (0/1/many flow)."
+            },
+            "user_group_id": {
+                "oneOf": [{"type": "string"}, {"type": "integer"}],
+                "description": "Destination user group id."
+            },
+            "group_name": {
+                "type": "string",
+                "description": "Destination group name (substring match; 0/1/many flow)."
+            },
+            "group_search_text": {
+                "type": "string",
+                "description": "Alias of group_name."
+            }
+        },
+        "anyOf": [
+            {"required": ["user_id", "user_group_id"]},
+            {"required": ["user_id", "group_name"]},
+            {"required": ["name", "user_group_id"]},
+            {"required": ["name", "group_name"]}
+        ]
+    }
+)
+
+REMOVE_USER_FROM_GROUP_TOOL = Tool(
+    name="remove-user-from-group",
+    description="Exclude a user from a specific group by moving to a destination group via PUT /api/users/{user_id}. Validates target and supports 0/1/many selection.",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "user_id": {
+                "oneOf": [{"type": "string"}, {"type": "integer"}],
+                "description": "Target user id (if omitted, 'name' is used to resolve)."
+            },
+            "name": {
+                "type": "string",
+                "description": "Target user name (0/1/many flow)."
+            },
+            "from_user_group_id": {
+                "oneOf": [{"type": "string"}, {"type": "integer"}],
+                "description": "(Optional) Enforce that the user is currently in this group."
+            },
+            "from_group_name": {
+                "type": "string",
+                "description": "(Optional) From-group name (substring match; 0/1/many flow)."
+            },
+            "from_group_search_text": {
+                "type": "string",
+                "description": "(Optional) Alias of from_group_name."
+            },
+            "destination_group_id": {
+                "oneOf": [{"type": "string"}, {"type": "integer"}],
+                "description": "(Optional) Destination group id. If omitted, will try parent or fallback to id=1."
+            },
+            "destination_group_name": {
+                "type": "string",
+                "description": "(Optional) Destination group name (substring match; 0/1/many flow)."
+            },
+            "destination_group_search_text": {
+                "type": "string",
+                "description": "(Optional) Alias of destination_group_name."
+            }
+        },
+        "anyOf": [
+            {"required": ["user_id"]},
+            {"required": ["name"]}
+        ]
+    }
+)
+
+
+BULK_EDIT_USERS_TOOL = Tool(
+    name="bulk-edit-users",
+    description=(
+        "Bulk update multiple users at once using the fixed endpoint "
+        "PUT https://192.168.120.71/api/users?adv=mode1. "
+        "Provide 'adv_criteria' to select targets and any combination of: "
+        "new_user_group_id/new_user_group (user group change), "
+        "start_datetime/expiry_datetime (period), "
+        "access_group_ids/access_groups or clear_access_groups (access levels/groups). "
+        "Use 'dry_run=true' to preview the request payload without calling the API."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "adv_criteria": {
+                "type": "object",
+                "description": "Advanced criteria object to select target users (e.g., {'user_group_id': 4037})."
+            },
+            "new_user_group_id": {
+                "oneOf": [{"type": "string"}, {"type": "integer"}],
+                "description": "Destination user group id for all matched users."
+            },
+            "new_user_group": {
+                "type": "object",
+                "description": "Full user_group_id object to pass-through (e.g., {'id':'4036','name':'ACE'})."
+            },
+            "start_datetime": {
+                "type": "string",
+                "description": "ISO8601 start datetime, e.g., '2001-01-01T00:00:00'."
+            },
+            "expiry_datetime": {
+                "type": "string",
+                "description": "ISO8601 expiry datetime, e.g., '2034-12-31T23:59:00'."
+            },
+            "access_group_ids": {
+                "type": "array",
+                "items": {"oneOf": [{"type": "string"}, {"type": "integer"}]},
+                "description": "List of Access Group IDs to assign (minimal form [{'id': <id>}])."
+            },
+            "access_groups": {
+                "type": "array",
+                "items": {"type": "object"},
+                "description": "Full AccessGroup objects to pass-through (supports 'accessLevels', 'users', etc.)."
+            },
+            "clear_access_groups": {
+                "type": "boolean",
+                "description": "If true, sets 'access_groups': [] (overrides access_group_ids/access_groups).",
+                "default": False
+            },
+            "dry_run": {
+                "type": "boolean",
+                "description": "If true, returns the planned payload without calling the API.",
+                "default": False
+            },
+            "timeout": {
+                "type": "integer",
+                "description": "HTTP timeout seconds (1-120). Default: 30.",
+                "default": 30
+            }
+        },
+        "required": ["adv_criteria"],
+        "allOf": [
+            {
+                "anyOf": [
+                    {"required": ["new_user_group_id"]},
+                    {"required": ["new_user_group"]},
+                    {"required": ["start_datetime"]},
+                    {"required": ["expiry_datetime"]},
+                    {"required": ["access_group_ids"]},
+                    {"required": ["access_groups"]},
+                    {"required": ["clear_access_groups"]}
+                ]
+            }
+        ]
+    }
+)
+
+
+IMPORT_USERS_CSV_TOOL = Tool(
+    name="import-users-csv",
+    description=(
+        "Import users from a CSV into BioStar.\n- Always use this tool whenever the user asks to add/import users via a CSV (e.g., 'add users from CSV', 'import users').\n- The server download directory prefix is applied automatically to file paths: C:\\Program Files\\BioStar X\\nginx\\html\\download (override via session.config.download_dir).\n- Inputs: either 'file_path' to upload or ('uri' + 'fileName') if the file already exists on the server."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "file_path": {
+                "type": "string",
+                "description": "Local CSV path to upload via /api/attachments (optional if uri+fileName provided)"
+            },
+            "uri": {
+                "type": "string",
+                "description": "Attachment URI already uploaded to BioStar 2 (used when file_path is not provided)"
+            },
+            "fileName": {
+                "type": "string",
+                "description": "Attachment fileName already uploaded (used when file_path is not provided)"
+            },
+            "original_file_name": {
+                "type": "string",
+                "description": "Original filename to show in BioStar 2 (defaults to fileName)"
+            },
+            "start_line": {
+                "type": "integer",
+                "description": "CSV import start line (1-based). Usually header=1, data starts at 2. Default=2",
+                "default": 2
+            },
+            "timeout": {
+                "type": "integer",
+                "description": "HTTP timeout seconds (default 60)",
+                "default": 60
+            },
+            "use_server_columns": {
+                "type": "boolean",
+                "description": "Fetch /api/users/csv_option to determine columns; fallback to known default.",
+                "default": True
+            },
+            "columns": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Override columns list (if omitted, will use server columns or fallback)."
+            },
+            "headers": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Header mapping aligned with 'columns'. If omitted, applies safe default mapping."
+            },
+            "data_rows": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Optional inline CSV line strings to send via 'Data' (header line should NOT be included)."
+            }
+        },
+        "required": []
+    }
+)
+
+IMPORT_USERS_CSV_SMART_TOOL = Tool(
+    name="import-users-csv-smart",
+    description=(
+        "Smart CSV import for BioStar 2 with automatic post-processing.\n"
+        "- Use when the CSV may be missing required headers or has minimal columns.\n"
+        "- Automatically adds/fills required headers (user_group, start_datetime, expiry_datetime) with defaults.\n"
+        "- AUTO-UPDATE FEATURE: After creating users, automatically updates User Groups, Access Groups, and Dates if present in CSV.\n"
+        "- Supports flexible date formats (20251225, 12.25.2025, 2025-12-25) and auto-converts to ISO 8601.\n"
+        "- CSV columns recognized: 'User Group', 'Access Group', 'Start Date', 'End Date' (case-insensitive).\n"
+        "- Fetches the exact server column list via /api/users/csv_option and builds a full-length mapping to prevent '211 not defined'.\n"
+        "- Delegates the actual import to the strict importer (import-users-csv) by passing enhanced bytes and the full mapping.\n"
+        "CRITICAL: Always use the tool's default values unless the user explicitly specifies different values. Do not override default_group_name based on context or assumptions.\n"
+        "Defaults: user_group='All Users', start_datetime='2001-01-01 00:00', expiry_datetime='2030-12-31 23:59', auto_update=true.\n"
+        "Tip: set dry_run=true to preview the planned mapping without sending the import request."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            # ----- Input sources (same loader as strict tool) -----
+            "file_path": {
+                "type": "string",
+                "description": "Local path or http(s) URL; smart search also checks common locations (/mnt/data, CWD, Downloads, session.config.upload_inbox_dir)."
+            },
+            "uri": {
+                "type": "string",
+                "description": "If the CSV already exists in the server download dir, pass the basename here."
+            },
+            "fileName": {
+                "type": "string",
+                "description": "Usually the same as 'uri' when referencing an existing server file."
+            },
+            "original_file_name": {
+                "type": "string",
+                "description": "Original filename for display; defaults to the basename of the uploaded file."
+            },
+            "file_base64": {
+                "type": "string",
+                "description": "Provide raw CSV content as Base64 (highest priority input)."
+            },
+            "file_text": {
+                "type": "string",
+                "description": "Provide raw CSV text (will be encoded with 'charset', default utf-8-sig)."
+            },
+            "file_bytes": {
+                "type": "array",
+                "items": {"type": "integer"},
+                "description": "Provide raw CSV bytes as an array of integers (0-255)."
+            },
+
+            # ----- Behavior & defaults -----
+            "delimiter": {
+                "type": "string",
+                "description": "Optional delimiter override. Auto-sniff by default.",
+                "enum": [",", ";", "|", "\\t"]
+            },
+            "charset": {
+                "type": "string",
+                "description": "Decode charset for file_text/bytes (default: utf-8-sig).",
+                "default": "utf-8-sig"
+            },
+            "default_group_name": {
+                "type": "string",
+                "description": "Default user_group value when missing/empty.",
+                "default": "All Users"
+            },
+            "default_start_datetime": {
+                "type": "string",
+                "description": "Default start_datetime when missing/empty.",
+                "default": "2001-01-01 00:00"
+            },
+            "default_expiry_datetime": {
+                "type": "string",
+                "description": "Default expiry_datetime when missing/empty.",
+                "default": "2030-12-31 23:59"
+            },
+            "start_line": {
+                "type": "integer",
+                "description": "CSV data start line (1-based). Enhanced CSV includes a header at line 1, so data starts at 2.",
+                "default": 2
+            },
+            "timeout": {
+                "type": "integer",
+                "description": "HTTP timeout seconds.",
+                "default": 60
+            },
+            "dry_run": {
+                "type": "boolean",
+                "description": "If true, return the planned mapping/details without calling the import API.",
+                "default": False
+            },
+            "auto_update": {
+                "type": "boolean",
+                "description": "If true, automatically update User Groups, Access Groups, and Dates from CSV after import. Enabled by default.",
+                "default": True
+            }
+        },
+        "required": []
+    }
+)
+
+# --- Add this near other Tool definitions in users.py ---
+
+EXPORT_NON_ACCESSED_USERS_CSV_TOOL = Tool(
+    name="export-non-accessed-users-csv",
+    description=(
+        "Export users who have NOT accessed a specific door within a given time period to CSV. "
+        "This tool first identifies non-accessed users by analyzing event logs, then exports only those users to CSV. "
+        "Perfect for finding inactive users or users who didn't use a specific entry point."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "door_id": {
+                "oneOf": [{"type": "string"}, {"type": "integer"}],
+                "description": "Door ID to check access for"
+            },
+            "door_name": {
+                "type": "string",
+                "description": "Door name (alternative to door_id, will search for matching door)"
+            },
+            "days": {
+                "type": "integer",
+                "description": "Number of days to look back (default: 7)",
+                "default": 7
+            },
+            "hours": {
+                "type": "integer",
+                "description": "Number of hours to look back (alternative to days)"
+            },
+            "copy_to_downloads": {
+                "type": "boolean",
+                "description": "Copy the exported CSV into Windows Downloads folder",
+                "default": True
+            },
+            "dest_dir": {
+                "type": "string",
+                "description": "Absolute destination directory for the copy (overrides Downloads)"
+            },
+            "target_username": {
+                "type": "string",
+                "description": "Windows username for Downloads path"
+            }
+        },
+        "anyOf": [
+            {"required": ["door_id"]},
+            {"required": ["door_name"]}
+        ]
+    }
+)
+
+BULK_UPDATE_USERS_FROM_FILE_TOOL = Tool(
+    name="bulk-update-users-from-file",
+    description=(
+        "Read a CSV/Excel-like file and update users in bulk:\n"
+        "- Columns recognized (case/spacing tolerant): 'name', 'group' (user group), 'access group' (Access Group), 'start date', 'end date'.\n"
+        "- Date columns support flexible formats: 20251225, 12.25.2025, 2025-12-25, etc. Automatically converted to ISO 8601 format.\n"
+        "- Flow: list-all-users -> resolve each Name (0/1/many) -> PUT /api/users/{id} to change user_group and dates -> "
+        "POST /api/v2/access_groups to map group names -> for each Access Group, PUT /api/access_groups/{id} with new_users.\n"
+        "- If any name is ambiguous (0 or >1), the tool MUST return needs_selection=true with candidates and a selection_token.\n"
+        "- The caller should re-call with 'name_resolutions' to confirm the exact user_id for those names.\n"
+        "- Supports dry_run to preview without making updates."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            # --- file inputs (choose one way) ---
+            "file_path": {
+                "type": "string",
+                "description": "Absolute/local path to the uploaded CSV file (e.g., C:\\path\\to\\file.csv or /mnt/data/file.csv)."
+            },
+            "uri": {
+                "type": "string",
+                "description": "Attachment URI on the server, if already uploaded via /api/attachments."
+            },
+            "fileName": {
+                "type": "string",
+                "description": "Original file name when using 'uri'."
+            },
+            "file_bytes": {
+                "type": "string",
+                "description": "Base64-encoded file content; use with 'original_file_name'."
+            },
+            "original_file_name": {
+                "type": "string",
+                "description": "Original file name when using 'file_bytes'."
+            },
+
+            # --- parsing options ---
+            "charset": {
+                "type": "string",
+                "description": "Text encoding for CSV decode. Default: 'utf-8-sig'."
+            },
+            "delimiter": {
+                "type": "string",
+                "description": "Override CSV delimiter. Auto-detected if omitted."
+            },
+
+            # --- ambiguity resolution ---
+            "selection_token": {
+                "type": "string",
+                "description": "Token provided from a previous ambiguous run; optional verification."
+            },
+            "name_resolutions": {
+                "type": "object",
+                "description": "Map of display name -> chosen user_id for conflicted names, e.g., {'Alice Johnson':'258258750'}.",
+                "additionalProperties": {
+                    "oneOf": [{"type": "string"}, {"type": "integer"}]
+                }
+            },
+
+            # --- execution controls ---
+            "dry_run": {
+                "type": "boolean",
+                "description": "If true, build the plan but do not call the update APIs.",
+                "default": False
+            },
+            "max_bulk_size": {
+                "type": "integer",
+                "description": "Max users per /api/users/bulk call (<=100). Default: 100.",
+                "default": 100
+            }
+        },
+        "anyOf": [
+            {"required": ["file_path"]},
+            {"required": ["uri", "fileName"]},
+            {"required": ["file_bytes", "original_file_name"]}
+        ]
+    }
+)
+
+# Helper function tools for user data processing
+FORMAT_PHONE_NUMBER_TOOL = Tool(
+    name="format-phone-number",
+    description="Clean and format phone number by removing all non-digit characters. Example: '1) 415-732-9042' becomes '14157329042'",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "phone": {
+                "type": "string",
+                "description": "Raw phone number string to clean"
+            }
+        },
+        "required": ["phone"]
+    }
+)
+
+FORMAT_PIN_FROM_PHONE_TOOL = Tool(
+    name="format-pin-from-phone",
+    description="Extract last 8 digits from phone number to generate PIN. Example: '14157329042' becomes '73290426'",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "phone": {
+                "type": "string",
+                "description": "Phone number (digits only) to extract PIN from"
+            }
+        },
+        "required": ["phone"]
+    }
+)
+
+FORMAT_DATETIME_RANGE_TOOL = Tool(
+    name="format-datetime-range",
+    description="Convert a date string (YYYY-MM-DD) to BioStar datetime range (start: 00:00:00, end: 23:59:00). Example: '2025-12-25' becomes ('2025-12-25T00:00:00.00Z', '2025-12-25T23:59:00.00Z')",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "date_str": {
+                "type": "string",
+                "description": "Date string in YYYY-MM-DD format"
+            }
+        },
+        "required": ["date_str"]
+    }
+)
+
+# List of all user tools
+USER_TOOLS = [
+    GET_USERS_TOOL,
+    CREATE_USER_TOOL,
+    GET_USER_TOOL,
+    UPDATE_USER_TOOL,
+    DELETE_USER_TOOL,
+    SEARCH_USERS_TOOL,
+    ADVANCED_SEARCH_USERS_TOOL,
+    GET_USER_CARDS_TOOL,
+    UNASSIGN_USER_CARDS_TOOL,
+    BULK_ADD_USERS_TOOL,
+    EXPORT_USERS_CSV_TOOL,
+    EXPORT_NON_ACCESSED_USERS_CSV_TOOL,
+    GET_USER_GROUPS_TOOL,
+    CREATE_USER_GROUP_TOOL,
+    ADD_USER_TO_GROUP_TOOL,
+    REMOVE_USER_FROM_GROUP_TOOL,
+    BULK_EDIT_USERS_TOOL,
+    IMPORT_USERS_CSV_TOOL,
+    IMPORT_USERS_CSV_SMART_TOOL,
+    BULK_UPDATE_USERS_FROM_FILE_TOOL,
+    FORMAT_PHONE_NUMBER_TOOL,
+    FORMAT_PIN_FROM_PHONE_TOOL,
+    FORMAT_DATETIME_RANGE_TOOL
+]