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

biostar_x_mcp_server/tools/access.py

@@ -0,0 +1,510 @@
+from mcp.types import Tool
+
+# -----------------------------
+# Access Group management tools
+# -----------------------------
+GET_ACCESS_GROUPS_TOOL = Tool(
+    name="get-access-groups",
+    description="Retrieve all access groups from the BioStar 2 system",
+    inputSchema={
+        "type": "object",
+        "properties": {},
+        "required": []
+    }
+)
+
+GET_ACCESS_GROUP_TOOL = Tool(
+    name="get-access-group",
+    description="Get detailed information about a specific access group",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "group_id": {
+                "type": "integer",
+                "description": "ID of the access group to retrieve"
+            }
+        },
+        "required": ["group_id"]
+    }
+)
+
+CREATE_ACCESS_GROUP_TOOL = Tool(
+    name="create-access-group",
+    description="""
+Create a new access group (POST /api/access_groups).
+
+USER GROUP BEHAVIOR (NEW):
+- Optional user group inclusion via either:
+  * user_group_ids: explicit list of ids (validated), or
+  * user_group_search_text: substring search (3-case):
+      0 match -> return all user groups + needs_selection=true,
+      1 match -> proceed with that group,
+      2+ matches -> return candidates + needs_selection=true.
+- If neither is provided, user_groups are not included.
+
+STRICT CALLER RULES:
+- Do NOT attempt to set floor levels here (ignored).
+- Do NOT guess users or access levels; list and pick explicitly before calling.
+
+PAYLOAD:
+{
+  "AccessGroup": {
+    "name": "...",
+    "description": "...",
+    "users": [ {"user_id": "1"}, ... ],
+    "user_groups": [ {"id": 1106, "name": "ACE Group"}, ... ],
+    "access_levels": [ {"id": "2"}, ... ]
+  }
+}
+""",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "name": {
+                "type": "string",
+                "description": "Access group name"
+            },
+            "description": {
+                "type": "string",
+                "description": "Description for the access group",
+                "default": ""
+            },
+            "user_ids": {
+                "type": "array",
+                "items": {"oneOf": [{"type": "string"}, {"type": "integer"}]},
+                "description": "Explicit list of user ids to include. Do NOT auto-select."
+            },
+            "access_level_ids": {
+                "type": "array",
+                "items": {"oneOf": [{"type": "string"}, {"type": "integer"}]},
+                "description": "Existing access level ids to assign to this group."
+            },
+            "user_group_ids": {
+                "type": "array",
+                "items": {"oneOf": [{"type": "integer"}, {"type": "string"}]},
+                "description": "Explicit user group ids to include (validated against GET /api/user_groups)"
+            },
+            "user_group_search_text": {
+                "type": "string",
+                "description": "Substring to search user group name (3-case resolution)"
+            }
+        },
+        "required": ["name"]
+    }
+)
+
+UPDATE_ACCESS_GROUP_TOOL = Tool(
+    name="update-access-group",
+    description="""
+Update an existing access group (PUT /api/access_groups/{group_id}).
+
+User groups:
+- Replacement:
+  * If "user_group_ids" KEY IS PRESENT (even []), replace with that exact list.
+  * "user_group_search_text" (legacy) -> single-match replacement; 0/Many -> needs_selection=true.
+- Delta:
+  * add_user_group_ids / add_user_group_search_text
+  * remove_user_group_ids / remove_user_group_search_text
+  Each search_text uses 3-case logic (0/1/Many) identical to create().
+Users:
+- user_ids -> full replacement of 'users'
+- Or apply delta with new_users / delete_users (and include those arrays in payload)
+Access levels:
+- access_level_ids -> full replacement of 'access_levels'
+Floor levels:
+- Ignored with a warning
+Only provided fields are included in the PUT body; others are preserved server-side.
+""",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "group_id": {"type": "integer", "description": "ID of the access group to update"},
+            "name": {"type": "string", "description": "New name"},
+            "description": {"type": "string", "description": "New description"},
+
+            # Users
+            "user_ids": {
+                "type": "array",
+                "items": {"oneOf": [{"type": "string"}, {"type": "integer"}]},
+                "description": "Final set of user ids (replacement)."
+            },
+            "new_users": {
+                "type": "array",
+                "items": {"oneOf": [{"type": "string"}, {"type": "integer"}]},
+                "description": "User ids to add (delta)."
+            },
+            "delete_users": {
+                "type": "array",
+                "items": {"oneOf": [{"type": "string"}, {"type": "integer"}]},
+                "description": "User ids to remove (delta)."
+            },
+
+            # Access Levels (replacement)
+            "access_level_ids": {
+                "type": "array",
+                "items": {"oneOf": [{"type": "string"}, {"type": "integer"}]},
+                "description": "Replace the group's access_levels with these ids."
+            },
+
+            # User Groups - Replacement
+            "user_group_ids": {
+                "type": "array",
+                "items": {"oneOf": [{"type": "integer"}, {"type": "string"}]},
+                "description": "Replace user_groups with these ids. If [], clears all."
+            },
+            "user_group_search_text": {
+                "type": "string",
+                "description": "(Legacy) Single-match replacement by name."
+            },
+
+            # User Groups - Delta
+            "add_user_group_ids": {
+                "type": "array",
+                "items": {"oneOf": [{"type": "integer"}, {"type": "string"}]},
+                "description": "Add these user group ids (delta)."
+            },
+            "remove_user_group_ids": {
+                "type": "array",
+                "items": {"oneOf": [{"type": "integer"}, {"type": "string"}]},
+                "description": "Remove these user group ids (delta)."
+            },
+            "add_user_group_search_text": {
+                "type": "string",
+                "description": "Add by name (3-case resolution)."
+            },
+            "remove_user_group_search_text": {
+                "type": "string",
+                "description": "Remove by name (3-case resolution)."
+            }
+        },
+        "required": ["group_id"]
+    }
+)
+
+DELETE_ACCESS_GROUP_TOOL = Tool(
+    name="delete-access-group",
+    description=" CRITICAL: Delete an access group. 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": {
+            "group_id": {
+                "type": "integer",
+                "description": "ID of the access group to delete"
+            }
+        },
+        "required": ["group_id"]
+    }
+)
+
+# -----------------------------
+# Access Level management tools
+# -----------------------------
+GET_ACCESS_LEVELS_TOOL = Tool(
+    name="get-access-levels",
+    description="""
+Retrieve access levels from the BioStar 2 system.
+
+Supports the official "View All AL" query parameters (GET /api/access_levels):
+- limit: integer (0 shows all; default 50)
+- offset: integer (default 0)
+- order_by: string (e.g., "id:false" for ascending by id)
+
+Example:
+curl --location 'https://127.0.0.1/api/access_levels?limit=50&offset=0&order_by=id:false'
+""",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "limit": {"type": "integer", "description": "Limit number of records (0 to show all)", "default": 50},
+            "offset": {"type": "integer", "description": "Offset/skip records", "default": 0},
+            "order_by": {"type": "string", "description": "Order by (e.g., 'id:false')", "default": "id:false"}
+        },
+        "required": []
+    }
+)
+
+GET_ACCESS_LEVEL_TOOL = Tool(
+    name="get-access-level",
+    description="Get detailed information about a specific access level",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "level_id": {
+                "type": "integer",
+                "description": "ID of the access level to retrieve"
+            }
+        },
+        "required": ["level_id"]
+    }
+)
+
+CREATE_ACCESS_LEVEL_TOOL = Tool(
+    name="create-access-level",
+    description="""
+Create a new Access Level (AL) with strict door validation and an enforced 'Always' schedule.
+
+SMART AUTO-SELECT MODE:
+- If `access_level_items` is NOT provided or empty, the tool will automatically fetch all available doors.
+- You can then specify door IDs/names in the `door_ids` or `door_names` parameter for simple cases.
+- For complex multi-item scenarios, provide full `access_level_items` structure.
+
+CALLER RULES:
+- Recommended: Use `door_ids=[177, 178, 179]` or `door_names=["Main Entrance", "CEO Office"]` for simple access levels.
+- Advanced: Use `access_level_items=[{"doors": [...]}]` for multiple schedule items (though all use 'Always' internally).
+- Do NOT use this tool as a fallback for `update-access-level` when the target does not exist. Creation must be explicitly requested by the user.
+
+WHAT THIS TOOL DOES:
+- Accepts `door_ids`, `door_names`, OR `access_level_items` (at least one required).
+- Any `schedule_id` provided in the input is ignored; 'Always' will be applied internally.
+- Nonexistent door ids -> error with `available_doors` list for retry.
+
+BEHAVIOR:
+- Duplicate-name check (case-insensitive). If an AL with the same name exists, returns that info and does not create.
+- Normalizes per-item doors (int-cast & de-dup) to avoid API errors.
+- Preview (confirm=false) is allowed ONLY when all provided door ids are valid.
+- On proceed (confirm=true), calls POST /api/access_levels (no trailing slash).
+- If 'Always' schedule is missing, it is created and used automatically.
+""",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "confirm": {
+                "type": "boolean",
+                "default": True,
+                "description": "If true, create the Access Level; otherwise preview only. Defaults to True for automatic creation."
+            },
+            "name": {
+                "type": "string",
+                "description": "Unique Access Level name."
+            },
+            "description": {
+                "type": "string",
+                "default": "",
+                "description": "Description for the Access Level."
+            },
+            "door_ids": {
+                "type": "array",
+                "items": {"type": "integer"},
+                "description": "Simple mode: List of door IDs to include (e.g., [177, 178, 179]). Mutually exclusive with access_level_items."
+            },
+            "door_names": {
+                "type": "array",
+                "items": {"type": "string"},
+                "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": {
+                "type": "boolean",
+                "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": {
+                "type": "array",
+                "minItems": 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.",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "doors": {
+                            "type": "array",
+                            "minItems": 1,
+                            "items": {"anyOf": [{"type": "integer"}, {"type": "string"}]},
+                            "description": "Door IDs or names; de-duplicated per item."
+                        }
+                    },
+                    "required": ["doors"]
+                }
+            }
+        },
+        "required": ["name"],
+        "oneOf": [
+            {"required": ["door_ids"]},
+            {"required": ["door_names"]},
+            {"required": ["access_level_items"]}
+        ]
+    }
+)
+
+from mcp.types import Tool
+
+UPDATE_ACCESS_LEVEL_TOOL = Tool(
+    name="update-access-level",
+    description="""
+Update an Access Level (PUT /api/access_levels/{level_id}) with a SINGLE enforced schedule 'Always'.
+
+HARD GUARD (DO NOT BYPASS):
+- This tool MUST NEVER create a new access level when the target does not exist.
+- If the target cannot be resolved, this tool returns an error with status="target_not_found",
+  includes a list of existing access levels (`available_levels`), and sets `do_not_autocreate=true`.
+- Callers MUST NOT chain to `create-access-level` based solely on this result. They MUST ask the user first.
+
+Target specification:
+- Prefer `level_id`. Or provide `level_name` (exact) and/or `search_text` for fuzzy match.
+
+Editable fields:
+- name (optional)
+- description (optional; empty string clears)
+- doors (optional): choose exactly one of set_doors / add_doors / remove_doors
+
+STRICT RULES:
+- Schedule is not user-editable; it is always set to 'Always' (created if missing).
+- If no door operation is provided, existing doors are preserved.
+- All door ids are validated against GET /api/doors; invalid ids -> error with `available_doors`.
+- Duplicate door ids are removed automatically.
+- If multiple access_level_items exist on server, they are collapsed into one (first item's id).
+
+Optional:
+- dry_run: true -> return the planned PUT body & door diff without calling the API.
+""",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "level_id": {"type": "integer", "description": "ID of the access level to update"},
+            "level_name": {"type": "string", "description": "Exact name of the access level to update"},
+            "search_text": {"type": "string", "description": "Fuzzy search text (name/description contains)"},
+            "name": {"type": "string", "description": "New name (optional)"},
+            "description": {"type": "string", "description": "New description (optional; empty string clears)"},
+            "set_doors": {
+                "type": "array",
+                "items": {"oneOf": [{"type": "integer"}, {"type": "string"}]},
+                "description": "Full replacement of door ids (takes precedence over add/remove)"
+            },
+            "add_doors": {
+                "type": "array",
+                "items": {"oneOf": [{"type": "integer"}, {"type": "string"}]},
+                "description": "Door ids to add"
+            },
+            "remove_doors": {
+                "type": "array",
+                "items": {"oneOf": [{"type": "integer"}, {"type": "string"}]},
+                "description": "Door ids to remove (ignored if not currently assigned)"
+            },
+            "dry_run": {"type": "boolean", "default": False, "description": "Preview changes without calling the API"}
+        },
+        "required": []
+    }
+)
+
+
+DELETE_ACCESS_LEVEL_TOOL = Tool(
+    name="delete-access-level",
+    description=" CRITICAL: Delete an access level. 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": {
+            "level_id": {
+                "type": "integer",
+                "description": "ID of the access level to delete"
+            }
+        },
+        "required": ["level_id"]
+    }
+)
+
+ADD_ACCESS_LEVEL_TO_GROUP_TOOL = Tool(
+    name="add-access-level-to-group",
+    description="""
+Add one or more access levels to an access group by updating the group's access_levels array via PUT /api/access_groups/{id}.
+- Preserves other fields (name, description, users, user_groups, floor_levels, new_users, delete_users) as-is.
+- Validates that requested access level ids exist; otherwise returns error and a full list of existing access levels.
+- Idempotent: already-assigned ids are ignored.
+""".strip(),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "access_group_id": {
+                "type": "integer",
+                "description": "Target access group ID"
+            },
+            "access_level_id": {
+                "type": "integer",
+                "description": "An access level id to add (single)"
+            },
+            "access_level_ids": {
+                "type": "array",
+                "items": {"oneOf": [{"type": "integer"}, {"type": "string"}]},
+                "description": "Access level ids to add (one or many)"
+            }
+        },
+        "required": ["access_group_id"]
+    }
+)
+
+REMOVE_ACCESS_LEVEL_FROM_GROUP_TOOL = Tool(
+    name="remove-access-level-from-group",
+    description="""
+Remove one or more access levels from an access group by updating the group's access_levels array via PUT /api/access_groups/{id}.
+- Preserves other fields (name, description, users, user_groups, floor_levels, new_users, delete_users) as-is.
+- Validates that requested access level ids exist; otherwise returns error and a full list of existing access levels.
+- Idempotent: ids not currently assigned are ignored.
+""".strip(),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "access_group_id": {
+                "type": "integer",
+                "description": "Target access group ID"
+            },
+            "access_level_id": {
+                "type": "integer",
+                "description": "An access level id to remove (single)"
+            },
+            "access_level_ids": {
+                "type": "array",
+                "items": {"oneOf": [{"type": "integer"}, {"type": "string"}]},
+                "description": "Access level ids to remove (one or many)"
+            }
+        },
+        "required": ["access_group_id"]
+    }
+)
+
+# -----------------------------------------
+# Access Group v2 search (optional helper)
+# -----------------------------------------
+SEARCH_ACCESS_GROUPS_V2_TOOL = Tool(
+    name="search-access-groups",
+    description="""
+Search (list) access groups using v2 endpoint (POST /api/v2/access_groups/search/).
+Required body fields:
+- limit: number (0 shows all)
+- order_by: string "name:false" or "id:false" (false=ascending, true=descending)
+""",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "limit": {
+                "type": "integer",
+                "description": "To limit result by n record(s), 0 to show all",
+                "default": 0
+            },
+            "order_by": {
+                "type": "string",
+                "description": "Order by string like 'id:false' or 'name:true'",
+                "default": "id:false"
+            }
+        },
+        "required": ["limit", "order_by"]
+    }
+)
+
+# -----------------------------
+# Access Log tools
+# -----------------------------
+# Export all access tools
+# -----------------------------
+# Note: get-access-logs is in events.py (EventHandler has the implementation)
+ACCESS_TOOLS = [
+    GET_ACCESS_GROUPS_TOOL,
+    GET_ACCESS_GROUP_TOOL,
+    CREATE_ACCESS_GROUP_TOOL,
+    UPDATE_ACCESS_GROUP_TOOL,
+    DELETE_ACCESS_GROUP_TOOL,
+    SEARCH_ACCESS_GROUPS_V2_TOOL,
+    GET_ACCESS_LEVELS_TOOL,
+    GET_ACCESS_LEVEL_TOOL,
+    CREATE_ACCESS_LEVEL_TOOL,
+    UPDATE_ACCESS_LEVEL_TOOL,
+    DELETE_ACCESS_LEVEL_TOOL,
+    ADD_ACCESS_LEVEL_TO_GROUP_TOOL,
+    REMOVE_ACCESS_LEVEL_FROM_GROUP_TOOL
+]