MCP Openstack Ops

MCP OpenStack运维

MCP OpenStack操作服务器：一个全面的MCP（模型上下文协议）服务器，提供OpenStack项目管理和监控功能，具有内置的安全控制和单个项目范围。




______________________________________________________________________

建筑与内部（DeepWiki）


______________________________________________________________________

特性

• ✅ 项目范围操作：每个工具都强制执行配置 OS_PROJECT_NAME，验证资源所有权，以便操作保持在单个租户内。
• ✅ 安全防护写入：修改(set_*)工具仅在以下情况下注册 ALLOW_MODIFY_OPERATIONS=true，保持默认部署的只读性和可审计性。
• ✅ 90+专用工具：广泛覆盖计算、网络、存储、映像、身份、Heat和Octavia负载平衡任务，所有这些任务都受当前项目的限制。
• ✅ 批量和筛选操作：实例、卷、网络、映像、快照和密钥对管理器接受逗号分隔的目标或筛选条件，以有意编排批量更改。
• ✅ 行动后反馈和异步指导：突变工具重用共享结果处理程序，该处理程序添加表情符号状态检查、异步计时注释和后续验证命令。
• ✅ 监控和使用洞察: get_service_status, get_resource_monitoring, get_usage_statistics，以及活动项目的配额工具表面服务可用性、利用率和容量。
• ✅ 统一实例查询：The get_instance 该工具通过分页和摘要/详细模式整合了名称、ID、状态和自由形式的搜索路径。
• ✅ 服务器洞察和审计跟踪：专用工具公开服务器事件、管理程序详细信息、可用区域、配额和资源所有权，以加快诊断速度。
• ✅ 负载均衡器管理：Octavia工具涵盖了具有相同安全门的监听器、池、成员、健康监测器、口味、配额和双耳罐操作。
• ✅ 连接和部署灵活性：连接缓存、可配置服务端点、Docker打包，以及两者兼而有之 stdio/streamable-http 传输支持代理/堡垒和多项目设置。

⚠️ 兼容性通知：此MCP服务器是为以下目的开发和优化的 OpenStack环氧树脂（2025.1） 作为主要目标环境。然而，它与大多数现代OpenStack版本（达尔马提亚、卡拉卡尔、山猫等）兼容，因为大多数API在版本之间保持一致。只有少数特定的API端点可能需要进行调整，以与旧版本完全兼容。 🚧 即将推出：动态多版本OpenStack API兼容性正在积极开发中，并将在即将发布的版本中提供，自动为所有主要的OpenStack部署提供无缝支持。

🔧 OpenStackSDK旧版本定制

官方支持的版本：

• ✅ 开源云平台 环氧树脂（2025.1） -经过全面测试
• ✅ 开源云平台 达尔马提亚犬（2024.2） -经过全面测试

对于较旧的OpenStack版本 （Wallaby、Caracal、Bobcat等），您可能需要自定义OpenStackSDK版本以匹配您的环境。必须更改SDK版本 文件:

第一步：修改 Dockerfile.MCP-Server

RUN pip install \
        'uv>=0.8.5' \
        'mcpo>=0.0.17' \
        'fastmcp>=2.12.3' \
        'aiohttp>=3.12.0' \
        'openstacksdk==3.1.1' \  # ← Change to your required version (e.g., 3.1.1 for Wallaby)
        'python-dotenv>=1.0.0'

第二步：修改 pyproject.toml

dependencies = [
    "fastmcp>=2.12.3",
    "openstacksdk==3.1.1",  # ← Must match Dockerfile version
    "python-dotenv>=1.1.1",
    # ... other dependencies
]

步骤3：重建Docker镜像

docker-compose build --no-cache mcp-server
docker-compose up -d

OpenStackSDK版本参考：

⚠️ 重要：两者都有 Dockerfile.MCP-Server 和 pyproject.toml 必须有 相同版本 以避免容器运行时发生依赖冲突。

______________________________________________________________________

截图

OpenStack仪表板（环氧树脂2025.1）

OpenStack Dashboard (Epoxy 2025.1)

MCP查询示例-群集状态

Example Cluster Status

______________________________________________________________________

🆕 最新增强功能（v1.x）

批量操作和基于过滤器的目标定位

革命性的资源管理方法，实现一步式操作：

# Traditional approach (multiple steps):
1. search_instances("test") → get list
2. set_instance("vm1", "stop") → stop individually  
3. set_instance("vm2", "stop") → stop individually

# NEW enhanced approach (single step):
set_instance(action="stop", name_contains="test")  # ✨ Stops ALL instances containing "test"

具有增强功能的支持工具：

• set_instance：具有过滤功能的批量生命周期管理（名称_内容、状态、风味_内容、图像_内容）
• set_volume：具有过滤功能的批量卷操作（名称_内容、状态、大小过滤）
• set_image：具有过滤功能的批量图像管理（name_contains、status）
• set_networks：具有过滤功能的批量网络操作（name_contains、status）
• set_keypair：带过滤的批量密钥对管理（name_contains）
• set_snapshot：具有筛选功能的批量快照操作（name_contains、status）

输入格式灵活性：

# Single resource
resource_names="vm1"

# Multiple resources (comma-separated)
resource_names="vm1,vm2,vm3"

# JSON array format
resource_names='["vm1", "vm2", "vm3"]'

# Filter-based (automatic target identification)
name_contains="test", status="ACTIVE"

行动后状态验证

现在，每项操作都会通过视觉指示器提供即时反馈：

✅ Bulk Instance Management - Action: stop
📊 Total instances: 3
✅ Successes: 2
❌ Failures: 1

Post-Action Status:
🟢 test-vm-1: SHUTOFF  
🟢 test-vm-2: SHUTOFF
🔴 test-vm-3: ERROR

统一资源查询

新合并 get_instance 该工具取代了多个单独的工具：

• ❌ 老的 get_instance_details, get_instance_info, get_instance_status, get_instance_network_info
• ✅ 新 get_instance(instance_names="vm1,vm2") -单一工具，全面信息

______________________________________________________________________

📊 OpenStack CLI与MCP工具映射

按类别详细映射

1. 🖥️ 计算（Nova）

2. 🌐 网络（中子）

3. 💾 储存（煤渣）

4. 🖼️ 图片（一瞥）

5. 👥 身份（Keystone）

6. 🔥 编排（热）

7. ⚖️ 负载平衡器（Octavia）

8. 📊 监控和记录

9. 📏 使用和配额

______________________________________________________________________

快速开始

💡 需要OpenStack集群进行测试吗？\ 查看此综合指南： 教程：安装OpenStack多节点集群/w Kolla Ansible（环氧树脂/达尔马提亚）\ 非常适合设置测试环境来探索MCP OpenStack Ops功能。

Flow Diagram of Quickstart/Tutorial

1.环境设置

# Clone and navigate to project
cd MCP-OpenStack-Ops

# Install dependencies
uv sync

# Configure environment
cp .env.example .env
# Edit .env with your OpenStack credentials

环境配置

配置您的 .env 带有OpenStack凭据的文件：

# OpenStack Authentication (required)
OS_AUTH_HOST=your-openstack-host
OS_AUTH_PORT=5000
OS_AUTH_PROTOCOL=http  # Use 'https' for production with SSL/TLS
# OS_CACERT=/etc/ssl/certs/openstack-ca.pem  # Required for HTTPS (optional for HTTP)
OS_IDENTITY_API_VERSION=3
OS_USERNAME=your-username
OS_PASSWORD=your-password
OS_PROJECT_NAME=your-project
OS_PROJECT_DOMAIN_NAME=default
OS_USER_DOMAIN_NAME=default
OS_REGION_NAME=RegionOne

# OpenStack Service Ports (customizable)
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

# MCP Server Configuration (optional)
MCP_LOG_LEVEL=INFO
ALLOW_MODIFY_OPERATIONS=false
FASTMCP_TYPE=stdio
FASTMCP_HOST=127.0.0.1
FASTMCP_PORT=8080

生产环境的HTTPS配置

对于使用SSL/TLS的安全OpenStack部署：

# Enable HTTPS protocol
OS_AUTH_PROTOCOL=https
OS_AUTH_HOST=your-secure-openstack-host
OS_AUTH_PORT=13000  # Your HTTPS Keystone port

# SSL Certificate Configuration
# Option 1: Use custom CA certificate (recommended for production)
OS_CACERT=/etc/ssl/certs/openstack-ca.pem

# Option 2: Skip CA certificate (SSL verification disabled - insecure)
# Just omit OS_CACERT - the server will warn you about insecure connection

# Docker: Mount CA certificate into container
# Add to docker-compose.yml volumes:
#   - /path/to/your/ca-cert.pem:/etc/ssl/certs/openstack-ca.pem:ro

协议配置说明：

• OS_AUTH_PROTOCOL=http：用于本地开发或仅支持HTTP的OpenStack部署
• OS_AUTH_PROTOCOL=https：用于启用SSL/TLS的生产环境
• 什么时候 https 未设置 OS_CACERT，SSL验证已禁用（不安全但功能正常）
• 为了安全的生产部署，始终提供 OS_CACERT 使用您的CA证书路径

2.运行服务器

# Start all services
docker-compose up -d

# Check logs
docker-compose logs mcp-server
docker-compose logs mcpo-proxy

容器架构:

• mcp服务器：带工具的OpenStack MCP服务器
• mcpo代理：OpenAPI（REST-API）
• 打开webui：用于测试和交互的Web界面

📌 备注：Web UI配置说明基于OpenWebUI v0.6.22。菜单位置和设置在较新版本中可能有所不同。

服务URL-Docker内部:

• MCP服务器： localhost:8080 （HTTP传输）
• MCPO代理： localhost:8000 （OpenStack API代理）
• 打开WebUI： localhost:3000 （Web界面）

服务URL-Docker外部:

• MCP服务器： host.docker.internal:18005 （HTTP传输）
• MCPO代理： host.docker.internal:8005 （OpenStack API代理）
• 打开WebUI： host.docker.internal:3005 （Web界面）

用于Claude桌面集成

添加到您的Claude Desktop配置中：

{
  "mcpServers": {
    "mcp-openstack-ops": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-openstack-ops"],
      "env": {
        "OS_AUTH_HOST": "your-openstack-host",
        "OS_AUTH_PORT": "5000",
        "OS_PROJECT_NAME": "your-project",
        "OS_USERNAME": "your-username",
        "OS_PASSWORD": "your-password",
        "OS_USER_DOMAIN_NAME": "Default",
        "OS_PROJECT_DOMAIN_NAME": "Default",
        "OS_REGION_NAME": "RegionOne",
        "OS_IDENTITY_API_VERSION": "3",
        "OS_INTERFACE": "internal",
        "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": "18888",
        "ALLOW_MODIFY_OPERATIONS": "false",
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

______________________________________________________________________

服务器配置

命令行选项

uv run python -m mcp_openstack_ops --help

Options:
  --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Logging level
  --type {stdio,streamable-http}
                        Transport type (default: stdio)
  --host HOST          Host address for HTTP transport (default: 127.0.0.1)
  --port PORT          Port number for HTTP transport (default: 8080)
  --auth-enable        Enable Bearer token authentication for streamable-http mode
  --secret-key SECRET  Secret key for Bearer token authentication

环境变量

______________________________________________________________________

🔒 项目隔离和安全

单一项目范围操作

MCP OpenStack运维在严格定义的项目范围内运行 由 OS_PROJECT_NAME 环境变量。这在多租户OpenStack环境中提供了完全的租户隔离和数据隐私。

主要安全功能：

• 100%完全资源隔离：所有操作都仅限于具有增强安全验证的指定项目内的资源
• 零跨租户数据泄漏：高级项目所有权验证可防止访问其他项目的资源
• 多层安全过滤：每个服务都通过当前项目ID实现智能资源过滤，并进行额外验证
• 安全资源查找：所有资源搜索都使用具有所有权验证的项目范围查找
• 共享资源访问：智能地包括共享/公共资源（网络、图像），同时保持严格的安全边界
• 跨项目访问预防：加强对其他项目中类似名称资源的意外操作的保护

按项目筛选的资源：

安全验证和测试

项目隔离安全测试

要验证项目隔离是否正常工作，请运行附带的安全测试：

# Run project isolation security test
python test_project_isolation.py

预期测试结果：

🔒 OpenStack Project Isolation Security Test
==================================================
📋 Testing project isolation for: your-project

1️⃣ Testing Connection and Project ID...
✅ Connection successful
✅ Current project ID: abc123-def456-ghi789
✅ Project name 'your-project' matches project ID

2️⃣ Testing Resource Ownership Validation...
✅ Found 5 compute instances
   Instance web-server-01: ✅ Owned
   Instance db-server-01: ✅ Owned
✅ Found 3/8 owned networks
✅ Found 10/10 owned volumes

3️⃣ Testing Service-Level Project Filtering...
✅ Compute service returned 5 instances
✅ Network service returned 3 networks  
✅ Storage service returned 10 volumes

4️⃣ Testing Secure Resource Lookup...
ℹ️  Network 'admin' not found or not accessible in current project
ℹ️  Instance 'demo' not found or not accessible in current project

🎯 Project Isolation Test Results
========================================
✅ All security tests passed!
✅ Project 'your-project' isolation verified
✅ Cross-project access prevention confirmed

🔒 Your OpenStack MCP Server is properly secured!

安全功能已验证：

• ✅ 项目ID验证和匹配
• ✅ 所有服务的资源所有权验证
• ✅ 服务级别项目过滤
• ✅ 具有跨项目保护的安全资源查找
• ✅ 防止对其他项目资源的意外操作

为了管理多个OpenStack项目，部署多个具有不同配置的MCP服务器实例 OS_PROJECT_NAME 值：

示例：管理3个项目

# Project 1: Production Environment
OS_PROJECT_NAME=production
# ... other config
python -m mcp_openstack_ops --type stdio

# Project 2: Development Environment  
OS_PROJECT_NAME=development
# ... other config  
python -m mcp_openstack_ops --type streamable-http --port 8001

# Project 3: Testing Environment
OS_PROJECT_NAME=testing  
# ... other config
python -m mcp_openstack_ops --type streamable-http --port 8002

Claude桌面多项目配置示例：

{
  "mcpServers": {
    "openstack-production": {
      "command": "python",
      "args": ["-m", "mcp_openstack_ops", "--type", "stdio"],
      "env": {
        "OS_PROJECT_NAME": "production",
        "OS_USERNAME": "admin",
        "OS_PASSWORD": "your-password",
        "OS_AUTH_HOST": "192.168.35.2"
      }
    },
    "openstack-development": {
      "command": "python", 
      "args": ["-m", "mcp_openstack_ops", "--type", "stdio"],
      "env": {
        "OS_PROJECT_NAME": "development",
        "OS_USERNAME": "admin",
        "OS_PASSWORD": "your-password", 
        "OS_AUTH_HOST": "192.168.35.2"
      }
    },
    "openstack-testing": {
      "command": "python",
      "args": ["-m", "mcp_openstack_ops", "--type", "stdio"], 
      "env": {
        "OS_PROJECT_NAME": "testing",
        "OS_USERNAME": "admin",
        "OS_PASSWORD": "your-password",
        "OS_AUTH_HOST": "192.168.35.2"
      }
    }
  }
}

这允许Claude独立访问每个项目，在环境之间完全隔离。

📁 即用型配置文件：

完整的多项目配置示例可在 mcp-config.json.multi-project:

• 生产：为安全起见，只读操作(ALLOW_MODIFY_OPERATIONS=false)
• 发展：已启用完整操作(ALLOW_MODIFY_OPERATIONS=true)
• 测试：已启用调试日志记录(MCP_LOG_LEVEL=DEBUG)

# Copy and customize the multi-project configuration
cp mcp-config.json.multi-project ~/.config/claude-desktop/mcp_servers.json
# Edit with your OpenStack credentials

______________________________________________________________________

安全控制

修改操作保护

默认情况下，所有可以修改或删除OpenStack资源的操作都是 残疾的 为了安全：

# Default setting - Only read-only operations allowed
ALLOW_MODIFY_OPERATIONS=false

受保护的操作（当 ALLOW_MODIFY_OPERATIONS=false):

• 实例管理（启动、停止、重新启动、暂停、取消暂停）
• 卷操作（创建、删除、附着、分离）
• 密钥对管理（创建、删除、导入）
• 浮动IP操作（创建、删除、关联、解除关联）
• 快照管理（创建、删除）
• 图像管理（创建、删除、更新）
• 热堆操作（创建、删除、更新）

始终可用（只读操作）：

• 集群状态和监控
• 资源列表（实例、卷、网络等）
• 服务状态检查
• 使用和配额信息
• 搜索和过滤操作

⚠️ 要启用修改操作，请执行以下操作：

# Enable all operations (USE WITH CAUTION)
ALLOW_MODIFY_OPERATIONS=true

工具注册行为：

• 什么时候 ALLOW_MODIFY_OPERATIONS=false：只有只读工具在MCP服务器上注册
• 什么时候 ALLOW_MODIFY_OPERATIONS=true：所有工具（只读+修改操作）都已注册
• 工具可用性在服务器启动时确定-更改此设置后需要重新启动

最佳实践：

• 保持 ALLOW_MODIFY_OPERATIONS=false 在生产环境中
• 仅在开发/测试环境中启用修改操作
• 为不同的环境使用单独的配置
• 在启用修改功能之前审查操作
• 更改后重新启动MCP服务器 ALLOW_MODIFY_OPERATIONS 设置

______________________________________________________________________

💬 示例查询和使用模式

有关如何与此MCP服务器交互的综合示例，包括自然语言查询及其相应的工具映射，请参阅：

📖 示例查询和使用模式

本节包括：

• 🎯 集群概述和状态查询
• �️ 实例管理操作
• 🌐 网络配置任务
• � 存储管理工作流程
• 🔥 热编排示例
• ⚖️ 负载平衡器操作
• � 高级搜索模式
• 📊 监控和故障排除
• 🧠 复杂的多工具查询组合

______________________________________________________________________

性能优化

大规模环境支持

MCP服务器针对具有数千个实例的大型OpenStack环境进行了优化：

分页功能：

• 默认限制可防止内存溢出（每个请求50个实例）
• 可配置的安全限制（每次请求最多200个实例）
• 基于偏移量的分页，用于浏览大型数据集
• 性能指标跟踪（处理时间、每秒实例数）

搜索优化：

• 两阶段搜索过程（基本信息过滤→ 详细信息检索）
• 具有连接重用功能的智能缓存
• 选择性API调用可最大限度地减少开销
• 区分大小写的搜索选项，用于精确过滤

连接管理：

• 具有有效性测试的全局连接缓存
• 瞬态故障的自动重试机制
• 用于高吞吐量场景的连接池

使用示例：

# Safe large environment browsing
get_instance_details(limit=50, offset=0)     # First 50 instances
get_instance_details(limit=50, offset=50)    # Next 50 instances

# Emergency override for small environments
get_instance_details(include_all=True)       # All instances (use with caution)

# Optimized search for large datasets
search_instances("web", "name", limit=20)    # Search with reasonable limit

______________________________________________________________________

发展

添加新工具

编辑 src/mcp_openstack_ops/mcp_main.py 添加新的MCP工具：

@mcp.tool()
async def my_openstack_tool(param: str) -> str:
    """
    Brief description of the tool's purpose.
    
    Functions:
    - List specific functions this tool performs
    - Describe the operations it enables
    - Mention when to use this tool
    
    Use when user requests [specific scenarios].
    
    Args:
        param: Description of the parameter
        
    Returns:
        Description of return value format.
    """
    try:
        logger.info(f"Tool called with param: {param}")
        # Implementation using functions.py helpers
        result = my_helper_function(param)
        
        response = {
            "timestamp": datetime.now().isoformat(),
            "result": result
        }
        
        return json.dumps(response, indent=2, ensure_ascii=False)
        
    except Exception as e:
        error_msg = f"Error: Failed to execute tool - {str(e)}"
        logger.error(error_msg)
        return error_msg

Helper函数

将实用程序功能添加到 src/mcp_openstack_ops/functions.py:

def my_helper_function(param: str) -> dict:
    """Helper function for OpenStack operations"""
    try:
        conn = get_openstack_connection()
        
        # OpenStack SDK operations
        result = conn.some_service.some_operation(param)
        
        logger.info(f"Operation completed successfully")
        return {"success": True, "data": result}
        
    except Exception as e:
        logger.error(f"Helper function error: {e}")
        raise

______________________________________________________________________

测试与验证

本地测试

# Test with MCP Inspector (recommended)
./scripts/run-mcp-inspector-local.sh

# Test with debug logging
MCP_LOG_LEVEL=DEBUG uv run python -m mcp_openstack_ops

# Validate OpenStack connection
uv run python -c "from src.mcp_openstack_ops.functions import get_openstack_connection; print(get_openstack_connection())"

______________________________________________________________________

🔐 安全和身份验证

承载令牌身份验证

对于 streamable-http 模式下，此MCP服务器支持承载令牌身份验证，以确保远程访问的安全。在生产环境中运行服务器时，这一点尤为重要。

配置

启用身份验证：

# In .env file
REMOTE_AUTH_ENABLE=true
REMOTE_SECRET_KEY=my-test-secret-key-12345

或者通过CLI：

uv run python -m mcp_openstack_ops --type streamable-http --auth-enable --secret-key your-secure-secret-key-here

安全等级

1. stdio模式 （默认）：仅本地访问，无需身份验证
2. 可流式传输的http+REMOTE_AUTH_ENABLE=false/undefined：无身份验证的远程访问⚠️ 不建议用于生产
3. 可流式传输http+REMOTE_AUTH_ENABLE=true：使用承载令牌身份验证进行远程访问✅ 建议用于生产

🔒 默认策略: REMOTE_AUTH_ENABLE 默认为 false 如果未定义、为空或为null。这确保了服务器即使在没有显式身份验证配置的情况下也能启动。

客户端配置

启用身份验证后，MCP客户端必须在授权标头中包含Bearer令牌：

{
  "mcpServers": {
    "mcp-openstack-ops": {
      "type": "streamable-http",
      "url": "http://your-server:8000/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-secret-key-here"
      }
    }
  }
}

安全最佳实践

• 始终启用身份验证 在生产环境中使用流式http模式时
• 使用强随机生成的密钥 （建议使用32+个字符）
• 使用HTTPS 如果可能（使用SSL/TLS配置反向代理）
• 限制网络访问 使用防火墙或网络策略
• 定期旋转密钥 增强安全性
• 监控访问日志 未经授权的访问尝试

错误处理

当身份验证失败时，服务器返回：

• 401未经授权 用于丢失或无效的令牌
• 详细的错误消息 JSON格式用于调试

______________________________________________________________________

🎯 最近的改进和增强

🔒 完成项目隔离安全实施 ✨

100%项目隔离保证：

• ✅ 多层安全验证：为所有资源操作添加了全面的项目所有权验证
• ✅ 增强的删除操作安全性：所有删除操作现在都使用带有所有权验证的安全项目范围查找
• ✅ 创建操作安全：创建过程中的资源引用（网络、图像等）已验证项目所有权
• ✅ 查询安全增强：所有列表/获取操作都包括明确的项目验证和资源所有权检查
• ✅ 跨项目访问预防：对其他项目中类似名称资源的意外操作提供高级保护
• ✅ 安全测试套件：已添加 test_project_isolation.py 用于全面的安全验证

技术实施：

• ✅ 新的安全实用程序：已添加 get_current_project_id(), validate_resource_ownership(), find_resource_by_name_or_id() 函数
• ✅ 服务级别安全：通过项目所有权验证增强了所有服务模块（计算、网络、存储等）
• ✅ 安全资源查找：用安全的项目范围资源查找替换了不安全的基于名称的循环
• ✅ 错误消息增强：改进了错误消息，以清楚地指示项目访问限制

完成项目范围界定实施

增强的安全性和租户隔离：

• ✅ 所有服务项目范围：身份、计算、网络、存储、映像、编排、负载均衡器和监控服务现在按当前项目ID过滤资源
• ✅ 零跨租户数据泄露：使用OpenStack SDK级别的自动过滤 current_project_id
• ✅ 智能资源访问：智能处理共享/公共资源（网络、图像），同时保持安全边界

修复了图像服务问题 🖼️

解决了零图像计数问题：

• ✅ 增强图像过滤：现在包括公共、社区、共享和项目拥有的图像
• ✅ 智能可视性处理：正确处理不同的图像可见性类型
• ✅ 防止空结果：修复了过于严格的过滤逻辑

改进的vCPU/RAM计算 ⚡

固定实例资源显示：

• ✅ 嵌入式风味数据使用：直接使用server.flavor属性，避免了404 API错误
• ✅ 准确的资源报告：群集状态报告中的vCPU和RAM值正确
• ✅ 消除了API故障：不再出现导致资源值为零的风味查找失败

增强文档 📚

综合项目范围界定文件：

• ✅ 多项目管理指南：管理多个OpenStack项目的完整设置说明
• ✅ 安全和隔离细节：租户隔离功能的详细说明
• ✅ 即用型配置：预配置 mcp-config.json.multi-project 用于快速设置
• ✅ 更新环境变量：增强 .env.example 在项目范围界定指导下

______________________________________________________________________

🚀 添加自定义工具

此MCP服务器旨在易于扩展。按照以下步骤添加您自己的自定义工具：

分步指南

1. 添加辅助函数（可选）

添加可重用的数据函数 src/mcp_openstack_ops/functions.py:

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. 创建MCP工具文件

创建一个新文件 src/mcp_openstack_ops/tools/get_your_custom_analysis.py:

"""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. 用于修改操作（可选）

如果您的工具执行修改操作，请使用 @conditional_tool 改为装饰师：

"""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. 更新提示模板（推荐）

将您的工具描述添加到 src/mcp_openstack_ops/prompt_template.md 为了更好地识别自然语言：

### **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. 测试你的工具

# 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"

工具注册系统

MCP服务器使用自动工具发现。在中创建新文件时 src/mcp_openstack_ops/tools/，它通过自动注册 register_all_tools() 功能在 tools/__init__.py无需手动进行导入注册！

安全系统

• 只读工具：使用 @mcp.tool() -始终可用
• 修改工具：使用 @conditional_tool -仅在以下情况下可用 ALLOW_MODIFY_OPERATIONS=true
• 连接：始终使用 get_openstack_connection() 用于OpenStack API访问
• 项目隔离：所有操作都会自动限定范围 OS_PROJECT_NAME

就是这样！您的自定义工具已准备好用于自然语言查询。

______________________________________________________________________

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求