MCP Server Oci

🚀 適用於甲骨文雲基礎設施 (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 - 停止一個數據庫系統的所有節點。

更多使用示例

配置文件管理

# 從Claude或任何MCP客戶端：

# 列出可用的配置文件
"Show me all available OCI profiles"

# 激活特定的配置文件
"Set the OCI profile to 'production'"

# 檢查當前的配置文件
"What OCI profile am I currently using?"

# 在租戶之間切換
"Switch to the DEFAULT profile"

計算實例管理

# 列出實例
"Show me all compute instances in compartment ocid1.compartment.oc1..."

# 獲取實例詳細信息
"Get details for instance ocid1.instance.oc1..."

# 啟動/停止實例
"Start the instance ocid1.instance.oc1..."
"Stop the instance ocid1.instance.oc1... with force stop"

數據庫系統管理

# 列出數據庫系統
"Show me all DB Systems in compartment ocid1.compartment.oc1..."

# 獲取數據庫系統詳細信息
"Get details for DB System ocid1.dbsystem.oc1..."

# 管理數據庫節點
"List all DB Nodes for DB System ocid1.dbsystem.oc1..."
"Start DB Node ocid1.dbnode.oc1..."
"Stop all nodes of DB System ocid1.dbsystem.oc1..."

# 重啟操作
"Reboot DB Node ocid1.dbnode.oc1..."
"Soft reset DB Node ocid1.dbnode.oc1..."

資源發現

# 列出分區
"List all compartments in my tenancy"

# 跨資源查詢
"Show me all running instances in compartment X"
"List all DB Systems and their current states"

🔧 技術細節

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原則：使用裝飾器處理常見模式。

📄 許可證

[在此處添加許可證信息]