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助手。