<p align="center">
  <img src="./assets/oraclemind_logo_light.png" alt="OracleMind Logo" width="420"/>
</p>

<h1 align="center">OracleMind</h1>
<p align="center"><em>AI-powered MCP server for Oracle Cloud Infrastructure — 85 tools to manage OCI with Claude and other LLMs</em></p>


> Skill MCP permettant aux LLM comme **Claude** d'interagir directement avec **Oracle Cloud Infrastructure** via le Model Context Protocol.

[![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/Protocol-MCP-orange)](https://modelcontextprotocol.io/)
[![OCI](https://img.shields.io/badge/Cloud-Oracle%20OCI-red)](https://cloud.oracle.com/)
[![Tools](https://img.shields.io/badge/Tools-85%20outils-green)]()
[![License](https://img.shields.io/badge/License-Non--Commercial%20Personal%20Use-lightgrey)](./LICENSE)
[![Pro Services](https://img.shields.io/badge/Pro%20Services-Available-blueviolet)](./COMMERCIAL_LICENSE.md)
[![Contact](https://img.shields.io/badge/Contact-contact%40journeyinto--ai.com-blue)](mailto:contact@journeyinto-ai.com)

---

## ✨ Caractéristiques

- **Sélection dynamique de profils** : basculez entre les profils/locations OCI sans redémarrer le serveur
- **Connexion OCI standard** : utilise la configuration standard de l'interface CLI OCI
- **85 outils complets** couvrant plus de 11 catégories de services OCI
- **Gestion du cycle de vie des instances** (démarrage, arrêt)
- **Gestion des systèmes de bases de données** et des nœuds de bases de données
- **Gestion des clusters OKE** et des pools de nœuds Kubernetes
- **Intégration native Claude Desktop** via le protocole MCP

---

## 📜 Licence

Ce projet est distribué sous une **licence personnelle non commerciale**.

> ✅ **Usage personnel gratuit** — Pour tout développeur individuel à des fins non commerciales.
> ❌ **Usage commercial interdit** — Toute utilisation commerciale nécessite une licence commerciale.

**Zehair Louzza** détient l'intégralité des droits sur ce logiciel (droits intellectuels, commerciaux et moraux).

👉 Voir [LICENSE](./LICENSE) pour les termes complets.
👉 Pour un usage commercial : [COMMERCIAL_LICENSE.md](./COMMERCIAL_LICENSE.md) ou 📧 [contact@journeyinto-ai.com](mailto:contact@journeyinto-ai.com)

---

## 🚀 Pro Services & MVPs

Des services professionnels et des licences commerciales sont disponibles directement auprès de l'auteur.

| Offre | Cible | Détails |
|---|---|---|
| **Licence Individuelle Pro** | Freelances, consultants solo | Droits commerciaux pour usage individuel |
| **Licence Team / Startup** | Équipes ≤ 10 ingénieurs | Support prioritaire + outils personnalisés |
| **Licence Enterprise** | Entreprises, MSP, intégrateurs cloud | Droits illimités, white-label, NDA |

### MVPs disponibles

- **OCI Infrastructure Monitor** — Dashboard SaaS temps réel (FastAPI + React + OCI MCP)
- **AI-Powered OCI Ops Assistant** — Assistant conversationnel LLM pour gérer OCI en langage naturel
- **Multi-Cloud Data Pipeline** — Pipeline OCI → Snowflake/Supabase avec dbt et monitoring
- **Custom MCP Tool Development** — Développement d'outils OCI sur mesure

👉 Voir [COMMERCIAL_LICENSE.md](./COMMERCIAL_LICENSE.md) pour les détails complets.
📧 Contact : [contact@journeyinto-ai.com](mailto:contact@journeyinto-ai.com)

---

## 📦 Prérequis

- Python **3.10** ou version ultérieure
- CLI OCI configurée (`oci setup config`)
- Autorisations appropriées dans Oracle Cloud

---

## 🚀 Installation

```bash
# 1. Clonez ce dépôt
git clone https://github.com/zehair-louzza/mcp-server-oci.git
cd mcp-server-oci

# 2. Installez le SDK MCP
pip install git+https://github.com/modelcontextprotocol/python-sdk.git

# 3. Installez les dépendances
pip install oci fastapi uvicorn click pydantic loguru

# 4. Installez le package en mode éditable
pip install -e .
```

---

## ▶️ Usage

### Option 1 : Sélection dynamique du profil (recommandée)

```bash
python -m mcp_server_oci.mcp_server
```

Puis utilisez les outils MCP pour gérer les profils :

| Outil | Description |
|---|---|
| `list_oci_profiles` | Consulter les profils dans `~/.oci/config` |
| `set_oci_profile` | Activer un profil spécifique |
| `get_current_oci_profile` | Vérifier quel profil est actif |

### Option 2 : Avec profil par défaut

```bash
python -m mcp_server_oci.mcp_server --profile DEFAULT
```

### Avec `uv`

```bash
uv --directory /path/to/mcp-server-oci run python -m mcp_server_oci.mcp_server --profile DEFAULT
```

---

## 🖥️ Configuration Claude Desktop (macOS)

Ajoutez cette configuration dans :
`/Users/<username>/Library/Application Support/Claude/claude_desktop_config.json`

### Profil dynamique (recommandé)

```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"
      }
    }
  }
}
```

### Profil fixe

```json
{
  "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"
      }
    }
  }
}
```

### Avec `uv` et profils dynamiques

```json
{
  "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"
      }
    }
  }
}
```

---

## 📋 85 Outils MCP disponibles

### 🔑 Gestion des profils

| Outil | Description |
|---|---|
| `list_oci_profiles` | Lister tous les profils OCI dans `~/.oci/config` |
| `set_oci_profile` | Activer un profil spécifique |
| `get_current_oci_profile` | Afficher le profil actif |

### 👤 Identités et Accès (IAM)

| Outil | Description |
|---|---|
| `list_compartments` | Lister tous les compartiments accessibles |
| `list_users` | Lister les utilisateurs IAM avec statut MFA |
| `get_user` | Détails utilisateur + appartenances aux groupes |
| `list_groups` | Lister les groupes IAM avec nombre de membres |
| `get_group` | Détails groupe avec liste des membres |
| `list_policies` | Lister les politiques IAM avec déclarations |
| `get_policy` | Détails d'une politique avec toutes les règles |
| `list_dynamic_groups` | Lister les groupes dynamiques avec règles |
| `get_dynamic_group` | Détails groupe dynamique + règles principales |

### 🖥️ Instances de calcul

| Outil | Description |
|---|---|
| `list_instances` | Lister les VM dans un compartiment |
| `get_instance` | Détails d'une instance |
| `start_instance` | Démarrer une instance arrêtée |
| `stop_instance` | Arrêter une instance (progressif/forcé) |

### 🗄️ Bases de données

| Outil | Description |
|---|---|
| `list_db_systems` | Lister les systèmes de bases de données |
| `get_db_system` | Détails d'un système de BDD |
| `list_db_nodes` | Lister les nœuds de BDD |
| `get_db_node` | Détails d'un nœud de BDD |
| `start_db_node` | Démarrer un nœud arrêté |
| `stop_db_node` | Arrêter un nœud (progressif/forcé) |
| `reboot_db_node` | Redémarrer un nœud |
| `reset_db_node` | Forcer le redémarrage d'un nœud |
| `softreset_db_node` | Redémarrage logiciel d'un nœud |
| `start_db_system` | Démarrer tous les nœuds d'un système |
| `stop_db_system` | Arrêter tous les nœuds d'un système |
| `list_databases` | Lister les bases de données d'un compartiment |
| `get_database` | Détails BDD + chaînes de connexion + PDB |
| `list_autonomous_databases` | Lister les ADB avec type de charge de travail |
| `get_autonomous_database` | Détails ADB + portefeuille + auto-scaling |

### 🌐 Réseau

| Outil | Description |
|---|---|
| `list_vcns` | Lister les VCN avec blocs CIDR |
| `get_vcn` | Détails VCN incluant IPv6 |
| `list_subnets` | Lister les sous-réseaux |
| `get_subnet` | Détails sous-réseau + sécurité + routage |
| `list_vnics` | Lister les VNIC d'un compartiment/instance |
| `get_vnic` | Détails VNIC + IPs + NSG |
| `list_security_lists` | Lister les listes de sécurité avec règles |
| `get_security_list` | Détails liste de sécurité |
| `list_network_security_groups` | Lister les NSG |
| `get_network_security_group` | Détails NSG avec toutes les règles |

### 💾 Stockage

| Outil | Description |
|---|---|
| `get_namespace` | Espace de noms Object Storage |
| `list_buckets` | Lister les buckets Object Storage |
| `get_bucket` | Détails bucket + accès public + versionnage |
| `list_volumes` | Lister les volumes Block Storage |
| `get_volume` | Détails volume + performance + sauvegarde |
| `list_boot_volumes` | Lister les volumes de démarrage |
| `get_boot_volume` | Détails volume boot + image source |
| `list_file_systems` | Lister les systèmes de fichiers |
| `get_file_system` | Détails + octets mesurés + instantanés |

### ⚖️ Équilibreurs de charge

| Outil | Description |
|---|---|
| `list_load_balancers` | Lister les load balancers classiques |
| `get_load_balancer` | Détails + backends + écouteurs + certificats |
| `list_network_load_balancers` | Lister les NLB |
| `get_network_load_balancer` | Détails NLB + config backend |

### 🏗️ Infrastructure & Services publics

| Outil | Description |
|---|---|
| `list_availability_domains` | Lister les domaines de disponibilité |
| `list_fault_domains` | Lister les domaines de panne |
| `list_images` | Lister les images de calcul (OS, version, taille) |
| `get_image` | Détails image + options de lancement |
| `list_shapes` | Lister les shapes (CPU, RAM, GPU, réseau) |
| `list_regions` | Lister toutes les régions OCI |
| `get_tenancy_info` | Infos de la location + région d'origine |

### 🔐 Sécurité & Chiffrement (KMS)

| Outil | Description |
|---|---|
| `list_vaults` | Lister les coffres KMS |
| `get_vault` | Détails coffre + points de terminaison |
| `list_keys` | Lister les clés de chiffrement dans un coffre |
| `get_key` | Détails clé + algorithme + structure + versions |

### 💰 Gestion des coûts

| Outil | Description |
|---|---|
| `get_cost_usage_summary` | Récapitulatif coûts/utilisation (quotidien/mensuel) |
| `get_cost_by_service` | Ventilation des coûts par service |
| `get_cost_by_compartment` | Ventilation des coûts par compartiment |
| `list_budgets` | Lister les budgets avec dépenses réelles/prévues |
| `get_budget` | Détails budget + objectifs + règles d'alerte |

### 📊 Surveillance & Observabilité

| Outil | Description |
|---|---|
| `list_alarms` | Lister les alarmes avec sévérité et destinations |
| `get_alarm` | Détails alarme + seuils + notifications |
| `get_alarm_history` | Historique des états avec horodatage |
| `list_metrics` | Lister les métriques disponibles + espaces de noms |
| `query_metric_data` | Interroger les données métriques avec MQL |
| `search_logs` | Rechercher des journaux (Log Search API) |
| `list_log_groups` | Lister les groupes de journaux |
| `list_logs` | Lister les journaux d'un groupe |

### ☸️ Container Engine for Kubernetes (OKE)

| Outil | Description |
|---|---|
| `list_oke_clusters` | Lister les clusters OKE avec version K8s |
| `get_oke_cluster` | Détails cluster + réseau + addons + upgrades |
| `get_oke_cluster_kubeconfig` | Obtenir le kubeconfig pour kubectl |
| `list_oke_node_pools` | Lister les pools de nœuds |
| `get_oke_node_pool` | Détails pool + nœuds + éviction + cycling |
| `list_oke_work_requests` | Lister les opérations asynchrones OKE |
| `get_oke_work_request` | État et avancement d'une work request |

---

## 💡 Exemples d'utilisation

### Gestion des profils

```
# Depuis Claude ou tout client 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"
```

### IAM & Sécurité

```
"List all IAM users in my tenancy"
"Does this user have MFA enabled?"
"List all IAM groups in compartment X"
"List all IAM policies in the root compartment"
"What permissions does this policy grant?"
"Which users have admin access?"
"What dynamic groups allow instance principals?"
```

### Instances de calcul

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

### Bases de données

```
"Show me all DB Systems in compartment ocid1.compartment.oc1..."
"List all databases in compartment X"
"Get connection strings for database ocid1.database.oc1..."
"List all Autonomous Databases in compartment Z"
"Is auto-scaling enabled on this Autonomous Database?"
```

### Réseau

```
"List all VCNs in compartment ocid1.compartment.oc1..."
"List all subnets in VCN ocid1.vcn.oc1..."
"Show me all security lists in compartment X"
"List all network security groups in VCN Y"
"List all VNICs for instance ocid1.instance.oc1..."
```

### Stockage

```
"What is my Object Storage namespace?"
"List all buckets in compartment X"
"Is bucket 'public-bucket' publicly accessible?"
"List all volumes in compartment Y"
"List all file systems in compartment W and AD-1"
```

### Équilibreurs de charge

```
"List all load balancers in compartment X"
"What backend sets and listeners does this load balancer have?"
"List all network load balancers in compartment Y"
"Which load balancers are private vs public?"
```

### Infrastructure

```
"List all availability domains in my tenancy"
"List all compute shapes available in compartment Y"
"What shapes support GPU?"
"List all available OCI regions"
"What is my tenancy name and home region?"
```

### KMS & Sécurité

```
"List all vaults in compartment X"
"List all encryption keys in vault Y"
"What algorithm and protection mode does this key use?"
```

### Gestion des coûts

```
"Show me cost and usage summary for the last 30 days"
"Get cost breakdown by service from 2024-01-01 to 2024-01-31"
"Which services are costing the most?"
"List all budgets in compartment X"
"What is my actual spend vs budget?"
```

### Surveillance

```
"List all alarms in compartment X"
"What alarms are currently firing?"
"Show me alarm history for the last 24 hours"
"Query CpuUtilization for the last hour"
"Search logs for errors in the last hour"
"Search for 'ERROR' in application logs"
```

### OKE (Kubernetes)

```
"List all OKE clusters in compartment X"
"What Kubernetes version is this cluster running?"
"Get the kubeconfig for cluster ocid1.cluster.oc1..."
"List all node pools in compartment Y"
"Show me all work requests that failed"
"Which node pools are running outdated Kubernetes versions?"
```

---

## 🚀 Historique des versions

| Version | Catégorie | Nouveautés | Nbre d'outils |
|---|---|---|---|
| v1.15 | OKE ☸️ | 7 outils : clusters, node pools, work requests | 85 |
| v1.14 | Surveillance 🔍 | 8 outils : alarmes, métriques, journaux | 78 |
| v1.13 | Coûts 💰 | 5 outils : analyse coûts, budgets | 70 |
| v1.12 | Sécurité/KMS 🔐 | 4 outils : coffres-forts, clés | 65 |
| v1.11 | Infrastructure 🏗️ | 7 outils : AD, FD, images, shapes, régions | 61 |
| v1.10 | Load Balancers ⚖️ | 4 outils : LB classique et réseau | 54 |
| v1.9 | IAM 🔐 | 8 outils : users, groupes, policies, dyn. groups | 50 |
| v1.8 | BDD 🗄️ | 4 outils : BDD classiques et autonomes | 42 |
| v1.7 | Stockage 💾 | 9 outils : object, block, file storage | 38 |
| v1.6 | Réseau 🌐 | 10 outils : VCN, subnets, VNIC, NSG | 29 |
| v1.5 | Profils 🔥 | Sélection dynamique multi-locataires | 19 |
| v1.0 | Base | Compute + DB Nodes | — |

---

## 📚 Documentation

- [Guide de sélection dynamique des profils](./DYNAMIC_PROFILE_SELECTION.md)
- [Modèle de gestion des erreurs](./ERROR_HANDLING_PATTERN.md)
- [Exemples de gestion des erreurs](./EXAMPLE_ERROR_HANDLING.py)
- [Licence commerciale & Pro Services](./COMMERCIAL_LICENSE.md)

---

## 🤝 Contribuer

Les contributions sont les bienvenues pour un usage non commercial ! Le code source suit les patterns suivants :

- **Gestion hybride des erreurs** : lever une exception pour les erreurs techniques, retourner un dictionnaire pour les états métier
- **Opérations asynchrones** : pas d'appels bloquants (`time.sleep()`)
- **Configuration centralisée** : constantes dans `config.py`
- **Principe DRY** : décorateurs pour les patterns communs (`mcp_tool_wrapper`)

> ⚠️ Toute contribution reste soumise aux termes de la licence. En contribuant, vous acceptez que vos modifications soient intégrées sous la même licence et que les droits restent la propriété exclusive de Zehair Louzza.

---

## 📝 Licence & Contact

Ce projet est sous **licence personnelle non commerciale**.
Zehair Louzza détient l'intégralité des droits sur ce logiciel.

- 📄 [Licence personnelle (usage gratuit)](./LICENSE)
- 💼 [Licence commerciale & Pro Services](./COMMERCIAL_LICENSE.md)
- 📧 [contact@journeyinto-ai.com](mailto:contact@journeyinto-ai.com)

© 2026 Zehair Louzza. All rights reserved.