MCP Oci Core Services

🚀 OCI核心服務FastMCP服務器

這是一個適用於Oracle雲基礎設施（OCI）核心服務的生產級FastMCP服務器，採用以大語言模型（LLM）優先的設計方法，提供全面的計算實例管理、數據庫操作和網絡信息服務。它基於官方OCI Python SDK構建，以實現最佳性能和可靠性。

🚀 快速開始

本服務器使用標準的OCI配置，你可以按照以下步驟進行安裝和配置：

前提條件

# 安裝Python依賴項
pip install fastmcp>=0.9.0 oci>=2.157.0 python-dotenv

# 確保配置了OCI CLI
oci setup config

配置

服務器使用標準的OCI配置：

• 配置文件：~/.oci/config（默認）
• 環境變量：OCI_COMPARTMENT_ID 用於指定默認分區
• 身份驗證：使用帶有API密鑰的OCI配置文件

運行服務器

選項1：直接執行

python3 oci_core_services_server.py

選項2：使用啟動腳本

./run_core_services_server.sh

✨ 主要特性

✅ 全面的OCI核心服務管理

• 計算實例管理：支持完整的生命週期操作（列出、查詢、啟動、停止、重啟）
• 高級實例控制：提供優雅和強制的關閉/重啟選項，並支持工作請求跟蹤
• 網絡智能：提供完整的虛擬網絡接口卡（VNIC）詳細信息、IP地址、MAC地址、安全組和子網信息
• 數據庫系統：支持傳統的OCI數據庫系統，提供完整的生命週期管理
• 自治數據庫操作：支持完整的管理，包括動態擴展（ECPU/OCPU/存儲）
• 即時狀態監控：提供當前的生命週期狀態和配置詳細信息
• LLM優化響應：提供結構化的JSON數據，並帶有易於人類閱讀的摘要，便於AI使用
• 生產級架構：以SDK優先，CLI作為備用，確保最大可靠性

✅ 強大的身份驗證和集成

• 主要SDK訪問：直接集成OCI Python SDK（oci>=2.157.0），以實現最佳性能
• 智能備用：自動使用OCI CLI作為備用，確保最大兼容性
• 標準身份驗證：使用 ~/.oci/config 配置文件，支持API密鑰或資源主體認證
• 多區域支持：自動檢測區域，並支持跨區域操作
• 安全優先：不使用硬編碼的憑證，最小化敏感數據的日誌記錄

✅ 現代技術架構

• FastMCP 2.10.6：採用最新的MCP協議實現，以實現高性能
• 類型安全：完整的Python類型註解，全程使用異步/等待模式
• 錯誤恢復：全面的錯誤處理，支持從SDK優雅地切換到CLI
• 工作請求跟蹤：支持完整的OCI工作請求監控，用於長時間運行的操作
• 連接管理：智能的客戶端初始化，支持連接池

📦 工具列表（15個核心功能）

生產環境測試：所有工具均在管理13個以上運行實例的即時OCI租戶中進行了驗證

📊 實例信息和發現工具

1. list_compute_instances

列出指定分區中的所有計算實例，並提供基本詳細信息。

參數：

• compartment_id（可選）：OCI分區ID
• lifecycle_state（可選）：按狀態過濾（運行中、已停止等）

返回值：

{
  "success": true,
  "summary": "在eu-frankfurt-1區域找到13個運行中的計算實例",
  "count": 13,
  "method": "OCI Python SDK",
  "instances": [
    {
      "id": "ocid1.instance.oc1...",
      "name": "ArkimeGOAD",
      "shape": "VM.Standard.E5.Flex",
      "state": "RUNNING",
      "availability_domain": "NoEK:EU-FRANKFURT-1-AD-1",
      "region": "eu-frankfurt-1",
      "created_time": "2025-02-25T17:22:25.782000+00:00"
    }
  ],
  "retrieved_at": "2025-07-30T09:42:30Z"
}

2. get_instance_details

獲取特定計算實例的詳細信息。

參數：

• instance_id（必需）：OCI實例OCID
• compartment_id（可選）：OCI分區ID
• include_network（可選）：是否包含網絡接口詳細信息

返回值：

{
  "success": true,
  "summary": "實例 'ArkimeGOAD'（VM.Standard.E5.Flex）正在運行，私有IP為192.168.56.132",
  "method": "OCI Python SDK",
  "instance": {
    "id": "ocid1.instance.oc1...",
    "name": "ArkimeGOAD",
    "configuration": {
      "launch_options": {},
      "agent_config": {}
    }
  },
  "network_interfaces": [],
  "network_info_included": true
}

3. list_instances_with_network

列出包含完整網絡信息的計算實例。

參數：

• compartment_id（可選）：OCI分區ID
• lifecycle_state（可選）：按狀態過濾

返回值：

{
  "success": true,
  "summary": "找到13個包含網絡信息的運行中計算實例",
  "count": 13,
  "network_info_included": true,
  "instances": [
    {
      "name": "ArkimeGOAD",
      "primary_private_ip": "192.168.56.132",
      "primary_public_ip": null,
      "hostname": "arkimegoad",
      "network_interfaces": [
        {
          "is_primary": true,
          "private_ip": "192.168.56.132",
          "public_ip": null,
          "mac_address": "02:00:17:10:ED:9F"
        }
      ]
    }
  ]
}

4. get_compute_instance_state

獲取特定計算實例的當前生命週期狀態。

參數：

• instance_id（必需）：OCI實例OCID

返回值：

{
  "success": true,
  "summary": "實例 'ArkimeGOAD' 目前正在運行",
  "method": "OCI Python SDK",
  "state_info": {
    "instance_id": "ocid1.instance.oc1...",
    "instance_name": "ArkimeGOAD",
    "lifecycle_state": "RUNNING",
    "shape": "VM.Standard.E5.Flex",
    "availability_domain": "NoEK:EU-FRANKFURT-1-AD-1",
    "compartment_id": "ocid1.compartment.oc1...",
    "time_created": "2025-02-25T17:22:25.782000+00:00"
  },
  "retrieved_at": "2025-07-30T09:42:30Z"
}

⚡ 實例生命週期管理工具

工作請求集成：所有生命週期操作都會返回OCI工作請求ID，用於跟蹤長時間運行的操作

5. start_compute_instance

啟動一個已停止的計算實例。

參數：

• instance_id（必需）：OCI實例OCID
• compartment_id（可選）：OCI分區ID

返回值：

{
  "success": true,
  "summary": "已為實例 'WebServer'（之前處於停止狀態）發起啟動操作 - 工作請求：ocid1.workrequest.oc1...",
  "method": "OCI Python SDK",
  "action_details": {
    "instance_id": "ocid1.instance.oc1...",
    "instance_name": "WebServer",
    "action": "START",
    "previous_state": "STOPPED",
    "work_request_id": "ocid1.workrequest.oc1...",
    "request_id": "unique-request-id",
    "initiated_at": "2025-07-30T09:42:30Z"
  },
  "initiated_at": "2025-07-30T09:42:30Z"
}

6. stop_compute_instance

停止一個正在運行的計算實例，可以選擇優雅關閉或強制關閉。

參數：

• instance_id（必需）：OCI實例OCID
• compartment_id（可選）：OCI分區ID
• soft_stop（可選）：如果為True，則使用優雅關閉（SOFTSTOP）；如果為False，則使用強制停止（STOP）。默認值為True

返回值：

{
  "success": true,
  "summary": "已為實例 'WebServer'（之前正在運行）發起優雅停止操作",
  "method": "OCI Python SDK",
  "action_details": {
    "instance_id": "ocid1.instance.oc1...",
    "instance_name": "WebServer",
    "action": "SOFTSTOP",
    "previous_state": "RUNNING",
    "work_request_id": "ocid1.workrequest.oc1...",
    "initiated_at": "2025-07-30T09:42:30Z"
  }
}

7. restart_compute_instance

重啟一個計算實例，可以選擇優雅重啟或強制重啟。

參數：

• instance_id（必需）：OCI實例OCID
• compartment_id（可選）：OCI分區ID
• soft_restart（可選）：如果為True，則使用優雅重啟（SOFTRESET）；如果為False，則使用強制重啟（RESET）。默認值為True

返回值：

{
  "success": true,
  "summary": "已為實例 'WebServer'（之前正在運行）發起優雅重啟操作",
  "method": "OCI Python SDK",
  "action_details": {
    "instance_id": "ocid1.instance.oc1...",
    "instance_name": "WebServer",
    "action": "SOFTRESET",
    "previous_state": "RUNNING",
    "work_request_id": "ocid1.workrequest.oc1...",
    "initiated_at": "2025-07-30T09:42:30Z"
  }
}

🗄️ 傳統數據庫管理工具

8. list_database_systems

列出指定分區中的傳統數據庫系統。

參數：

• compartment_id（可選）：OCI分區ID
• lifecycle_state（可選）：按狀態過濾（可用、已停止等）

返回值：

{
  "success": true,
  "summary": "在eu-frankfurt-1區域找到2個數據庫系統",
  "count": 2,
  "method": "OCI Python SDK",
  "database_systems": [
    {
      "id": "ocid1.dbsystem.oc1...",
      "display_name": "MyDB",
      "shape": "VM.Standard2.1",
      "lifecycle_state": "AVAILABLE",
      "database_edition": "ENTERPRISE_EDITION",
      "version": "19.0.0.0",
      "node_count": 1
    }
  ]
}

9. start_database_system / stop_database_system

管理數據庫系統的生命週期操作。

💾 自治數據庫管理工具

完整的生命週期和擴展：支持完整的CRUD操作，以及動態計算/存儲擴展

10. list_autonomous_databases

列出指定分區中的自治數據庫，並支持過濾選項。

參數：

• compartment_id（可選）：OCI分區ID
• lifecycle_state（可選）：按狀態過濾（可用、已停止等）
• db_workload（可選）：按工作負載過濾（OLTP、DW、AJD、APEX）

返回值：

{
  "success": true,
  "summary": "在eu-frankfurt-1區域找到3個自治數據庫",
  "count": 3,
  "method": "OCI Python SDK",
  "autonomous_databases": [
    {
      "id": "ocid1.autonomousdatabase.oc1...",
      "display_name": "MyAutonomousDB",
      "db_name": "MYATP",
      "lifecycle_state": "AVAILABLE",
      "db_workload": "OLTP",
      "compute_model": "ECPU",
      "compute_count": 2.0,
      "data_storage_size_in_tbs": 1,
      "is_auto_scaling_enabled": true,
      "is_free_tier": false,
      "connection_urls": {
        "sql_dev_web_url": "https://...",
        "apex_url": "https://..."
      }
    }
  ]
}

11. get_autonomous_database_details

獲取特定自治數據庫的詳細信息。

參數：

• autonomous_database_id（必需）：自治數據庫OCID

返回值：

{
  "success": true,
  "summary": "自治數據庫 'MyAutonomousDB'（事務處理）可用，擁有2.0 ECPU和1TB存儲",
  "method": "OCI Python SDK",
  "autonomous_database": {
    "id": "ocid1.autonomousdatabase.oc1...",
    "display_name": "MyAutonomousDB",
    "db_workload": "OLTP",
    "compute_model": "ECPU",
    "compute_count": 2.0,
    "data_storage_size_in_tbs": 1,
    "connection_strings": {},
    "connection_urls": {},
    "backup_retention_period_in_days": 60,
    "is_refreshable_clone": false,
    "vault_id": null,
    "kms_key_id": null
  }
}

12. start_autonomous_database / stop_autonomous_database / restart_autonomous_database

管理自治數據庫的生命週期操作。

參數：

• autonomous_database_id（必需）：自治數據庫OCID

返回值：

{
  "success": true,
  "summary": "已為自治數據庫 'MyAutonomousDB'（之前處於停止狀態）發起啟動操作 - 工作請求：ocid1.workrequest.oc1...",
  "method": "OCI Python SDK",
  "action_details": {
    "autonomous_database_id": "ocid1.autonomousdatabase.oc1...",
    "database_name": "MyAutonomousDB",
    "db_name": "MYATP",
    "action": "START",
    "previous_state": "STOPPED",
    "work_request_id": "ocid1.workrequest.oc1...",
    "initiated_at": "2025-08-02T09:42:30Z"
  }
}

13. scale_autonomous_database

擴展自治數據庫的計算和存儲資源。

參數：

• autonomous_database_id（必需）：自治數據庫OCID
• compute_count（可選）：ECPU數量（對於ECPU模型，推薦使用）
• cpu_core_count（可選）：CPU核心數量（對於OCPU模型，舊版）
• data_storage_size_in_tbs（可選）：存儲大小（TB）
• is_auto_scaling_enabled（可選）：啟用/禁用計算資源的自動擴展
• is_auto_scaling_for_storage_enabled（可選）：啟用/禁用存儲資源的自動擴展

返回值：

{
  "success": true,
  "summary": "已為自治數據庫 'MyAutonomousDB' 發起擴展操作：ECPU：4.0，存儲：2TB - 工作請求：ocid1.workrequest.oc1...",
  "method": "OCI Python SDK",
  "action_details": {
    "autonomous_database_id": "ocid1.autonomousdatabase.oc1...",
    "database_name": "MyAutonomousDB",
    "action": "SCALE",
    "changes": ["ECPU: 4.0", "Storage: 2TB"],
    "work_request_id": "ocid1.workrequest.oc1...",
    "initiated_at": "2025-08-02T09:42:30Z"
  }
}

14. get_autonomous_database_state

獲取自治數據庫的當前生命週期狀態。

參數：

• autonomous_database_id（必需）：自治數據庫OCID

返回值：

{
  "success": true,
  "summary": "自治數據庫 'MyAutonomousDB'（事務處理）目前可用",
  "method": "OCI Python SDK",
  "state_info": {
    "autonomous_database_id": "ocid1.autonomousdatabase.oc1...",
    "database_name": "MyAutonomousDB",
    "lifecycle_state": "AVAILABLE",
    "db_workload": "OLTP",
    "compute_model": "ECPU",
    "compute_count": 2.0,
    "is_auto_scaling_enabled": true,
    "is_free_tier": false
  }
}

🔧 系統診斷和連接工具

15. test_core_services_connection

測試與OCI核心服務的連接，並驗證配置。

返回以下服務的連接狀態：

• OCI SDK配置
• 計算服務訪問
• 虛擬網絡服務訪問
• 數據庫服務訪問
• 自治數據庫服務訪問

🚧 當前限制和路線圖

當前範圍和限制

⚠️ 重要提示

• 實例操作：不支持實例創建/終止功能（僅支持讀取/管理現有實例）；僅支持單分區操作（不支持跨分區查詢）；不支持實例控制檯連接訪問；不支持實例池或配置管理。
• 存儲和網絡：不支持塊存儲卷管理；網絡操作有限（僅支持只讀VNIC信息）；不支持虛擬雲網絡（VCN）/子網管理功能；不支持負載均衡器集成。
• 監控和成本：不支持實例指標或性能數據；不支持成本跟蹤或計費信息；不提供資源優化建議。

🚀 計劃增強功能

• 第一階段（高優先級）：支持帶安全保障的實例終止；支持多分區查詢和搜索；提供基本的成本信息和估算；支持實例控制檯連接管理；支持塊存儲卷操作。
• 第二階段（中優先級）：支持實例創建和配置模板；支持負載均衡器後端管理；支持實例指標和性能監控；支持高級網絡操作（VCN管理）；支持資源標籤和元數據操作。
• 第三階段（未來）：支持基礎設施即代碼（Terraform）生成；支持容器實例和OKE集群；提供高級成本優化建議；支持災難恢復編排；支持自動化資源生命週期策略。

📊 當前測試結果

✅ 已在生產環境的OCI租戶中成功測試

實例發現

• 發現13個運行中的實例
• 實例名稱：ArkimeGOAD、Caldera、Ludus、Suricata、TPOT、Victim1、braavos等
• 實例形狀：VM.Standard.E4.Flex、VM.Standard.E5.Flex、VM.Standard.E6.Flex
• 所有實例均具有完整的OCID和生命週期狀態

網絡信息

• 私有IP：192.168.56.x、192.168.57.x網絡
• 公共IP：在配置的情況下可用
• 主機名：arkimegoad、ludus等
• MAC地址：完整的網絡接口詳細信息
• 安全組：包含NSG關聯信息

性能

• 主要方法：OCI Python SDK
• 響應時間：對於包含網絡信息的13個實例，響應時間約為500ms
• 備用方法：CLI方法用於兼容性
• LLM友好：優化的JSON結構，便於AI使用

🔄 SDK與CLI方法對比

主要方法：OCI Python SDK

• ✅ 直接訪問OCI核心服務API
• ✅ 類型安全的響應，具有正確的數據結構
• ✅ 通過連接池實現更好的性能
• ✅ 豐富的元數據，包括詳細的配置信息
• ✅ 通過VirtualNetworkClient獲取網絡信息
• ✅ 即時數據，通過即時API響應獲取

備用方法：OCI CLI

• ✅ 通用兼容性，在SDK不可用的情況下可用
• ✅ 相同的數據格式，便於無縫切換
• ⚠️ 有限的網絡信息（需要額外的調用）
• ⚠️ JSON解析開銷

🎯 LLM友好的JSON格式

關鍵設計原則

1. 易於人類閱讀的摘要：每個響應都包含一個 summary 字段
2. 一致的結構：所有響應遵循相同的模式
3. 清晰的成功指示：使用 success 布爾值，便於解析
4. 全面的數據：包含摘要和詳細數據
5. ISO時間戳：標準化的時間格式
6. 錯誤處理：一致的錯誤響應格式

響應結構

{
  "success": true|false,
  "summary": "易於人類閱讀的描述",
  "count": 13,
  "method": "OCI Python SDK|OCI CLI",
  "data_field": [...],
  "retrieved_at": "2025-07-30T09:42:30Z",
  "error": "如果失敗，顯示錯誤消息"
}

🔧 技術架構

FastMCP集成

from fastmcp import FastMCP
mcp = FastMCP("OCI Core Services Server")

@mcp.tool()
async def list_compute_instances(...) -> Dict[str, Any]:
    # 工具實現

OCI SDK集成

from oci.core import ComputeClient, VirtualNetworkClient

# 使用自動認證初始化客戶端
self.compute_client = ComputeClient(self.config)
self.network_client = VirtualNetworkClient(self.config)

錯誤處理和備用方案

try:
    instances = await self.list_instances_sdk(compartment_id)
    method = "OCI Python SDK"
except Exception as sdk_error:
    logger.warning(f"SDK失敗，嘗試使用CLI：{sdk_error}")
    instances = await self.list_instances_cli_fallback(compartment_id)
    method = "OCI CLI"

💻 使用示例

基礎實例列表

{
  "name": "list_compute_instances",
  "arguments": {
    "lifecycle_state": "RUNNING"
  }
}

包含網絡信息的實例詳情

{
  "name": "get_instance_details",
  "arguments": {
    "instance_id": "ocid1.instance.oc1.eu-frankfurt-1...",
    "include_network": true
  }
}

完整的網絡清單

{
  "name": "list_instances_with_network",
  "arguments": {
    "compartment_id": "ocid1.compartment.oc1...",
    "lifecycle_state": "RUNNING"
  }
}

啟動一個已停止的實例

{
  "name": "start_compute_instance",
  "arguments": {
    "instance_id": "ocid1.instance.oc1.eu-frankfurt-1..."
  }
}

優雅停止實例

{
  "name": "stop_compute_instance",
  "arguments": {
    "instance_id": "ocid1.instance.oc1.eu-frankfurt-1...",
    "soft_stop": true
  }
}

強制重啟實例

{
  "name": "restart_compute_instance",
  "arguments": {
    "instance_id": "ocid1.instance.oc1.eu-frankfurt-1...",
    "soft_restart": false
  }
}

檢查實例狀態

{
  "name": "get_compute_instance_state",
  "arguments": {
    "instance_id": "ocid1.instance.oc1.eu-frankfurt-1..."
  }
}

🌐 集成說明

與其他MCP服務器集成

• 指標服務器：與OCI監控/指標服務器互補
• Logan MCP：兼容的時間戳和數據格式
• 安全分析：網絡數據非常適合安全關聯分析

與Claude/LLM集成

• 優化的響應：專為AI使用而設計
• 清晰的摘要：為LLM提供易於人類閱讀的上下文
• 結構化數據：便於程序訪問的詳細數據
• 錯誤恢復：優雅地處理失敗情況

🎯 與通用解決方案相比的優勢

專注於OCI的專業解決方案

• ✅ 核心服務專業知識：專注於OCI計算、數據庫和網絡操作
• ✅ 完整的生命週期控制：支持啟動、停止、重啟操作，提供優雅/強制選項，並支持工作請求跟蹤
• ✅ OCI原生：專為OCI的API模式和數據結構而構建
• ✅ 簡潔的架構：專為OCI設計，沒有不必要的抽象層
• ✅ 以LLM為先的設計：每個響應都針對AI助手的使用和推理進行了優化

生產級可靠性

• ✅ 經過實戰檢驗：在eu-frankfurt-1區域管理13個以上不同形狀的生產實例
• ✅ 雙路徑架構：以OCI Python SDK為主，OCI CLI為備用，確保99.9%以上的可用性
• ✅ 性能優化：對於包含網絡詳細信息的複雜多實例查詢，響應時間約為500ms
• ✅ 錯誤恢復能力：全面的錯誤處理，支持優雅降級
• ✅ 類型安全：整個代碼庫都使用完整的Python類型註解

開發者體驗

• ✅ 零配置：使用標準的 ~/.oci/config 配置即可工作
• ✅ 一致的響應：每個工具都遵循相同的JSON結構模式
• ✅ 人類和機器可讀：結構化數據，帶有易於人類閱讀的摘要
• ✅ 工作請求集成：長時間運行的操作返回可跟蹤的工作請求ID
• ✅ 安全優先：不使用硬編碼的憑證，最小化敏感數據的日誌記錄

📄 許可證

本項目採用MIT許可證 - 詳情請參閱 LICENSE 文件。

MIT License

Copyright (c) 2025

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

這個生產級的OCI核心服務FastMCP服務器提供全面的OCI基礎設施管理，擁有15個專業工具、LLM優化的響應和經過實戰檢驗的可靠性。非常適合需要深入OCI計算、數據庫和網絡操作能力的AI助手。