MCP OCI OPSI Server

MCP OCI OPSI服务器

版本3.0 | FastMCP 2.0 | 13 DBA技能 | OAuth+neneneba API密钥验证 | 多租户

用于Oracle云基础架构（OCI）运营洞察的MCP（模型上下文协议）服务器。此服务器通过Claude Desktop、Claude Code、ChatGPT或任何兼容MCP的客户端（stdio或HTTP传输）提供全面的Oracle数据库监控和分析功能。

快速链接: 安装 | 快速开始 | 启动和运输 | 提示和播放手册 | OCI VM部署 | API 参考 指南: 技能指南 | FastMCP v3指南 | OCI部署指南

______________________________________________________________________

标准

• docs/OCI_MCP_SERVER_STANDARD.md

______________________________________________________________________

截图

车队摘要-即时概述

使用零API调用获取数据库车队的完整概览：

Fleet Summary

*显示数据库计数、类型和隔间分布的车队概述-来自本地缓存的即时响应*

数据库搜索结果

立即搜索和发现整个租约中的数据库：

Database List

*包含OCID、类型和隔间的全面数据库列表-缓存以供即时查询*

数据库详细信息

获取有关任何特定数据库的详细信息：

Database Details

*详细的数据库信息，包括OCID、类型、隔间和状态-从缓存中即时查找*

______________________________________________________________________

v3.0中的新增功能

______________________________________________________________________

启动和运输

• stdio（默认）: python -m mcp_oci_opsi （最适合克劳德桌面/代码，ChatGPT MCP）。
• 超文本传输协议: MCP_TRANSPORT=http MCP_PORT=8000 python -m mcp_oci_opsi （适用于远程客户端）。
• SSE/流式HTTP: MCP_TRANSPORT=sse|streamable-http MCP_PORT=8000 python -m mcp_oci_opsi （如果您的FastMCP运行时支持）。
• 版本切换: MCP_VERSION=v2 （FastMCP服务器）。 MCP_VERSION=v3 运行本地引导/CLI（不是MCP服务器）。
• 日志记录：设置 LOG_LEVEL=DEBUG 用于冗长的启动；OCI SDK日志默认为警告。
• 超时: OCI_CLIENT_TIMEOUT, OPSI_CLIENT_TIMEOUT, DBM_CLIENT_TIMEOUT （秒）绑定每个呼叫延迟； MCP_CLIENT_TIMEOUT_MS caps工具调用。

______________________________________________________________________

架构概述

高级体系结构

                                    ┌─────────────────────────────────────┐
                                    │         MCP Clients                 │
                                    │  (Claude Desktop/Code, ChatGPT)     │
                                    └──────────────┬──────────────────────┘
                                                   │
                                    MCP Protocol (stdio/HTTP)
                                                   │
┌──────────────────────────────────────────────────┴──────────────────────────────────────────────────┐
│                                                                                                      │
│                              MCP OCI OPSI SERVER v3.0                                               │
│                                                                                                      │
│  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐ │
│  │                                    FastMCP 2.0 Core                                            │ │
│  │                                                                                                │ │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │ │
│  │  │   cache_*   │  │   opsi_*    │  │    dbm_*    │  │   admin_*   │  │    Skills Engine    │  │ │
│  │  │   8 tools   │  │   9 tools   │  │   8 tools   │  │  10 tools   │  │    13 DBA skills    │  │ │
│  │  │  4 resources│  │  1 resource │  │  2 resources│  │  3 resources│  │                     │  │ │
│  │  │             │  │             │  │             │  │             │  │  • Fleet Overview   │  │ │
│  │  │ Zero API    │  │ Operations  │  │  Database   │  │   Profile   │  │  • SQL Performance  │  │ │
│  │  │   calls     │  │  Insights   │  │ Management  │  │   Config    │  │  • Capacity Plan    │  │ │
│  │  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────────────┘  │ │
│  │                                                                                                │ │
│  │  ┌─────────────────────────────────────────────────────────────────────────────────────────┐  │ │
│  │  │                              15 MCP Prompts (Workflow Templates)                        │  │ │
│  │  │  Analysis: analyze_database_performance, investigate_slow_query, analyze_wait_events   │  │ │
│  │  │  Operations: enable_monitoring, security_audit, tablespace_maintenance                 │  │ │
│  │  │  Reporting: capacity_planning_report, fleet_inventory_report, compliance_report        │  │ │
│  │  └─────────────────────────────────────────────────────────────────────────────────────────┘  │ │
│  └────────────────────────────────────────────────────────────────────────────────────────────────┘ │
│                                                                                                      │
│  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐ │
│  │                                  Authentication Layer                                          │ │
│  │                                                                                                │ │
│  │  ┌─────────────────────┐  ┌─────────────────────┐  ┌─────────────────────────────────────┐   │ │
│  │  │    OCI IAM OAuth    │  │    API Key Auth     │  │     Resource Principal (Future)     │   │ │
│  │  │  (Production/HTTP)  │  │  (Development/stdio)│  │     (OCI Functions/Containers)      │   │ │
│  │  │                     │  │                     │  │                                     │   │ │
│  │  │  • OIDC Proxy       │  │  • ~/.oci/config    │  │  • Instance metadata auth           │   │ │
│  │  │  • Token Exchange   │  │  • Profile support  │  │  • Dynamic credentials              │   │ │
│  │  │  • Disk storage     │  │  • Multi-tenancy    │  │  • Auto-rotation                    │   │ │
│  │  └─────────────────────┘  └─────────────────────┘  └─────────────────────────────────────┘   │ │
│  └────────────────────────────────────────────────────────────────────────────────────────────────┘ │
│                                                                                                      │
│  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐ │
│  │                                    OCI SDK Client Layer                                        │ │
│  │  • Operations Insights Client    • Database Management Client    • Identity Client             │ │
│  │  • Client caching (16 clients)   • Multi-region support          • Automatic pagination        │ │
│  └────────────────────────────────────────────────────────────────────────────────────────────────┘ │
│                                                                                                      │
└──────────────────────────────────────────────────────────────────────────────────────────────────────┘
                                                   │
                                    HTTPS REST API Calls
                                    (Regional endpoints)
                                                   │
┌──────────────────────────────────────────────────┴──────────────────────────────────────────────────┐
│                                                                                                      │
│                                 ORACLE CLOUD INFRASTRUCTURE                                          │
│                                                                                                      │
│  ┌──────────────────────────┐  ┌──────────────────────────┐  ┌──────────────────────────┐           │
│  │  Operations Insights     │  │  Database Management     │  │      Identity            │           │
│  │                          │  │                          │  │                          │           │
│  │  • Host Insights         │  │  • Managed Databases     │  │  • Users & Groups        │           │
│  │  • Database Insights     │  │  • SQL Plan Baselines    │  │  • Compartments          │           │
│  │  • SQL Statistics        │  │  • Performance Hub       │  │  • Policies              │           │
│  │  • Capacity Planning     │  │  • ADDM / AWR            │  │  • Identity Domains      │           │
│  │  • ML Forecasting        │  │  • Tablespaces           │  │                          │           │
│  └──────────────────────────┘  └──────────────────────────┘  └──────────────────────────┘           │
│                                                                                                      │
│  Regional Endpoints: operationsinsights.{region}.oci.oraclecloud.com                                │
│                      database.{region}.oraclecloud.com                                               │
│                      identity.{region}.oci.oraclecloud.com                                           │
└──────────────────────────────────────────────────────────────────────────────────────────────────────┘

工具组织（v3.0）

身份验证流程

┌────────────────────────────────────────────────────────────────────────────────┐
│                           Authentication Decision Tree                          │
└────────────────────────────────────────────────────────────────────────────────┘
                                       │
                    ┌──────────────────┴──────────────────┐
                    ▼                                      ▼
        ┌─────────────────────┐              ┌─────────────────────┐
        │  HTTP Transport?    │              │  stdio Transport    │
        │  (Production)       │              │  (Development)      │
        └──────────┬──────────┘              └──────────┬──────────┘
                   │                                    │
        ┌──────────┴──────────┐                        │
        ▼                      ▼                        ▼
┌───────────────┐    ┌───────────────┐        ┌───────────────────┐
│ OAuth Enabled │    │ OAuth Not     │        │  API Key Auth     │
│ (FASTMCP_     │    │ Configured    │        │  ~/.oci/config    │
│  OAUTH=1)     │    │               │        │                   │
└───────┬───────┘    └───────┬───────┘        └─────────┬─────────┘
        │                    │                          │
        ▼                    ▼                          ▼
┌───────────────────────────────────────────────────────────────────┐
│                        OCI API Calls                               │
│  • Signed requests with user/tenancy context                      │
│  • Regional endpoint routing                                       │
│  • Automatic retry and error handling                             │
└───────────────────────────────────────────────────────────────────┘

______________________________________________________________________

先决条件

1. Python 3.10+
2. OCI CLI已配置 在 ~/.oci/config
3. 所需IAM策略:

   Allow group YourGroup to read operations-insights-family in tenancy
   Allow group YourGroup to read database-management-family in tenancy
   Allow group YourGroup to read compartments in tenancy

______________________________________________________________________

提示和播放手册

• 提示模板: admin_list_prompts 返回CPU热点、存储风险、慢速SQL和机群概述的预构建指令。用作任何LLM的罐装系统提示。
• 故障排除手册: admin_get_troubleshooting_playbook(issue?) 建议缓存优先的工具流及其原因。
• 健康检查: admin_ping, opsi_health, dbm_health 是零成本准备探头。
• 异步任务：启动缓存构建 cache_start_cache_build_task(compartment_ids=[...]) 并投票给 cache_get_task_status(task_id=...).

______________________________________________________________________

安装

快速安装（开发）

# Clone repository
git clone https://github.com/adibirzu/mcp_oci_opsi.git
cd mcp_oci_opsi

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e .

# Verify installation
python -c "from mcp_oci_opsi.main_v3 import app; print('OK')"

生产安装（Docker）

# Build image
docker build -t mcp-oci-opsi .

# Run with stdio transport
docker run -it --rm \
  -v ~/.oci:/home/mcp/.oci:ro \
  mcp-oci-opsi

# Run with HTTP transport
docker run -d \
  -p 8000:8000 \
  -v ~/.oci:/home/mcp/.oci:ro \
  -e MCP_TRANSPORT=http \
  mcp-oci-opsi

______________________________________________________________________

快速开始

1.构建缓存（推荐）

# One-time setup - builds local cache for instant queries
./scripts/setup_and_build.sh

# Or with specific profile
./scripts/setup_and_build.sh --profile PRODUCTION

2.配置MCP客户端（stdio）

克劳德桌面版 (~/Library/Application Support/Claude/claude_desktop_config.json)或ChatGPT MCP：

{
  "mcpServers": {
    "oci-opsi": {
      "command": "/path/to/mcp_oci_opsi/.venv/bin/python",
      "args": ["-m", "mcp_oci_opsi"],
      "env": {
        "MCP_VERSION": "v3",
        "OCI_CLI_PROFILE": "DEFAULT"
      }
    }
  }
}

3.HTTP传输（远程）

export MCP_TRANSPORT=http
export MCP_HTTP_PORT=8000
python -m mcp_oci_opsi

ChatGPT MCP（HTTP）

{
  "mcpServers": {
    "oci-opsi": {
      "url": "http://127.0.0.1:8000"
    }
  }
}

4.开始使用

# Instant queries (from cache)
"How many databases do I have?"
"Find database PRODDB01"
"Show fleet summary"

# Real-time analytics (API calls)
"Analyze SQL performance for the last 24 hours"
"Show CPU forecast for next 30 days"
"Generate ADDM report for database X"

# Guided workflows (skills)
"Use the sql-performance skill to analyze slow queries"
"Run daily health check"

### 5. Run tests

cd mcp_oci_opsi python -m pytest

Example: Fleet Summary Response

Ask "Show me a summary of my database fleet" and get instant results:

Fleet Summary Example

OCI VM Deployment

Deploy to OCI Compute with automated provisioning using Terraform.

Quick Deploy

cd terraform/oci-vm

# Configure variables
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars with your values

# Deploy
terraform init
terraform plan
terraform apply

# Get connection info
terraform output

什么被配置

• OCI计算实例 （VM.标准E.4.Flex，2个OCPU，16GB RAM）
• 带子网的VCN （公共或私人）
• 安全列表 （SSH+可选HTTP）
• 云初始化配置:

- Python 3.11+pip - Docker+Docker组合 - MCP OCI OPSI服务器 - OCI-CLI - 自动启动系统服务

详细指南

看 docs/OCI_VM_DEPLOYMENT.md 用于：

• 分步说明
• 网络配置选项
• 安全强化
• 用于生产的OAuth设置
• 监测和维护

______________________________________________________________________

可用工具

缓存工具（即时-零API调用）

Cache Tools Examples (click to expand)

数据库搜索： Database Search

数据库详细信息： Database Details

OPSI工具（运营洞察）

DBM工具（数据库管理）

管理工具

技能工具

______________________________________________________________________

MCP资源

通过URI模式访问只读数据：

______________________________________________________________________

MCP提示

可重复使用的工作流模板：

分析提示

• analyze_database_performance(database_name, time_range)
• investigate_slow_query(sql_id)
• analyze_wait_events(database_name, wait_class)
• analyze_resource_contention(compartment_name)
• daily_health_check()

操作提示

• enable_monitoring(compartment_name)
• security_audit(compartment_name)
• tablespace_maintenance(database_name)
• plan_baseline_management(database_name)
• profile_setup(profile_name)

报告提示

• capacity_planning_report(compartment_name, forecast_days)
• performance_summary_report(database_name, days)
• fleet_inventory_report()
• awr_comparison_report(database_name, baseline, compare)
• compliance_report(compartment_name)

______________________________________________________________________

DBA技能

常见DBA任务的13项专业技能：

______________________________________________________________________

配置

环境变量

OAuth配置（生产）

看 FASTCMP_V3_GUIDE.md 用于使用OCI身份域进行OAuth设置。

______________________________________________________________________

文档

______________________________________________________________________

许可证

麻省理工学院

贡献

欢迎投稿！请看 贡献.md.

资源

• 模型上下文协议
• FastMCP文档
• OCI运营洞察
• OCI Python SDK