# MariaDB MCP Server

🚀 **Serveur MCP (Model Context Protocol) optimisé pour interroger une instance MariaDB/MySQL locale avec une consommation minimale de tokens.**

## ✨ Caractéristiques

- 🔍 **4 outils MCP** : list_databases, list_tables, describe_table, query_database
- 🛡️ **Sécurisé** : Bloque automatiquement les requêtes destructives (DROP, DELETE, etc.)
- ⚡ **Ultra-optimisé** : Format de sortie compact (75-95% de tokens économisés vs JSON)
- 🔌 **Compatible** : Fonctionne avec Warp, Claude Desktop, et tout client MCP
- 📊 **Formats lisibles** : Sortie en texte brut avec séparateurs `\n` et ` | `

## 📦 Installation

### Prérequis

- Node.js 18+ 
- MariaDB ou MySQL installé et accessible
- Un client MCP (Warp, Claude Desktop, etc.)

### Étapes

```bash
git clone https://github.com/Ophecy/mariadb-mcp-server.git
cd mariadb-mcp-server
npm install
```

## ⚙️ Configuration

### 1. Variables d'environnement

Créer un fichier `.env` :

```bash
cp .env.example .env
```

Éditer `.env` avec vos identifiants :

```env
DB_HOST=localhost
DB_PORT=3306
DB_USER=votre_utilisateur
DB_PASSWORD=votre_mot_de_passe
DB_NAME=nom_base_defaut  # optionnel
```

### 2. Configuration Warp

Ajouter dans votre configuration Warp (`~/.config/warp/mcp_config.json` ou équivalent) :

```json
{
  "mcpServers": {
    "mariadb": {
      "command": "node",
      "args": ["/chemin/absolu/vers/mariadb-mcp-server/index.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_USER": "votre_utilisateur",
        "DB_PASSWORD": "votre_mot_de_passe",
        "DB_NAME": "nom_base_defaut"
      }
    }
  }
}
```

### 3. Configuration Claude Desktop

Ajouter dans `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) ou équivalent :

```json
{
  "mcpServers": {
    "mariadb": {
      "command": "node",
      "args": ["/chemin/absolu/vers/mariadb-mcp-server/index.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_USER": "votre_utilisateur",
        "DB_PASSWORD": "votre_mot_de_passe"
      }
    }
  }
}
```

**Redémarrer votre client MCP** après la configuration.

## 🔧 Outils disponibles

### `list_databases`
Liste toutes les bases de données disponibles.

**Exemple de sortie :**
```
backend65_test
conversion_queue
converter
dev1
```

### `list_tables`
Liste toutes les tables d'une base de données.

**Paramètres :**
- `database` (optionnel) : Nom de la base

**Exemple de sortie :**
```
users
products
orders
```

### `describe_table`
Affiche la structure complète d'une table.

**Paramètres :**
- `table` (requis) : Nom de la table
- `database` (optionnel) : Nom de la base

**Exemple de sortie :**
```
id | int(11) | NO | PRI | - | auto_increment
name | varchar(255) | NO | - | - | -
email | varchar(255) | YES | UNI | - | -
```

### `query_database`
Exécute une requête SQL SELECT personnalisée.

**Paramètres :**
- `query` (requis) : Requête SQL (SELECT, SHOW, DESCRIBE uniquement)

**Exemple de sortie :**
```
id | name | email
1 | Alice | alice@example.com
2 | Bob | bob@example.com
```

## 🛡️ Sécurité

**Protection intégrée** : Le serveur bloque automatiquement les requêtes destructives :
- ❌ DROP, DELETE, TRUNCATE
- ❌ ALTER, CREATE
- ❌ INSERT, UPDATE

✅ **Seules les requêtes en lecture sont autorisées** (SELECT, SHOW, DESCRIBE)

## 🧪 Test manuel

Pour tester le serveur en ligne de commande :

```bash
DB_USER=votre_user DB_PASSWORD=votre_pass node index.js
```

## 📊 Optimisation des tokens

Ce serveur utilise des formats de sortie ultra-compacts :

| Type de données | Format JSON | Format optimisé | Économie |
|----------------|-------------|-----------------|----------|
| Listes simples | `["a","b","c"]` | `a\nb\nc` | ~93% |
| Tables | `[{"col":"val"}]` | `col\|val` | ~75% |
| Structures | JSON indenté | Pipe-separated | ~80% |

**Impact** : Réduction drastique des coûts d'API et des temps de réponse ! 🚀

## 🗺️ Roadmap & Futures évolutions

### Version 1.1 (Court terme)
- [ ] Support des connexions distantes sécurisées (SSH tunnel)
- [ ] Pagination automatique pour les grandes requêtes
- [ ] Option `--limit` pour limiter le nombre de résultats
- [ ] Cache des schémas de tables pour réduire les requêtes
- [ ] Support des transactions en lecture seule

### Version 1.2 (Moyen terme)
- [ ] Mode d'écriture optionnel avec confirmation explicite
- [ ] Export des résultats (CSV, JSON)
- [ ] Statistiques d'utilisation et monitoring
- [ ] Support de multiples connexions simultanées
- [ ] Interface web pour visualiser les résultats

### Version 2.0 (Long terme)
- [ ] Support PostgreSQL et SQLite
- [ ] Génération automatique de requêtes SQL à partir de langage naturel
- [ ] Analyse et suggestions d'optimisation de schéma
- [ ] Détection automatique des relations entre tables
- [ ] Mode "explain" pour les performances des requêtes
- [ ] Snapshots de bases pour comparaisons

### Idées à explorer
- [ ] Plugin pour VSCode
- [ ] Support des vues matérialisées
- [ ] Système de permissions granulaire par table
- [ ] Audit logs des requêtes exécutées
- [ ] Support des procédures stockées (lecture seule)

## 🤝 Contribution

Les contributions sont les bienvenues !

1. Fork le projet
2. Créer une branche (`git checkout -b feature/amelioration`)
3. Commit vos changements (`git commit -m 'Ajout fonctionnalité'`)
4. Push vers la branche (`git push origin feature/amelioration`)
5. Ouvrir une Pull Request

## 📝 License

MIT License - voir le fichier [LICENSE](LICENSE) pour plus de détails.

## 🙏 Remerciements

- [Model Context Protocol](https://modelcontextprotocol.io/) par Anthropic
- [mariadb](https://www.npmjs.com/package/mariadb) - Client Node.js pour MariaDB

## 📧 Contact

Pour toute question ou suggestion, ouvrez une [issue](https://github.com/Ophecy/mariadb-mcp-server/issues).