mcp-openstack-ops 3.2.2__tar.gz → 3.2.3__tar.gz

{mcp_openstack_ops-3.2.2/src/mcp_openstack_ops.egg-info → mcp_openstack_ops-3.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-openstack-ops
-Version: 3.2.2
+Version: 3.2.3
 Summary: OpenStack operations automation MCP server
 Author-email: JungJungIn <call518@gmail.com>
 Requires-Python: >=3.12
@@ -19,10 +19,15 @@ Dynamic: license-file
 > **MCP OpenStack Operations Server**: A comprehensive MCP (Model Context Protocol) server providing OpenStack project management and monitoring capabilities with built-in safety controls and single-project scope.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![Deploy to PyPI with tag](https://github.com/call518/MCP-OpenStack-Ops/actions/workflows/pypi-publish.yml/badge.svg)](https://github.com/call518/MCP-OpenStack-Ops/actions/workflows/pypi-publish.yml)
+![Python](https://img.shields.io/badge/Python-3776AB?style=flat&logo=python&logoColor=white)
+![Docker Pulls](https://img.shields.io/docker/pulls/call518/mcp-server-openstack-ops)
 [![smithery badge](https://smithery.ai/badge/@call518/mcp-openstack-ops)](https://smithery.ai/server/@call518/mcp-openstack-ops)
 [![BuyMeACoffee](https://raw.githubusercontent.com/pachadotdev/buymeacoffee-badges/main/bmc-donate-yellow.svg)](https://www.buymeacoffee.com/call518)
 
+[![Deploy to PyPI with tag](https://github.com/call518/MCP-OpenStack-Ops/actions/workflows/pypi-publish.yml/badge.svg)](https://github.com/call518/MCP-OpenStack-Ops/actions/workflows/pypi-publish.yml)
+![PyPI](https://img.shields.io/pypi/v/MCP-OpenStack-Ops?label=pypi%20package)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/MCP-OpenStack-Ops)
+
 ---
 
 ## Architecture & Internal (DeepWiki)
@@ -1029,6 +1034,200 @@ When authentication fails, the server returns:
 
 ---
 
+## 🚀 Adding Custom Tools
+
+This MCP server is designed for easy extensibility. Follow these steps to add your own custom tools:
+
+### Step-by-Step Guide
+
+#### 1. **Add Helper Functions (Optional)**
+
+Add reusable data functions to `src/mcp_openstack_ops/functions.py`:
+
+```python
+async def get_your_custom_data(target_resource: str = None) -> List[Dict[str, Any]]:
+    """Your custom data retrieval function."""
+    # Example implementation - adapt to your OpenStack service
+    conn = get_openstack_connection()
+    results = []
+    
+    try:
+        # Example: Custom query using OpenStack SDK
+        resources = conn.your_service.list_resources(
+            filters={'name': target_resource} if target_resource else {}
+        )
+        
+        for resource in resources:
+            results.append({
+                'name': resource.name,
+                'id': resource.id,
+                'status': resource.status,
+                'created_at': resource.created_at,
+                # Add your custom fields
+            })
+            
+    except Exception as e:
+        logger.error(f"Failed to get custom data: {e}")
+        return []
+        
+    return results
+```
+
+#### 2. **Create Your MCP Tool File**
+
+Create a new file `src/mcp_openstack_ops/tools/get_your_custom_analysis.py`:
+
+```python
+"""Tool implementation for get_your_custom_analysis."""
+
+import json
+from datetime import datetime
+from typing import Optional
+from ..functions import get_your_custom_data  # Import your helper function
+from ..mcp_main import (
+    logger,
+    mcp,
+)
+
+@mcp.tool()
+async def get_your_custom_analysis(limit: int = 50, target_name: Optional[str] = None) -> str:
+    """
+    [Tool Purpose]: Brief description of what your tool does
+    
+    [Exact Functionality]:
+    - Feature 1: Data aggregation and analysis
+    - Feature 2: Resource monitoring and insights
+    - Feature 3: Performance metrics and reporting
+    
+    [Required Use Cases]:
+    - When user asks "your specific analysis request"
+    - Your business-specific monitoring needs
+    
+    Args:
+        limit: Maximum results (1-100)
+        target_name: Target resource/service name
+    
+    Returns:
+        Formatted analysis results
+    """
+    try:
+        limit = max(1, min(limit, 100))  # Always validate input
+        
+        logger.info(f"Getting custom analysis, limit: {limit}, target: {target_name}")
+        
+        results = await get_your_custom_data(target_resource=target_name)
+        
+        if not results:
+            return f"No custom analysis data found" + (f" for '{target_name}'" if target_name else "")
+        
+        # Apply limit
+        results = results[:limit]
+        
+        # Format results as table
+        table_data = []
+        for item in results:
+            table_data.append({
+                'Name': item.get('name', 'N/A'),
+                'ID': item.get('id', 'N/A'),
+                'Status': item.get('status', 'N/A'),
+                'Created': item.get('created_at', 'N/A'),
+            })
+        
+        # Return formatted JSON
+        return json.dumps({
+            'title': f'Custom Analysis (Top {len(results)})',
+            'data': table_data,
+            'total_count': len(results),
+            'timestamp': datetime.now().isoformat()
+        }, indent=2)
+        
+    except Exception as e:
+        logger.error(f"Failed to get custom analysis: {e}")
+        return f"Error: {str(e)}"
+```
+
+#### 3. **For Modify Operations (Optional)**
+
+If your tool performs modify operations, use the `@conditional_tool` decorator instead:
+
+```python
+"""Tool implementation for set_your_custom_resource."""
+
+from ..mcp_main import (
+    conditional_tool,  # Use this instead of @mcp.tool()
+    handle_operation_result,
+    logger,
+)
+from ..functions import set_your_custom_resource
+
+@conditional_tool  # Only registers when ALLOW_MODIFY_OPERATIONS=true
+async def set_your_custom_resource(resource_name: str, action: str) -> str:
+    """
+    Manage your custom OpenStack resources.
+    
+    Use when user requests custom resource management.
+    """
+    try:
+        result = set_your_custom_resource(resource_name, action)
+        
+        return handle_operation_result(
+            result=result,
+            operation_name="Custom Resource Management",
+            details={
+                'Resource': resource_name,
+                'Action': action
+            }
+        )
+        
+    except Exception as e:
+        logger.error(f"Custom resource operation failed: {e}")
+        return f"Error: {str(e)}"
+```
+
+#### 4. **Update Prompt Template (Recommended)**
+
+Add your tool description to `src/mcp_openstack_ops/prompt_template.md` for better natural language recognition:
+
+```markdown
+### **Your Custom Analysis Tool**
+
+### X. **get_your_custom_analysis**
+**Purpose**: Brief description of what your tool does
+**Usage**: "Show me your custom analysis" or "Get custom analysis for resource_name"
+**Features**: Data aggregation, resource monitoring, performance metrics
+**Optional**: `target_name` parameter for specific resource analysis
+```
+
+#### 5. **Test Your Tool**
+
+```bash
+# Local testing
+./scripts/run-mcp-inspector-local.sh
+
+# Or with Docker
+docker-compose up -d
+docker-compose logs -f mcp-server
+
+# Test with natural language:
+# "Show me your custom analysis"
+# "Get custom analysis for target_name"
+```
+
+### Tool Registration System
+
+The MCP server uses automatic tool discovery. When you create a new file in `src/mcp_openstack_ops/tools/`, it's automatically registered through the `register_all_tools()` function in `tools/__init__.py`. No manual import registration needed!
+
+### Safety System
+
+- **Read-only tools**: Use `@mcp.tool()` - always available
+- **Modify tools**: Use `@conditional_tool` - only available when `ALLOW_MODIFY_OPERATIONS=true`
+- **Connection**: Always use `get_openstack_connection()` for OpenStack API access
+- **Project isolation**: All operations are automatically scoped to `OS_PROJECT_NAME`
+
+That's it! Your custom tool is ready to use with natural language queries.
+
+---
+
 ## License
 
 This project is licensed under the MIT License - see the LICENSE file for details.

{mcp_openstack_ops-3.2.2 → mcp_openstack_ops-3.2.3}/README.md

@@ -3,10 +3,15 @@
 > **MCP OpenStack Operations Server**: A comprehensive MCP (Model Context Protocol) server providing OpenStack project management and monitoring capabilities with built-in safety controls and single-project scope.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![Deploy to PyPI with tag](https://github.com/call518/MCP-OpenStack-Ops/actions/workflows/pypi-publish.yml/badge.svg)](https://github.com/call518/MCP-OpenStack-Ops/actions/workflows/pypi-publish.yml)
+![Python](https://img.shields.io/badge/Python-3776AB?style=flat&logo=python&logoColor=white)
+![Docker Pulls](https://img.shields.io/docker/pulls/call518/mcp-server-openstack-ops)
 [![smithery badge](https://smithery.ai/badge/@call518/mcp-openstack-ops)](https://smithery.ai/server/@call518/mcp-openstack-ops)
 [![BuyMeACoffee](https://raw.githubusercontent.com/pachadotdev/buymeacoffee-badges/main/bmc-donate-yellow.svg)](https://www.buymeacoffee.com/call518)
 
+[![Deploy to PyPI with tag](https://github.com/call518/MCP-OpenStack-Ops/actions/workflows/pypi-publish.yml/badge.svg)](https://github.com/call518/MCP-OpenStack-Ops/actions/workflows/pypi-publish.yml)
+![PyPI](https://img.shields.io/pypi/v/MCP-OpenStack-Ops?label=pypi%20package)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/MCP-OpenStack-Ops)
+
 ---
 
 ## Architecture & Internal (DeepWiki)
@@ -1013,6 +1018,200 @@ When authentication fails, the server returns:
 
 ---
 
+## 🚀 Adding Custom Tools
+
+This MCP server is designed for easy extensibility. Follow these steps to add your own custom tools:
+
+### Step-by-Step Guide
+
+#### 1. **Add Helper Functions (Optional)**
+
+Add reusable data functions to `src/mcp_openstack_ops/functions.py`:
+
+```python
+async def get_your_custom_data(target_resource: str = None) -> List[Dict[str, Any]]:
+    """Your custom data retrieval function."""
+    # Example implementation - adapt to your OpenStack service
+    conn = get_openstack_connection()
+    results = []
+    
+    try:
+        # Example: Custom query using OpenStack SDK
+        resources = conn.your_service.list_resources(
+            filters={'name': target_resource} if target_resource else {}
+        )
+        
+        for resource in resources:
+            results.append({
+                'name': resource.name,
+                'id': resource.id,
+                'status': resource.status,
+                'created_at': resource.created_at,
+                # Add your custom fields
+            })
+            
+    except Exception as e:
+        logger.error(f"Failed to get custom data: {e}")
+        return []
+        
+    return results
+```
+
+#### 2. **Create Your MCP Tool File**
+
+Create a new file `src/mcp_openstack_ops/tools/get_your_custom_analysis.py`:
+
+```python
+"""Tool implementation for get_your_custom_analysis."""
+
+import json
+from datetime import datetime
+from typing import Optional
+from ..functions import get_your_custom_data  # Import your helper function
+from ..mcp_main import (
+    logger,
+    mcp,
+)
+
+@mcp.tool()
+async def get_your_custom_analysis(limit: int = 50, target_name: Optional[str] = None) -> str:
+    """
+    [Tool Purpose]: Brief description of what your tool does
+    
+    [Exact Functionality]:
+    - Feature 1: Data aggregation and analysis
+    - Feature 2: Resource monitoring and insights
+    - Feature 3: Performance metrics and reporting
+    
+    [Required Use Cases]:
+    - When user asks "your specific analysis request"
+    - Your business-specific monitoring needs
+    
+    Args:
+        limit: Maximum results (1-100)
+        target_name: Target resource/service name
+    
+    Returns:
+        Formatted analysis results
+    """
+    try:
+        limit = max(1, min(limit, 100))  # Always validate input
+        
+        logger.info(f"Getting custom analysis, limit: {limit}, target: {target_name}")
+        
+        results = await get_your_custom_data(target_resource=target_name)
+        
+        if not results:
+            return f"No custom analysis data found" + (f" for '{target_name}'" if target_name else "")
+        
+        # Apply limit
+        results = results[:limit]
+        
+        # Format results as table
+        table_data = []
+        for item in results:
+            table_data.append({
+                'Name': item.get('name', 'N/A'),
+                'ID': item.get('id', 'N/A'),
+                'Status': item.get('status', 'N/A'),
+                'Created': item.get('created_at', 'N/A'),
+            })
+        
+        # Return formatted JSON
+        return json.dumps({
+            'title': f'Custom Analysis (Top {len(results)})',
+            'data': table_data,
+            'total_count': len(results),
+            'timestamp': datetime.now().isoformat()
+        }, indent=2)
+        
+    except Exception as e:
+        logger.error(f"Failed to get custom analysis: {e}")
+        return f"Error: {str(e)}"
+```
+
+#### 3. **For Modify Operations (Optional)**
+
+If your tool performs modify operations, use the `@conditional_tool` decorator instead:
+
+```python
+"""Tool implementation for set_your_custom_resource."""
+
+from ..mcp_main import (
+    conditional_tool,  # Use this instead of @mcp.tool()
+    handle_operation_result,
+    logger,
+)
+from ..functions import set_your_custom_resource
+
+@conditional_tool  # Only registers when ALLOW_MODIFY_OPERATIONS=true
+async def set_your_custom_resource(resource_name: str, action: str) -> str:
+    """
+    Manage your custom OpenStack resources.
+    
+    Use when user requests custom resource management.
+    """
+    try:
+        result = set_your_custom_resource(resource_name, action)
+        
+        return handle_operation_result(
+            result=result,
+            operation_name="Custom Resource Management",
+            details={
+                'Resource': resource_name,
+                'Action': action
+            }
+        )
+        
+    except Exception as e:
+        logger.error(f"Custom resource operation failed: {e}")
+        return f"Error: {str(e)}"
+```
+
+#### 4. **Update Prompt Template (Recommended)**
+
+Add your tool description to `src/mcp_openstack_ops/prompt_template.md` for better natural language recognition:
+
+```markdown
+### **Your Custom Analysis Tool**
+
+### X. **get_your_custom_analysis**
+**Purpose**: Brief description of what your tool does
+**Usage**: "Show me your custom analysis" or "Get custom analysis for resource_name"
+**Features**: Data aggregation, resource monitoring, performance metrics
+**Optional**: `target_name` parameter for specific resource analysis
+```
+
+#### 5. **Test Your Tool**
+
+```bash
+# Local testing
+./scripts/run-mcp-inspector-local.sh
+
+# Or with Docker
+docker-compose up -d
+docker-compose logs -f mcp-server
+
+# Test with natural language:
+# "Show me your custom analysis"
+# "Get custom analysis for target_name"
+```
+
+### Tool Registration System
+
+The MCP server uses automatic tool discovery. When you create a new file in `src/mcp_openstack_ops/tools/`, it's automatically registered through the `register_all_tools()` function in `tools/__init__.py`. No manual import registration needed!
+
+### Safety System
+
+- **Read-only tools**: Use `@mcp.tool()` - always available
+- **Modify tools**: Use `@conditional_tool` - only available when `ALLOW_MODIFY_OPERATIONS=true`
+- **Connection**: Always use `get_openstack_connection()` for OpenStack API access
+- **Project isolation**: All operations are automatically scoped to `OS_PROJECT_NAME`
+
+That's it! Your custom tool is ready to use with natural language queries.
+
+---
+
 ## License
 
 This project is licensed under the MIT License - see the LICENSE file for details.

{mcp_openstack_ops-3.2.2 → mcp_openstack_ops-3.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-openstack-ops"
-version = "3.2.2"
+version = "3.2.3"
 description = "OpenStack operations automation MCP server"
 readme = "README.md"
 requires-python = ">=3.12"

{mcp_openstack_ops-3.2.2 → mcp_openstack_ops-3.2.3/src/mcp_openstack_ops.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-openstack-ops
-Version: 3.2.2
+Version: 3.2.3
 Summary: OpenStack operations automation MCP server
 Author-email: JungJungIn <call518@gmail.com>
 Requires-Python: >=3.12
@@ -19,10 +19,15 @@ Dynamic: license-file
 > **MCP OpenStack Operations Server**: A comprehensive MCP (Model Context Protocol) server providing OpenStack project management and monitoring capabilities with built-in safety controls and single-project scope.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![Deploy to PyPI with tag](https://github.com/call518/MCP-OpenStack-Ops/actions/workflows/pypi-publish.yml/badge.svg)](https://github.com/call518/MCP-OpenStack-Ops/actions/workflows/pypi-publish.yml)
+![Python](https://img.shields.io/badge/Python-3776AB?style=flat&logo=python&logoColor=white)
+![Docker Pulls](https://img.shields.io/docker/pulls/call518/mcp-server-openstack-ops)
 [![smithery badge](https://smithery.ai/badge/@call518/mcp-openstack-ops)](https://smithery.ai/server/@call518/mcp-openstack-ops)
 [![BuyMeACoffee](https://raw.githubusercontent.com/pachadotdev/buymeacoffee-badges/main/bmc-donate-yellow.svg)](https://www.buymeacoffee.com/call518)
 
+[![Deploy to PyPI with tag](https://github.com/call518/MCP-OpenStack-Ops/actions/workflows/pypi-publish.yml/badge.svg)](https://github.com/call518/MCP-OpenStack-Ops/actions/workflows/pypi-publish.yml)
+![PyPI](https://img.shields.io/pypi/v/MCP-OpenStack-Ops?label=pypi%20package)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/MCP-OpenStack-Ops)
+
 ---
 
 ## Architecture & Internal (DeepWiki)
@@ -1029,6 +1034,200 @@ When authentication fails, the server returns:
 
 ---
 
+## 🚀 Adding Custom Tools
+
+This MCP server is designed for easy extensibility. Follow these steps to add your own custom tools:
+
+### Step-by-Step Guide
+
+#### 1. **Add Helper Functions (Optional)**
+
+Add reusable data functions to `src/mcp_openstack_ops/functions.py`:
+
+```python
+async def get_your_custom_data(target_resource: str = None) -> List[Dict[str, Any]]:
+    """Your custom data retrieval function."""
+    # Example implementation - adapt to your OpenStack service
+    conn = get_openstack_connection()
+    results = []
+    
+    try:
+        # Example: Custom query using OpenStack SDK
+        resources = conn.your_service.list_resources(
+            filters={'name': target_resource} if target_resource else {}
+        )
+        
+        for resource in resources:
+            results.append({
+                'name': resource.name,
+                'id': resource.id,
+                'status': resource.status,
+                'created_at': resource.created_at,
+                # Add your custom fields
+            })
+            
+    except Exception as e:
+        logger.error(f"Failed to get custom data: {e}")
+        return []
+        
+    return results
+```
+
+#### 2. **Create Your MCP Tool File**
+
+Create a new file `src/mcp_openstack_ops/tools/get_your_custom_analysis.py`:
+
+```python
+"""Tool implementation for get_your_custom_analysis."""
+
+import json
+from datetime import datetime
+from typing import Optional
+from ..functions import get_your_custom_data  # Import your helper function
+from ..mcp_main import (
+    logger,
+    mcp,
+)
+
+@mcp.tool()
+async def get_your_custom_analysis(limit: int = 50, target_name: Optional[str] = None) -> str:
+    """
+    [Tool Purpose]: Brief description of what your tool does
+    
+    [Exact Functionality]:
+    - Feature 1: Data aggregation and analysis
+    - Feature 2: Resource monitoring and insights
+    - Feature 3: Performance metrics and reporting
+    
+    [Required Use Cases]:
+    - When user asks "your specific analysis request"
+    - Your business-specific monitoring needs
+    
+    Args:
+        limit: Maximum results (1-100)
+        target_name: Target resource/service name
+    
+    Returns:
+        Formatted analysis results
+    """
+    try:
+        limit = max(1, min(limit, 100))  # Always validate input
+        
+        logger.info(f"Getting custom analysis, limit: {limit}, target: {target_name}")
+        
+        results = await get_your_custom_data(target_resource=target_name)
+        
+        if not results:
+            return f"No custom analysis data found" + (f" for '{target_name}'" if target_name else "")
+        
+        # Apply limit
+        results = results[:limit]
+        
+        # Format results as table
+        table_data = []
+        for item in results:
+            table_data.append({
+                'Name': item.get('name', 'N/A'),
+                'ID': item.get('id', 'N/A'),
+                'Status': item.get('status', 'N/A'),
+                'Created': item.get('created_at', 'N/A'),
+            })
+        
+        # Return formatted JSON
+        return json.dumps({
+            'title': f'Custom Analysis (Top {len(results)})',
+            'data': table_data,
+            'total_count': len(results),
+            'timestamp': datetime.now().isoformat()
+        }, indent=2)
+        
+    except Exception as e:
+        logger.error(f"Failed to get custom analysis: {e}")
+        return f"Error: {str(e)}"
+```
+
+#### 3. **For Modify Operations (Optional)**
+
+If your tool performs modify operations, use the `@conditional_tool` decorator instead:
+
+```python
+"""Tool implementation for set_your_custom_resource."""
+
+from ..mcp_main import (
+    conditional_tool,  # Use this instead of @mcp.tool()
+    handle_operation_result,
+    logger,
+)
+from ..functions import set_your_custom_resource
+
+@conditional_tool  # Only registers when ALLOW_MODIFY_OPERATIONS=true
+async def set_your_custom_resource(resource_name: str, action: str) -> str:
+    """
+    Manage your custom OpenStack resources.
+    
+    Use when user requests custom resource management.
+    """
+    try:
+        result = set_your_custom_resource(resource_name, action)
+        
+        return handle_operation_result(
+            result=result,
+            operation_name="Custom Resource Management",
+            details={
+                'Resource': resource_name,
+                'Action': action
+            }
+        )
+        
+    except Exception as e:
+        logger.error(f"Custom resource operation failed: {e}")
+        return f"Error: {str(e)}"
+```
+
+#### 4. **Update Prompt Template (Recommended)**
+
+Add your tool description to `src/mcp_openstack_ops/prompt_template.md` for better natural language recognition:
+
+```markdown
+### **Your Custom Analysis Tool**
+
+### X. **get_your_custom_analysis**
+**Purpose**: Brief description of what your tool does
+**Usage**: "Show me your custom analysis" or "Get custom analysis for resource_name"
+**Features**: Data aggregation, resource monitoring, performance metrics
+**Optional**: `target_name` parameter for specific resource analysis
+```
+
+#### 5. **Test Your Tool**
+
+```bash
+# Local testing
+./scripts/run-mcp-inspector-local.sh
+
+# Or with Docker
+docker-compose up -d
+docker-compose logs -f mcp-server
+
+# Test with natural language:
+# "Show me your custom analysis"
+# "Get custom analysis for target_name"
+```
+
+### Tool Registration System
+
+The MCP server uses automatic tool discovery. When you create a new file in `src/mcp_openstack_ops/tools/`, it's automatically registered through the `register_all_tools()` function in `tools/__init__.py`. No manual import registration needed!
+
+### Safety System
+
+- **Read-only tools**: Use `@mcp.tool()` - always available
+- **Modify tools**: Use `@conditional_tool` - only available when `ALLOW_MODIFY_OPERATIONS=true`
+- **Connection**: Always use `get_openstack_connection()` for OpenStack API access
+- **Project isolation**: All operations are automatically scoped to `OS_PROJECT_NAME`
+
+That's it! Your custom tool is ready to use with natural language queries.
+
+---
+
 ## License
 
 This project is licensed under the MIT License - see the LICENSE file for details.