suprema-biostar-mcp 1.0.1__tar.gz

suprema_biostar_mcp-1.0.1/.env.example

@@ -0,0 +1,37 @@
+# BioStar X MCP Server Configuration
+# Copy this file to .env and fill in your values
+
+# ===========================================
+# REQUIRED: BioStar X Server Configuration
+# ===========================================
+BIOSTAR_URL=https://your-biostar-server.com
+BIOSTAR_USERNAME=admin
+BIOSTAR_PASSWORD=your_password
+
+# ===========================================
+# OPTIONAL: API Settings
+# ===========================================
+# API request timeout in seconds (default: 30)
+API_TIMEOUT=30
+
+# Verify SSL certificates (default: true)
+# Set to false for self-signed certificates
+VERIFY_SSL=true
+
+# Session refresh interval in seconds (default: 3600)
+SESSION_REFRESH_INTERVAL=3600
+
+# ===========================================
+# OPTIONAL: Documentation Settings
+# ===========================================
+# Base URL for BioStar X documentation (default: https://docs.supremainc.com)
+DOCS_BASE_URL=https://docs.supremainc.com
+
+# Documentation cache TTL in seconds (default: 3600)
+DOCS_CACHE_TTL=3600
+
+# ===========================================
+# OPTIONAL: Debug Settings
+# ===========================================
+# Enable debug mode (default: false)
+DEBUG=false

suprema_biostar_mcp-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Suprema Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

suprema_biostar_mcp-1.0.1/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: suprema-biostar-mcp
+Version: 1.0.1
+Summary: MCP Server for Suprema BioStar X - Access Control System Integration for AI Assistants
+Project-URL: Homepage, https://www.supremainc.com
+Project-URL: Documentation, https://docs.supremainc.com/en/platform/biostar_x
+Project-URL: Repository, https://github.com/anthropics/mcp-servers
+Author-email: "Suprema Inc." <support@supremainc.com>
+License: MIT
+License-File: LICENSE
+Keywords: access-control,ai-assistant,biostar,claude,mcp,security,suprema
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0.1
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Suprema BioStar MCP Server
+
+MCP (Model Context Protocol) server for **Suprema BioStar X** - Next-generation access control platform integration for AI assistants.
+
+> **🚀 One-Click Installation**: `uvx suprema-biostar-mcp`
+
+## Features
+
+- **129+ Tools**: Full BioStar X API coverage (users, doors, devices, access control, events, and more)
+- **Lightweight**: No heavy ML dependencies (~50MB vs 900MB)
+- **Live Documentation**: Real-time docs from docs.supremainc.com
+- **Multi-language**: Korean and English support
+- **Easy Setup**: Works with Claude Desktop, Claude Code, and any MCP client
+
+## Quick Start
+
+### 1. Add to Claude Desktop
+
+Edit your Claude Desktop config file:
+
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "suprema-biostar": {
+      "command": "uvx",
+      "args": ["suprema-biostar-mcp"],
+      "env": {
+        "BIOSTAR_URL": "https://your-biostar-server.com",
+        "BIOSTAR_USERNAME": "admin",
+        "BIOSTAR_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+### 2. Restart Claude Desktop
+
+That's it! 🎉
+
+## Configuration
+
+| Environment Variable | Required | Description |
+|---------------------|----------|-------------|
+| `BIOSTAR_URL` | ✅ | BioStar X server URL (e.g., `https://192.168.1.100`) |
+| `BIOSTAR_USERNAME` | ✅ | Login username |
+| `BIOSTAR_PASSWORD` | ✅ | Login password |
+| `VERIFY_SSL` | ❌ | SSL verification (default: `true`) |
+| `API_TIMEOUT` | ❌ | API timeout in seconds (default: `30`) |
+
+### Changing Credentials
+
+1. Edit `claude_desktop_config.json`
+2. Update the `env` values
+3. Restart Claude Desktop
+
+## Available Tools (129+)
+
+| Category | Tools | Description |
+|----------|-------|-------------|
+| **auth** | 4 | Login, logout, session management |
+| **users** | 23 | User CRUD, groups, CSV import/export |
+| **doors** | 22 | Door control, groups, APB settings |
+| **access** | 13 | Access groups and levels |
+| **devices** | 38 | Device management, network config |
+| **cards** | 5 | Card creation (CSN, Wiegand, QR) |
+| **events** | 6 | Event search, logs, export |
+| **audit** | 6 | Audit trail tracking |
+| **occupancy** | 2 | Occupancy analysis |
+| **logs** | 5 | Server log analysis |
+| **files** | 1 | File reading (CSV, PDF) |
+| **navigation** | 1 | UI navigation |
+| **help** | 3 | Documentation search |
+
+## Example Usage
+
+Once connected to Claude:
+
+```
+"List all users"
+"Create a user named John Smith"
+"Open the main entrance door"
+"Show access events from today"
+"How do I configure anti-passback?"
+```
+
+## Alternative Installation
+
+### Using pip
+
+```bash
+pip install suprema-biostar-mcp
+suprema-biostar-mcp
+```
+
+### From source
+
+```bash
+git clone https://github.com/supremainc/suprema-biostar-mcp.git
+cd suprema-biostar-mcp
+pip install -e .
+python -m biostar_x_mcp_server
+```
+
+## Requirements
+
+- Python 3.10+
+- BioStar X server with API access
+- Network connectivity to BioStar server
+- [uv](https://docs.astral.sh/uv/) for `uvx` command (recommended)
+
+## Documentation
+
+- **BioStar X Docs**: https://docs.supremainc.com/en/platform/biostar_x
+- **MCP Protocol**: https://modelcontextprotocol.io
+
+## Support
+
+- **Suprema Support**: https://www.supremainc.com/support
+- **Documentation**: https://docs.supremainc.com
+
+---
+
+Made with ❤️ by [Suprema Inc.](https://www.supremainc.com)

suprema_biostar_mcp-1.0.1/README.md

@@ -0,0 +1,127 @@
+# Suprema BioStar MCP Server
+
+MCP (Model Context Protocol) server for **Suprema BioStar X** - Next-generation access control platform integration for AI assistants.
+
+> **🚀 One-Click Installation**: `uvx suprema-biostar-mcp`
+
+## Features
+
+- **129+ Tools**: Full BioStar X API coverage (users, doors, devices, access control, events, and more)
+- **Lightweight**: No heavy ML dependencies (~50MB vs 900MB)
+- **Live Documentation**: Real-time docs from docs.supremainc.com
+- **Multi-language**: Korean and English support
+- **Easy Setup**: Works with Claude Desktop, Claude Code, and any MCP client
+
+## Quick Start
+
+### 1. Add to Claude Desktop
+
+Edit your Claude Desktop config file:
+
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "suprema-biostar": {
+      "command": "uvx",
+      "args": ["suprema-biostar-mcp"],
+      "env": {
+        "BIOSTAR_URL": "https://your-biostar-server.com",
+        "BIOSTAR_USERNAME": "admin",
+        "BIOSTAR_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+### 2. Restart Claude Desktop
+
+That's it! 🎉
+
+## Configuration
+
+| Environment Variable | Required | Description |
+|---------------------|----------|-------------|
+| `BIOSTAR_URL` | ✅ | BioStar X server URL (e.g., `https://192.168.1.100`) |
+| `BIOSTAR_USERNAME` | ✅ | Login username |
+| `BIOSTAR_PASSWORD` | ✅ | Login password |
+| `VERIFY_SSL` | ❌ | SSL verification (default: `true`) |
+| `API_TIMEOUT` | ❌ | API timeout in seconds (default: `30`) |
+
+### Changing Credentials
+
+1. Edit `claude_desktop_config.json`
+2. Update the `env` values
+3. Restart Claude Desktop
+
+## Available Tools (129+)
+
+| Category | Tools | Description |
+|----------|-------|-------------|
+| **auth** | 4 | Login, logout, session management |
+| **users** | 23 | User CRUD, groups, CSV import/export |
+| **doors** | 22 | Door control, groups, APB settings |
+| **access** | 13 | Access groups and levels |
+| **devices** | 38 | Device management, network config |
+| **cards** | 5 | Card creation (CSN, Wiegand, QR) |
+| **events** | 6 | Event search, logs, export |
+| **audit** | 6 | Audit trail tracking |
+| **occupancy** | 2 | Occupancy analysis |
+| **logs** | 5 | Server log analysis |
+| **files** | 1 | File reading (CSV, PDF) |
+| **navigation** | 1 | UI navigation |
+| **help** | 3 | Documentation search |
+
+## Example Usage
+
+Once connected to Claude:
+
+```
+"List all users"
+"Create a user named John Smith"
+"Open the main entrance door"
+"Show access events from today"
+"How do I configure anti-passback?"
+```
+
+## Alternative Installation
+
+### Using pip
+
+```bash
+pip install suprema-biostar-mcp
+suprema-biostar-mcp
+```
+
+### From source
+
+```bash
+git clone https://github.com/supremainc/suprema-biostar-mcp.git
+cd suprema-biostar-mcp
+pip install -e .
+python -m biostar_x_mcp_server
+```
+
+## Requirements
+
+- Python 3.10+
+- BioStar X server with API access
+- Network connectivity to BioStar server
+- [uv](https://docs.astral.sh/uv/) for `uvx` command (recommended)
+
+## Documentation
+
+- **BioStar X Docs**: https://docs.supremainc.com/en/platform/biostar_x
+- **MCP Protocol**: https://modelcontextprotocol.io
+
+## Support
+
+- **Suprema Support**: https://www.supremainc.com/support
+- **Documentation**: https://docs.supremainc.com
+
+---
+
+Made with ❤️ by [Suprema Inc.](https://www.supremainc.com)

suprema_biostar_mcp-1.0.1/biostar_x_mcp_server/__init__.py

@@ -0,0 +1,25 @@
+"""
+BioStar X MCP Server
+Lightweight MCP server for BioStar X integration
+
+Features:
+- Full BioStar X API integration (138+ tools)
+- Web-based documentation (no vector DB required)
+- Dynamic tool category loading
+- Session management with auto-refresh
+- Multi-language support (Korean/English)
+"""
+
+__version__ = "1.0.0"
+__author__ = "Suprema Inc."
+
+from .config import Config
+from .session import BioStarSession
+from .tool_manager import ToolManager
+
+__all__ = [
+    "Config",
+    "BioStarSession",
+    "ToolManager",
+    "__version__"
+]

suprema_biostar_mcp-1.0.1/biostar_x_mcp_server/__main__.py

@@ -0,0 +1,15 @@
+"""
+BioStar X MCP Server - Main Entry Point
+Run with: python -m biostar_x_mcp_server
+"""
+import asyncio
+import sys
+from pathlib import Path
+
+# Ensure the parent directory is in the path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from .server import main
+
+if __name__ == "__main__":
+    asyncio.run(main())

suprema_biostar_mcp-1.0.1/biostar_x_mcp_server/config.py

@@ -0,0 +1,87 @@
+"""
+BioStar X MCP Server Configuration
+Lightweight configuration without vector DB dependencies
+"""
+import os
+from typing import Optional
+from pydantic import BaseModel, Field
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+class Config(BaseModel):
+    """Configuration for BioStar X MCP Server (Lightweight)."""
+
+    # BioStar X API settings
+    biostar_url: str = Field(
+        default_factory=lambda: os.getenv("BIOSTAR_URL", "https://localhost"),
+        description="BioStar X server URL"
+    )
+    biostar_username: str = Field(
+        default_factory=lambda: os.getenv("BIOSTAR_USERNAME", ""),
+        description="BioStar X username"
+    )
+    biostar_password: str = Field(
+        default_factory=lambda: os.getenv("BIOSTAR_PASSWORD", ""),
+        description="BioStar X password"
+    )
+
+    # API settings
+    api_timeout: int = Field(
+        default_factory=lambda: int(os.getenv("API_TIMEOUT", "30")),
+        description="API request timeout in seconds"
+    )
+    verify_ssl: bool = Field(
+        default_factory=lambda: os.getenv("VERIFY_SSL", "true").lower() == "true",
+        description="Verify SSL certificates"
+    )
+
+    # Session settings
+    session_refresh_interval: int = Field(
+        default_factory=lambda: int(os.getenv("SESSION_REFRESH_INTERVAL", "3600")),
+        description="Session refresh interval in seconds"
+    )
+
+    # Server settings
+    debug: bool = Field(
+        default_factory=lambda: os.getenv("DEBUG", "false").lower() == "true",
+        description="Enable debug mode"
+    )
+
+    # Tool loading settings
+    default_categories: list[str] = Field(
+        default=["auth"],
+        description="Categories to load by default"
+    )
+    max_active_categories: int = Field(
+        default=15,
+        description="Maximum number of active tool categories"
+    )
+
+    # Documentation settings (Web-based help)
+    docs_base_url: str = Field(
+        default_factory=lambda: os.getenv("DOCS_BASE_URL", "https://docs.supremainc.com"),
+        description="Base URL for BioStar X documentation"
+    )
+    docs_cache_ttl: int = Field(
+        default_factory=lambda: int(os.getenv("DOCS_CACHE_TTL", "3600")),
+        description="Documentation cache TTL in seconds"
+    )
+
+    class Config:
+        env_file = ".env"
+        env_file_encoding = "utf-8"
+
+    def validate_required(self) -> list[str]:
+        """Validate required configuration and return list of errors."""
+        errors = []
+
+        if not self.biostar_url:
+            errors.append("BIOSTAR_URL is required")
+        if not self.biostar_username:
+            errors.append("BIOSTAR_USERNAME is required")
+        if not self.biostar_password:
+            errors.append("BIOSTAR_PASSWORD is required")
+
+        return errors

suprema_biostar_mcp-1.0.1/biostar_x_mcp_server/handlers/__init__.py

@@ -0,0 +1,35 @@
+"""
+BioStar X MCP Server Handlers
+All API handlers for BioStar X integration
+"""
+from .base_handler import BaseHandler
+from .auth_handler import AuthHandler
+from .user_handler import UserHandler
+from .door_handler import DoorHandler
+from .access_handler import AccessHandler
+from .device_handler import DeviceHandler
+from .event_handler import EventHandler
+from .audit_handler import AuditHandler
+from .card_handler import CardsHandler
+from .navigation_handler import NavigationHandler
+from .file_handler import FileHandler
+from .log_handler import LogHandler
+from .occupancy_handler import OccupancyHandler
+from .help_web_handler import HelpWebHandler
+
+__all__ = [
+    "BaseHandler",
+    "AuthHandler",
+    "UserHandler",
+    "DoorHandler",
+    "AccessHandler",
+    "DeviceHandler",
+    "EventHandler",
+    "AuditHandler",
+    "CardsHandler",
+    "NavigationHandler",
+    "FileHandler",
+    "LogHandler",
+    "OccupancyHandler",
+    "HelpWebHandler"
+]