OCI OPSI Server

Бесплатно

Enables comprehensive monitoring and analysis of Oracle Cloud Infrastructure database fleets through natural language interfaces. It supports performance troubl

автор: adibirzu

GitHub

Описание

Enables comprehensive monitoring and analysis of Oracle Cloud Infrastructure database fleets through natural language interfaces. It supports performance troubleshooting, capacity planning, and automated DBA workflows across multi-tenant environments using specialized tools and playbooks.

README

Version 3.0 | FastMCP 2.0 | 13 DBA Skills | OAuth + API Key Auth | Multi-Tenancy

MCP (Model Context Protocol) server for Oracle Cloud Infrastructure (OCI) Operations Insights. This server provides comprehensive Oracle database monitoring and analysis capabilities through Claude Desktop, Claude Code, ChatGPT, or any MCP-compatible client (stdio or HTTP transports).

Quick Links: Installation | Quick Start | Startup & Transports | Prompts & Playbooks | OCI VM Deployment | API Reference

Guides: Skills Guide | FastMCP v3 Guide | OCI Deployment Guide

Standards

docs/OCI_MCP_SERVER_STANDARD.md

Screenshots

Fleet Summary - Instant Overview

Get a complete overview of your database fleet with zero API calls:

Fleet overview showing database counts, types, and compartment distribution - instant response from local cache

Database Search Results

Search and discover databases across your tenancy instantly:

Comprehensive database list with OCIDs, types, and compartments - cached for instant queries

Database Details

Get detailed information about any specific database:

Detailed database information including OCID, type, compartment, and status - instant lookup from cache

What's New in v3.0

Feature	Description
OCI IAM OAuth	Enterprise authentication with OCI Identity Domains
API Key Fallback	Seamless fallback to ~/.oci/config for development
MCP Resources	10 read-only data endpoints for efficient access
MCP Prompts	15 guided DBA workflow templates
Server Composition	4 modular sub-servers with tool prefixes
DBA Skills	13 specialized skills for token-efficient workflows
Di[Link to Secure Variable: OPENAI_API_KEY] Storage	No Redis required - encrypted file storage
OCI VM Ready	Terraform scripts for automated deployment
Async Tasks	Background cache builds (`cache_start_cache_build_task`) with polling
Prebuilt Playbooks	`admin_get_troubleshooting_playbook` and `admin_list_prompts` for fast LLM guidance

Startup & Transports

stdio (default): python -m mcp_oci_opsi (best for Claude Desktop/Code, ChatGPT MCP).
HTTP: MCP_TRANSPORT=http MCP_PORT=8000 python -m mcp_oci_opsi (for remote clients).
SSE / Streamable HTTP: MCP_TRANSPORT=sse|streamable-http MCP_PORT=8000 python -m mcp_oci_opsi (if supported by your FastMCP runtime).
Version switch: MCP_VERSION=v2 (FastMCP server). MCP_VERSION=v3 runs a local bootstrap/CLI (not an MCP server).
Logging: Set LOG_LEVEL=DEBUG for verbose startup; OCI SDK logs default to WARNING.
Timeouts: OCI_CLIENT_TIMEOUT, OPSI_CLIENT_TIMEOUT, DBM_CLIENT_TIMEOUT (seconds) bound per-call latency; MCP_CLIENT_TIMEOUT_MS caps tool invocations.

Architecture Overview

High-Level Architecture

                                    ┌─────────────────────────────────────┐
                                    │         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                                           │
└──────────────────────────────────────────────────────────────────────────────────────────────────────┘

Tool Organization (v3.0)

Prefix	Server	Description
`cache_`	cache-tools	Instant operations (zero API calls) and async cache build tasks
`opsi_`	opsi-tools	Operations Insights analytics with pagination and rate-limit hints
`dbm_`	dbm-tools	Database Management operations with pagination
`admin_`	admin-tools	Profile/config, health, prompts, troubleshooting playbook
(prompts)	admin-tools	`admin_list_prompts`, `admin_get_troubleshooting_playbook`

Authentication Flow

┌────────────────────────────────────────────────────────────────────────────────┐
│                           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                             │
└───────────────────────────────────────────────────────────────────┘

Prerequisites

Python 3.10+
OCI CLI configured at ~/.oci/config

Required IAM Policies:

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

Prompts & Playbooks

Prompt templates: admin_list_prompts returns prebuilt instructions for CPU hotspots, storage risk, slow SQL, and fleet overview. Use as canned system prompts for any LLM.
Troubleshooting playbook: admin_get_troubleshooting_playbook(issue?) suggests cache-first tool flows with reasons.
Health checks: admin_ping, opsi_health, dbm_health are zero-cost readiness probes.
Async tasks: Kick off cache builds with cache_start_cache_build_task(compartment_ids=[...]) and poll with cache_get_task_status(task_id=...).

Installation

Quick Install (Development)

# 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')"

Production Install (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

Quick Start

1. Build the Cache (Recommended)

# 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. Configure MCP Client (stdio)

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json) or 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 Transport (remote)

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. Start Using

# 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

```bash
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](Screenshots/fleet.png)

---

## OCI VM Deployment

Deploy to OCI Compute with automated provisioning using Terraform.

### Quick Deploy

```bash
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

What Gets Provisioned

OCI Compute Instance (VM.Standard.E4.Flex, 2 OCPU, 16GB RAM)
VCN with Subnet (public or private)
Security Lists (SSH + optional HTTP)
Cloud-Init Provisioning:
- Python 3.11 + pip
- Docker + Docker Compose
- MCP OCI OPSI Server
- OCI CLI
- Systemd service for auto-start

Detailed Guide

See docs/OCI_VM_DEPLOYMENT.md for:

Step-by-step instructions
Network configuration options
Security hardening
OAuth setup for production
Monitoring and maintenance

Available Tools

Cache Tools (Instant - Zero API Calls)

Tool	Description
`cache_get_fleet_summary`	Fleet overview with counts and types
`cache_search_databases`	Search by name, type, compartment
`cache_get_databases_by_compartment`	List databases in compartment
`cache_get_cached_statistics`	Cache metadata and stats
`cache_list_cached_compartments`	All compartments in cache
`cache_build_database_cache`	Build/rebuild cache
`cache_refresh_cache_if_needed`	Check and refresh cache
`cache_get_database_by_id`	Get database by OCID

Cache Tools Examples (click to expand)

Database Search:

Database Details:

OPSI Tools (Operations Insights)

Tool	Description
`opsi_list_database_insights`	List database insights
`opsi_summarize_sql_statistics`	SQL performance metrics
`opsi_summarize_sql_insights`	SQL anomaly detection
`opsi_get_database_capacity_trend`	Historical capacity
`opsi_get_database_resource_forecast`	ML forecasting
`opsi_list_host_insights`	Host monitoring
`opsi_list_exadata_insights`	Exadata monitoring
`opsi_query_warehouse`	OPSI warehouse SQL
`opsi_summarize_addm_findings`	ADDM analysis

DBM Tools (Database Management)

Tool	Description
`dbm_list_managed_databases`	List managed databases
`dbm_get_managed_database`	Database details
`dbm_get_tablespace_usage`	Storage metrics
`dbm_list_awr_snapshots`	AWR snapshots
`dbm_get_awr_report`	Generate AWR report
`dbm_get_addm_report`	ADDM recommendations
`dbm_list_sql_plan_baselines`	SPM baselines
`dbm_get_database_parameters`	DB parameters

Admin Tools

Tool	Description
`admin_ping`	Health check
`admin_whoami`	Current context
`admin_list_profiles`	OCI profiles
`admin_validate_profile`	Validate config
`admin_switch_profile`	Change profile
`admin_get_auth_status`	Auth mode info
`admin_diagnose_permissions`	Permission check
`admin_generate_oauth_keys`	Generate keys
`admin_list_compartments`	Compartment tree
`admin_get_tenancy_info`	Tenancy details

Skills Tools

Tool	Description
`list_available_skills`	List 13 DBA skills
`get_skill_context`	Get skill instructions
`get_skill_for_query`	Auto-match skill
`get_quick_reference`	Ta[Link to Secure Variable: OPENAI_API_KEY] mapping
`get_token_optimization_tips`	Best practices

MCP Resources

Access read-only data via URI patterns:

Resource URI	Description
`resource://fleet/summary`	Fleet overview
`resource://fleet/statistics`	Detailed stats
`resource://fleet/compartments`	Compartment list
`resource://database/{id}`	Database info
`resource://database/{id}/tablespaces`	Tablespace usage
`resource://config/profiles`	OCI profiles
`resource://config/current`	Current config
`resource://auth/status`	Auth status
`resource://welcome`	Getting started

MCP Prompts

Reusable workflow templates:

Analysis Prompts

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()

Operations Prompts

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

Reporting Prompts

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 Skills

13 specialized skills for common DBA tasks:

Skill	Description	Key Tools
`fleet-overview`	Fleet inventory and health	cache_get_fleet_summary
`sql-performance`	SQL analysis and tuning	opsi_summarize_sql_statistics
`capacity-planning`	Forecasting and trends	opsi_get_database_resource_forecast
`database-diagnostics`	ADDM and troubleshooting	dbm_get_addm_report
`awr-analysis`	AWR reports and snapshots	dbm_get_awr_report
`host-monitoring`	Host resource monitoring	opsi_list_host_insights
`storage-management`	Tablespace monitoring	dbm_get_tablespace_usage
`security-audit`	User and privilege audit	admin_diagnose_permissions
`sql-watch-management`	SQL Watch configuration	opsi tools
`sql-plan-baselines`	SPM management	dbm_list_sql_plan_baselines
`multi-tenancy`	Profile management	admin_list_profiles
`exadata-monitoring`	Exadata insights	opsi_list_exadata_insights
`dba-assistant`	General DBA help	all tools

Configuration

Environment Variables

Variable	Default	Description
`MCP_VERSION`	`v2`	Entry mode (v2 = MCP server, v3 = bootstrap/CLI)
`MCP_TRANSPORT`	`stdio`	Transport (stdio, http, sse, streamable-http)
`MCP_HOST`	`0.0.0.0`	Bind address for network transports
`MCP_PORT`	`8000`	Port for network transports
`MCP_HTTP_HOST`	`0.0.0.0`	Legacy HTTP bind address (fallback)
`MCP_HTTP_PORT`	`8000`	Legacy HTTP port (fallback)
`OCI_CLI_PROFILE`	`DEFAULT`	OCI profile name
`OCI_REGION`	from config	Region override
`FASTMCP_OAUTH_ENABLED`	`0`	Enable OAuth
`JWT_SIGNING_KEY`	-	JWT signing key (OAuth)
`STORAGE_ENCRYPTION_KEY`	-	Token encryption key
`OTEL_TRACING_ENABLED`	`true`	Enable OpenTelemetry tracing
`OCI_APM_ENDPOINT`	-	OCI APM OTLP endpoint ([Link to Secure Variable: OCI_APM_ENDPOINT])
`OCI_APM_PRIVATE_DATA_KEY`	-	OCI APM private data key ([Link to Secure Variable: OCI_APM_PRIVATE_DATA_KEY])
`OTEL_EXPORTER_OTLP_ENDPOINT`	-	Generic OTLP endpoint (HTTP or gRPC)
`OTEL_DISABLE_LOCAL`	`false`	Disable local collector fallback

OAuth Configuration (Production)

See FASTMCP_V3_GUIDE.md for OAuth setup with OCI Identity Domains.

Documentation

Document	Description
FASTMCP_V3_GUIDE.md	Complete v3.0 guide
SKILLS_GUIDE.md	DBA skills reference
docs/OCI_VM_DEPLOYMENT.md	OCI VM deployment
docs/ARCHITECTURE.md	Detailed architecture
CACHE_SYSTEM.md	Cache system docs
SECURITY.md	Security guidelines

License

MIT

Contributing

Contributions welcome! Please see CONTRIBUTING.md.

Resources

Как установить

Добавь это в claude_desktop_config.json и перезапусти Claude Desktop.

{
  "mcpServers": {
    "mcp-oci-opsi-server": {
      "command": "npx",
      "args": []
    }
  }
}