JinDaGe - mcp-server-oci MCP Details

article

README

🚀 适用于甲骨文云基础设施 (OCI) 的MCP服务器

本项目为甲骨文云基础设施实现了一个模型上下文协议 (MCP) 服务器，允许像Claude这样的大语言模型直接与OCI资源进行交互。

演示图

🚀 快速开始

本项目实现的MCP服务器能让大语言模型与OCI资源交互，以下为使用前的准备及启动方式。

✨ 主要特性

动态配置文件选择：无需重启服务器即可在OCI配置文件/租户之间进行切换。
使用标准OCI CLI配置连接到甲骨文云：借助标准的OCI CLI配置实现与甲骨文云的连接。
全面的OCI资源管理工具：具备用于列出和管理OCI资源的综合工具。
实例生命周期管理：可对实例进行启动、停止等操作。
数据库系统和数据库节点管理：支持对数据库系统和数据库节点进行管理。
与MCP协议集成：便于从Claude桌面端进行访问。

📦 安装指南

前提条件

Python 3.10 或更高版本。
已配置OCI CLI（oci setup config）。
在甲骨文云中具有适当的权限。

安装步骤

克隆此仓库：

pip install git+https://github.com/modelcontextprotocol/python-sdk.git
pip install oci fastapi uvicorn click pydantic loguru
pip install -e .

💻 使用示例

启动服务器

基础用法

选项1：动态配置文件选择（推荐） 不指定配置文件启动服务器，然后在运行时选择：

python -m mcp_server_oci.mcp_server

然后使用MCP工具管理配置文件：

list_oci_profiles - 查看 ~/.oci/config 中可用的配置文件。
set_oci_profile - 激活特定的配置文件。
get_current_oci_profile - 检查当前激活的配置文件。

选项2：使用默认配置文件 预先加载特定的配置文件启动：

python -m mcp_server_oci.mcp_server --profile DEFAULT

使用 uv 启动：

uv --directory /path/to/mcp-server-oci run python -m mcp_server_oci.mcp_server --profile DEFAULT

高级用法

在租户之间切换

无需重启服务器即可在不同的OCI租户之间进行切换：

# 在你的MCP客户端（例如Claude）中：
# 1. 列出可用的配置文件
"Show me available OCI profiles"

# 2. 切换到不同的租户
"Switch to the 'production' OCI profile"

# 3. 验证当前的配置文件
"What OCI profile am I using?"

为Claude桌面端（MacOS）进行配置

将以下配置添加到文件 /Users/<usuario>/Library/Application Support/Claude/claude_desktop_config.json 中：

使用动态配置文件选择（推荐）：

"mcpServers": {
  "mcp-server-oci": {
    "command": "python",
    "args": [
      "-m",
      "mcp_server_oci.mcp_server"
    ],
    "env": {
      "PYTHONPATH": "/<PATH_TO_MCP>/mcp-server-oci",
      "FASTMCP_LOG_LEVEL": "INFO"
    }
  }
}

使用固定配置文件：

"mcpServers": {
  "mcp-server-oci": {
    "command": "python",
    "args": [
      "-m",
      "mcp_server_oci.mcp_server",
      "--profile", "DEFAULT"
    ],
    "env": {
      "PYTHONPATH": "/<PATH_TO_MCP>/mcp-server-oci",
      "FASTMCP_LOG_LEVEL": "INFO"
    }
  }
}

使用 uv 和动态配置文件：

"mcpServers": {
  "mcp-server-oci": {
    "command": "uv",
    "args": [
      "--directory",
      "/<PATH_TO_MCP>/mcp-server-oci",
      "run",
      "python",
      "-m",
      "mcp_server_oci.mcp_server"
    ],
    "env": {
      "FASTMCP_LOG_LEVEL": "INFO"
    }
  }
}

可用的MCP工具

配置文件管理 🆕

list_oci_profiles - 列出 ~/.oci/config 中所有可用的OCI配置文件。
set_oci_profile - 激活特定的配置文件以进行API调用。
get_current_oci_profile - 显示当前激活的配置文件。

身份与访问管理

list_compartments - 列出你可以访问的所有分区。

计算资源

list_instances - 列出某个分区中的虚拟机实例。
get_instance - 获取特定实例的详细信息。
start_instance - 启动一个已停止的实例。
stop_instance - 停止一个正在运行的实例（支持软停止/强制停止）。

数据库系统 🔥

list_db_systems - 列出某个分区中的数据库系统。
get_db_system - 获取数据库系统的详细信息。
list_db_nodes - 列出某个分区中的数据库节点（可根据数据库系统进行过滤）。
get_db_node - 获取数据库节点的详细信息。
start_db_node - 启动一个已停止的数据库节点。
stop_db_node - 停止一个正在运行的数据库节点（软停止或硬停止）。
reboot_db_node - 重启一个数据库节点。
reset_db_node - 重置（强制重启）一个数据库节点。
softreset_db_node - 软重置（正常重启）一个数据库节点。
start_db_system - 启动一个数据库系统的所有节点。
stop_db_system - 停止一个数据库系统的所有节点。

🔧 技术细节

v1.5 - 动态配置文件选择（最新） 🔥

多租户支持：无需重启即可在OCI配置文件之间进行切换。
新的MCP工具：list_oci_profiles、set_oci_profile、get_current_oci_profile。
配置文件要求验证：在所有OCI工具中对配置文件要求进行验证。
可选的 --profile 参数：支持懒初始化。
完整文档：在 DYNAMIC_PROFILE_SELECTION.md 中提供了完整的文档。
更新的README：准确列出了可用的工具。

v1.4 - 集中式配置

创建集中式配置文件：在 config.py 中创建了包含所有配置常量的集中式文件。
消除魔法数字：在整个代码库中消除了魔法数字。
提高可维护性：提高了配置值的可维护性和可发现性。

v1.3 - 异步操作

移除阻塞调用：移除了所有阻塞的 time.sleep() 调用。
实现异步操作：使所有操作真正实现异步。
提高服务器响应性：提高了服务器的响应能力。

v1.2 - 标准化错误处理

实现混合错误处理模式：实现了混合错误处理模式。
技术错误处理：抛出异常。
业务状态处理：返回成功字典。
详细文档：在 ERROR_HANDLING_PATTERN.md 中提供了详细的文档。

v1.1 - 遵循DRY原则

创建装饰器：创建了 mcp_tool_wrapper 装饰器。
消除重复代码：消除了约150行重复代码。
统一错误处理和日志记录：所有工具的错误处理和日志记录保持一致。

v1.0 - 代码清理

移除无用文件：移除了未使用/过时的文件。
清理注释代码：清理了注释掉的代码。
建立干净的基线：建立了干净的代码基线。

📚 详细文档

动态配置文件选择指南 - 多租户支持的完整指南。
错误处理模式 - 开发人员的错误处理指南。
错误处理示例 - 实际示例。

🤝 贡献代码

欢迎贡献代码！代码库遵循以下模式：

混合错误处理：技术错误抛出异常，业务状态返回字典。
异步操作：无阻塞调用。
集中式配置：常量存储在 config.py 中。
遵循DRY原则：使用装饰器处理常见模式。

📄 许可证

[在此处添加许可证信息]

mcp-server-oci