mcp-openstack-ops 3.4.9__tar.gz → 3.5.1__tar.gz

mcp_openstack_ops-3.5.1/.env.example

@@ -0,0 +1,73 @@
+# MCP Server Configuration Template
+# Copy this file to .env and modify values as needed
+
+# Logging level
+MCP_LOG_LEVEL=INFO
+
+# Safety Control - Allow OpenStack state modification operations
+# Set to true to enable modification operations (create, delete, update)
+# Set to false to allow only read-only operations (list, get, show)
+ALLOW_MODIFY_OPERATIONS=false
+
+# Python module path for Docker
+PYTHONPATH=/app/src
+
+# Transport configuration
+FASTMCP_TYPE=streamable-http
+
+# HTTP Transport settings (used only when FASTMCP_TYPE=streamable-http)
+FASTMCP_HOST=0.0.0.0
+FASTMCP_PORT=8000
+
+# (Optional) Enable authentication for streamable-http mode
+# Recommended for production environments
+REMOTE_AUTH_ENABLE=false
+REMOTE_SECRET_KEY=your-secure-secret-key-here
+
+# OpenStack API Environment Variables Template
+# PROJECT ISOLATION SECURITY: All operations are 100% scoped to specified project
+# Enhanced multi-layer security prevents cross-tenant access and ensures complete isolation
+OS_PROJECT_DOMAIN_NAME=Default
+OS_USER_DOMAIN_NAME=Default
+
+# CRITICAL SECURITY PARAMETER: All operations are scoped to this project only
+# Enhanced project isolation with ownership validation and secure resource lookup
+# For multi-project management, deploy multiple MCP servers with different OS_PROJECT_NAME values
+# NEVER modify resources in other projects - complete tenant isolation guaranteed
+OS_PROJECT_NAME=your_project_name
+OS_TENANT_NAME=your_tenant_name
+OS_USERNAME=your_username
+OS_PASSWORD=your_password
+OS_AUTH_HOST=your-openstack-host
+OS_INTERFACE=internal
+OS_ENDPOINT_TYPE=internalURL
+OS_IDENTITY_API_VERSION=3
+OS_REGION_NAME=RegionOne
+OS_AUTH_PLUGIN=password
+
+# OpenStack Connection Protocol (http or https)
+# Use 'https' for production environments with SSL/TLS enabled
+# When using https, set OS_CACERT to your CA certificate path
+# If OS_CACERT is not set with https, SSL verification will be disabled (insecure)
+OS_AUTH_PROTOCOL=http
+
+# (Optional) SSL CA Certificate for HTTPS connections
+# Required for secure HTTPS connections to OpenStack API
+# Example: OS_CACERT=/etc/ssl/certs/openstack-ca.pem
+# OS_CACERT=
+
+# OpenStack Service Port Configuration
+# These ports can be customized to match your OpenStack deployment
+OS_AUTH_PORT=5000
+OS_COMPUTE_PORT=8774
+OS_NETWORK_PORT=9696
+OS_VOLUME_PORT=8776
+OS_IMAGE_PORT=9292
+OS_PLACEMENT_PORT=8780
+OS_HEAT_STACK_PORT=8004
+OS_HEAT_STACK_CFN_PORT=8000
+
+# Docker Port Mappings
+DOCKER_EXTERNAL_PORT_OPENWEBUI=3000
+DOCKER_EXTERNAL_PORT_MCP_SERVER=8000
+DOCKER_EXTERNAL_PORT_MCPO_PROXY=8080

mcp_openstack_ops-3.5.1/.env.test

@@ -0,0 +1 @@
+ALLOW_MODIFY_OPERATIONS=true

mcp_openstack_ops-3.5.1/.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+buy_me_a_coffee: call518

mcp_openstack_ops-3.5.1/.github/copilot-instructions.md

@@ -0,0 +1,153 @@
+# GitHub Copilot Instructions
+
+## 🚫 CRITICAL RESTRICTIONS - ALWAYS ENFORCE
+
+### **Never Execute These Operations Directly:**
+- **Git operations**: Never run `git add`, `git commit`, `git push`, `git pull`, `git tag`, or any Git commands
+- **Docker operations**: Never run `docker build`, `docker run`, `docker-compose up/down`, `docker push`, or any Docker commands
+- **Instead**: Always ask the user to execute these commands manually
+
+### **Python Execution Requirements:**
+- **MANDATORY**: Always use `.venv/bin/python` for all Python execution
+- **MANDATORY**: Always use `.venv/bin/pip` for all package management
+- **NEVER use**: `python`, `python3`, `/usr/bin/python`, `pip`, `pip3`, or system Python/pip
+- **Example**: Use `.venv/bin/python -m mcp_openstack_ops` instead of `python -m mcp_openstack_ops`
+- **Example**: Use `.venv/bin/pip install package` instead of `pip install package`
+
+### **MCP Tool Safety Control Requirements:**
+- **MANDATORY**: When adding new MCP tools with modify operations, always use `@conditional_tool` decorator
+- **MANDATORY**: Verify that ALLOW_MODIFY_OPERATIONS=false properly hides modify tools from registration
+- **NEVER use**: `@mcp.tool()` for operations that can modify/delete OpenStack resources
+- **Always test**: Tool visibility with both `ALLOW_MODIFY_OPERATIONS=true` and `ALLOW_MODIFY_OPERATIONS=false`
+- **Pattern**: Read-only tools use `@mcp.tool()`, modify tools use `@conditional_tool`
+
+---
+
+## Architecture Overview
+This is an **MCP (Model Context Protocol) Server for OpenStack Operations** - a Python service providing real-time OpenStack cluster management through 24+ tools. The architecture follows a layered pattern:
+
+- **`src/mcp_openstack_ops/functions.py`** (3000+ lines): Core OpenStack SDK operations with connection caching
+- **`src/mcp_openstack_ops/mcp_main.py`** (1400+ lines): FastMCP tool definitions and conditional safety system
+- **`src/mcp_openstack_ops/prompt_template.md`**: AI assistant behavior guide with tool patterns
+
+## Critical Safety System
+The codebase implements a **conditional tool registration pattern** via `ALLOW_MODIFY_OPERATIONS` environment variable:
+
+```python
+@conditional_tool  # Only registers when ALLOW_MODIFY_OPERATIONS=true
+async def set_instance(instance_name: str, action: str) -> str:
+```
+
+vs.
+
+```python
+@mcp.tool()  # Always available (read-only operations)
+async def get_cluster_status() -> str:
+```
+
+**Never bypass this safety system** - it prevents destructive operations in production.
+
+## Environment Configuration Patterns
+Connection management uses **proxy-based routing** with service-specific ports:
+
+```bash
+# Required for OpenStack connection
+OS_AUTH_HOST=192.168.35.2
+OS_AUTH_PORT=5555
+
+# Service-specific ports (Heat Stack naming convention)
+OS_HEAT_STACK_PORT=8004
+OS_HEAT_STACK_CFN_PORT=18888
+```
+
+## Key Development Workflows
+
+### Testing MCP Server
+```bash
+# REQUIRED: Use virtual environment Python only
+.venv/bin/python -m mcp_openstack_ops --stdio
+
+# Connection validation
+.venv/bin/python -c "from mcp_openstack_ops.functions import get_openstack_connection; print('OK')"
+
+# NEVER use system Python
+# ❌ python -m mcp_openstack_ops
+# ❌ python3 -m mcp_openstack_ops
+```
+
+### Adding New OpenStack Services
+1. Add core function to `functions.py` with connection caching pattern
+2. Create MCP tool wrapper in `mcp_main.py` (use `@conditional_tool` for modify operations)
+3. Update `prompt_template.md` with tool patterns and decision flows
+4. Add environment variables for service ports if needed
+
+## Connection Management Pattern
+Global connection caching with automatic retry:
+
+```python
+_connection_cache = None
+
+def get_openstack_connection():
+    global _connection_cache
+    if _connection_cache is not None:
+        try:
+            _connection_cache.identity.get_token()  # Test validity
+            return _connection_cache
+        except Exception:
+            _connection_cache = None  # Reset on failure
+```
+
+## Resource Monitoring Conventions
+Always distinguish **physical vs. virtual resources** in monitoring results:
+- `pCPU` = physical CPU cores (hypervisor hardware)
+- `vCPU` = virtual CPU allocation (project quota)
+- Use separate table rows, never combine in single row
+
+## Function Naming Conventions
+- Core functions: `get_*()`, `set_*()`, `search_*()`, `monitor_*()`  
+- Heat-specific: `get_heat_stacks()`, `set_heat_stack()` (not generic `stack`)
+- Load Balancer: `get_load_balancer_*()`, `set_load_balancer*()` (Octavia operations)
+- MCP tools: Must exactly match underlying function names
+
+## Docker Multi-Service Architecture
+The `docker-compose.yml` orchestrates three services:
+- **mcp-server**: Main FastMCP server (port via `DOCKER_EXTERNAL_PORT_MCP_SERVER`)
+- **mcpo-proxy**: HTTP proxy for web clients  
+- **open-webui**: Chat interface for testing
+
+**Critical**: MCP server ports must align across `.env`, `docker-compose.yml`, and `mcp-config.json.http`.
+
+## Error Handling Pattern
+All OpenStack operations use consistent error handling:
+
+```python
+try:
+    conn = get_openstack_connection()
+    # OpenStack SDK operations
+    return result_data
+except Exception as e:
+    logger.error(f"Operation failed: {e}")
+    return {"error": str(e), "success": False}
+```
+
+## Never Execute Directly
+- **Git operations**: `git add`, `commit`, `push`, `pull`, `tag` - ask user to run manually
+- **Docker operations**: `docker build`, `docker-compose up/down`, `docker push` - ask user to run manually  
+- **Package management**: `uv add`, `pip install`, `uv sync` - ask user to run manually
+- **Python execution**: Only use `.venv/bin/python`, never system Python
+- **Pip commands**: Only use `.venv/bin/pip`, never system pip
+
+## Pagination Support
+Large-scale environments require pagination in data-heavy functions:
+
+```python
+def get_instance_details(instance_names=None, limit=50, offset=0, include_all=False):
+```
+
+Default limit: 50, max: 200, always include pagination metadata in responses.
+
+## Transport Modes
+- **stdio**: Direct pipe communication via `mcp-config.json.stdio`
+- **streamable-http**: Web API via `mcp-config.json.http` with optional authentication
+
+Both modes share the same environment variable structure but different client configurations.

mcp_openstack_ops-3.5.1/.github/dependabot.yml

@@ -0,0 +1,58 @@
+version: 2
+updates:
+  # Python dependencies (pyproject.toml, requirements files)
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "Asia/Seoul"
+    open-pull-requests-limit: 5
+    assignees:
+      - "call518"
+    commit-message:
+      prefix: "deps"
+      include: "scope"
+    labels:
+      - "dependencies"
+      - "python"
+    ignore:
+      - dependency-name: "fastmcp"
+        update-types: ["version-update:semver-major"]
+
+  # GitHub Actions workflow dependencies
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:30"
+      timezone: "Asia/Seoul"
+    open-pull-requests-limit: 3
+    assignees:
+      - "call518"
+    commit-message:
+      prefix: "ci"
+      include: "scope"
+    labels:
+      - "dependencies"
+      - "github-actions"
+
+  # Docker dependencies (Dockerfile, docker-compose.yml)
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "10:00"
+      timezone: "Asia/Seoul"
+    open-pull-requests-limit: 3
+    assignees:
+      - "call518"
+    commit-message:
+      prefix: "docker"
+      include: "scope"
+    labels:
+      - "dependencies"
+      - "docker"

mcp_openstack_ops-3.5.1/.github/workflows/pypi-publish.yml

@@ -0,0 +1,73 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: Publish to PyPI on tag
+
+on:
+  push:
+    tags: ["*"]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12.x"
+      - name: Install build tool
+        run: pip install --upgrade build
+      - name: Build distributions
+        run: python -m build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish-to-testpypi:
+    name: Publish to TestPyPI
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      id-token: write
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/mcp-openstack-ops
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    needs: build
+    #needs: publish-to-testpypi
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/project/mcp-openstack-ops
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://upload.pypi.org/legacy/

mcp_openstack_ops-3.5.1/.gitignore

@@ -0,0 +1,20 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Environment files
+.env
+
+**/__pycache__/
+**/.pytest_cache/
+
+.vscode*
+#.github/copilot-instructions.md
+*.swp

mcp_openstack_ops-3.5.1/.gitleaks.toml

@@ -0,0 +1,11 @@
+title = "README REDACTED 허용 (extend)"
+
+[extend]
+useDefault = true  # 기본 내장 rules 로드
+
+[[allowlists]]
+description = "README.md generic-api-key 예시"
+paths = ["README\\.md"]
+ruleIDs = ["generic-api-key"]
+regexes = ['''REDACTED''']
+regexTarget = "secret"

mcp_openstack_ops-3.5.1/.pre-commit-config.yaml

@@ -0,0 +1,5 @@
+repos:
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.0
+    hooks:
+      - id: gitleaks

mcp_openstack_ops-3.5.1/.python-version

@@ -0,0 +1 @@
+3.12

mcp_openstack_ops-3.5.1/Dockerfile.MCP-Server

@@ -0,0 +1,20 @@
+FROM rockylinux:9.3
+
+ARG PYTHON_VERSION=3.12
+
+WORKDIR /app
+
+RUN dnf install -y epel-release \
+        && dnf install -y python${PYTHON_VERSION} python${PYTHON_VERSION}-pip git procps-ng lsof telnet screen iputils nmap-ncat \
+        && dnf clean all \
+        && update-alternatives --install /usr/bin/python python /usr/bin/python${PYTHON_VERSION} 1000 --slave /usr/bin/pip pip /usr/bin/pip${PYTHON_VERSION}
+
+RUN pip install \
+        'uv>=0.8.5' \
+        'mcpo>=0.0.17' \
+        'fastmcp>=2.12.4' \
+        'aiohttp>=3.12.0' \
+        'openstacksdk>=4.1.0,<=4.9.0' \
+        'python-dotenv>=1.1.1'
+
+CMD ["/bin/bash", "/app/scripts/mcp-server-docker-cmd.sh"]

mcp_openstack_ops-3.5.1/Dockerfile.MCPO-Proxy

@@ -0,0 +1,20 @@
+FROM rockylinux:9.3
+
+ARG PYTHON_VERSION=3.12
+
+RUN mkdir -p /app/config
+
+WORKDIR /app
+
+RUN dnf install -y epel-release \
+        && dnf install -y python${PYTHON_VERSION} python${PYTHON_VERSION}-pip git procps-ng lsof telnet screen iputils \
+        && dnf clean all \
+        && update-alternatives --install /usr/bin/python python /usr/bin/python${PYTHON_VERSION} 1000 --slave /usr/bin/pip pip /usr/bin/pip${PYTHON_VERSION}
+
+RUN pip install \
+        'uv>=0.8.5' \
+        'mcpo>=0.0.17' \
+        'fastmcp>=2.12.4' \
+        'aiohttp>=3.12.0'
+
+CMD ["mcpo", "--host", "0.0.0.0", "--port", "8000", "--config", "/app/config/mcp-config.json", "--hot-reload"]

{mcp_openstack_ops-3.4.9/src/mcp_openstack_ops.egg-info → mcp_openstack_ops-3.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-openstack-ops
-Version: 3.4.9
+Version: 3.5.1
 Summary: OpenStack operations automation MCP server
 Author-email: JungJungIn <call518@gmail.com>
 Requires-Python: >=3.12
@@ -9,6 +9,8 @@ License-File: LICENSE
 Requires-Dist: fastmcp>=2.12.3
 Requires-Dist: openstacksdk<=4.11.0,>=4.1.0
 Requires-Dist: python-dotenv>=1.1.1
+Requires-Dist: setuptools-scm>=10.0.5
+Requires-Dist: pre-commit>=4.6.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
@@ -21,7 +23,6 @@ Dynamic: license-file
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 ![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)

{mcp_openstack_ops-3.4.9 → mcp_openstack_ops-3.5.1}/README.md

@@ -5,7 +5,6 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 ![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)

mcp_openstack_ops-3.5.1/build-mcp-server-docker-image.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+set -eo pipefail
+
+Dockerfile_PATH="./Dockerfile.MCP-Server"
+IMAGE_NAME="call518/mcp-server-openstack-ops"
+
+echo "=== Building Docker image Name: ${IMAGE_NAME} ==="
+
+VERSION="1.0.3"
+TAGs="latest"
+
+# Build once with version tag
+docker build -t ${IMAGE_NAME}:${VERSION} -f ${Dockerfile_PATH} .
+
+# Tag as latest
+for TAG in ${TAGs}
+do
+    docker tag ${IMAGE_NAME}:${VERSION} ${IMAGE_NAME}:${TAG}
+done
+
+echo
+
+read -p "Do you want to push the images to Docker Hub? (y/N): " answer
+if [[ "$answer" == "y" || "$answer" == "Y" ]]; then
+    echo "Pushing version ${VERSION}..."
+    docker push ${IMAGE_NAME}:${VERSION}
+    
+    echo "Pushing latest tag..."
+    for TAG in ${TAGs}
+    do
+        docker push ${IMAGE_NAME}:${TAG}
+    done
+fi

mcp_openstack_ops-3.5.1/build-mcpo-server-docker-image.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+set -eo pipefail
+
+Dockerfile_PATH="./Dockerfile.MCPO-Proxy"
+IMAGE_NAME="call518/mcpo-proxy-openstack-ops"
+
+echo "=== Building Docker image Name: ${IMAGE_NAME} ==="
+
+VERSION="1.0.2"
+TAGs="latest"
+
+# Build once with version tag
+docker build -t ${IMAGE_NAME}:${VERSION} -f ${Dockerfile_PATH} .
+
+# Tag as latest
+for TAG in ${TAGs}
+do
+    docker tag ${IMAGE_NAME}:${VERSION} ${IMAGE_NAME}:${TAG}
+done
+
+echo
+
+read -p "Do you want to push the images to Docker Hub? (y/N): " answer
+if [[ "$answer" == "y" || "$answer" == "Y" ]]; then
+    echo "Pushing version ${VERSION}..."
+    docker push ${IMAGE_NAME}:${VERSION}
+    
+    echo "Pushing latest tag..."
+    for TAG in ${TAGs}
+    do
+        docker push ${IMAGE_NAME}:${TAG}
+    done
+fi